cctally 1.52.1 → 1.54.0

package/bin/_lib_conversation_query.py

@@ -26,6 +26,11 @@ from _lib_pricing import _calculate_entry_cost
 # content block the same way the parser does at ingest — reuse the parser's
 # _stringify so the full (un-capped) result text matches the cached/capped one.
 from _lib_conversation import _stringify
+# #217 S1 / U5: the payload-clip helpers moved DOWN into the parser module (low
+# in the dependency graph) so _bound_input's total-cap backstop and this module's
+# read_full_payload share one bound-guaranteeing implementation. Imported here
+# (query depends on the parser, never the reverse — verified at #217).
+from _lib_conversation import _clip_payload_input, _shrink_largest_leaf
 # #177 S4: the media-route reader walks a content array with the SAME ordinal
 # generator the ingest placeholders used, so "media item N" addresses one item.
 from _lib_conversation import iter_media_items
@@ -272,39 +277,124 @@ def _subagent_key(source_path):
     return stem or None
 
 
-# §4 1a — nested (grandchild) subagent result parse. The new Claude Code format
-# emits a grandchild's spawn result as STRING content (no structured
-# `agent_id`/`subagent_meta`), with a trailing `agentId: <hash> (use SendMessage
-# …)` line and an OPTIONAL `<usage>` totals wrapper. Anchored on the literal
-# `<usage>` wrapper; tolerant of whitespace/newline variants (re.DOTALL).
-_NESTED_AGENT_ID_RE = re.compile(r"agentId:\s*([0-9a-f]+)")
-_NESTED_USAGE_RE = re.compile(
-    r"<usage>\s*subagent_tokens:\s*(\d+)\s*tool_uses:\s*(\d+)\s*duration_ms:\s*(\d+)\s*</usage>",
-    re.DOTALL,
+# §4 1a / #217 S1 U6 — nested (grandchild) subagent result parse. The new Claude
+# Code format emits a grandchild's spawn result as STRING content (no structured
+# record-level toolUseResult.agentId), with a trailing `agentId: <hash> (use
+# SendMessage …)` line and an OPTIONAL `<usage>` totals wrapper. The regex
+# constants + the parse rule moved DOWN into the parser (_lib_conversation) so
+# the INGEST stamp runs them over the FULL raw before the 16 KB clip (#217 S1
+# U6); re-exported here for the read-time fallback over un-reingested rows.
+from _lib_conversation import (
+    _NESTED_AGENT_ID_RE, _NESTED_USAGE_RE, _nested_agent_stamp_from_text,
 )
+# #217 S5 F2 — the true per-edit +N/-M stat, recomputed at outline-build time for
+# non-truncated edits (the stamped `block["edit_stat"]` only exists on truncated
+# inputs, where the bounded copy can't be recounted; Codex P1-7).
+from _lib_conversation import _edit_stat_for
+
+# #217 S5 F2 — the files-touched aggregation is DELIBERATELY scoped to the three
+# named edit tools, NOT `_lib_conversation._FILE_TOUCH_TOOLS` (which also includes
+# NotebookEdit — rare; out of scope, Codex P2-4). Lower-cased for case-insensitive
+# block-name matching.
+_EXPORT_EDIT_TOOLS = {"edit", "multiedit", "write"}
+
+
+def _collect_files(items):
+    """Whole-session files-touched aggregation (#217 S5 F2, spec §2).
+
+    For every Edit / MultiEdit / Write ``tool_call`` block (NOT NotebookEdit —
+    the narrower set is deliberate, Codex P2-4) carrying a string ``file_path``,
+    emit one ``touch`` per call and a per-path running ``+N/-M`` sum, preserving
+    first-touch document order. The signed stat is the stamped ``edit_stat`` when
+    present (truncated inputs), else a recompute via ``_edit_stat_for``; when
+    NEITHER is available the touch is STILL listed with ``add``/``del`` = ``None``
+    and the file total sums only the known values (``None`` only when every touch
+    is unknown — Codex P1-7). Pure over the assembled ``items``.
+    """
+    order, agg = [], {}
+    for it in items:
+        anchor_uuid = it["anchor"]["uuid"]
+        for b in it.get("blocks", []):
+            if b.get("kind") not in ("tool_call", "tool_use"):
+                continue
+            nm = (b.get("name") or "").lower()
+            if nm not in _EXPORT_EDIT_TOOLS:
+                continue
+            inp = b.get("input")
+            path = inp.get("file_path") if isinstance(inp, dict) else None
+            if not isinstance(path, str) or not path:
+                continue
+            st = b.get("edit_stat")
+            if st is None:
+                st = _edit_stat_for(b.get("name"), inp)
+            add = st.get("add") if isinstance(st, dict) else None
+            dele = st.get("del") if isinstance(st, dict) else None
+            if path not in agg:
+                agg[path] = {"path": path, "add": None, "del": None, "touches": []}
+                order.append(path)
+            entry = agg[path]
+            entry["touches"].append({
+                "uuid": anchor_uuid,
+                "tool_use_id": b.get("tool_use_id") or b.get("id"),
+                "op": nm,
+                "add": add,
+                "del": dele,
+            })
+            if add is not None:
+                entry["add"] = (entry["add"] or 0) + add
+            if dele is not None:
+                entry["del"] = (entry["del"] or 0) + dele
+    return [agg[p] for p in order]
+
+
+def _task_completion(items):
+    """Whole-session task-completion detection (#217 S5 F7, spec §3).
+
+    Scan the assembled ``items`` in document order, MAIN THREAD ONLY
+    (``subagent_key is None`` AND not ``is_sidechain`` — Codex P1-1, because
+    ``_fold_task_runs`` keeps task state PER subagent thread, so a global
+    last-snapshot could describe a subagent's checklist rather than the
+    session's). Take the LAST main-thread block carrying a folded
+    ``task_snapshot`` (the Task* family, stamped by ``_fold_task_runs``) or a
+    legacy ``TodoWrite`` (``name == "TodoWrite"``, ``input.todos``). Returns
+    ``{all_done, total, completed, anchor_uuid}`` or ``None`` when the
+    main thread has no tasks. Pure over the assembled ``items``.
+    """
+    final = None
+    final_uuid = None
+    for it in items:
+        if it.get("subagent_key") is not None or it.get("is_sidechain"):
+            continue
+        for b in it.get("blocks", []):
+            if b.get("kind") not in ("tool_call", "tool_use"):
+                continue
+            snap = b.get("task_snapshot")
+            if snap is None and b.get("name") == "TodoWrite":
+                inp = b.get("input")
+                snap = inp.get("todos") if isinstance(inp, dict) else None
+            if isinstance(snap, list):
+                final = snap
+                final_uuid = it["anchor"]["uuid"]
+    if not final:
+        return None
+    total = len(final)
+    completed = sum(1 for t in final
+                    if isinstance(t, dict) and t.get("status") == "completed")
+    return {"all_done": total > 0 and completed == total,
+            "total": total,
+            "completed": completed,
+            "anchor_uuid": final_uuid}
 
 
 def _parse_nested_agent_result(text):
-    """Nested (grandchild) subagent result: string-content, no structured
-    `agentId` (spec §4 1a). Parse `agentId` (+ OPTIONAL `<usage>` totals) out of
-    the result text. Returns (agent_id, meta) — meta is {} when `<usage>` is
-    absent/clipped past the 16 KB cap, populated with completed totals when
-    present. Returns None when no `agentId` is present (an ordinary result, or a
-    >16 KB clip past the `agentId:` line itself — degrades to a flat card, no
-    mis-link). Linking on `agentId` ALONE is sufficient (Codex P1-B)."""
-    if not text:
-        return None
-    m = _NESTED_AGENT_ID_RE.search(text)
-    if not m:
-        return None
-    meta = {}
-    u = _NESTED_USAGE_RE.search(text)
-    if u:
-        meta["total_tokens"] = int(u.group(1))
-        meta["total_tool_use_count"] = int(u.group(2))
-        meta["total_duration_ms"] = int(u.group(3))
-        meta["status"] = "completed"
-    return m.group(1), meta
+    """Read-time fallback for nested (grandchild) subagent results on rows that
+    were ingested BEFORE the #217 S1 U6 structured stamp (un-reingested history).
+    Delegates to the parser's single-source rule over the (already-clipped) block
+    text — so a >16 KB result whose `agentId:` trailer was cut survives only via
+    the ingest stamp + the migration-017 offset-0 reingest, never here. Returns
+    (agent_id, meta) or None when no `agentId:` is present. Linking on `agentId`
+    ALONE is sufficient (Codex P1-B)."""
+    return _nested_agent_stamp_from_text(text)
 
 
 def _iso_ms(ts):
@@ -374,122 +464,338 @@ def _cache_read_saved_usd(model, cache_read):
     return full - read
 
 
+# A normalized cache-failure event. ``compaction`` marks a context-compaction
+# boundary (resets the running-max); otherwise it is an assistant-token event
+# carrying its per-thread/per-model key + the cache_creation/cache_read signal.
+# Both the full-assembly stamp path and the lightweight rebuild-count path build
+# a document-ordered list of these and feed it to the ONE predicate below — the
+# rule is implemented exactly once (U1, #217 S1).
+class _CFEvent:
+    __slots__ = ("compaction", "key", "cc", "cr", "model")
+
+    def __init__(self, *, compaction=False, key=None, cc=0, cr=0, model=None):
+        self.compaction = compaction
+        self.key = key
+        self.cc = cc
+        self.cr = cr
+        self.model = model
+
+
+def _iter_cache_failures(events):
+    """The single cache-failure rule (spec §1), as a generator over a
+    document-ordered ``_CFEvent`` stream. Yields ``(index, prev_cached, lost,
+    model)`` for each FLAGGED assistant event — ``index`` is the event's position
+    in ``events`` so a caller can map a flag back to its source item.
+
+    Maintains a running-max of ``cache_read`` keyed by the event's ``key``
+    (``(subagent_key, model)`` — ``None`` subagent_key = main session). The key
+    is per-thread AND per-model because Anthropic prompt caches are model-
+    specific: a model switch within a thread legitimately starts a fresh cache
+    (cr ~ 0) and must not read as a loss, and the compound key makes that the
+    first event under its own key (no prior rm). The whole map is RESET on a
+    compaction event, since compaction legitimately invalidates the prefix and
+    the post-compaction re-prime is not a failure.
+
+    For each assistant event — cc, cr, and rm (the running-max for this key
+    BEFORE this event) — flag iff rm >= CACHE_FLOOR and cc >= CREATE_FLOOR and
+    cr <= COLLAPSE_FRACTION*rm and cc/(cc+cr) >= RECREATE_FRACTION. The fourth
+    term keeps the rule aligned with the Evidence: it requires that most of THIS
+    event's context was freshly created, not merely that cache_read dipped. After
+    the check, ``running_max[key] = max(rm, cr)`` (a failure's small cr never
+    lowers the high-water mark; the next healthy event re-establishes it).
+
+    ``lost`` is the lost-prefix basis (NOT raw cc, which over-counts when the
+    turn also writes genuinely-new cacheable content): ``min(cc, max(0,
+    rm - cr))``. Order-dependent by construction; run over document-ordered
+    events."""
+    running_max = {}   # (subagent_key, model) -> high-water cache_read
+    for i, ev in enumerate(events):
+        if ev.compaction:
+            # Reset the whole map (compaction invalidates every thread's prefix
+            # in this session view; a per-key reset would need a thread tag the
+            # meta row does not reliably carry).
+            running_max.clear()
+            continue
+        cc, cr = ev.cc, ev.cr
+        rm = running_max.get(ev.key, 0)
+        total = cc + cr
+        if (rm >= _CACHE_FAILURE_CACHE_FLOOR
+                and cc >= _CACHE_FAILURE_CREATE_FLOOR
+                and cr <= _CACHE_FAILURE_COLLAPSE_FRACTION * rm
+                and total > 0
+                and cc / total >= _CACHE_FAILURE_RECREATE_FRACTION):
+            lost = min(cc, max(0, rm - cr))
+            yield (i, rm, lost, ev.model)
+        running_max[ev.key] = max(rm, cr)
+
+
+def _cache_failure_count_over_events(events) -> int:
+    """Count of flagged events in a normalized ``_CFEvent`` stream (the pure
+    predicate the lightweight rebuild-count path consumes). Single source of
+    truth — shares ``_iter_cache_failures`` with the full-assembly stamp."""
+    return sum(1 for _ in _iter_cache_failures(events))
+
+
+def _cache_failure_events_from_items(items):
+    """Build the document-ordered ``_CFEvent`` stream from assembled reader
+    ``items`` plus a parallel ``sources`` list (the source item per event, for
+    stamping). A compaction event per ``meta``/``compaction`` item; an assistant-
+    token event per assistant item carrying a ``tokens`` dict. Items lacking a
+    ``tokens`` dict (no session_entries row, or non-assistant non-compaction
+    items) emit NOTHING and so neither flag nor move the running-max — exactly
+    the pre-U1 skip behavior."""
+    events = []
+    sources = []   # parallel list: the source item per event (for stamping)
+    for it in items:
+        if it.get("kind") == "meta" and it.get("meta_kind") == "compaction":
+            events.append(_CFEvent(compaction=True))
+            sources.append(it)
+            continue
+        if it.get("kind") != "assistant":
+            continue
+        tok = it.get("tokens")
+        if not isinstance(tok, dict):
+            continue                      # no session_entries row -> skip
+        events.append(_CFEvent(
+            key=(it.get("subagent_key"), it.get("model")),
+            cc=tok.get("cache_creation", 0) or 0,
+            cr=tok.get("cache_read", 0) or 0,
+            model=it.get("model")))
+        sources.append(it)
+    return events, sources
+
+
 def _stamp_cache_failures(items):
     """Stamp ``item["cache_failure"]`` on each assistant turn that re-creates the
     bulk of its cached prefix instead of reading it (spec §1). Mutates `items` in
     place; healthy turns are left WITHOUT the key (absent, not zero — matching the
     ``tokens?`` "absent, not zero" convention).
 
-    Walks items in DOCUMENT ORDER (the order `_assemble_session` produces),
-    maintaining a running-max of ``cache_read`` keyed by ``(subagent_key, model)``
-    — ``None`` subagent_key = main session. The key is per-thread AND per-model
-    because Anthropic prompt caches are model-specific: a model switch within a
-    thread legitimately starts a fresh cache (cr ~ 0) and must not read as a loss,
-    and the compound key makes that the first turn under its own key (no prior rm).
-    The per-key running-max is RESET when a context-compaction boundary is crossed
-    (a ``meta`` item whose ``meta_kind == "compaction"``), since compaction
-    legitimately invalidates the prefix and the post-compaction re-prime is not a
-    failure.
-
-    For each assistant item with a ``tokens`` dict — cc = tokens["cache_creation"],
-    cr = tokens["cache_read"], rm = the running-max for this key BEFORE this turn —
-    flag iff rm >= CACHE_FLOOR and cc >= CREATE_FLOOR and cr <= COLLAPSE_FRACTION*rm
-    and cc/(cc+cr) >= RECREATE_FRACTION. The fourth term keeps the rule aligned
-    with the Evidence: it requires that most of THIS turn's context was freshly
-    created, not merely that cache_read dipped. After the check, update
-    ``running_max[key] = max(rm, cr)`` (a failure's small cr never lowers the
-    high-water mark; the next healthy turn re-establishes it).
-
-    Payload (lost-prefix basis — NOT raw cc, which would over-count when the turn
-    also writes genuinely-new cacheable content that was never cached):
+    Builds a document-ordered ``_CFEvent`` stream from the items (a compaction
+    event per compaction-meta, an assistant-token event per token-bearing
+    assistant turn) and runs the SAME ``_iter_cache_failures`` rule the
+    lightweight rebuild-count path uses (single source of truth — the rule lives
+    in exactly one place; U1). The payload is computed here on the lost-prefix
+    basis (NOT raw cc, which would over-count when the turn also writes
+    genuinely-new cacheable content that was never cached):
         lost            = min(cc, max(0, rm - cr))
         tokens_recreated = lost
         prev_cached      = rm
         est_wasted_usd   = write(lost) - read(lost)
+    """
+    events, sources = _cache_failure_events_from_items(items)
+    for idx, prev_cached, lost, model in _iter_cache_failures(events):
+        sources[idx]["cache_failure"] = {
+            "tokens_recreated": lost,
+            "prev_cached": prev_cached,
+            "est_wasted_usd": _cache_failure_wasted_usd(model, lost),
+        }
+
 
-    Items lacking a ``tokens`` dict (no session_entries row, or non-assistant
-    items other than a compaction meta) are skipped and do NOT move the
-    running-max. Order-dependent by construction; run over document-ordered items.
+def _lightweight_rebuild_events(conn, session_id):
+    """Build the document-ordered ``_CFEvent`` stream for a session WITHOUT a
+    full ``_assemble_session`` (U1, #217 S1). Skips the expensive assembly work
+    (no ``blocks_json`` body parse, no tool-result folding, no meta-classify /
+    ANSI strip, no subagent correlation) but faithfully reproduces the canonical
+    normalization the cache-failure predicate depends on:
+
+      - UUID dedup: canonical row per ``(session_id, uuid)`` = first occurrence
+        in (timestamp_utc, id) order (a replay carries the original uuid);
+      - turn grouping by ``(msg_id, req_id)``: an assistant turn — possibly split
+        across non-consecutive fragments interleaved by a tool_result — emits ONE
+        event at the FIRST fragment's position, with cost-once-per-(msg_id,req_id)
+        token attribution from the deduped session_entries row;
+      - first-prose MODEL promotion: the turn's model is the FIRST prose-bearing
+        fragment's model (the canonical anchor), matching ``_build_turn`` /
+        ``_fold_fragment``; a turn with no prose keeps its seed fragment's model;
+      - seed ``source_path -> subagent_key`` derivation (``_subagent_key``);
+      - compaction-reset detection: an ``entry_type in ('meta','human')`` row
+        whose all-text body is a compaction summary (``_is_compaction_body``)
+        and which is NOT a slash-command invocation — mirroring the assembly
+        meta-classify — emits a compaction event.
+
+    The event ORDER is the turn's first-fragment document position, byte-for-byte
+    the order ``_assemble_session`` walks (which emits each turn item at its first
+    fragment, and each meta/human row at its own position). That preserves the
+    running-max walk the predicate requires.
     """
-    running_max = {}   # (subagent_key, model) -> high-water cache_read
-    for it in items:
-        # Context-compaction boundary resets the per-key prefix high-water mark:
-        # the post-compaction re-prime is a legitimate fresh build, not a loss.
-        # Reset the whole map (compaction invalidates every thread's prefix in
-        # this session view; a per-key reset would need a thread tag the meta row
-        # does not reliably carry).
-        if it.get("kind") == "meta" and it.get("meta_kind") == "compaction":
-            running_max.clear()
-            continue
-        if it.get("kind") != "assistant":
+    exists = conn.execute(
+        "SELECT 1 FROM conversation_messages WHERE session_id=? LIMIT 1",
+        (session_id,)).fetchone()
+    if exists is None:
+        return []
+    # Narrow column set: enough to dedup, group turns, derive the subagent_key,
+    # detect compaction, and join the token row. No blocks_json body parse beyond
+    # the all-text compaction guard (which needs text OR the text-block join).
+    rows = conn.execute(
+        "SELECT id, uuid, entry_type, text, blocks_json, model, "
+        "       msg_id, req_id, source_path "
+        "FROM conversation_messages WHERE session_id=? "
+        "ORDER BY timestamp_utc, id", (session_id,)).fetchall()
+    seen_uuid = set()
+    logical = []
+    for row in rows:
+        u = row[1]
+        if u in seen_uuid:
+            continue            # UUID dedup: keep the first (canonical) occurrence
+        seen_uuid.add(u)
+        logical.append(row)
+
+    # Group assistant turns by (msg_id, req_id) at the first-fragment position;
+    # later same-key fragments fold their model (first-prose promotion) without
+    # adding a second event. A `None`-msg_id assistant row carries no turn key and
+    # no session_entries cost, so it never contributes a token event.
+    events = []
+    sources = []                # parallel: the turn key per assistant event
+    turn_index = {}             # (msg_id, req_id) -> index into events
+    turn_has_prose = {}         # (msg_id, req_id) -> bool (model promoted yet?)
+    turn_keys = []              # ordered list of grouped turn keys (for the token map)
+    for (rid, u, etype, text, blocks, model, msg_id, req_id,
+         source_path) in logical:
+        if etype == "assistant" and msg_id is not None:
+            key = (msg_id, req_id)
+            frag_text = (text or "").strip()
+            ev_idx = turn_index.get(key)
+            if ev_idx is None:
+                ev_idx = len(events)
+                turn_index[key] = ev_idx
+                turn_keys.append(key)
+                ev = _CFEvent(key=(_subagent_key(source_path), model),
+                              model=model)
+                events.append(ev)
+                sources.append(key)
+                # The seed model holds until the first prose fragment promotes it.
+                turn_has_prose[key] = bool(frag_text)
+            else:
+                ev = events[ev_idx]
+                # First prose fragment promotes the turn's model anchor. The full
+                # path (`_build_turn`) SEEDS subagent_key from the first fragment
+                # and re-promotes ONLY the model; mirror that here by keeping the
+                # seeded `ev.key[0]` and re-promoting just the model (#218 I-A.1).
+                # subagent_key is per-file-invariant across a turn's fragments (one
+                # (msg_id,req_id) = one file), so this matches in all real data and
+                # is exact structural parity for the engineered cross-file split.
+                if not turn_has_prose.get(key) and frag_text:
+                    ev.key = (ev.key[0], model)
+                    ev.model = model
+                    turn_has_prose[key] = True
+        elif etype in ("meta", "human"):
+            # Mirror the assembly meta-classify's compaction branch: an all-text
+            # body that is a compaction summary AND is not a slash-command
+            # invocation. A command invocation (#188) is promoted to a human turn
+            # BEFORE meta-classify, so a body carrying <command-args> never reads
+            # as compaction; compaction bodies have no <command-args>, so in
+            # practice the invocation check is a faithful belt-and-suspenders.
+            try:
+                parsed_blocks = _json.loads(blocks or "[]")
+            except (ValueError, TypeError):
+                parsed_blocks = []
+            body = text or _join_text_blocks(parsed_blocks)
+            all_text = all(b.get("kind") == "text"
+                           for b in (parsed_blocks or []))
+            if (all_text and _is_compaction_body(body)
+                    and _extract_command_invocation(parsed_blocks, body) is None):
+                events.append(_CFEvent(compaction=True))
+                sources.append(None)
+        # tool_result rows and null-msg_id assistant rows carry no token event.
+
+    # Cost-once token attribution: ONE deduped session_entries row per
+    # (msg_id, req_id) — the same map the full path stamps from. An assistant
+    # turn key absent from session_entries carries NO tokens, so its event is
+    # dropped (neither flags nor moves the running-max) — parity with
+    # _cache_failure_events_from_items's `tokens` skip.
+    usage = _turn_usage_map(conn, turn_keys)
+    filtered = []
+    si = 0
+    for ev in events:
+        if ev.compaction:
+            filtered.append(ev)
+            si += 1
             continue
-        tok = it.get("tokens")
-        if not isinstance(tok, dict):
-            continue                      # no session_entries row -> skip, don't move max
-        cc = tok.get("cache_creation", 0) or 0
-        cr = tok.get("cache_read", 0) or 0
-        key = (it.get("subagent_key"), it.get("model"))
-        rm = running_max.get(key, 0)
-        total = cc + cr
-        if (rm >= _CACHE_FAILURE_CACHE_FLOOR
-                and cc >= _CACHE_FAILURE_CREATE_FLOOR
-                and cr <= _CACHE_FAILURE_COLLAPSE_FRACTION * rm
-                and total > 0
-                and cc / total >= _CACHE_FAILURE_RECREATE_FRACTION):
-            lost = min(cc, max(0, rm - cr))
-            it["cache_failure"] = {
-                "tokens_recreated": lost,
-                "prev_cached": rm,
-                "est_wasted_usd": _cache_failure_wasted_usd(it.get("model"), lost),
-            }
-        running_max[key] = max(rm, cr)
+        key = sources[si]
+        si += 1
+        tok = usage.get(key)
+        if tok is None:
+            continue            # no session_entries row -> skip (don't move max)
+        ev.cc = tok.get("cache_creation", 0) or 0
+        ev.cr = tok.get("cache_read", 0) or 0
+        filtered.append(ev)
+    return filtered
 
 
 def session_cache_rebuild_count(conn, session_id) -> int:
     """Per-session count of cache-rebuild (cache-failure) turns.
 
-    Single source of truth: assembles the session via the SAME pipeline the
-    reader/outline use and runs the SAME _stamp_cache_failures kernel, then
-    counts flagged items. /outline omits stats.cache_failures when the count is
-    0, so "no flagged items" -> 0 (byte-identical to outline). Stored on the
-    conversation_sessions rollup by _recompute_conversation_sessions; filtered
-    by list_conversations(rebuild_min=...).
-
-    _assemble_session already runs _stamp_cache_failures internally before
-    returning, so the items carry the flag on entry; re-running the kernel here
-    is an idempotent recompute (it only ADDS the key on a flagged turn, never
-    clears one, and the predicate is deterministic over the same items) that
-    keeps the helper correct even if assembly ever stops stamping.
+    Single source of truth: builds a document-ordered cache-failure event stream
+    via the LIGHTWEIGHT builder (``_lightweight_rebuild_events`` — no full
+    ``_assemble_session``, so this stays cheap on the flock-held rollup path; U1,
+    #217 S1) and runs it through the SAME ``_cache_failure_count_over_events``
+    predicate the reader's full assembly stamps with. The light builder
+    reproduces the canonical normalization (UUID dedup, turn grouping, first-prose
+    model promotion, seed subagent_key, cost-once token attribution, compaction
+    reset), so the count is byte-identical to the full-assembly count (guarded by
+    ``test_session_cache_rebuild_count_lightweight_matches_full_assembly``).
+
+    /outline omits stats.cache_failures when the count is 0, so "no flagged
+    items" -> 0 (byte-identical to outline). Stored on the conversation_sessions
+    rollup by _recompute_conversation_sessions; filtered by
+    list_conversations(rebuild_min=...).
     """
-    asm = _assemble_session(conn, session_id)
-    if asm is None:
-        return 0
-    items = asm["items"]
-    _stamp_cache_failures(items)
-    return sum(1 for it in items if "cache_failure" in it)
+    return _cache_failure_count_over_events(
+        _lightweight_rebuild_events(conn, session_id))
+
+
+def _turn_costs_for_keys(conn, keys):
+    """{(msg_id, req_id): cost_usd} for the given turn keys, joined ONCE to the
+    deduped session_entries row per (msg_id, req_id) (#217 S1 / U7b — the SINGLE
+    cost-attribution chokepoint both ``_turn_cost_map`` and ``_session_cost_map``
+    delegate to, so the cost-once-per-turn rule is never reimplemented).
+
+    NULL-filters the keys, chunks the OR-of-pairs to stay well under SQLite's
+    variable limit, and computes each cost via the shared pricing helper
+    (honoring a vendor ``cost_usd_raw`` override). Keys absent from
+    session_entries (e.g. ``<synthetic>`` walker-skipped rows) are simply not
+    present in the result -> cost 0 by omission. Parity guard:
+    ``test_session_and_turn_cost_map_share_helper_parity``."""
+    costs = {}
+    norm = [(m, r) for (m, r) in keys if m is not None and r is not None]
+    if not norm:
+        return costs
+    for i in range(0, len(norm), 400):
+        chunk = norm[i:i + 400]
+        cond = " OR ".join("(msg_id=? AND req_id=?)" for _ in chunk)
+        params = [v for pair in chunk for v in pair]
+        sql = ("SELECT msg_id, req_id, model, input_tokens, output_tokens, "
+               "cache_create_tokens, cache_read_tokens, cost_usd_raw "
+               "FROM session_entries WHERE " + cond)
+        for m, r, model, inp, out, cc, cr, raw in conn.execute(sql, params):
+            costs[(m, r)] = _entry_cost(model, inp, out, cc, cr, raw)
+    return costs
 
 
 def _session_cost_map(conn, session_ids):
-    """{session_id: total_cost_usd} for the given sessions. Joins
-    conversation_messages turn keys to the single deduped session_entries row
-    per (msg_id, req_id), so a turn replayed across files contributes once.
-    (msg_id, req_id) is globally unique in session_entries and maps to exactly
-    one session_id, so per-session sums are clean."""
+    """{session_id: total_cost_usd} for the given sessions. Resolves each
+    session's distinct (msg_id, req_id) turn keys, then attributes cost via the
+    shared ``_turn_costs_for_keys`` helper (cost-once per deduped session_entries
+    row), summing into the owning session. (msg_id, req_id) is globally unique in
+    session_entries and maps to exactly one session_id, so per-session sums are
+    clean and a turn replayed across files contributes once."""
     costs = {sid: 0.0 for sid in session_ids}
     if not session_ids:
         return costs
     placeholders = ",".join("?" for _ in session_ids)
-    sql = (
-        "SELECT cm.session_id, se.model, se.input_tokens, se.output_tokens, "
-        "       se.cache_create_tokens, se.cache_read_tokens, se.cost_usd_raw "
-        "FROM (SELECT DISTINCT session_id, msg_id, req_id "
-        "      FROM conversation_messages "
-        "      WHERE session_id IN (%s) AND msg_id IS NOT NULL AND req_id IS NOT NULL) cm "
-        "JOIN session_entries se ON se.msg_id = cm.msg_id AND se.req_id = cm.req_id"
-        % placeholders
-    )
-    for sid, model, inp, out, cc, cr, raw in conn.execute(sql, list(session_ids)):
-        costs[sid] = costs.get(sid, 0.0) + _entry_cost(model, inp, out, cc, cr, raw)
+    pairs = conn.execute(
+        "SELECT DISTINCT session_id, msg_id, req_id "
+        "FROM conversation_messages "
+        "WHERE session_id IN (%s) AND msg_id IS NOT NULL AND req_id IS NOT NULL"
+        % placeholders,
+        list(session_ids),
+    ).fetchall()
+    if not pairs:
+        return costs
+    key_cost = _turn_costs_for_keys(conn, [(m, r) for _, m, r in pairs])
+    for sid, m, r in pairs:
+        costs[sid] = costs.get(sid, 0.0) + key_cost.get((m, r), 0.0)
     return costs
 
 
@@ -513,23 +819,31 @@ def _session_latest_meta_map(conn, session_ids):
     """{session_id: (cwd, git_branch)} using the most-recent NON-NULL value per
     column — the SAME posture as get_conversation's _latest, so the rail and the
     reader agree on a session whose cwd/branch changed over its lifetime (a plain
-    MAX() picks the lexical max, not the latest). Bounded to the page's sessions
-    via per-session correlated lookups over idx (session_id, timestamp_utc, id),
-    mirroring _session_cost_map / _session_models_map."""
+    MAX() picks the lexical max, not the latest). The latest non-null cwd and the
+    latest non-null git_branch may land on DIFFERENT rows (the newest row can
+    carry one but not the other), so each is resolved independently.
+
+    #217 S1 / U7b: consolidated from the prior TWIN correlated subqueries into a
+    SINGLE windowed scan — two ``FIRST_VALUE`` window functions over one
+    partition pass per column, each ordered ``(<col> IS NULL), timestamp_utc DESC,
+    id DESC`` so the most-recent non-null value sorts first (and an all-null
+    session yields NULL, exactly as the LIMIT-1 subquery did). Guarded by
+    ``test_session_latest_meta_map_parity_*`` against the prior semantics; if the
+    window form could not match it, the old correlated SQL would be kept (it
+    matched cleanly, so the consolidation lands)."""
     meta = {sid: (None, None) for sid in session_ids}
     if not session_ids:
         return meta
     placeholders = ",".join("?" for _ in session_ids)
     sql = (
-        "SELECT s.session_id, "
-        "  (SELECT c.cwd FROM conversation_messages c "
-        "   WHERE c.session_id = s.session_id AND c.cwd IS NOT NULL "
-        "   ORDER BY c.timestamp_utc DESC, c.id DESC LIMIT 1), "
-        "  (SELECT b.git_branch FROM conversation_messages b "
-        "   WHERE b.session_id = s.session_id AND b.git_branch IS NOT NULL "
-        "   ORDER BY b.timestamp_utc DESC, b.id DESC LIMIT 1) "
-        "FROM (SELECT DISTINCT session_id FROM conversation_messages "
-        "      WHERE session_id IN (%s)) s" % placeholders
+        "SELECT DISTINCT session_id, "
+        "  FIRST_VALUE(cwd) OVER ("
+        "    PARTITION BY session_id "
+        "    ORDER BY (cwd IS NULL), timestamp_utc DESC, id DESC), "
+        "  FIRST_VALUE(git_branch) OVER ("
+        "    PARTITION BY session_id "
+        "    ORDER BY (git_branch IS NULL), timestamp_utc DESC, id DESC) "
+        "FROM conversation_messages WHERE session_id IN (%s)" % placeholders
     )
     for sid, cwd, branch in conn.execute(sql, list(session_ids)):
         meta[sid] = (cwd, branch)
@@ -561,16 +875,38 @@ def session_source_paths(conn, session_id):
 _SORTS = {
     "recent": "last_activity_utc DESC, session_id DESC",
     "oldest": "started_utc ASC, session_id ASC",
+    # #217 S4 / I-2.1: stored-column rollup sorts. Each tie-broken by
+    # session_id for stable pagination. ``project`` uses an explicit CASE so a
+    # NULL label (not-yet-filled row) or '' (the no-cwd _project_label(None)
+    # sentinel) sorts LAST — a plain COLLATE NOCASE ASC would put them first.
+    "cost": "cost_usd DESC, session_id DESC",
+    "messages": "msg_count DESC, session_id DESC",
+    "project": ("CASE WHEN project_label IS NULL OR project_label = '' "
+                "THEN 1 ELSE 0 END, project_label COLLATE NOCASE ASC, "
+                "session_id ASC"),
 }
 
 # The matching ORDER BY for the live GROUP BY fallback: the rollup's
 # last_activity_utc IS MAX(timestamp_utc) and started_utc IS MIN(timestamp_utc),
 # so the two branches paginate in byte-identical order (the load-bearing
 # invariant). Keep this table in lockstep with _SORTS.
+#
+# ``messages`` has FULL live parity (COUNT(*) DESC over the raw messages == the
+# rollup's stored msg_count). ``cost`` and ``project`` have NO raw-message
+# column, so they are INTENTIONALLY ABSENT here — list_conversations resolves
+# them to the ``recent`` live ordering and flags page.sort_degraded (a brief,
+# self-correcting non-authoritative window). #217 S4 / I-2.1.
 _SORTS_LIVE = {
     "recent": "MAX(timestamp_utc) DESC, session_id DESC",
     "oldest": "MIN(timestamp_utc) ASC, session_id ASC",
+    "messages": "COUNT(*) DESC, session_id DESC",
 }
+# The rollup-only sorts — expressible on the rollup branch but NOT in the live
+# GROUP BY fallback. A request for one of these under the live branch falls back
+# to the recent ordering AND sets page.sort_degraded (keyed to the REQUESTED
+# sort, never the effective order — an unknown sort also falls back to recent
+# but must stay byte-stable, so it is excluded here).
+_DEGRADABLE_SORTS = frozenset(("cost", "project"))
 
 
 def _rollup_authoritative(conn) -> bool:
@@ -663,6 +999,47 @@ def _live_having(filters):
     return (" HAVING " + " AND ".join(having)) if having else "", params
 
 
+def _resolve_search_session_filter(conn, filters):
+    """Resolve the filtered-search session-scope restriction (#217 S2 /
+    Filtered-search). Returns ``(subquery_sql, params, degraded)`` where
+    ``subquery_sql`` is a complete ``"SELECT session_id FROM ... "`` the caller
+    wraps as ``" AND <col> IN (<subquery_sql>)"``, or ``""`` (no restriction) when
+    no axis is set.
+
+    Mirrors the browse dual-branch parity (``list_conversations``):
+
+      * Rollup AUTHORITATIVE (``conversation_sessions_backfill_pending`` clear):
+        every axis is a stored column on the rollup, so restrict to
+        ``SELECT session_id FROM conversation_sessions <_rollup_where(filters)>``
+        (the SAME ``_rollup_where`` the browse rail uses, verbatim). ``degraded``
+        is False.
+      * Rollup PENDING (live fallback) AND a rollup-only axis
+        (project/cost/rebuild) is requested (P1-5): drop the rollup-only axes,
+        set ``degraded`` True, and express ONLY the date axis via a LIVE session
+        prefilter over ``conversation_messages`` keyed on
+        ``MAX(timestamp_utc)`` — the SAME session-activity semantics as
+        ``_live_having``/``_list_session_rows_live``. We restrict by session
+        ACTIVITY, never by a matched row's own timestamp (a session whose match is
+        old but whose activity is in-window must stay).
+      * Rollup pending but ONLY date axis requested: the rollup is not needed
+        (date is expressible live), so use the live prefilter and ``degraded``
+        stays False (no rollup-only axis was dropped — byte-stable with browse).
+    """
+    any_axis = any(filters[k] is not None for k in _FILTER_KEYS)
+    if not any_axis:
+        return "", [], False
+    if _rollup_authoritative(conn):
+        where, params = _rollup_where(filters)
+        return "SELECT session_id FROM conversation_sessions" + where, params, False
+    # Live fallback: only the date axis is expressible over raw messages.
+    degraded = any(filters[k] is not None for k in _ROLLUP_ONLY_FILTER_KEYS)
+    having, hparams = _live_having(filters)
+    sub = (
+        "SELECT session_id FROM conversation_messages "
+        "WHERE session_id IS NOT NULL GROUP BY session_id" + having)
+    return sub, hparams, degraded
+
+
 def _list_session_rows_rollup(conn, order, limit, offset, filters=None):
     """FAST path: read the pre-aggregated rail rows straight from the
     conversation_sessions rollup (spec §3). No GROUP BY, no temp B-tree for the
