cctally 1.53.0 → 1.54.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.54.0] - 2026-06-22
+
+### Added
+- **Dashboard conversation viewer — side-by-side session comparison.** A new **⟷ Compare with…** control in the reader head puts the conversation list into a pick-mode (a banner with Cancel/Esc; the anchor session's row greyed out) to choose a second session, then opens a side-by-side **prompt-sequence diff** of the two runs — built for comparing variations of the same or a similar task to see where they diverged and which run was cheaper / faster / cleaner. A metrics-delta strip heads the view with A→B Cost, Tokens, Prompts, Errors, Duration, and Files (an improvement arrow only on the lower-is-better cost / errors / duration), the two prompt spines are aligned by their normalized first lines with a ⚡ divergence marker on replaced regions and a hatched gap where one run has an extra prompt, and clicking any row lazily expands both runs' full prompt text inline (new `GET /api/conversation/<id>/prompts` route behind the same fail-closed transcript gate) with an "open in reader →" jump per side. The view is two-column on a wide viewport and a unified single column below ~1100px, divergence is conveyed by the ⚡ bar + ◆ markers + del/add styling (never color alone), and the comparison is shareable and cold-loadable via its `#/conversations/compare/<A>/<B>` URL with ⇄ swap / ✕ close. (#217)
+- **Dashboard conversation viewer — transcript export & per-card extraction.** The reader header gains an `Export ▾` menu with four Markdown scopes — Whole transcript, Prompts only, Chat only, and Replay recipe (a numbered list of your prompts) — each offering Copy (clipboard) and Download (`.md`); the export is computed server-side over the whole assembled session (new `GET /api/conversation/<id>/export` route behind the same fail-closed transcript gate), so it's complete even for a long transcript you've only partially paged in, and truncated tool data is marked `… [truncated]` rather than shown as complete. A diff card additionally offers a `.patch` download (a real `diff --git`/`@@` unified diff — Write yields an applyable add-patch, Edit/MultiEdit are snippet-relative best-effort), and a Bash card offers a `copy full` action (`$ cmd` + stdout + stderr, with a truncation marker when clipped). (#217)
+- **Dashboard conversation viewer — files-touched tab + tool-type/subagent focus filters.** The outline sidebar gains an `[Outline] [Files]` tab listing every file the session modified via an Edit/MultiEdit/Write call (in first-touch order) with a summed `+N −M` badge per path, expandable to per-touch jump rows that scroll the transcript to the change; a truncated edit with no computable stat is still listed (its badge side omitted), and `NotebookEdit`/read-only tools never appear. The focus control gains a `▾ More` menu adding three filters on the same single-select axis — Edits (Edit/MultiEdit/Write turns), Bash, and a Subagent submenu that isolates one top-level subagent thread (labelled by its agent kind, key fallback when no metadata) — that filter the reading column like the four primary modes; `v` keeps cycling only the four primary modes and returns to All from a More filter. (#217)
+- **Dashboard conversation viewer — git-context diff rendering + a task-completion summary.** An injected `Injected context` block that carries an unfenced git diff (e.g. `diff --git a/CLAUDE.md b/CLAUDE.md … @@ … @@`) now renders as a real red/green unified diff — per-file path header, a `+N −M` stat, and the same syntax-highlighted hunk rows as an Edit diff — with the surrounding prose left as Markdown; detection is conservative (a real `diff --git` marker, never a bare `-`/`+` bullet), so a Markdown list is never mistaken for a diff. And when a session's main-thread to-do checklist ends fully completed, the reader header shows a green `✓ Complete · N` chip (always visible regardless of scroll) that jumps to the final checklist, plus a `✓ Session complete (N tasks)` outline landmark — both gated on the final *main-thread* snapshot being entirely done, so a subagent's own checklist never triggers them. (#217)
+- **Dashboard conversation viewer — in-reader cost/token analytics.** Each assistant turn's cost footer gains a thin micro-bar whose width and intensity encode that turn's cost relative to the most-expensive turn loaded so far (the exact `$`/token text is unchanged; the bar is a relative cue with the precise cost in its tooltip); the reader header carries a cumulative-cost chip showing `$so-far / $total` plus a progress bar that tracks your scroll position, prefixed `~` when earlier pages aren't loaded yet (a lower bound) and hidden both on a costless session and until you've scrolled a turn into view (so it never flashes a transient `$0.00`); and the outline's cache-rebuild stat expands from a single count into a per-rebuild jump list — each row labelled with its turn, wasted tokens, and `~$` cost, worst-first, capped at three with a "+N more" expander, honoring the `dashboard.cache_failure_markers` opt-out. (#217)
+- **Dashboard conversation viewer — per-turn bookmarks & notes.** Each turn's action row gains a ★ bookmark toggle with an inline note editor (saved on Enter/blur, cancelled on Esc); bookmarks persist in your browser's local storage only — nothing leaves the machine — and surface as ★ landmarks in the outline (labelled with your note or the turn's heading, including bookmarks on subagent turns), with a ★ chip in the outline's "Jump to" cluster and reader keys `i` / `I` to step to the next / previous bookmark and `t` to toggle a bookmark on the current turn. (#217)
+- **Dashboard conversation viewer — inline PDF rendering.** A PDF attachment now offers a `view inline ▾` toggle that renders the PDF in the reading column at a capped, scrollable height (with a `collapse ▴` control); the viewer mounts — and the bytes fetch — only when expanded, is served behind the same privacy gate as every other transcript media request, and falls back to the `open ↗` link automatically in a browser without a built-in PDF viewer. (#217)
+
+### Changed
+- **Dashboard conversation search — the Files facet now matches a file-path substring instead of a path prefix.** Searching the Files facet for a bare basename (`package.json`) or a mid-path fragment (`cctally`) now returns the sessions that touched a matching path, instead of requiring a leading path prefix; the match is a case-insensitive substring over the (modest) touched-file table. (#223)
+- **Dashboard conversation find bar — regex matches are now underlined in the transcript.** In regex find mode the in-prose highlight is no longer suppressed: matches get a best-effort inline underline (per rendered text segment, case-toggle-aware), alongside the existing match count and jump-to-match. Invalid or pathological patterns degrade to no underline (the match count still drives navigation). (#223)
+
+### Fixed
+- **Dashboard conversation viewer — the reader-header `Export ▾` and focus `▾ More` menus are now fully keyboard-navigable.** Both popovers previously exposed a `role="menu"` with no arrow-key navigation; they now implement the full menu keyboard pattern — opening moves focus to the first item, `↑`/`↓` cycle through items (wrapping), `Home`/`End` jump to the ends, and `Esc` closes and restores focus to the trigger, with a single roving tab stop so `Tab` moves past the menu rather than through every item. In the focus `▾ More` menu, `→` opens the Subagent submenu (focusing its first entry) and `←` collapses back to the parent. (#224)
+- **Dashboard conversation viewer — git-context diff path parsing no longer over-captures a trailing word into the file path.** The `diff --git a/… b/…` path capture now stops at whitespace instead of greedily running to end-of-line, so a pathological marker line carrying trailing prose after the `b/` path can't bleed that text into the displayed new-path header; real injected diffs (whose paths are whitespace-free) are unaffected. (#224)
+- Conversation viewer: subagents dispatched without an explicit type (the default general-purpose case, e.g. SDD implementors/reviewers) now show their kind, description, and token/duration/tool usage in the card chip and outline — previously only explicitly-typed subagents (e.g. Explore) did (#225).
+- **Dashboard conversation viewer — jumping to a deeply-nested subagent no longer occasionally leaves that subagent's card collapsed.** When you jump to a target inside a subagent that was itself spawned by another subagent (a grandchild thread), the reader force-opens the whole ancestor chain; that expansion now latches each card's open-state in the same render that opens it instead of a beat later, so the brief reset that runs once the jump has scrolled into place can no longer race the parent's expansion and silently re-collapse the nested target. (#222)
+
 ## [1.53.0] - 2026-06-21
 
 ### Added

package/bin/_cctally_dashboard.py

@@ -5483,6 +5483,15 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # Live-tail SSE for the open reader (spec §2). Matched BEFORE the
             # <id> reader catch-all.
             self._handle_get_conversation_events(path)
+        elif path.startswith("/api/conversation/") and path.endswith("/export"):
+            # #217 S5: whole-session Markdown export (F1/F5). Matched BEFORE the
+            # <id> reader catch-all (same precedence as /outline).
+            self._handle_get_conversation_export(path)
+        elif path.startswith("/api/conversation/") and path.endswith("/prompts"):
+            # #217 S7: ordered main-thread prompt spine for session comparison
+            # (F10). Matched BEFORE the <id> reader catch-all (same precedence
+            # as /outline).
+            self._handle_get_conversation_prompts(path)
         elif path.startswith("/api/conversation/"):
             self._handle_get_conversation_detail(path)
         else:
@@ -7877,6 +7886,75 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
         self._respond_json(200, body)
 
+    def _handle_get_conversation_prompts(self, path: str) -> None:
+        """``GET /api/conversation/<sid>/prompts`` — ordered main-thread human
+        prompts + full text (#217 S7 F10, the session-comparison spine). Same
+        fail-closed transcript privacy gate as ``/outline`` —
+        ``_require_transcripts_allowed()`` ONLY (no ``_check_origin_csrf``: the
+        sibling transcript GETs gate on this predicate alone). Unknown id → 404.
+        """
+        if not self._require_transcripts_allowed():
+            return
+        import urllib.parse as _u
+        session_id = _u.unquote(path[len("/api/conversation/"):-len("/prompts")])
+        if not session_id:
+            self.send_error(404, "conversation not found")
+            return
+        ok, body = self._run_conversation_query(
+            lambda conn: self._conversation_query().get_conversation_prompts(conn, session_id),
+            "/api/conversation/prompts")
+        if not ok:
+            return
+        if body is None:
+            self.send_error(404, "conversation not found")
+            return
+        self._respond_json(200, body)
+
+    _CONV_EXPORT_SCOPES = ("all", "prompts", "chat", "recipe")
+
+    def _handle_get_conversation_export(self, path: str) -> None:
+        """``GET /api/conversation/<sid>/export?scope=<all|prompts|chat|recipe>``
+        — whole-session Markdown (issue #217 S5 F1/F5).
+
+        Same fail-closed transcript privacy gate as ``/outline`` / ``/payload``
+        / ``/find`` — ``_require_transcripts_allowed()`` ONLY. **No
+        ``_check_origin_csrf``** (Codex P0-1): the sibling transcript GETs gate
+        on this predicate alone; ``_check_origin_csrf`` rejects a missing
+        ``Origin`` and would make export STRICTER than its sibling reader routes.
+
+        ``scope`` is validated HERE, BEFORE the kernel (the
+        ``_run_conversation_query``-collapses-kernel-exceptions-to-500 gotcha —
+        an invalid scope is a clean 400, never a 500). Unknown session → 404.
+        Emits ``text/markdown; charset=utf-8`` (the client builds the download
+        Blob/filename, so no ``Content-Disposition`` is needed)."""
+        if not self._require_transcripts_allowed():
+            return
+        import urllib.parse as _u
+        session_id = _u.unquote(path[len("/api/conversation/"):-len("/export")])
+        q = _u.parse_qs(self.path.partition("?")[2])
+        scope = _qs_str(q, "scope", "all")
+        if scope not in self._CONV_EXPORT_SCOPES:
+            self._respond_json(400, {"error": f"unknown scope: {scope}"})
+            return
+        if not session_id:
+            self.send_error(404, "conversation not found")
+            return
+        ok, body = self._run_conversation_query(
+            lambda conn: self._conversation_query().get_conversation_export(
+                conn, session_id, scope),
+            "/api/conversation/export")
+        if not ok:
+            return
+        if body is None:
+            self.send_error(404, "conversation not found")
+            return
+        data = body.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/markdown; charset=utf-8")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
     def _handle_get_conversation_find(self, path: str) -> None:
         """``GET /api/conversation/<sid>/find?q=...&kind=...`` — in-conversation
         find → document-ordered rendered-turn anchors (#177 S6). Same fail-closed

package/bin/_cctally_db.py

@@ -2413,14 +2413,15 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
             tool        TEXT NOT NULL,
             UNIQUE(message_id, file_path, tool)
         );
-        -- COLLATE NOCASE is load-bearing (#217 S2 / I-3 review Important #1): the
-        -- default ``LIKE`` is case-insensitive, and SQLite only rides a btree index
-        -- for ``file_path LIKE 'prefix%'`` when the index column folds the same way
-        -- (NOCASE) — a BINARY-collated index leaves the prefix probe a full SCAN. So
-        -- the kind=files PREFIX branch (``_search_files``) is genuinely index-assisted
-        -- ONLY with this NOCASE collation. (The substring branch leads with '%' and is
-        -- a documented scan regardless.) NOCASE folds A-Z/a-z the same way the LIKE
-        -- built-in does, so matching semantics are byte-identical to the prior index.
+        -- COLLATE NOCASE keeps the index's case-folding identical to the default
+        -- (case-insensitive) ``LIKE`` (#217 S2 / I-3 review Important #1): NOCASE folds
+        -- A-Z/a-z the same way the LIKE built-in does, so matching semantics are
+        -- byte-identical to a BINARY index. (#223: ``_search_files`` now substring-
+        -- matches EVERY query (``file_path LIKE '%q%'``) — a deliberate scan over the
+        -- modest touch table — so this index no longer drives a prefix probe; it is
+        -- retained as-is with no schema change. NOCASE was originally load-bearing so a
+        -- ``LIKE 'prefix%'`` could ride the btree, which SQLite only does when the index
+        -- column folds the same way.)
         CREATE INDEX IF NOT EXISTS idx_file_touches_path
             ON conversation_file_touches(file_path COLLATE NOCASE);
 

package/bin/_lib_conversation.py

@@ -617,9 +617,12 @@ def _attach_subagent_result(blocks, obj):
     block — the unambiguous subagent-spawn result shape. Zero or >1 tool_result
     blocks: no-op (the kernel then degrades that subagent card to title-only).
     The kind (subagent_type) is captured separately on the spawn tool_use block;
-    the kernel joins the two on tool_use_id. ``agentId`` == the subagent file's
-    ``_subagent_key``. Meta keys are normalized to snake_case here so the kernel
-    stays a pure pass-through (same posture as is_error / tool_use_id)."""
+    the kernel identifies a spawn by the tool NAME (Agent/Task), so an untyped
+    general-purpose spawn — no subagent_type recorded — still links, with the
+    kernel defaulting its kind to ``general-purpose`` (#225). The kernel joins
+    the two on tool_use_id. ``agentId`` == the subagent file's ``_subagent_key``.
+    Meta keys are normalized to snake_case here so the kernel stays a pure
+    pass-through (same posture as is_error / tool_use_id)."""
     tur = obj.get("toolUseResult")
     if not isinstance(tur, dict):
         return

package/bin/_lib_conversation_export.py

@@ -0,0 +1,325 @@
+"""Pure, I/O-free Markdown serializer for a conversation session (issue #217 S5,
+F1/F5). No DB / filesystem / locks — fed the assembled ``items`` (+
+``subagent_meta``) from ``_assemble_session`` in ``_lib_conversation_query.py``,
+so the renderer stays golden-testable (the same purity contract as
+``_lib_share.py``). Golden-tested in ``tests/test_conversation_export.py``.
+
+Public surface::
+
+    export_session_markdown(items, scope, *, subagent_meta=None,
+                            title=None, session_id=None) -> str
+
+``scope`` is one of ``all`` / ``chat`` / ``prompts`` / ``recipe`` (the four
+export scopes; the handler validates the value, so an unknown scope here falls
+back to the ``all`` renderer). ``subagent_meta`` supplies subagent labels
+(Codex P1-2); the serializer groups subagent turns by ``subagent_key`` in
+document order — a deliberate simplification of the reader's full nesting tree.
+
+Item / block shape (matches ``_assemble_session``): each item is a dict with
+``kind`` (``human``/``assistant``/``tool_result``/``meta``), ``anchor`` (with
+``uuid``), ``ts``, ``text``, ``blocks`` (list), ``subagent_key`` (``None`` for
+the main session), ``is_sidechain``, plus ``meta_kind`` on meta items and
+``model`` on assistant turns. Tool blocks are ``kind == "tool_call"`` with
+``name`` / ``input`` (bounded dict) / ``input_truncated`` / ``result``
+(``{text, truncated, is_error, ...}`` or ``None``) / optional ``edit_stat`` /
+optional ``stderr`` (the structured Bash stderr suffix of ``result.text``).
+"""
+
+# Deliberately the narrow {Edit, MultiEdit, Write} set — NOT the wider
+# `_FILE_TOUCH_TOOLS` (which includes NotebookEdit). Edit-family tool calls
+# render as a fenced ```diff block.
+_EDIT_TOOLS = {"edit", "multiedit", "write"}
+_TRUNCATED = " … [truncated]"
+
+
+def export_session_markdown(items, scope, *, subagent_meta=None, title=None,
+                            session_id=None):
+    """Render a whole assembled session to Markdown for one export scope."""
+    items = list(items or [])
+    subagent_meta = subagent_meta or {}
+    if scope == "recipe":
+        return _render_recipe(items, title)
+    if scope == "prompts":
+        return _render_prompts(items, title)
+    if scope == "chat":
+        return _render_chat(items, title)
+    return _render_all(items, subagent_meta, title)   # "all" (default)
+
+
+# ---- shared predicates / helpers ------------------------------------------
+
+def _is_main(it):
+    """True for a main-session turn (not a subagent thread, not a sidechain)."""
+    return it.get("subagent_key") is None and not it.get("is_sidechain")
+
+
+def _item_text(it):
+    return (it.get("text") or "").strip()
+
+
+def _human_prompts(items):
+    """Main-session human turns with non-empty prose, in document order."""
+    return [it for it in items
+            if it.get("kind") == "human" and _is_main(it) and _item_text(it)]
+
+
+def extract_prompt_entries(items):
+    """Ordered main-thread human prompts as ``[{"uuid", "text"}]``.
+
+    Single source of truth for the structured prompt spine (#217 S7) — reuses
+    the same main-thread predicate (``_human_prompts``) and the same prose
+    extraction (``_item_text``) as the recipe/prompts export, so the
+    ``/prompts`` route and the export can never drift. The uuid is the turn's
+    ``anchor`` uuid — the same identity ``get_conversation_outline`` emits — so
+    the spine aligns 1:1 with the outline's human turns.
+    """
+    return [{"uuid": it["anchor"]["uuid"], "text": _item_text(it)}
+            for it in _human_prompts(items)]
+
+
+def _title_header(title):
+    """An H1 title block (with a trailing blank line) or empty string."""
+    t = (title or "").strip()
+    return f"# {t}\n\n" if t else ""
+
+
+def _role_header(it):
+    kind = it.get("kind")
+    ts = it.get("ts") or ""
+    if kind == "human":
+        label = "## 👤 Human"
+    elif kind == "assistant":
+        label = "## 🤖 Assistant"
+    elif kind == "meta":
+        label = f"## ⚙️ {_meta_label(it)}"
+    else:                                   # tool_result orphan / other
+        label = "## 🔧 Tool result"
+    return f"{label}{f'  ·  {ts}' if ts else ''}"
+
+
+def _meta_label(it):
+    mk = (it.get("meta_kind") or "note")
+    return mk.replace("_", " ").title()
+
+
+def _blockquote(text):
+    """Render ``text`` as a Markdown blockquote (one ``> `` per line)."""
+    lines = (text or "").splitlines() or [""]
+    return "\n".join(f"> {ln}" if ln else ">" for ln in lines)
+
+
+# ---- tool-call rendering ---------------------------------------------------
+
+def _render_tool_call(b):
+    """Render one ``tool_call`` block to a Markdown chunk."""
+    name = b.get("name") or "Tool"
+    nm = name.lower()
+    inp = b.get("input") if isinstance(b.get("input"), dict) else {}
+    if nm in _EDIT_TOOLS:
+        return _render_edit_call(name, inp, b)
+    if nm == "bash":
+        return _render_bash_call(inp, b)
+    return _render_generic_call(name, b)
+
+
+def _edit_diff_lines(name, inp):
+    """Reconstruct +/- diff lines for an Edit/MultiEdit/Write call from the
+    bounded input (best-effort — bounded leaves may be clipped)."""
+    nm = (name or "").lower()
+    lines = []
+    if nm == "write":
+        content = inp.get("content")
+        if isinstance(content, str):
+            for ln in content.splitlines():
+                lines.append("+" + ln)
+        return lines
+    if nm == "multiedit":
+        edits = inp.get("edits")
+        if isinstance(edits, list):
+            for e in edits:
+                e = e if isinstance(e, dict) else {}
+                lines.extend(_one_edit_lines(e.get("old_string"),
+                                             e.get("new_string")))
+        return lines
+    # edit
+    return _one_edit_lines(inp.get("old_string"), inp.get("new_string"))
+
+
+def _one_edit_lines(old, new):
+    out = []
+    if isinstance(old, str):
+        for ln in old.splitlines():
+            out.append("-" + ln)
+    if isinstance(new, str):
+        for ln in new.splitlines():
+            out.append("+" + ln)
+    return out
+
+
+def _render_edit_call(name, inp, b):
+    path = inp.get("file_path")
+    path = path if isinstance(path, str) and path else "(file)"
+    diff = "\n".join(_edit_diff_lines(name, inp))
+    trunc = _TRUNCATED if b.get("input_truncated") else ""
+    head = f"**{name}** `{path}`{trunc}"
+    return f"{head}\n\n```diff\n{diff}\n```"
+
+
+def _render_bash_call(inp, b):
+    command = inp.get("command")
+    command = command if isinstance(command, str) else ""
+    res = b.get("result") if isinstance(b.get("result"), dict) else None
+    out_lines = [f"$ {command}"]
+    if res is not None:
+        text = res.get("text") or ""
+        stderr = b.get("stderr")
+        stdout = text
+        # result.text == stdout + stderr (the empirical Bash storage shape); when
+        # the structured stderr suffix is present, split it out for clarity.
+        if isinstance(stderr, str) and stderr and text.endswith(stderr):
+            stdout = text[: len(text) - len(stderr)]
+        if stdout:
+            out_lines.append(stdout.rstrip("\n"))
+        if isinstance(stderr, str) and stderr:
+            out_lines.append("# stderr")
+            out_lines.append(stderr.rstrip("\n"))
+        if res.get("truncated"):
+            out_lines.append(_TRUNCATED.strip())
+    body = "\n".join(out_lines)
+    return f"```bash\n{body}\n```"
+
+
+def _render_generic_call(name, b):
+    parts = [f"**Tool: {name}**"]
+    summary = b.get("input_summary")
+    if isinstance(summary, str) and summary.strip() and summary.strip() != "{}":
+        parts.append(f"`{summary.strip()}`")
+    res = b.get("result") if isinstance(b.get("result"), dict) else None
+    if res is not None:
+        text = (res.get("text") or "").rstrip("\n")
+        trunc = _TRUNCATED if res.get("truncated") else ""
+        if text:
+            parts.append(f"```\n{text}\n```{trunc}" if not trunc
+                         else f"```\n{text}\n```\n{trunc.strip()}")
+        elif trunc:
+            parts.append(trunc.strip())
+    return "\n\n".join(parts)
+
+
+# ---- per-turn rendering (the `all` matrix) ---------------------------------
+
+def _render_turn_body(it):
+    """The body chunks of a single turn (prose, thinking, tool calls, meta)."""
+    chunks = []
+    kind = it.get("kind")
+    prose = _item_text(it)
+
+    if kind == "meta":
+        # A meta turn renders its body as a labeled blockquote.
+        if prose:
+            chunks.append(_blockquote(prose))
+        return chunks
+
+    if prose:
+        chunks.append(prose)
+
+    for b in it.get("blocks", []):
+        bk = b.get("kind")
+        if bk == "thinking":
+            tx = (b.get("text") or "").strip()
+            if tx:
+                chunks.append("> 💭 Thinking\n>\n" + _blockquote(tx))
+        elif bk in ("tool_call", "tool_use"):
+            chunks.append(_render_tool_call(b))
+        elif bk == "tool_result":
+            # orphan tool_result block (rare — a result the kernel could not fold)
+            tx = (b.get("text") or "").rstrip("\n")
+            trunc = _TRUNCATED.strip() if b.get("truncated") else ""
+            if tx:
+                chunks.append(f"**Tool result**\n\n```\n{tx}\n```"
+                              + (f"\n{trunc}" if trunc else ""))
+    return chunks
+
+
+def _render_all(items, subagent_meta, title):
+    """Full-fidelity, document-order render. Main-session turns render inline;
+    consecutive subagent turns (same subagent_key) group under one heading."""
+    parts = [_title_header(title)] if _title_header(title) else []
+    cur_subagent = None     # the subagent_key whose heading is currently open
+
+    for it in items:
+        sk = it.get("subagent_key")
+        if sk is not None or it.get("is_sidechain"):
+            # Subagent turn — open a grouping heading on a new key.
+            if sk != cur_subagent:
+                label = _subagent_label(sk, subagent_meta)
+                parts.append(f"### ⎇ Subagent: {label}")
+                cur_subagent = sk
+        else:
+            cur_subagent = None     # back to the main thread
+
+        body = _render_turn_body(it)
+        block = [_role_header(it)]
+        block.extend(body)
+        parts.append("\n\n".join(p for p in block if p))
+
+    return "\n\n".join(p for p in parts if p).rstrip() + "\n"
+
+
+def _subagent_label(sk, subagent_meta):
+    meta = subagent_meta.get(sk) if isinstance(subagent_meta, dict) else None
+    if isinstance(meta, dict):
+        kind = meta.get("kind") or meta.get("subagent_type")
+        if isinstance(kind, str) and kind.strip():
+            return kind.strip()
+    return sk if isinstance(sk, str) and sk else "subagent"
+
+
+# ---- the `chat` scope (prose-only, main-session) --------------------------
+
+def _render_chat(items, title):
+    """Human + assistant prose only — no thinking, no tools, no meta;
+    main-session only. Deliberately leaner than the live 'chat' focus mode
+    (which retains thinking) — an intentional divergence (spec §1)."""
+    parts = [_title_header(title)] if _title_header(title) else []
+    for it in items:
+        if it.get("kind") not in ("human", "assistant"):
+            continue
+        if not _is_main(it):
+            continue
+        prose = _item_text(it)
+        if not prose:
+            continue
+        parts.append(f"{_role_header(it)}\n\n{prose}")
+    return "\n\n".join(p for p in parts if p).rstrip() + "\n"
+
+
+# ---- the `prompts` scope --------------------------------------------------
+
+def _render_prompts(items, title):
+    """Main-session human turns only, each as ``## Prompt N`` + full text."""
+    parts = [_title_header(title)] if _title_header(title) else []
+    for n, it in enumerate(_human_prompts(items), start=1):
+        parts.append(f"## Prompt {n}\n\n{_item_text(it)}")
+    return "\n\n".join(p for p in parts if p).rstrip() + "\n"
+
+
+# ---- the `recipe` scope (F5) ----------------------------------------------
+
+def _render_recipe(items, title):
+    """A ``# Replay recipe`` header + a numbered list of main-session prompts —
+    the re-runnable script form."""
+    prompts = _human_prompts(items)
+    out = ["# Replay recipe"]
+    if title and title.strip():
+        out.append(f"_{title.strip()}_")
+    if prompts:
+        numbered = []
+        for n, it in enumerate(prompts, start=1):
+            # Collapse internal newlines so each prompt is one numbered step.
+            text = " ".join(_item_text(it).split())
+            numbered.append(f"{n}. {text}")
+        out.append("\n".join(numbered))
+    else:
+        out.append("_(no prompts)_")
+    return "\n\n".join(out).rstrip() + "\n"