fix(tui): consolidation review no longer returns silently in the run dashboard

A book run in manual mode that stalled on a continuity-check contradiction (pending_review with review_kind=consolidation) fell through the post-run router (which only handled chapter/section escalations) and dropped to the prompt with no card. Add _consolidation_card (resume with 'run --force') and a catch-all final branch so no not-done terminal state ever returns silently. Autonomous runs auto-repair contradictions and were unaffected. Tests: consolidation card renders its resume command; explain_error now covers context-overflow + token-budget.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Smrutiranjan Patri

CHANGELOG.md

@@ -64,6 +64,13 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `_isolated_settings` fixture points `config._SETTINGS` at a tmp path, so the suite always runs against
   shipped dataclass defaults; a local `config/settings.yaml` (e.g. `agentic=true`) can no longer turn a
   local run red while CI (which has no such file, it's gitignored) stays green.
+- **Consolidation review no longer returns silently (`dashboard.py`).** A book run in manual mode that
+  stalled on a continuity-check contradiction (`pending_review` with `review_kind="consolidation"`) fell
+  through the post-run router — which only handled `chapter`/`section` escalations — and dropped back to
+  the prompt with no card (only a `[!]` line buried in the event log). It now shows a `_consolidation_card`
+  with the resume command (`run --force`), and a catch-all final branch guarantees no not-done terminal
+  state ever returns silently. (Autonomous runs auto-repair contradictions, so they were unaffected.)
+  Also added `explain_error` coverage for **context-window overflow** and **token-budget** failures.
 
 ### Added (earlier this cycle)
 - **The compositor — personas, emotions, and layer composition (plan §23, 2026-06-17).** Built the

resume.md

@@ -52,11 +52,20 @@
     Emotions **8→12** (`emotions.py`): `disgust`, `surprise`, `jealousy`, `pride` - completes Ekman's six
     + the two top dramatic drivers; each adds an anti-cliché deny-list + show-don't-name cue + aliases.
     Counts refreshed in README, plan.md §23, and learning.md.
-  - **NEXT STEP:** the bigger UX gap from the audit is **failure feedback in full-auto (autonomous)
-    runs** - context-overflow/budget errors aren't mapped in `ui.explain_error()`, and a non-escalation
-    pause may show no recovery card. Verify the control flow in `dashboard.run_with_dashboard` and
-    `explain_error`, then make those failures actionable. (Audit also flagged discoverability wins:
-    `/agentic` policy explainer, `/praise`/`/path` help, missing-dep hints.)
+  - **Failure feedback in full-auto - VERIFIED + closed.** Traced the real control flow (not the audit's
+    guess): in **autonomous mode the path was already covered** - contradictions auto-repair
+    (`escalate_on_contradiction=False`), budget is caught -> `_paused_card`, Ctrl-C prints a saved line,
+    raised errors now hit the actionable `explain_error` (context-overflow + budget cases added). The one
+    real gap was a **book + manual-mode consolidation stall** (`review_kind="consolidation"`): it fell
+    through the post-run router (which only handled `chapter`/`section`) and returned **silently**. Fixed
+    with `_consolidation_card` (`run --force` resume) + a catch-all so no not-done state is ever silent.
+    Tests: consolidation card + `explain_error` overflow/budget coverage.
+  - **NEXT STEP (toward "fully agentic"):** the remaining caveats are (1) the **`trace` (learned) policy
+    is under-trained** - turn accumulated `agent_trace.jsonl` into the first real training set; (2) the
+    **agentic branch is lightly validated** - add agentic-branch test coverage to match the fixed
+    pipeline + log a few real agentic runs; (3) minor discoverability wins (`/agentic` policy explainer,
+    `/praise`/`/path` help, missing-dep hints). See the "fully agentic?" assessment - these three are
+    what keep it from a no-caveats claim.
 
 - **New (2026-06-17 - the compositor: personas, emotions, layer composition - DONE, branch
   `feat/compositor-personas-emotions`, stacked on the craft-engine branch):** built the §22.6 deferral

src/writingagent/shell/dashboard.py

@@ -462,6 +462,26 @@ def _paused_card(console, book_id: str) -> None:
     console.print(Panel(body, title=title, title_align="left", border_style=border, padding=(1, 2)))
 
 
+def _consolidation_card(console) -> None:
+    """The continuity check (consolidation) found possible contradictions and paused for a
+    look - a book, manual-mode review. Without this the run returned SILENTLY (the only hint
+    was a `[!]` line buried in the event log). Say what happened, where to see it, and the one
+    command to proceed."""
+    from rich.panel import Panel
+    from rich.text import Text
+    console.print()
+    body = Text()
+    body.append("The continuity check flagged possible contradictions across chapters.\n",
+                style=f"bold {GOLD}")
+    body.append("Everything committed so far is saved.\n\n", style=DIM)
+    body.append("see them:  status", style=f"bold {GOLD}")
+    body.append("            then either —\n", style=DIM)
+    body.append("accept & finish:  run --force", style=f"bold {GOLD}")
+    body.append("     or fix one:  revise --chapter N --instruction \"…\"", style=DIM)
+    console.print(Panel(body, title=f"[{GOLD}]⏸ consolidation review[/]", title_align="left",
+                        border_style=GOLD, padding=(1, 2)))
+
+
 def _escalation_picker(console, cfg, uid: str, book_id: str, state: dict) -> str:
     """Interactive resolution of a stalled chapter/section - one keypress instead of
     a two-flag command. Returns 'rerun' (resume the pipeline) or 'stop'."""
@@ -632,14 +652,19 @@ def _ask(prompt: str) -> str:
                 _ring()
                 _summary_card(console, dash, state, uid, book_id)
             return
-        if (interactive and state.get("pending_review")
-                and state.get("review_kind") in ("chapter", "section")):
+        pending = state.get("pending_review")
+        kind = state.get("review_kind")
+        if interactive and pending and kind in ("chapter", "section"):
             _ring()
             if _escalation_picker(console, cfg, uid, book_id, state) == "rerun":
                 continue
-        elif console and not state.get("pending_review"):
-            # Not done, not a unit escalation → paused (budget cap / interrupt). Make it
-            # a clear recovery moment rather than a silent return to the prompt.
+        elif console and pending and kind == "consolidation":
+            # Continuity-check stall (book, manual mode): used to return silently.
+            _ring()
+            _consolidation_card(console)
+        elif console:
+            # Anything else not-done (budget cap / interrupt / a pending review we don't
+            # drive interactively here): never return silently — leave a recovery card.
             _paused_card(console, book_id)
         return
 

tests/test_themes.py

@@ -106,4 +106,9 @@ def test_explain_error_maps_known_failures():
     assert "key" in ui.explain_error(RuntimeError("401 Unauthorized")).lower()
     assert "rate" in ui.explain_error(RuntimeError("429 Too Many Requests")).lower()
     assert ui.explain_error(RuntimeError("Connection timed out")) is not None
+    # context-window overflow + token-budget map to an actionable next step (not a traceback)
+    assert "context" in ui.explain_error(
+        RuntimeError("This model's maximum context length is 8192 tokens")).lower()
+    assert "max_run_tokens" in ui.explain_error(
+        RuntimeError("run token budget reached (500000 >= 500000 tokens)"))
     assert ui.explain_error(ValueError("totally unknown thing")) is None

tests/test_ui.py

@@ -256,6 +256,17 @@ def test_paused_card_renders(tmp_brain):
     assert "paused" in console.file.getvalue().lower()
 
 
+def test_consolidation_card_renders_recovery(tmp_brain):
+    """A continuity-check stall must show a recovery card (it used to return silently):
+    say what happened and give the one resume command."""
+    from writingagent.shell.dashboard import _consolidation_card
+    console = _record_console()
+    _consolidation_card(console)
+    out = console.file.getvalue()
+    assert "contradiction" in out.lower()
+    assert "run --force" in out                    # the documented resume command
+
+
 def test_narrow_banner_drops_figlet():
     import io