Escalation reason truncated at 2000 chars drops the blocker and the operator instructions

[tronghieu]

Observed on bmad-loop 0.11.0, run 20260826-114252-3da1.

Summary

A CRITICAL escalation's reason is truncated at 2000 characters with no marker. Because a dev session's report leads with what it built and closes with why it stopped, the truncation reliably keeps the narrative and drops the blocker and the operator instructions — the only two things the paused run actually needs a human to read.

Mechanism

• devcontract.py:395 — escalations.append({"type": "blocked", "severity": "CRITICAL", "detail": detail[:2000]})
• escalation.py:129 — return Decision(Action.PAUSE, f"CRITICAL escalation from dev session: {details}")

That single string then becomes:

• reason on the dev-decision, story-escalated and run-paused journal entries — all three carry the same truncated copy, so the run directory holds no untruncated version;
• the notice appended to ATTENTION;
• the body of bmad-loop status <run-id>;
• the escalation pane in bmad-loop tui.

Measured on this run: len(reason) == 2038 on all three entries — the 38-character prefix plus exactly 2000 characters of detail.

What the operator sees

The notice opens with Status: done and goes on for two thousand characters describing a completed, reviewed implementation. It ends mid-word:

[2026-08-26 17:13:09] CRITICAL escalation: 9-2-define-negotiated-variant-prices: CRITICAL escalation from dev session: Status: done
...
a database outage rendered as "this group has no negotiated prices" on the one screen whose purpose
is the negotiated-price record; and picking a catalog varia

There is no ellipsis, no (truncated), no length, and no pointer to the full text. Nothing in the notice signals that it is partial.

What was dropped

Everything after character 2000, which in this case was the entire reason for the pause:

### Blocking condition

`protected file change requires human approval (pnpm-lock.yaml)`

The implementation is complete and every verification command is green, but the
finalizing commit cannot be made by an agent. ... The pre-commit hook refuses it
and says so in the same words as review-process.md: agents and automated
sessions must not bypass it, and must escalate to a human.

Everything is staged and nothing else blocks. A maintainer completes the run
with the documented local escape hatch:

    LEFTHOOK_EXCLUDE=protected-files git commit

Reading ATTENTION and journal.jsonl alone, an operator cannot tell why the run paused. Both say Status: done and describe finished work. The blocking condition and the one command that clears it survived only in the terminal log capture, which is a TUI redraw dump and not something an operator can reliably read.

The full text is already on disk

arr.detail comes from parse_auto_run_result(spec_path) (devcontract.py:373), so the untruncated blocking condition is sitting in the story spec's result section the whole time — here, _bmad-output/implementation-artifacts/spec-9-2-define-negotiated-variant-prices.md. The escalation record already knows that path; it just never hands it to the reader.

Suggested fixes

In rough order of value:

1. Mark the truncation and point at the source. When detail is cut, append something like \n\n[truncated at 2000 chars — full detail in <spec_file>]. Cheap, and it alone would have made this run self-explanatory.
2. Do not truncate in the journal. journal.jsonl is line-delimited JSON on disk with no size pressure; the 2000-character cap belongs on display surfaces (status, tui, ATTENTION), not on the durable record.
3. Truncate from the right end, or prefer the blocking section. If a cap must apply to a single field, the tail of an escalation report carries the actionable content. Better still, when the report has an explicit ### Blocking condition section, use that as the detail and treat the rest as context.

[pbean]

Verdict: confirmed. Validated against main @ cf5d5b99; cites are against that commit.

One site, exactly where you said. devcontract.py:395 — escalations.append({"type": "blocked", "severity": "CRITICAL", "detail": detail[:2000]}). No marker, no named constant, no comment justifying the number. That string becomes the reason on dev-decision (engine.py:2269-2277), on story-escalated and the ATTENTION notice (engine.py:7239 → gates.notify, gates.py:86), on run-paused, in bmad-loop status (cli.py:3331), and in the TUI (tui/widgets.py:228-229).

Your fixes 1 and 2 are both being taken, implemented together. journal.jsonl keeps the full detail — it is line-delimited JSON on disk with no size pressure, and a durable record is the wrong place for a display cap. The cap moves to the display surfaces, and where it applies it is marked and names its source.

Fix 1 is genuinely one line, and closer to hand than you could see from outside. result["spec_file"] is built two keys away from "escalations" in the same dict literal (devcontract.py:397-404), decide_dev already receives that whole dict (escalation.py:126), and _record_dev_spec latches task.spec_file immediately before _escalate is called (engine.py:2380-2409).

One correction to relay. The run directory does retain an escalation record beyond the journal — resolve._gather_escalations writes resolve/<story_key>/context.json. But it is cut at the same 2000 characters, because the truncation happens at synthesis time, upstream of every consumer. So your core point stands unchanged: there is no untruncated copy anywhere in the run directory. Noting it only so that nobody later "fixes" this by pointing operators at that file.

One thing your report could not have found, which decides the shape of the fix. That format literal has five siblings — escalation.py:129 and :165, engine.py:6127, sweep.py:985, sweep.py:1175 — for the review, fix, migration and triage sessions. All are byte-identical apart from the session name, and all are display surfaces. So all six go through one shared helper, or the truncation marker you asked for ends up inconsistent across session kinds — which is a worse failure than today's uniform silence.

Fix 3 we are not taking. Once the journal is untruncated and the display cap is marked and sourced, choosing which 2000 characters to show is a guess about the report's shape, and a report that puts its blocker in the middle would defeat either heuristic. The pointer to the full text does the work instead.

Labelled bug, area:engine, P2.

The len(reason) == 2038 measurement — the 38-character prefix plus exactly 2000 — and the quoted mid-word cut are what made this a one-line diagnosis rather than a suspicion. The framing is what carried it, though: a dev report leads with what it built and closes with why it stopped, so a head-truncation reliably keeps the narrative and drops the two things a paused run actually needs a human to read.