feat(tui): animate the run dashboard between log events

The Live held a static render() snapshot, refreshed only when a log line
arrived - during one long LLM call the stage text and the elapsed clock froze
for minutes and the run looked hung. The dashboard object is now the Live
renderable (__rich_console__), so auto-refresh re-renders it ~8x/s: the clock
ticks and active stages (drafting/critiquing/humanising) animate with a
braille spinner + cycling dots. Settled stages stay static.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: vikast908

CHANGELOG.md

@@ -23,6 +23,10 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Interactive TUI** - escalation picker (fix/instruct/approve-as-is/go-autonomous/read on a
   stalled unit), manual divergent-variant picking, outline+thesis approval gate after `new`,
   post-run summary card + terminal bell, and a draft-opening glimpse in the dashboard.
+- **Animated run dashboard** - the dashboard is now a live Rich renderable
+  (auto-refreshed ~8×/s), so the elapsed clock ticks and active stages
+  (drafting/critiquing/humanising…) show a spinner with moving dots during long
+  model calls instead of freezing until the next log event.
 - **Compact welcome screen** - the startup screen shrank from ~66 to ~33 lines so the
   wordmark stays visible at the first prompt; the full command list moved to `/help` and
   the feature board to a new **`/features`** command (one-line feature status in the

resume.md

@@ -189,6 +189,13 @@ launched `writing-agent` from the same PowerShell window where a test command ha
   test env var can no longer silently can every model call.
 - Guard tests: welcome height budget (≤14 lines, the regression that started this),
   fake-warning presence, /features + /help tables render (`test_ui.py`, +3).
+- **Run dashboard animates (user feedback on a live run):** the `Live` previously got a
+  static `dash.render()` snapshot, re-rendered only on log events - during one long
+  critic call the stage text AND the elapsed clock froze for minutes. The dash object is
+  now the renderable (`__rich_console__`), so Live's auto-refresh (8/s) re-renders it
+  continuously: clock ticks, and active stages (`…`) get a braille spinner + cycling
+  dots (`⠹ critiquing..`). Settled stages (reviewed/committed) stay static. +1 test
+  (animation frames differ; dash is print-able). **215 tests pass.**
 - **Next step:** user re-runs `writing-agent` in a clean terminal (no BOOK_AGENT_FAKE) and
   retries the live article: chat-propose → "go ahead" → run.
 

src/book_agent/shell.py

@@ -1055,7 +1055,14 @@ def _execute_cmd(cmd_line: str, console, cfg, settings, state) -> None:
 
 class _RunDashboard:
     """Live, multi-line view for `run`: header (elapsed + live tokens), a chapter
-    progress bar, the current unit + stage, and a short scroll of recent events."""
+    progress bar, the current unit + stage, and a short scroll of recent events.
+
+    The dashboard object itself is handed to rich.Live (it renders via
+    __rich_console__), so the auto-refresh thread re-renders it ~8x/s - the
+    elapsed clock ticks and active stages animate even when the pipeline is deep
+    inside one long LLM call and no log event arrives for minutes."""
+
+    _SPIN = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"   # braille spinner, same family as console.status "dots"
 
     def __init__(self, book_id: str, total: int, done: int, brief: str = ""):
         self.book_id = book_id
@@ -1072,6 +1079,19 @@ def _elapsed(self) -> str:
         s = int(time.time() - self.start)
         return f"{s // 60:02d}:{s % 60:02d}"
 
+    def _stage_label(self) -> str:
+        """Active stages (ending in …) get a spinner + cycling dots so a long
+        model call visibly works instead of looking hung."""
+        if not self.stage.endswith("…"):
+            return self.stage
+        now = time.monotonic()
+        spin = self._SPIN[int(now * 8) % len(self._SPIN)]
+        dots = "." * (1 + int(now * 2.5) % 3)
+        return f"{spin} {self.stage[:-1]}{dots}"
+
+    def __rich_console__(self, console, options):
+        yield self.render()
+
     def render(self):
         from rich.console import Group
         from rich.text import Text
@@ -1101,7 +1121,7 @@ def render(self):
         stage = Text("  ")
         if self.unit:
             stage.append(self.unit + "  ", style=PARCH)
-        stage.append("· " + self.stage, style=f"italic {INK}")
+        stage.append("· " + self._stage_label(), style=f"italic {INK}")
         if self.verdict:
             stage.append("   " + self.verdict, style=DIM)
         rows = [head, *rows_brief, bar, stage]
@@ -1289,11 +1309,12 @@ def run_with_dashboard(cfg, uid: str, book_id: str, console, *, force: bool = Fa
             total, done_so_far = 1, 0
 
         dash = _RunDashboard(book_id, total, done_so_far, brief=brief)
-        with Live(dash.render(), console=console, refresh_per_second=8,
+        # The dash object (not a snapshot) is the renderable: Live's auto-refresh
+        # re-renders it 8x/s, so the clock + stage spinner animate between events.
+        with Live(dash, console=console, refresh_per_second=8,
                   transient=False, vertical_overflow="visible") as live:
-            def _log(msg: str, dash=dash, live=live) -> None:   # bind: defined in a loop
-                dash.log(msg)
-                live.update(dash.render())
+            def _log(msg: str, dash=dash) -> None:   # bind: defined in a loop
+                dash.log(msg)   # auto-refresh picks the mutation up within ~125ms
 
             def _ask(prompt: str) -> str:
                 # Pause the live render, take input, resume - prompting inside a Live
@@ -1307,7 +1328,6 @@ def _ask(prompt: str) -> str:
 
             state = orchestrator.run(cfg, uid, book_id, force=force, autonomous=autonomous,
                                      log=_log, ask=_ask if interactive else None)
-            live.update(dash.render())
         force, autonomous = False, None   # one-shot flags; later passes resume plainly
 
         if state.get("phase") == "done":

tests/test_ui.py

@@ -57,6 +57,26 @@ def test_run_dashboard_log_parsing():
     d.render()                                  # builds a renderable without raising
 
 
+def test_run_dashboard_stage_animates(monkeypatch):
+    """Active stages (…) must visibly move between log events: Live re-renders the
+    dash object, and the label changes frame-to-frame. Terminal stages stay static."""
+    import time as _time
+
+    from book_agent.shell import _RunDashboard
+    d = _RunDashboard("b", total=1, done=0)
+    d.stage = "critiquing…"
+    monkeypatch.setattr(_time, "monotonic", lambda: 0.0)
+    first = d._stage_label()
+    monkeypatch.setattr(_time, "monotonic", lambda: 0.5)
+    second = d._stage_label()
+    assert first != second                      # spinner/dots advanced
+    assert "critiquing" in first
+    d.stage = "committed"
+    assert d._stage_label() == "committed"      # no spinner on settled stages
+    # The dash itself is a Rich renderable (handed to Live directly).
+    _record_console().print(d)
+
+
 def _record_console():
     import io