@@ -754,6 +1131,7 @@ def list_conversations(conn, *, sort="recent", limit=50, offset=0,
         "rebuild_min": rebuild_min,
     }
     degraded = False
+    sort_degraded = False
     if _rollup_authoritative(conn):
         order = _SORTS.get(sort, _SORTS["recent"])
         rows = _list_session_rows_rollup(conn, order, limit, offset, filters)
@@ -761,6 +1139,10 @@ def list_conversations(conn, *, sort="recent", limit=50, offset=0,
         order = _SORTS_LIVE.get(sort, _SORTS_LIVE["recent"])
         degraded = any(
             filters[k] is not None for k in _ROLLUP_ONLY_FILTER_KEYS)
+        # sort_degraded is keyed to the REQUESTED sort, not the effective order:
+        # an unknown sort ALSO falls back to recent here (via _SORTS_LIVE.get),
+        # but must stay byte-stable, so only the known rollup-only sorts flag it.
+        sort_degraded = sort in _DEGRADABLE_SORTS
         rows = _list_session_rows_live(conn, order, limit, offset, filters)
     has_more = len(rows) > limit
     rows = rows[:limit]
@@ -792,6 +1174,10 @@ def list_conversations(conn, *, sort="recent", limit=50, offset=0,
         # The rail surfaces this: project/cost/rebuild filters apply once the
         # rollup finishes indexing; only the date axis held this page.
         page["filter_degraded"] = True
+    if sort_degraded:
+        # The rail surfaces this: cost/project ordering becomes available once
+        # the rollup finishes indexing; this page fell back to recent order.
+        page["sort_degraded"] = True
     return {
         "conversations": conversations,
         "page": page,
@@ -801,22 +1187,13 @@ def list_conversations(conn, *, sort="recent", limit=50, offset=0,
 def _turn_cost_map(conn, turn_keys):
     """{(msg_id, req_id): cost_usd} for the given non-null turn keys, joined ONCE
     to the deduped session_entries row. Keys absent from session_entries (e.g.
-    <synthetic> walker-skipped rows) are simply not present → cost 0 by omission."""
-    costs = {}
-    keys = [(m, r) for (m, r) in turn_keys if m is not None and r is not None]
-    if not keys:
-        return costs
-    # Chunk the OR-of-pairs to stay well under SQLite's variable limit.
-    for i in range(0, len(keys), 400):
-        chunk = keys[i:i + 400]
-        cond = " OR ".join("(msg_id=? AND req_id=?)" for _ in chunk)
-        params = [v for pair in chunk for v in pair]
-        sql = ("SELECT msg_id, req_id, model, input_tokens, output_tokens, "
-               "cache_create_tokens, cache_read_tokens, cost_usd_raw "
-               "FROM session_entries WHERE " + cond)
-        for m, r, model, inp, out, cc, cr, raw in conn.execute(sql, params):
-            costs[(m, r)] = _entry_cost(model, inp, out, cc, cr, raw)
-    return costs
+    <synthetic> walker-skipped rows) are simply not present → cost 0 by omission.
+
+    Thin wrapper over the shared ``_turn_costs_for_keys`` chokepoint (#217 S1 /
+    U7b) — the search path's ``_attach_costs`` still consumes this name + its
+    float-valued contract, so the public signature is unchanged while the body
+    is single-sourced with ``_session_cost_map``."""
+    return _turn_costs_for_keys(conn, turn_keys)
 
 
 def _turn_usage_map(conn, turn_keys):
@@ -846,6 +1223,13 @@ def _turn_usage_map(conn, turn_keys):
     return usage
 
 
+# #225: the two tool names that spawn a subagent. `Agent` = modern, `Task` =
+# older. Exact-match (does NOT match the TaskCreate/TaskUpdate/TaskList checklist
+# family). A spawn is identified by this name even when it carried no
+# subagent_type (the default general-purpose dispatch).
+_SPAWN_TOOL_NAMES = ("Agent", "Task")
+
+
 def _assemble_session(conn, session_id):
     """Shared assembly for get_conversation / get_conversation_outline (#177 S5).
 
@@ -943,12 +1327,15 @@ def _assemble_session(conn, session_id):
     # tool_call/tool_result block shapes are unchanged — the only new output is
     # the top-level subagent_meta map (no undocumented block keys leak). Join is
     # spawn tool_use id <-> tool_result tool_use_id; agent_id == subagent_key.
-    spawn_kind = {}     # tool_use id -> subagent_type
-    spawn_desc = {}     # tool_use id -> spawning Task description (#193)
+    spawn_kind = {}     # tool_use id -> subagent_type (kind), only when declared
+    spawn_ids = {}      # tool_use id -> None: ordered set of Agent/Task spawn ids
+                        # (#225, typed OR untyped). spawn_kind ⊆ spawn_ids. Dict
+                        # (NOT a set) so iteration stays document-ordered.
+    spawn_desc = {}     # tool_use id -> spawning Agent/Task description (#193/#225)
     agent_link = {}     # tool_use id -> (agent_id, raw_meta)
     nested_candidates = []  # §4 1a: (tool_use_id, block) — string-content spawn
                             # results with no structured agent_id, resolved after
-                            # spawn_kind is complete (text still present pre-fold)
+                            # the spawn maps are complete (text still present pre-fold)
     ask_link = {}       # tool_use id -> (answers, annotations)  (#177 S2)
     bash_link = {}      # tool_use id -> (stderr, interrupted)   (#177 S3)
     web_search_link = {}  # tool_use id -> web_search payload    (#177 S4)
@@ -959,15 +1346,23 @@ def _assemble_session(conn, session_id):
             k = b.get("kind")
             if k == "tool_use":
                 st = b.pop("subagent_type", None)
-                if st and b.get("id") is not None:
-                    spawn_kind[b["id"]] = st
-                    # #193: harvest the spawning Task description from the
-                    # already-stored bounded input. Guarded on subagent_type, so
-                    # a Bash `description` (no subagent_type) is NEVER picked up.
+                _id = b.get("id")
+                # #225: a spawn is an Agent/Task tool_use. Identify it by tool
+                # NAME (so an untyped general-purpose spawn — no subagent_type —
+                # still counts) OR by a recorded subagent_type. The name gate is
+                # what keeps a Bash/Read `description` (and a coincidental
+                # structured agent_id, #218 I-B.5) from ever being read as a
+                # spawn.
+                if _id is not None and (st or b.get("name") in _SPAWN_TOOL_NAMES):
+                    spawn_ids[_id] = None
+                    if st:
+                        spawn_kind[_id] = st       # #166: declared kind
+                    # #193/#225: harvest the spawn description from the bounded
+                    # input for ANY spawn (typed or untyped); name-gated above.
                     _inp = b.get("input")
                     _d = _inp.get("description") if isinstance(_inp, dict) else None
                     if isinstance(_d, str) and _d.strip():
-                        spawn_desc[b["id"]] = _d
+                        spawn_desc[_id] = _d
             elif k == "tool_result":
                 aid = b.pop("agent_id", None)
                 meta = b.pop("subagent_meta", None)
@@ -975,7 +1370,7 @@ def _assemble_session(conn, session_id):
                     agent_link[b["tool_use_id"]] = (aid, meta or {})
                 elif b.get("tool_use_id") is not None:
                     # §4 1a candidate — a tool_result with no structured agentId.
-                    # Resolved AFTER spawn_kind is complete (text still present,
+                    # Resolved AFTER the spawn maps are complete (text still present,
                     # pre-Phase-2-fold). The block's `text` holds the result body.
                     nested_candidates.append((b["tool_use_id"], b))
                 ans = b.pop("ask_answers", None)            # #177 S2
@@ -996,22 +1391,33 @@ def _assemble_session(conn, session_id):
                 tlist_ = b.pop("task_list", None)
                 if b.get("tool_use_id") is not None and (tid_ is not None or tlist_ is not None):
                     task_link[b["tool_use_id"]] = {"task_id": tid_, "task_list": tlist_}
+    # §4 symmetry (#218 I-B.5 / #225): drop any agent_link entry whose owning
+    # tool_use is NOT a spawn — an ordinary tool result that coincidentally
+    # carries a structured agent_id (e.g. a Read). Gated on spawn_ids (every
+    # Agent/Task spawn, typed OR untyped) rather than the old spawn_kind, which
+    # wrongly excluded untyped general-purpose spawns. A structured agent_id on a
+    # real spawn is authoritative; the heuristic nested text-parse below stays
+    # spawn-gated all the same.
+    agent_link = {t: v for t, v in agent_link.items() if t in spawn_ids}
     # §4 1a — nested grandchild results: gate the text-parse on the owning
-    # tool_use being a spawn (in spawn_kind), so an ordinary tool result that
+    # tool_use being a spawn (in spawn_ids), so an ordinary tool result that
     # merely mentions "agentId" never matches.
     for _tuid, _block in nested_candidates:
-        if _tuid in spawn_kind and _tuid not in agent_link:
+        if _tuid in spawn_ids and _tuid not in agent_link:
             parsed = _parse_nested_agent_result(_block.get("text"))
             if parsed is not None:
                 agent_link[_tuid] = parsed
     subagent_meta = {}
-    for _tuid, _kind in spawn_kind.items():
+    for _tuid in spawn_ids:                 # document order (ordered dict)
         _link = agent_link.get(_tuid)
         if _link is None:
             continue                       # spawn with no (yet) result -> title-only
         _aid, _raw = _link
-        _entry = {"kind": _kind}
-        if spawn_desc.get(_tuid):          # #193: spawning Task description
+        # #225: kind defaults to "general-purpose" for an untyped Agent/Task
+        # spawn (subagent_type omitted at dispatch ⟹ general-purpose; 0
+        # counterexamples across 3085 real sidecars).
+        _entry = {"kind": spawn_kind.get(_tuid, "general-purpose")}
+        if spawn_desc.get(_tuid):          # #193/#225: spawn description
             _entry["description"] = spawn_desc[_tuid]
         for _f in ("total_tokens", "total_duration_ms", "total_tool_use_count", "status"):
             if _raw.get(_f) is not None:
@@ -1285,13 +1691,27 @@ def _assemble_session(conn, session_id):
             "subagent_meta": subagent_meta, "header_cost": header_cost}
 
 
-def get_conversation(conn, session_id, *, after=None, limit=500):
+def get_conversation(conn, session_id, *, after=None, before=None, tail=False,
+                     limit=500):
     """Reader payload for one session (spec §3.2). Returns None for an unknown
     session. Dedups logical messages by (session_id, uuid) (canonical = earliest
     timestamp), groups assistant fragments into turn items by (msg_id, req_id),
     joins cost once, anchors a turn on its prose-bearing fragment, and exposes
     every member fragment uuid for jump resolution. Cursor over (timestamp_utc,
-    id); ~500 items/page."""
+    id); ~500 items/page.
+
+    Three mutually-exclusive cursor modes over the fully-assembled ascending
+    `items` list (#217 S2 / U4): `after=X` pages forward (existing), `before=X`
+    pages backward (returns the `limit` items immediately before X), and
+    `tail=1` opens at the bottom (returns the last page in one request). More
+    than one supplied raises ValueError (the handler maps it to 400). The
+    boundary keys are mode-uniform (`has_more = end < N`, `has_prev = start > 0`)
+    so a short `before` head-page still reports `has_more` (P2-8); the existing
+    `after`/no-cursor responses stay byte-stable except the two additive
+    `prev_before`/`has_prev` keys (for them `start + limit < N == end < N`, under
+    `end = min(start+limit, N)`)."""
+    if sum(1 for x in (after is not None, before is not None, bool(tail)) if x) > 1:
+        raise ValueError("after/before/tail are mutually exclusive")
     limit = max(1, min(int(limit), 1000))
     asm = _assemble_session(conn, session_id)
     if asm is None:
@@ -1322,34 +1742,60 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
         _la = items[-1]["anchor"]
         last_anchor = {"session_id": session_id, "uuid": _la["uuid"], "id": _la["id"]}
 
-    # Cursor pagination over the item list (anchored to each item's canonical id).
-    # A non-None `after` that matches no item's anchor (stale/deleted cursor)
-    # yields an EMPTY page — never silently re-serves the head (M1).
-    start = 0
-    if after is not None:
-        start = None
+    # Cursor pagination over the item list (anchored to each item's canonical
+    # id). Resolve `start`/`end` per mode, then `page = items[start:end]` and
+    # compute the boundary keys UNIFORMLY (#217 S2 / U4 — P2-8). A non-None
+    # `after`/`before` that matches no item's anchor (stale/deleted cursor)
+    # yields an EMPTY page — never silently re-serves the head/tail (M1).
+    N = len(items)
+
+    def _idx(cur):
         for k, it in enumerate(items):
-            if str(it["anchor"]["id"]) == str(after):
-                start = k + 1
-                break
-        if start is None:
-            return {
-                "session_id": session_id,
-                "title": _title,
-                "project_label": _pl,
-                "git_branch": _latest(logical, 11),
-                "started_utc": logical[0][2],
-                "last_activity_utc": logical[-1][2],
-                "cost_usd": header_cost,
-                "models": sorted({r[6] for r in logical if r[6]}),
-                "last_anchor": last_anchor,
-                "items": [],
-                "subagent_meta": subagent_meta,
-                "page": {"next_after": None, "has_more": False},
-            }
-    page = items[start:start + limit]
-    has_more = start + limit < len(items)
+            if str(it["anchor"]["id"]) == str(cur):
+                return k
+        return None
+
+    def _stale_empty_page():
+        return {
+            "session_id": session_id,
+            "title": _title,
+            "project_label": _pl,
+            "git_branch": _latest(logical, 11),
+            "started_utc": logical[0][2],
+            "last_activity_utc": logical[-1][2],
+            "cost_usd": header_cost,
+            "models": sorted({r[6] for r in logical if r[6]}),
+            "last_anchor": last_anchor,
+            "items": [],
+            "subagent_meta": subagent_meta,
+            "page": {"next_after": None, "has_more": False,
+                     "prev_before": None, "has_prev": False},
+        }
+
+    if tail:
+        end = N
+        start = max(0, N - limit)
+    elif before is not None:
+        b = _idx(before)
+        if b is None:                       # stale cursor → empty page (M1)
+            return _stale_empty_page()
+        end = b
+        start = max(0, end - limit)
+    elif after is not None:
+        a = _idx(after)
+        if a is None:                       # stale cursor → empty page (M1)
+            return _stale_empty_page()
+        start = a + 1
+        end = min(start + limit, N)
+    else:
+        start = 0
+        end = min(limit, N)
+
+    page = items[start:end]
+    has_more = end < N
+    has_prev = start > 0
     next_after = page[-1]["anchor"]["id"] if (page and has_more) else None
+    prev_before = page[0]["anchor"]["id"] if (page and has_prev) else None
 
     # Stamp the session_id into each anchor (spec anchor is (session_id, uuid);
     # the dict literals are built session-agnostic, so fill it here where the
@@ -1381,7 +1827,8 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
         "last_anchor": last_anchor,
         "items": page,
         "subagent_meta": subagent_meta,
-        "page": {"next_after": next_after, "has_more": has_more},
+        "page": {"next_after": next_after, "has_more": has_more,
+                 "prev_before": prev_before, "has_prev": has_prev},
     }
 
 
@@ -1432,6 +1879,23 @@ def get_conversation_outline(conn, session_id):
     cf_wasted = 0.0
     cf_rebuilds = []      # per-rebuild list (worst-first), spec §1
     cache_saved = 0.0     # session cache-value-saved, spec §1
+    # #217 S3 E6(a) — per-subagent cost, summed COST-ONCE over the assembled
+    # items (each item already carries the cost-once-per-turn `cost_usd`, so a
+    # plain per-subagent_key sum never double-counts across folded fragments —
+    # the same discipline `cache_saved` above uses). DISPLAY-ONLY (never a
+    # reconciled / budget / snapshot figure, like `cache_saved_usd`). Emitted as
+    # a SEPARATE top-level `subagent_costs` map — NOT inside `subagent_meta` —
+    # so the outline↔reader `subagent_meta` parity assert stays byte-for-byte
+    # unchanged AND every bucket is covered, including a subagent whose
+    # `subagent_meta` is absent (the s7 case: deriveOutline emits a row for it,
+    # so its cost must be present to render). Every non-null subagent_key bucket
+    # seeds at 0.0 so a zero-cost bucket still appears.
+    subagent_costs = {}   # subagent_key -> cost (cost-once)
+    for it in items:
+        sk = it.get("subagent_key")
+        if sk is not None:
+            subagent_costs.setdefault(sk, 0.0)
+            subagent_costs[sk] += it.get("cost_usd") or 0.0
     for it in items:
         kind = it["kind"]
         turn_counts["total"] += 1
@@ -1519,10 +1983,64 @@ def get_conversation_outline(conn, session_id):
     stats["cache_saved_usd"] = cache_saved
     return {"session_id": session_id,
             "subagent_meta": asm["subagent_meta"],
+            # #217 S3 E6(a) — display-only per-subagent cost (cost-once). 6dp,
+            # matching the per-item / header cost display precision.
+            "subagent_costs": {k: round(v, 6) for k, v in subagent_costs.items()},
             "stats": stats,
+            # #217 S5 F2 — whole-session files-touched aggregation (always
+            # present, possibly []; additive — existing consumers are byte-stable).
+            "files": _collect_files(items),
+            # #217 S5 F7 — main-thread task-completion (always present; None when
+            # the main thread has no tasks; additive — byte-stable for consumers).
+            "task_completion": _task_completion(items),
             "turns": turns}
 
 
+def get_conversation_prompts(conn, session_id):
+    """``{session_id, prompts:[{uuid,text}]}`` — ordered main-thread human
+    prompts with full text (#217 S7, F10 — the session-comparison spine).
+
+    Reuses the SAME ``_assemble_session`` pass as ``get_conversation_outline``
+    (one grouping/dedup pipeline, never a parallel one) and the SAME main-thread
+    predicate as the recipe/prompts export (``extract_prompt_entries`` →
+    ``_human_prompts``), so the spine aligns 1:1 with the outline's human turns
+    and can never drift from the export. Returns ``None`` for an unknown session
+    (the handler's 404 sentinel) — the same contract ``get_conversation_outline``
+    uses (``asm is None``).
+    """
+    asm = _assemble_session(conn, session_id)
+    if asm is None:
+        return None
+    from _lib_conversation_export import extract_prompt_entries
+    return {"session_id": session_id,
+            "prompts": extract_prompt_entries(asm["items"])}
+
+
+def get_conversation_export(conn, session_id, scope):
+    """Whole-session Markdown export for one scope (#217 S5, F1/F5).
+
+    Runs the SAME full ``_assemble_session`` the reader/outline use, then hands
+    the assembled ``items`` (+ ``subagent_meta``) to the pure
+    ``export_session_markdown`` serializer (`_lib_conversation_export.py`), so
+    the renderer stays I/O-free and golden-testable. Returns the Markdown string,
+    or ``None`` for an unknown session (the handler's 404 sentinel). ``scope`` is
+    pre-validated by the handler (an unknown scope never reaches here)."""
+    from _lib_conversation_export import export_session_markdown
+    asm = _assemble_session(conn, session_id)
+    if asm is None:
+        return None
+    items = asm["items"]
+    subagent_meta = asm["subagent_meta"]
+    logical = asm["logical"]
+    # Title via the SAME fallback chain the reader header uses (#193):
+    # ai-title → first human prompt → project label → session_id.
+    _pl = _project_label(_latest(logical, 10))
+    title = (_session_titles_map(conn, [session_id]).get(session_id)
+             or _pl or session_id)
+    return export_session_markdown(items, scope, subagent_meta=subagent_meta,
+                                   title=title, session_id=session_id)
+
+
 _TASK_TRIO = ("TaskCreate", "TaskUpdate", "TaskList")
 
 
@@ -1758,7 +2276,9 @@ def _search_depth(conn) -> str:
 
 
 def search_conversations(conn, query, *, limit=50, offset=0,
-                         kind="all", fts_available=None) -> dict:
+                         kind="all", fts_available=None,
+                         date_from=None, date_to=None, projects=None,
+                         cost_min=None, cost_max=None, rebuild_min=None) -> dict:
     """Cross-session search (spec §3.3). Uses FTS5 when available (bm25 rank +
     snippet); else a LIKE scan with a manual snippet. Hits deduped by
     (session_id, uuid); each carries the turn's cost. `fts_available` overrides
@@ -1767,11 +2287,27 @@ def search_conversations(conn, query, *, limit=50, offset=0,
     #177 S6: ``kind`` (one of ``_SEARCH_KINDS``) scopes the search to a column
     family — ``all`` is unfiltered, ``prompts``/``assistant`` filter the prose
     column + entry_type, ``tools``/``thinking`` filter the split index columns.
-    Every hit gains ``match_kinds`` (sorted ``['tool', 'thinking']`` badges;
-    prose never badges). The response carries additive ``kind`` + ``search_depth``
-    so the client can degrade the Tools/Thinking facets during the one-time
-    column split (``search_depth == 'prose-only'`` short-circuits those two
-    kinds to empty). An unknown ``kind`` raises ``ValueError`` (route → 400)."""
+    #217 S2 / E7: ``title`` searches the external-content title FTS over
+    conversation_ai_titles → one SESSION-level hit per matching session, anchored
+    to that session's first turn, ``match_kinds:["title"]``, snippet = the matched
+    title. #217 S2 / I-3: ``files`` searches ``conversation_file_touches`` (the
+    write-class file-touch axis) → one hit per DISTINCT ``(session_id, file_path)``,
+    anchored to that group's MOST-RECENT touch, ``match_kinds:["file"]``, snippet =
+    the file path. Every hit gains ``match_kinds`` (sorted badges; prose never badges).
+    The response carries additive ``kind`` + ``search_depth`` so the client can
+    degrade the Tools/Thinking facets during the one-time column split
+    (``search_depth == 'prose-only'`` short-circuits those two kinds to empty).
+    An unknown ``kind`` raises ``ValueError`` (route → 400).
+
+    #217 S2 / Filtered-search: the browse filters (``date_from``/``date_to``/
+    ``projects``/``cost_min``/``cost_max``/``rebuild_min``) restrict the search to
+    matching sessions, applied uniformly across EVERY kind as a session-scope
+    ``session_id IN (...)`` predicate (``_resolve_search_session_filter`` reuses
+    ``_rollup_where`` verbatim). When the rollup backfill is pending and a
+    rollup-only axis is requested, only the date axis applies (via a live
+    ``MAX(timestamp_utc)`` prefilter, P1-5) and the response carries additive
+    ``filter_degraded: True`` — exactly mirroring browse. A no-filter request
+    produces byte-stable existing output (no ``filter_degraded`` key)."""
     if kind not in _SEARCH_KINDS:
         raise ValueError(f"unknown kind: {kind}")
     q = (query or "").strip()
@@ -1783,20 +2319,60 @@ def search_conversations(conn, query, *, limit=50, offset=0,
     mode = "fts" if fts_available else "like"
     base = {"query": q, "mode": mode, "hits": [], "total": 0,
             "kind": kind, "search_depth": depth}
+    # Resolve the filtered-search session-scope restriction ONCE (reused by every
+    # kind). ``filt_sql`` is "" when no axis is set, so the no-filter path stays
+    # byte-stable; ``degraded`` flags the dropped rollup-only axes (P1-5).
+    filters = {
+        "date_from": date_from, "date_to": date_to,
+        "projects": list(projects) if projects else None,
+        "cost_min": cost_min, "cost_max": cost_max, "rebuild_min": rebuild_min,
+    }
+    filt_sql, filt_params, degraded = _resolve_search_session_filter(conn, filters)
+    if degraded:
+        base["filter_degraded"] = True
+
+    def _finish(out):
+        # Stamp the additive degraded flag onto whatever the search path returns,
+        # without disturbing the no-filter byte-stable shape.
+        if degraded:
+            out["filter_degraded"] = True
+        return out
+
     # Prose-only interim: the split columns are not yet indexed, so tools /
     # thinking can't match — short-circuit them to empty (spec §1 interim).
     if not q or (depth == "prose-only" and kind in ("tools", "thinking")):
         return base
+    if kind == "title":
+        if fts_available:
+            try:
+                out = _search_title(conn, q, limit, offset, True,
+                                    filt_sql, filt_params)
+                out.update(kind="title", search_depth=depth)
+                return _finish(out)
+            except sqlite3.OperationalError:
+                pass   # title FTS missing/corrupt at query time (the flag is
+                       # derived from fts5_unavailable, not a per-table probe) →
+                       # fall through to the title LIKE scan, mirroring the
+                       # message-FTS path's resilience
+        out = _search_title(conn, q, limit, offset, False,
+                            filt_sql, filt_params)
+        out.update(kind="title", search_depth=depth)
+        return _finish(out)
+    if kind == "files":
+        out = _search_files(conn, q, limit, offset, filt_sql, filt_params)
+        out.update(kind="files", search_depth=depth)
+        return _finish(out)
     if fts_available:
         try:
-            out = _search_fts(conn, q, limit, offset, kind, depth)
+            out = _search_fts(conn, q, limit, offset, kind, depth,
+                             filt_sql, filt_params)
             out.update(kind=kind, search_depth=depth)
-            return out
+            return _finish(out)
         except sqlite3.OperationalError:
             pass   # corrupt/missing FTS at query time → fall through to LIKE
-    out = _search_like(conn, q, limit, offset, kind, depth)
+    out = _search_like(conn, q, limit, offset, kind, depth, filt_sql, filt_params)
     out.update(kind=kind, mode="like", search_depth=depth)
-    return out
+    return _finish(out)
 
 
 def _row_to_hit(uuid_, sid, ts, cwd, snippet, msg_id, req_id, match_kinds=None):
@@ -1841,13 +2417,40 @@ def _attach_titles(conn, page):
     return page
 
 
-def _like_pattern(q):
-    """Build the LIKE pattern for `q`. Escape the ESCAPE char (\\) FIRST, then
+def _session_filter_pred(col, filt_sql):
+    """The session-scope filter fragment shared by the four ``_search_*``
+    subroutines (#219 S2.2): ``" AND <col> IN (<filt_sql>)"`` when a browse filter
+    is active, else ``""`` (the no-filter fast path). ``col`` is the caller's
+    table-qualified session_id column (``cm.session_id`` / ``t.session_id`` /
+    ``ft.session_id`` / bare ``session_id``)."""
+    return f" AND {col} IN ({filt_sql})" if filt_sql else ""
+
+
+def _attach_search_meta(conn, hits):
+    """The shared search-hit enrichment tail (#219 S2.2): per-turn cost then
+    per-session title/label. Every ``_search_*`` subroutine returns
+    ``_attach_titles(conn, _attach_costs(conn, hits))`` — centralized here so the
+    two-step order has one definition."""
+    return _attach_titles(conn, _attach_costs(conn, hits))
+
+
+def _like_escape(q):
+    """Escape the LIKE wildcards/escape-char in ``q`` (no surrounding ``%``),
+    paired with ``ESCAPE '\\'``. The ESCAPE char (``\\``) is escaped FIRST, then
     the wildcards — otherwise a query containing a backslash (incl. a trailing
-    one) mis-escapes the appended '%' and the LIKE silently matches nothing
-    (paired with ESCAPE '\\' in the queries below)."""
-    return ("%" + q.replace("\\", "\\\\").replace("%", r"\%").replace("_", r"\_")
-            + "%")
+    one) mis-escapes any appended ``%`` and the LIKE silently matches nothing.
+
+    Single source of the escape chain (#217 S2 / I-3 review Minor #3):
+    ``_like_pattern`` (substring) and ``_search_files``'s substring pattern both
+    build on this so the escaping is defined exactly once."""
+    return q.replace("\\", "\\\\").replace("%", r"\%").replace("_", r"\_")
+
+
+def _like_pattern(q):
+    """Build the SUBSTRING LIKE pattern for `q` — ``%`` + escaped(q) + ``%`` —
+    paired with ``ESCAPE '\\'`` in the queries below. The escape chain is
+    single-sourced in ``_like_escape``."""
+    return "%" + _like_escape(q) + "%"
 
 
 def _fts_snippets(conn, fts_q, ids, col=0):
@@ -1915,7 +2518,8 @@ def _match_kinds(conn, fts_q, rids_by_group):
             for grp, rids in rids_by_group.items()}
 
 
-def _search_fts(conn, q, limit, offset, kind, depth):
+def _search_fts(conn, q, limit, offset, kind, depth,
+                filt_sql="", filt_params=()):
     # All of dedup + paging + total live in SQL (#149) so Python never holds
     # more than one page of hits/snippets, regardless of corpus match count.
     #
@@ -1932,6 +2536,11 @@ def _search_fts(conn, q, limit, offset, kind, depth):
     entry_type = _KIND_ENTRY_TYPE.get(kind)
     et_pred = " AND cm.entry_type = ?" if entry_type is not None else ""
     et_args = (entry_type,) if entry_type is not None else ()
+    # #217 S2 / Filtered-search: session-scope restriction (empty when no filter,
+    # so the no-filter path stays byte-stable). cm.session_id is the FTS join's
+    # message column.
+    fpred = _session_filter_pred("cm.session_id", filt_sql)
+    fargs = tuple(filt_params)
     # Exact post-dedup logical total — counted in C with no snippet generation
     # and no Python row materialization.
     total = conn.execute(
@@ -1939,8 +2548,8 @@ def _search_fts(conn, q, limit, offset, kind, depth):
         "  SELECT DISTINCT cm.session_id, cm.uuid "
         "  FROM conversation_fts "
         "  JOIN conversation_messages cm ON cm.id = conversation_fts.rowid "
-        f"  WHERE conversation_fts MATCH ?{et_pred})",
-        (match_expr, *et_args),
+        f"  WHERE conversation_fts MATCH ?{et_pred}{fpred})",
+        (match_expr, *et_args, *fargs),
     ).fetchone()[0]
     # One row per logical (session_id, uuid): ROW_NUMBER()=1 keeps the SAME row
     # the old Python dedup kept as its FIRST occurrence (order: bm25, ts DESC,
@@ -1964,7 +2573,7 @@ def _search_fts(conn, q, limit, offset, kind, depth):
         f"         {bm25_expr} AS rank "
         "  FROM conversation_fts "
         "  JOIN conversation_messages cm ON cm.id = conversation_fts.rowid "
-        f"  WHERE conversation_fts MATCH ?{et_pred}), "
+        f"  WHERE conversation_fts MATCH ?{et_pred}{fpred}), "
         "ranked AS ("
         "  SELECT *, ROW_NUMBER() OVER ("
         "             PARTITION BY sid, uuid ORDER BY rank, ts DESC, rid DESC"
@@ -1972,14 +2581,14 @@ def _search_fts(conn, q, limit, offset, kind, depth):
         "  FROM matched) "
         "SELECT rid, sid, uuid, ts, cwd, mid, rqd FROM ranked WHERE rn = 1 "
         "ORDER BY rank, ts DESC, rid DESC LIMIT ? OFFSET ?",
-        (match_expr, *et_args, limit, offset),
+        (match_expr, *et_args, *fargs, limit, offset),
     ).fetchall()
     page_groups = {(sid, uuid): rid for (rid, sid, uuid, ts, cwd, mid, rqd) in page}
     if legacy:
         badges = {grp: [] for grp in page_groups}
     else:
         rids_by_group = _all_matched_rids_by_group(
-            conn, match_expr, et_pred, et_args, list(page_groups))
+            conn, et_pred, et_args, list(page_groups))
         badges = _match_kinds(conn, fts_q, rids_by_group)
     snips = _fts_snippets(conn, match_expr, [r[0] for r in page], col=0)
     # For hits badged tool/thinking but with no prose match, draw the snippet
@@ -1990,48 +2599,86 @@ def _search_fts(conn, q, limit, offset, kind, depth):
                         match_kinds=badges.get((sid, uuid), []))
             for (rid, sid, uuid, ts, cwd, mid, rqd) in page]
     return {"query": q, "mode": "fts",
-            "hits": _attach_titles(conn, _attach_costs(conn, hits)),
+            "hits": _attach_search_meta(conn, hits),
             "total": total}
 
 
-def _all_matched_rids_by_group(conn, match_expr, et_pred, et_args, groups):
-    """{(sid, uuid) -> [rids]} for the page groups: ALL matched physical rows of
-    each group (not just the rank-survivor), so badges aggregate completely."""
+def _all_matched_rids_by_group(conn, et_pred, et_args, groups):
+    """{(sid, uuid) -> [rids]} for the page groups: ALL physical rows of each
+    page group (a SUPERSET of the FTS-matched subset), so badges aggregate
+    completely. ``_match_kinds`` re-runs a per-column MATCH restricted to these
+    rids, so returning every physical row of the ≤200 page groups stays correct
+    for the column facets (the per-column MATCH filters).
+
+    U3 (#217 S1): a BOUNDED base-table lookup of the page groups' rows — NOT a
+    third full-corpus ``conversation_fts MATCH``. We stop scanning the corpus a
+    third time per request. The term expression is carried by the per-column
+    MATCH in ``_match_kinds``, so this lookup needs no match expression — the
+    formerly-vestigial ``match_expr`` param was dropped (#218 I-A.2).
+
+    Facet-scope fix (Codex P2): carry the SAME ``et_pred``/``et_args`` the page
+    query used (``kind=prompts``/``assistant`` filter ``cm.entry_type``), so a
+    same-group physical row OUTSIDE the facet can never contribute a badge. The
+    ``(session_id, uuid)`` match is NULL-safe (``IS``), since a pre-006 row may
+    carry a NULL uuid that a plain ``IN`` row-value would silently drop."""
     if not groups:
         return {}
     rids_by_group = {g: [] for g in groups}
-    rows = conn.execute(
-        "SELECT cm.id, cm.session_id, cm.uuid FROM conversation_fts "
-        "JOIN conversation_messages cm ON cm.id = conversation_fts.rowid "
-        f"WHERE conversation_fts MATCH ?{et_pred}",
-        (match_expr, *et_args),
-    ).fetchall()
-    for rid, sid, uuid in rows:
-        g = (sid, uuid)
-        if g in rids_by_group:
-            rids_by_group[g].append(rid)
+    # Chunk the OR-of-pairs to stay well under SQLite's variable limit (≤200
+    # page groups, 2 params each → one or two chunks in practice).
+    for i in range(0, len(groups), 300):
+        chunk = groups[i:i + 300]
+        cond = " OR ".join(
+            "(cm.session_id IS ? AND cm.uuid IS ?)" for _ in chunk)
+        params = [v for g in chunk for v in g]
+        rows = conn.execute(
+            "SELECT cm.id, cm.session_id, cm.uuid FROM conversation_messages cm "
+            f"WHERE ({cond}){et_pred}",
+            (*params, *et_args),
+        ).fetchall()
+        for rid, sid, uuid in rows:
+            g = (sid, uuid)
+            if g in rids_by_group:
+                rids_by_group[g].append(rid)
     return rids_by_group
 
 
 def _prefer_snippet_columns(conn, fts_q, page, page_groups, badges, snips):
     """Replace a hit's prose snippet with its matched column's snippet when the
-    prose column did NOT match (prose → tool → thinking preference). Probes
-    which column matched the survivor rowid, then re-snippets that column."""
+    prose column did NOT match (prose → tool → thinking preference). Probes which
+    of the badged survivors match prose, then re-snippets the non-prose ones from
+    their preferred column.
+
+    U3 (#217 S1): the per-hit ``rowid = ?`` prose probe (one query per badged
+    page hit, up to ~200 at limit=200) is collapsed into ONE bounded
+    ``rowid IN (…) AND MATCH text:(…)`` returning the prose-matching set;
+    subtracting gives the non-prose survivors routed to the already-batched
+    tool/thinking snippet calls."""
+    # The badged survivors are the only candidates (a hit with no badges keeps
+    # its col-0 prose snippet). Collect their survivor rowids.
+    badged = [(rid, sid, uuid)
+              for (rid, sid, uuid, ts, cwd, mid, rqd) in page
+              if badges.get((sid, uuid))]
+    if not badged:
+        return snips
+    badged_rids = [rid for (rid, _s, _u) in badged]
+    # ONE bounded probe: which badged survivors ALSO match prose? Keep their
+    # col-0 snippet; the rest fall through to their preferred column.
+    prose_hits = set()
+    for i in range(0, len(badged_rids), 300):
+        chunk = badged_rids[i:i + 300]
+        ph = ",".join("?" for _ in chunk)
+        rows = conn.execute(
+            "SELECT conversation_fts.rowid FROM conversation_fts "
+            f"WHERE conversation_fts MATCH ? AND conversation_fts.rowid IN ({ph})",
+            (f"{{text}}: ({fts_q})", *chunk)).fetchall()
+        prose_hits.update(r[0] for r in rows)
     by_col = {}   # snippet column index -> [rids needing it]
-    for (rid, sid, uuid, ts, cwd, mid, rqd) in page:
-        grp = (sid, uuid)
-        kinds = badges.get(grp, [])
-        if not kinds:
-            continue   # prose hit (or unbadged) — keep col-0 snippet
-        # Does THIS survivor row match prose? If so keep col 0.
-        prose_hit = conn.execute(
-            "SELECT 1 FROM conversation_fts "
-            "WHERE conversation_fts MATCH ? AND conversation_fts.rowid = ?",
-            (f"{{text}}: ({fts_q})", rid)).fetchone()
-        if prose_hit:
-            continue
+    for (rid, sid, uuid) in badged:
+        if rid in prose_hits:
+            continue   # prose matched the survivor → keep col 0
         for label, col in _SNIPPET_COL_PREFERENCE:
-            if label in kinds:
+            if label in badges.get((sid, uuid), []):
                 by_col.setdefault(col, []).append(rid)
                 break
     for col, rids in by_col.items():
@@ -2042,7 +2689,8 @@ def _prefer_snippet_columns(conn, fts_q, page, page_groups, badges, snips):
     return snips
 
 
-def _search_like(conn, q, limit, offset, kind, depth):
+def _search_like(conn, q, limit, offset, kind, depth,
+                 filt_sql="", filt_params=()):
     # SQL-bounded mirror of _search_fts for the no-FTS5 fallback (#149); the
     # COUNT + page each scan the table once (the degraded path already lacks an
     # index for the substring match). #177 S6: kind → column list (single-
@@ -2062,11 +2710,14 @@ def _search_like(conn, q, limit, offset, kind, depth):
     entry_type = _KIND_ENTRY_TYPE.get(kind)
     et_pred = " AND entry_type = ?" if entry_type is not None else ""
     et_args = (entry_type,) if entry_type is not None else ()
+    # #217 S2 / Filtered-search: session-scope restriction (empty when no filter).
+    fpred = _session_filter_pred("session_id", filt_sql)
+    fargs = tuple(filt_params)
     total = conn.execute(
         "SELECT COUNT(*) FROM ("
         "  SELECT DISTINCT session_id, uuid FROM conversation_messages "
-        f"  WHERE {col_pred}{et_pred})",
-        (*like_args, *et_args),
+        f"  WHERE {col_pred}{et_pred}{fpred})",
+        (*like_args, *et_args, *fargs),
     ).fetchone()[0]
     page = conn.execute(
         "WITH ranked AS ("
@@ -2077,10 +2728,10 @@ def _search_like(conn, q, limit, offset, kind, depth):
         "           ORDER BY timestamp_utc DESC, id DESC"
         "         ) AS rn "
         "  FROM conversation_messages "
-        f"  WHERE {col_pred}{et_pred}) "
+        f"  WHERE {col_pred}{et_pred}{fpred}) "
         "SELECT rid, sid, uuid, ts, cwd, mid, rqd FROM ranked WHERE rn = 1 "
         "ORDER BY ts DESC, rid DESC LIMIT ? OFFSET ?",
-        (*like_args, *et_args, limit, offset),
+        (*like_args, *et_args, *fargs, limit, offset),
     ).fetchall()
     texts = _texts_for_ids(conn, [r[0] for r in page])
     if legacy:
@@ -2093,7 +2744,158 @@ def _search_like(conn, q, limit, offset, kind, depth):
                         match_kinds=badges.get((sid, uuid), []))
             for (rid, sid, uuid, ts, cwd, mid, rqd) in page]
     return {"query": q, "mode": "like",
-            "hits": _attach_titles(conn, _attach_costs(conn, hits)),
+            "hits": _attach_search_meta(conn, hits),
+            "total": total}
+
+
+def _search_title(conn, q, limit, offset, fts_available, filt_sql="", filt_params=()):
+    """#217 S2 / E7: ``kind=title`` cross-session search over the per-session AI
+    title (conversation_ai_titles). Emits ONE SESSION-level hit per matching
+    session, anchored to that session's FIRST turn (the earliest
+    ``(timestamp_utc, id)`` conversation_messages row), ``match_kinds:["title"]``,
+    snippet = the matched title.
+
+    FTS5 available: ``MATCH ai_title`` over the external-content
+    ``conversation_title_fts``, mapping each hit rowid →
+    ``conversation_ai_titles.session_id``; the snippet comes from FTS ``snippet()``.
+    Else: a LIKE scan over ``conversation_ai_titles`` with the whole title as the
+    snippet (degraded; no marked span).
+
+    P2-9 (load-bearing): a session's title counts toward ``total`` and the page
+    ONLY when it has an anchorable first turn. Both the COUNT and the page JOIN
+    the SAME first-message anchor (``INNER JOIN`` against the per-session
+    first-turn CTE), so a title row whose session has no surviving message rows is
+    excluded from both — no lying count.
+
+    Filtered-search: the ``filt_sql`` session-scope restriction (over
+    conversation_ai_titles.session_id) applies the same as the message kinds.
+    """
+    fpred = _session_filter_pred("t.session_id", filt_sql)
+    fargs = tuple(filt_params)
+    # First-turn anchor per session: earliest (timestamp_utc, id) row. Rides
+    # idx_conv_session_ts. One row per session_id.
+    anchor_cte = (
+        "anchor AS ("
+        "  SELECT session_id, aid, auuid, ats, acwd, amid, arqd FROM ("
+        "    SELECT session_id, id AS aid, uuid AS auuid, timestamp_utc AS ats, "
+        "           cwd AS acwd, msg_id AS amid, req_id AS arqd, "
+        "           ROW_NUMBER() OVER (PARTITION BY session_id "
+        "                              ORDER BY timestamp_utc, id) AS rn "
+        "    FROM conversation_messages WHERE session_id IS NOT NULL"
+        "  ) WHERE rn = 1)")
+
+    if fts_available:
+        # matched titles: rowid → session_id + snippet, INNER-joined to the
+        # anchor so only anchorable sessions survive (P2-9).
+        fts_q = _fts_query(q, prefix_last=True)
+        total = conn.execute(
+            "WITH " + anchor_cte + " "
+            "SELECT COUNT(*) FROM conversation_title_fts f "
+            "JOIN conversation_ai_titles t ON t.rowid = f.rowid "
+            "JOIN anchor a ON a.session_id = t.session_id "
+            f"WHERE f.conversation_title_fts MATCH ?{fpred}",
+            (fts_q, *fargs)).fetchone()[0]
+        rows = conn.execute(
+            "WITH " + anchor_cte + " "
+            "SELECT t.session_id, a.auuid, a.ats, a.acwd, a.amid, a.arqd, "
+            "       snippet(conversation_title_fts, 0, '[', ']', ' … ', 12) AS snip "
+            "FROM conversation_title_fts f "
+            "JOIN conversation_ai_titles t ON t.rowid = f.rowid "
+            "JOIN anchor a ON a.session_id = t.session_id "
+            f"WHERE f.conversation_title_fts MATCH ?{fpred} "
+            "ORDER BY a.ats DESC, t.session_id DESC LIMIT ? OFFSET ?",
+            (fts_q, *fargs, limit, offset)).fetchall()
+        mode = "fts"
+    else:
+        like = _like_pattern(q)
+        total = conn.execute(
+            "WITH " + anchor_cte + " "
+            "SELECT COUNT(*) FROM conversation_ai_titles t "
+            "JOIN anchor a ON a.session_id = t.session_id "
+            f"WHERE t.ai_title LIKE ? ESCAPE '\\'{fpred}",
+            (like, *fargs)).fetchone()[0]
+        rows = conn.execute(
+            "WITH " + anchor_cte + " "
+            "SELECT t.session_id, a.auuid, a.ats, a.acwd, a.amid, a.arqd, "
+            "       t.ai_title AS snip "
+            "FROM conversation_ai_titles t "
+            "JOIN anchor a ON a.session_id = t.session_id "
+            f"WHERE t.ai_title LIKE ? ESCAPE '\\'{fpred} "
+            "ORDER BY a.ats DESC, t.session_id DESC LIMIT ? OFFSET ?",
+            (like, *fargs, limit, offset)).fetchall()
+        mode = "like"
+
+    hits = [_row_to_hit(auuid, sid, ats, acwd, snip, amid, arqd,
+                        match_kinds=["title"])
+            for (sid, auuid, ats, acwd, amid, arqd, snip) in rows]
+    return {"query": q, "mode": mode,
+            "hits": _attach_search_meta(conn, hits),
+            "total": total}
+
+
+def _search_files(conn, q, limit, offset, filt_sql="", filt_params=()):
+    """#217 S2 / I-3: ``kind=files`` cross-session search over the write-class
+    file-touch axis (``conversation_file_touches``). Emits one hit per DISTINCT
+    ``(session_id, file_path)``, anchored to that group's MOST-RECENT touch
+    (``MAX(message_id)`` → that message's ``(uuid, ts, cwd, msg_id, req_id)``),
+    ``match_kinds:["file"]``, snippet = the file path. ``total`` = the distinct
+    ``(session_id, file_path)`` count.
+
+    Match shape (#223): the query binds a SUBSTRING pattern (``%`` + escaped(q)
+    + ``%``) into ``file_path LIKE ? ESCAPE '\\'`` for EVERY query — a bare
+    basename, a mid-path fragment, or a leading-separator path all match. This
+    is a deliberate full SCAN over the modest ``conversation_file_touches``
+    table (a leading wildcard can never use ``idx_file_touches_path``),
+    consistent with how the content facets match; it replaces the former
+    prefix/separator special-case so a basename like ``package.json`` is
+    findable. ``LIKE`` stays case-insensitive (ASCII), matching the NOCASE path
+    index collation even though the index no longer drives a prefix probe.
+
+    Filtered-search: the ``filt_sql`` session-scope restriction is a post-match
+    ``ft.session_id IN (<subquery>)`` (the same as the message kinds) — there is NO
+    dedicated session index (the filter is a small IN over the already-narrowed
+    match set, so a ``session_id`` btree earned nothing; dropped per review Minor #2).
+    """
+    pat = _like_pattern(q)
+    fpred = _session_filter_pred("ft.session_id", filt_sql)
+    fargs = tuple(filt_params)
+
+    # The anchor per (session_id, file_path) group is its MAX(message_id). Compute
+    # the groups (filtered + matched), then join to conversation_messages on the
+    # anchor id for the turn's render/cost metadata.
+    #
+    # P2-9 (#219 S2.1): the COUNT INNER-JOINs the SAME anchor the page joins, so a
+    # group whose MAX(message_id) anchor is absent from conversation_messages is
+    # excluded from BOTH (never a lying count where total > page-reachable). Inert
+    # in a quiescent cache (touches are deleted with their message), but it keeps
+    # `total` provably equal to the page-reachable set — matching `_search_title`.
+    total = conn.execute(
+        "WITH g AS ("
+        "  SELECT ft.session_id AS sid, ft.file_path AS fp, "
+        "         MAX(ft.message_id) AS aid "
+        "  FROM conversation_file_touches ft "
+        f"  WHERE ft.file_path LIKE ? ESCAPE '\\'{fpred} "
+        "  GROUP BY ft.session_id, ft.file_path) "
+        "SELECT COUNT(*) FROM g JOIN conversation_messages cm ON cm.id = g.aid",
+        (pat, *fargs)).fetchone()[0]
+    rows = conn.execute(
+        "WITH g AS ("
+        "  SELECT ft.session_id AS sid, ft.file_path AS fp, "
+        "         MAX(ft.message_id) AS aid "
+        "  FROM conversation_file_touches ft "
+        f"  WHERE ft.file_path LIKE ? ESCAPE '\\'{fpred} "
+        "  GROUP BY ft.session_id, ft.file_path) "
+        "SELECT g.sid, g.fp, cm.uuid, cm.timestamp_utc, cm.cwd, "
+        "       cm.msg_id, cm.req_id "
+        "FROM g JOIN conversation_messages cm ON cm.id = g.aid "
+        "ORDER BY cm.timestamp_utc DESC, g.sid DESC, g.fp DESC "
+        "LIMIT ? OFFSET ?",
+        (pat, *fargs, limit, offset)).fetchall()
+
+    hits = [_row_to_hit(uuid_, sid, ts, cwd, fp, mid, rqd, match_kinds=["file"])
+            for (sid, fp, uuid_, ts, cwd, mid, rqd) in rows]
+    return {"query": q, "mode": "like",
+            "hits": _attach_search_meta(conn, hits),
             "total": total}
 
 
@@ -2118,9 +2920,19 @@ def _like_badges(conn, like, groups):
 
 # #177 S6: kind facets. `all` is the unfiltered MATCH; `prompts`/`assistant`
 # filter the prose column AND the entry_type; `tools`/`thinking` filter the
-# split index columns. Validated in search_conversations / find_in_conversation
-# (an unknown kind raises ValueError → the route maps it to a 400).
-_SEARCH_KINDS = ("all", "prompts", "assistant", "tools", "thinking")
+# split index columns. #217 S2 / E7: `title` is a CROSS-SESSION-SEARCH-ONLY kind
+# (external-content title FTS over conversation_ai_titles, session-level hits).
+# Validated in search_conversations (an unknown kind raises ValueError → the
+# route maps it to a 400).
+#
+# P1-1 (load-bearing kind-validation SPLIT): `_SEARCH_KINDS` (cross-session
+# search) carries `title` (and is ready for `files` in I-3); `_FIND_KINDS` (the
+# in-conversation /find route) does NOT — `find_in_conversation` indexes
+# `_FIND_KIND_COLUMNS[kind]`, which has no entry for `title`/`files`, so accepting
+# them there would KeyError → 500. Keeping the two enums distinct makes
+# `/find?kind=title` a clean 400, never a 500.
+_SEARCH_KINDS = ("all", "prompts", "assistant", "tools", "thinking", "title", "files")
+_FIND_KINDS = ("all", "prompts", "assistant", "tools", "thinking")
 _KIND_COLUMN = {"prompts": "text", "assistant": "text",
                 "tools": "search_tool", "thinking": "search_thinking"}
 _KIND_ENTRY_TYPE = {"prompts": "human", "assistant": "assistant"}
@@ -2156,6 +2968,14 @@ def _kind_match_expr(kind, fts_q):
 
 _FIND_ANCHOR_CAP = 500
 
+# #217 S4 / I-1.1: bound the regex/case Python-scan (Codex P2, ReDoS/perf).
+# An over-long pattern/query is rejected outright (empty result, no scan); each
+# scanned column value is also clipped before the predicate runs so a single
+# huge tool result can't pin a catastrophic-backtracking regex. Best-effort —
+# not a full ReDoS defense, but it bounds the worst case to a fixed budget.
+_FIND_REGEX_MAX_LEN = 1000
+_FIND_SCAN_TEXT_CAP = 200_000
+
 # Which physical-row columns the find match probes per kind, and the badge label
 # each non-prose column contributes. ``text`` maps to the synthetic ``prose``
 # label so a prose-only match still anchors a turn but never badges.
@@ -2170,7 +2990,8 @@ _FIND_KIND_COLUMNS = {
 
 
 def find_in_conversation(conn, session_id, query, *, kind="all",
-                         fts_available=None, cap=_FIND_ANCHOR_CAP):
+                         fts_available=None, cap=_FIND_ANCHOR_CAP,
+                         regex=False, case=False):
     """Document-ordered rendered-turn anchors for in-conversation find (#177 S6).
 
     Anchor identity is rendered-turn identity (spec F1): the FTS/LIKE match for
@@ -2183,8 +3004,29 @@ def find_in_conversation(conn, session_id, query, *, kind="all",
     rendered-turn anchors PRE-cap; the list caps at ``cap`` with
     ``anchors_truncated``. Returns None for an unknown session; an unknown
     ``kind`` raises ValueError (route → 400). Empty/whitespace query → empty;
-    prose-only depth + tools/thinking kinds → empty (the split index is pending)."""
-    if kind not in _SEARCH_KINDS:
+    prose-only depth + tools/thinking kinds → empty (the split index is pending).
+
+    P1-1: validates against ``_FIND_KINDS`` (NOT ``_SEARCH_KINDS``), so the
+    cross-session-only ``title``/``files`` kinds raise ValueError here (the route
+    → 400) rather than reaching ``_FIND_KIND_COLUMNS[kind]`` and KeyError → 500.
+
+    #217 S4 / I-1.1 — ``regex`` / ``case``: when either is set the FTS/LIKE fast
+    path is bypassed for a **physical-row Python scan** of ``conversation_messages``
+    (Codex P0 — *not* the rendered ``_assemble_session`` items, which drop the
+    ``search_tool``/``search_thinking`` corpus). The scan reuses the SAME column
+    derivation the FTS path matches on (``_find_kind_columns(kind, "full")`` +
+    ``_KIND_ENTRY_TYPE``) and produces the SAME ``{uuid -> labels}`` map, then
+    feeds the SAME assembly-to-anchor loop, so anchors / ordering / member_uuids /
+    match_kinds / the cap are byte-identical to the FTS path — only the matcher
+    differs. ``case`` only → case-sensitive substring (``mode == "like"``);
+    ``regex`` → per-row ``re.search`` compiled once (``re.IGNORECASE`` unless
+    ``case``; ``mode == "regex"``). Because the scan reads the full corpus
+    columns, ``search_depth == "full"`` — regex/case is NOT gated by the
+    prose-only split-index window. The scan is bounded by ``_FIND_REGEX_MAX_LEN``
+    (query/pattern length) and ``_FIND_SCAN_TEXT_CAP`` (per-row scanned text).
+    Default ``regex=False, case=False`` leaves every existing response
+    byte-stable (the ``_find_matched_rows`` path is untouched)."""
+    if kind not in _FIND_KINDS:
         raise ValueError(f"unknown kind: {kind}")
     # Cheap existence probe (one indexed SELECT) BEFORE the full assembly, so an
     # empty/prose-only-blocked query opening the find bar pays nothing — yet the
@@ -2198,17 +3040,55 @@ def find_in_conversation(conn, session_id, query, *, kind="all",
     if fts_available is None:
         fts_available = not _fts_flag_unavailable(conn)
     q = (query or "").strip()
+    # #217 S4 / I-1.1: a regex/case request scans the full corpus columns, so it
+    # reports search_depth "full" regardless of the prose-only split-index state,
+    # and is never blocked by it (the scan reads the base table, not the FTS).
+    scan = bool(regex or case)
+    eff_depth = "full" if scan else depth
     base = {"total": 0, "anchors": [], "anchors_truncated": False,
-            "search_depth": depth, "kind": kind,
-            "mode": "fts" if fts_available else "like"}
-    if not q or (depth == "prose-only" and kind in ("tools", "thinking")):
+            "search_depth": eff_depth, "kind": kind,
+            "mode": ("regex" if regex else "like") if scan
+                    else ("fts" if fts_available else "like")}
+    if not q:
         return base
+    if scan:
+        # Bound the scan (Codex P2): reject an over-long pattern/query outright
+        # rather than risk a catastrophic-backtracking regex over the corpus.
+        if len(q) > _FIND_REGEX_MAX_LEN:
+            return base
+        mode = "regex" if regex else "like"
+        matched = _find_matched_scan(conn, session_id, q, kind, regex, case)
+    else:
+        if depth == "prose-only" and kind in ("tools", "thinking"):
+            return base
+        # U2 (#217 S1): run the match probe BEFORE assembly so a non-empty query
+        # that matches ZERO rows in this session returns early — skipping the full
+        # `_assemble_session` walk a no-result find used to pay. The two functions
+        # are independent (neither consumes the other's output); a non-empty match
+        # still assembles, since the uuid → member_uuids anchor mapping needs the
+        # items. `mode` is taken from the match probe (it may fall through to LIKE
+        # on an FTS error) so the empty-match base carries the actually-used mode,
+        # not the `fts_available` default — byte-identical to the prior
+        # post-assembly answer.
+        mode, matched = _find_matched_rows(
+            conn, session_id, q, kind, depth, fts_available)
+    if not matched:
+        return {**base, "mode": mode}
     asm = _assemble_session(conn, session_id)
     if asm is None:
         return None
-    mode, matched = _find_matched_rows(
-        conn, session_id, q, kind, depth, fts_available)
-    # matched: {uuid -> set of labels in {"prose", "tool", "thinking"}}
+    anchors = _find_anchors_from_matched(asm, matched)
+    total = len(anchors)
+    return {**base, "mode": mode, "total": total,
+            "anchors": anchors[:cap], "anchors_truncated": total > cap}
+
+
+def _find_anchors_from_matched(asm, matched):
+    """Map the ``{uuid -> set(labels)}`` match map onto document-ordered
+    rendered-turn anchors (shared by the FTS/LIKE path and the regex/case scan,
+    so the two can never diverge on ordering / member folding / match_kinds).
+    ``matched`` labels are in ``{"prose", "tool", "thinking"}``; the synthetic
+    ``prose`` label anchors a turn but never badges."""
     anchors = []
     for it in asm["items"]:
         hit_kinds = set()
@@ -2222,9 +3102,51 @@ def find_in_conversation(conn, session_id, query, *, kind="all",
             anchors.append({
                 "uuid": it["anchor"]["uuid"],
                 "match_kinds": sorted(k for k in hit_kinds if k != "prose")})
-    total = len(anchors)
-    return {**base, "mode": mode, "total": total,
-            "anchors": anchors[:cap], "anchors_truncated": total > cap}
+    return anchors
+
+
+def _find_matched_scan(conn, session_id, q, kind, regex, case):
+    """({uuid -> {labels}}) for a regex/case PHYSICAL-ROW scan (Codex P0). Reads
+    the same corpus columns the FTS path matches on (``_find_kind_columns(kind,
+    "full")``) over the base ``conversation_messages`` rows — NOT the rendered
+    ``_assemble_session`` items, which drop the ``search_tool``/``search_thinking``
+    columns. Honors ``_KIND_ENTRY_TYPE`` exactly like ``_find_matched_like``.
+    Each scanned value is clipped to ``_FIND_SCAN_TEXT_CAP`` before the predicate
+    so one huge tool result can't pin the regex engine.
+
+    Precondition: ``regex or case``. ``find_in_conversation`` only enters the
+    physical-row scan when ``scan = bool(regex or case)`` (#217 S4 / I-1.1), so a
+    plain case-insensitive-substring scan is never requested here — the FTS/LIKE
+    path (``_find_matched_rows``) owns that case. The two regex/case predicates
+    below are therefore exhaustive; the assert documents (and enforces) that
+    rather than carrying an unreachable third branch."""
+    assert regex or case, "_find_matched_scan requires regex or case"
+    cols = _find_kind_columns(kind, "full")
+    if not cols:
+        return {}
+    et = _KIND_ENTRY_TYPE.get(kind)
+    et_pred = " AND entry_type = ?" if et is not None else ""
+    et_args = (et,) if et is not None else ()
+    if regex:
+        rx = re.compile(q, 0 if case else re.IGNORECASE)
+        pred = lambda text: rx.search(text) is not None
+    else:  # case-sensitive substring (case=True, regex=False)
+        pred = lambda text: q in text
+    out = {}
+    col_list = ", ".join(c for c, _ in cols)
+    rows = conn.execute(
+        f"SELECT uuid, {col_list} FROM conversation_messages "
+        f"WHERE session_id = ?{et_pred}",
+        (session_id, *et_args)).fetchall()
+    for row in rows:
+        u = row[0]
+        for idx, (_col, label) in enumerate(cols):
+            val = row[idx + 1]
+            if not val:
+                continue
+            if pred(val[:_FIND_SCAN_TEXT_CAP]):
+                out.setdefault(u, set()).add(label)
+    return out
 
 
 def _find_matched_rows(conn, session_id, q, kind, depth, fts_available):
@@ -2347,74 +3269,6 @@ def locate_tool_payload(conn, session_id, tool_use_id, which):
     return None
 
 
-def _clip_payload_input(inp, ceiling):
-    """Clip a structured input so the returned dict serializes to ``ceiling`` chars
-    or fewer, and report whether anything was clipped — the input-side analogue of
-    the result-side ceiling. A degenerate multi-MB input (one giant leaf OR many
-    sub-ceiling leaves that sum past the ceiling) is bounded so the HTTP server /
-    browser is protected, while every real payload returns whole.
-
-    The guarantee is AGGREGATE, not merely per-leaf: a shared remaining-char budget
-    is threaded through the walk (mirroring ``_bound_input``'s total-size backstop) —
-    each string leaf is clipped against the running budget and the budget is
-    decremented as we go, so once it is exhausted later leaves clip to ''.
-    ``truncated`` is True iff any leaf was clipped (or the post-walk serialized size
-    still exceeds ``ceiling``, the structural-overhead backstop). Post-condition:
-    ``len(json.dumps(clipped, ensure_ascii=False)) <= ceiling`` always."""
-    truncated = False
-    remaining = [ceiling]   # boxed so the nested walk can decrement it
-
-    def walk(v):
-        nonlocal truncated
-        if isinstance(v, str):
-            if len(v) > remaining[0]:
-                truncated = True
-                v = v[:remaining[0]]
-            remaining[0] -= len(v)
-            return v
-        if isinstance(v, dict):
-            return {k: walk(x) for k, x in v.items()}
-        if isinstance(v, list):
-            return [walk(x) for x in v]
-        return v
-
-    clipped = walk(inp)
-    # Backstop: structural JSON overhead (braces/quotes/keys) can push a
-    # budget-exact payload a few chars past the ceiling. Hard-clip the largest
-    # remaining string leaf(s) until the whole dict serializes within the ceiling.
-    while len(_json.dumps(clipped, ensure_ascii=False)) > ceiling:
-        truncated = True
-        if not _shrink_largest_leaf(clipped):
-            break   # no string leaf left to shrink (e.g. pure numeric/structural)
-    return clipped, truncated
-
-
-def _shrink_largest_leaf(obj):
-    """Halve the longest string leaf reachable in ``obj`` (a dict/list/scalar),
-    in place, and return True if one was shrunk — the post-walk backstop for the
-    rare structural-overhead overshoot. A leaf already at length 1 is truncated to
-    ''. Returns False when no non-empty string leaf exists."""
-    best = {"len": 0, "container": None, "key": None}
-
-    def scan(v, container, key):
-        if isinstance(v, str):
-            if len(v) > best["len"]:
-                best.update(len=len(v), container=container, key=key)
-        elif isinstance(v, dict):
-            for k, x in v.items():
-                scan(x, v, k)
-        elif isinstance(v, list):
-            for i, x in enumerate(v):
-                scan(x, v, i)
-
-    scan(obj, None, None)
-    if best["container"] is None or best["len"] == 0:
-        return False
-    s = best["container"][best["key"]]
-    best["container"][best["key"]] = s[: len(s) // 2]
-    return True
-
-
 def read_full_payload(source_path, byte_offset, tool_use_id, which):
     """Re-read the raw JSONL line at ``(source_path, byte_offset)`` and return the
     FULL (un-capped) payload for ``tool_use_id``:
@@ -2471,6 +3325,12 @@ def read_full_payload(source_path, byte_offset, tool_use_id, which):
             if (isinstance(tur, dict) and isinstance(tur.get("stderr"), str)
                     and tur.get("stderr")):
                 resp["stderr"] = tur["stderr"][:_FULL_PAYLOAD_CEILING]   # per-stream bound (see above)
+                # #217 S1 / U5 (data-contract honesty): `truncated` describes ONLY
+                # the `text` stream, but `stderr` is bounded INDEPENDENTLY against
+                # the same ceiling — so the client cannot tell from `truncated`
+                # alone whether stderr was clipped. Emit a dedicated per-stream
+                # flag whenever stderr is present (mirrors `stderr` itself).
+                resp["stderr_truncated"] = len(tur["stderr"]) > _FULL_PAYLOAD_CEILING
             return resp
     return None