cctally 1.88.2 → 1.89.1

package/bin/_lib_cache_report.py

@@ -119,6 +119,11 @@ CACHE_REPORT_MIN_BASELINE_SESSIONS = 10
 # dashboard/web/src/types/envelope.ts:71 — keeps the two surfaces in
 # lockstep so a typo on either side fails type-check.
 CacheAnomalyReason = Literal["net_negative", "cache_drop"]
+# Every predicate _classify_anomalies can run, in reason-append order. The
+# TypeScript mirror is CACHE_ANOMALY_PREDICATES in cacheReportVerdict.ts.
+CACHE_ANOMALY_PREDICATES: tuple[CacheAnomalyReason, ...] = (
+    "net_negative", "cache_drop",
+)
 
 
 @dataclass
@@ -185,6 +190,10 @@ class CacheRow:
     # Anomaly (populated by _classify_anomalies)
     anomaly_triggered: bool = False
     anomaly_reasons: list[CacheAnomalyReason] = field(default_factory=list)
+    # Predicates the classifier did NOT run for this row. Empty means every
+    # predicate was evaluated; a non-empty list is what lets the dashboard
+    # distinguish "evaluated, clean" from "never evaluated" (issue #443 F2).
+    anomaly_unevaluated: list[CacheAnomalyReason] = field(default_factory=list)
 
     @property
     def total_tokens(self) -> int:
@@ -767,6 +776,7 @@ def _classify_anomalies(
         for row in rows:
             row.anomaly_triggered = False
             row.anomaly_reasons = []
+            row.anomaly_unevaluated = list(CACHE_ANOMALY_PREDICATES)
         return
     if not rows:
         return
@@ -782,24 +792,31 @@ def _classify_anomalies(
 
     for i, row in enumerate(rows):
         reasons: list[CacheAnomalyReason] = []
+        unevaluated: list[CacheAnomalyReason] = []
 
         # Trigger 1: net_negative (no baseline needed; cache-activity guard).
         if row.cache_creation_tokens + row.cache_read_tokens > 0:
             if row.net_usd < 0:
                 reasons.append("net_negative")
+        else:
+            unevaluated.append("net_negative")
 
         # Trigger 2: cache_drop (requires baseline).
         anchor = anchors[i]
+        median = None
         if anchor is not None:
             median = _compute_baseline_median(
                 rows, anchor=anchor,
                 window_days=window_days, min_samples=min_baseline,
                 exclude_row=row, is_session_mode=is_session_mode,
             )
-            if median is not None and (median - row.cache_hit_percent) >= threshold_pp:
-                reasons.append("cache_drop")
+        if median is None:
+            unevaluated.append("cache_drop")
+        elif (median - row.cache_hit_percent) >= threshold_pp:
+            reasons.append("cache_drop")
 
         row.anomaly_reasons = reasons
+        row.anomaly_unevaluated = unevaluated
         row.anomaly_triggered = bool(reasons)
 
 

package/bin/_lib_codex_conversation.py

@@ -90,6 +90,14 @@ CODEX_CONVERSATION_REPLAY_FROM_ZERO_KEY = (
 # `CODEX_REPLAY_FROM_ZERO_KEY` — the replay is stalled, not merely pending, and
 # Codex transcript ingest is deferred behind it. Read by `doctor`.
 CODEX_REPLAY_BLOCKED_KEY = "codex_replay_from_zero_blocked"
+# Written when a BUDGETED tick declined the replay outright (public #5 §4). A
+# byte-zero replay is not sliceable, so the hook path never attempts one — but
+# that decline returns before the ingest-backlog record is written, so without
+# this key a hook-only install whose every Codex sync is frozen reads as a
+# drained store on `doctor`, in the lifecycle line and in the dashboard
+# envelope. `{since, at}`: `since` is when the freeze started and carries
+# forward across ticks, `at` is the most recent decline.
+CODEX_REPLAY_DEFERRED_KEY = "codex_replay_from_zero_deferred"
 
 # Structural wrapper prefixes skipped during title selection (§4.3), pinned from
 # the corpus (title-wrapper-window). Prefix-structural, never content heuristics.

package/bin/_lib_codex_conversation_query.py

@@ -1005,7 +1005,11 @@ def codex_conversation_source_paths(
 # ── detail assembly (§5.2 / §5.4 / §5.6) ──────────────────────────────────────
 
 
-def _paginate_items(items: list[dict], *, after, before, tail, limit):
+def _paginate_items(items: list[dict], *, after, before, tail: bool, limit: int):
+    # ``tail`` is the flag the HTTP layer parses out of ``?tail=1`` — which page
+    # of ``limit`` to cut, never how many items to return. Treating it as a count
+    # made ``min(True, limit)`` serve a one-item tail page, and ``tail=False``
+    # (the shape every non-tail request arrives in) skip ``limit`` altogether.
     keys = [it["item_key"] for it in items]
     aliases = {
         alias: index
@@ -1022,11 +1026,8 @@ def _paginate_items(items: list[dict], *, after, before, tail, limit):
     elif before is not None and before in aliases:
         hi = aliases[before]
     window = items[lo:hi]
-    if tail is not None:
-        cap = min(tail, limit) if limit else tail
-        window = window[-cap:] if cap else window
-    elif limit:
-        window = window[:limit]
+    if limit:
+        window = window[-limit:] if tail else window[:limit]
     first_key = window[0]["item_key"] if window else None
     last_key = window[-1]["item_key"] if window else None
     has_before = bool(window) and keys.index(first_key) > 0
@@ -1047,7 +1048,7 @@ def get_codex_conversation(
     effective_speed: str,
     after: str | None = None,
     before: str | None = None,
-    tail: int | None = None,
+    tail: bool = False,
     limit: int = 200,
     legacy_export: bool = False,
 ) -> dict:

package/bin/_lib_conversation.py

@@ -171,6 +171,7 @@ def _strip_remote_control_prefix(text):
 
 
 _TOOL_RESULT_CAP = 16000   # was 4000; full text always re-derivable from JSONL
+_BACKGROUND_NOTIFICATION_BLOCK_WIRE_CAP = 230_000
 _INPUT_LEAF_CAP = 8000     # max chars per string leaf in a bounded tool input
 _INPUT_TOTAL_CAP = 32000   # honesty backstop on the serialized bounded input
 _INPUT_MAX_NODES = 2000    # max dict-values + list-elements kept before tail elision
@@ -281,16 +282,31 @@ def _queued_prompt_row(obj, t, offset):
     ``{"type":"attachment","attachment":{"type":"queued_command",
     "commandMode":"prompt","prompt":<text>}}`` — carrying its OWN
     uuid/parentUuid/timestamp, with the text in ``attachment.prompt`` rather than
-    ``message.content``. Only ``commandMode=="prompt"`` is promoted: a queued
-    ``task-notification`` (``commandMode=="task-notification"``) is harness-injected
-    background plumbing — the same ``<task-notification>`` content already
-    classifies META when it arrives as a regular line — not something the user
-    typed, so it stays dropped."""
+    ``message.content``.
+
+    ``commandMode=="task-notification"`` is harness-injected background plumbing
+    rather than something the user typed, so it is NOT promoted as a HUMAN turn —
+    but it is no longer dropped either. This used to be justified by "the same
+    <task-notification> content already classifies META when it arrives as a
+    regular line", which is true for ONE notification shape and false for the
+    other, and the distinction is a whole bug class:
+
+      A  subagent / Monitor   arrives as a type:"user" line, joins on
+                              <tool-use-id> -> already classified META
+      B  backgrounded MCP     arrives ONLY as this attachment, carries
+                              <task-id> and NO <tool-use-id> -> nothing
+                              rescued it, so the response was lost
+
+    Claude Code moved MCP dispatch to the background after 120s, which made
+    shape B common; before that the assumption held in practice. Shape B is now
+    promoted as a BOUNDED META row (see ``_background_notification_row``)."""
     if t != "attachment" or not obj.get("uuid"):
         return None
     att = obj.get("attachment")
     if not isinstance(att, dict) or att.get("type") != "queued_command":
         return None
+    if att.get("commandMode") == "task-notification":
+        return _background_notification_row(obj, att.get("prompt"), offset)
     if att.get("commandMode") != "prompt":
         return None
     prompt = att.get("prompt")
@@ -308,6 +324,79 @@ def _queued_prompt_row(obj, t, offset):
     return _normalize(synth, "user", offset)
 
 
+def _background_notification_row(obj, prompt, offset):
+    """A backgrounded-MCP <task-notification> -> a BOUNDED META ``MessageRow``.
+
+    The raw wrapper is deliberately NOT stored verbatim. Text blocks are not
+    subject to ``_TOOL_RESULT_CAP`` and read-time meta classification restores
+    the whole body, so a verbatim store would put an arbitrary (multi-megabyte)
+    MCP payload into the transcript store and ship it whole to the browser
+    whenever the read-time join misses. Instead the notification is parsed HERE
+    into one bounded text block carrying the identity/status sidecars the
+    read-time join and the full-payload resolver consume.
+
+    ``text`` = a synthesized header plus the capped result, so a notification
+    whose join does NOT fire still renders something sane through the ordinary
+    text path. ``result_offset`` is the EXACT index where the capped result
+    begins inside ``text`` (``None`` when there is no result), so the join can
+    strip the header without re-deriving it — the card must receive the bare
+    ``{"threadId":…,"content":…}`` envelope its parser decodes, and a summary
+    containing a blank line would defeat a scan-based strip.
+
+    Classified META with ``text=""`` — like the shape-A notification already is
+    — which keeps it out of prose FTS, title derivation and the ``human``
+    prompts facet. The capped result still reaches ``search_tool``, so a
+    recovered response stays findable through dashboard search, in-conversation
+    find and ``transcript search``, exactly as the same result delivered inline
+    would be."""
+    import _lib_background_mcp as _bg
+    if not isinstance(prompt, str) or not prompt.strip():
+        return None
+    n = _bg.parse_task_notification(prompt)
+    if n is None:
+        return None            # no <task-id> -> no identity -> nothing to join
+    full = n.result_text or ""
+    capped = full[:_TOOL_RESULT_CAP]
+    header = f"Background task {n.task_id} — {n.status or 'unknown'}"
+    if n.summary:
+        header += f"\n{n.summary}"
+    block = {
+        "kind": "text",
+        "text": header + (("\n\n" + capped) if capped else ""),
+        "task_id": n.task_id,
+        "background_status": n.status,
+        "summary": n.summary,
+        "result_offset": (len(header) + 2) if capped else None,
+        "result_full_length": len(full),
+        "result_truncated": len(full) > _TOOL_RESULT_CAP,
+    }
+    blocks = [block]
+    blocks_json = json.dumps(blocks, separators=(",", ":"))
+    if len(blocks_json) > _BACKGROUND_NOTIFICATION_BLOCK_WIRE_CAP:
+        # All copied fields are capped by the background-MCP kernel. Keep a
+        # fail-closed storage backstop so a future field cannot silently make
+        # this supposedly bounded row unbounded.
+        return None
+    # Derive through the SAME chokepoint a blocks_json backfill would use, so
+    # ingest and any recompute-from-blocks pass agree by construction (#177 S6).
+    search_tool, search_thinking = _derive_search_columns(blocks)
+    return MessageRow(
+        byte_offset=offset,
+        session_id=obj.get("sessionId"),
+        uuid=obj.get("uuid"),
+        parent_uuid=obj.get("parentUuid"),
+        timestamp_utc=obj.get("timestamp"),
+        entry_type=META,
+        text="",
+        blocks_json=blocks_json,
+        model=None, msg_id=None, req_id=None,
+        cwd=obj.get("cwd"), git_branch=obj.get("gitBranch"),
+        is_sidechain=1 if obj.get("isSidechain") else 0,
+        search_tool=search_tool,
+        search_thinking=search_thinking,
+    )
+
+
 @dataclass
 class AiTitleRow:
     """Pure per-line AI-title record (no I/O). Parallels MessageRow but for the
@@ -1194,6 +1283,17 @@ def _derive_search_columns(blocks):
             t = b.get("text") or ""
             if t:
                 think_parts.append(t[:_TOOL_RESULT_CAP])
+        elif k == "text" and b.get("task_id") and b.get("result_offset") is not None:
+            # A recovered backgrounded-MCP result. It is TOOL output that merely
+            # rides in a text block (the block shape a renderer without the join
+            # can still display), so it belongs in search_tool — the identical
+            # result delivered inline is searchable and this must not regress to
+            # silently unsearchable. Gated on the task_id + result_offset pair so
+            # an ordinary prose text block is never indexed here (prose already
+            # lives in the `text` column).
+            res = (b.get("text") or "")[b["result_offset"]:]
+            if res:
+                tool_parts.append(res[:_TOOL_RESULT_CAP])
         elif k == "tool_use":
             tool_parts.extend(
                 s[:_TOOL_RESULT_CAP] for s in _aux_strings(b.get("input")))

package/bin/_lib_conversation_dispatch.py

@@ -545,7 +545,7 @@ def neutral_detail(
     if cref.source == "codex":
         return q.get_codex_conversation(
             conn, cref.conversation_key, effective_speed=speed,
-            after=after, before=before, tail=tail,
+            after=after, before=before, tail=bool(tail),
             limit=limit if limit is not None else 200)
     return _claude_detail(
         conn, cref.native_key, cref.conversation_key,
@@ -799,11 +799,22 @@ def neutral_payload(
     # Claude: tool_use_id + which={input,result}, contract unchanged.
     if not tool_use_id or which not in ("input", "result"):
         return {"status": "not_found", "tool_use_id": tool_use_id, "which": which}
-    loc = lcq.locate_tool_payload(conn, cref.native_key, tool_use_id, which)
+    if which == "result":
+        # Both payload routes address the SAME logical object, so both resolve it
+        # through the same carrier. A naive which="result" lookup finds the
+        # backgrounded-MCP PLACEHOLDER row first and would serve "still running
+        # after 120s" as the full response — 200, and silently wrong content.
+        mode, loc = lcq.locate_result_payload(conn, cref.native_key, tool_use_id)
+        if mode == "background_gone":
+            # A KNOWN background placeholder whose notification is unresolvable:
+            # gone (410), never not_found (404) and never the placeholder text.
+            return {"status": "gone", "tool_use_id": tool_use_id, "which": which}
+    else:
+        mode = which
+        loc = lcq.locate_tool_payload(conn, cref.native_key, tool_use_id, which)
     if loc is None:
         return {"status": "not_found", "tool_use_id": tool_use_id, "which": which}
-    source_path, byte_offset = loc
-    payload = lcq.read_full_payload(source_path, byte_offset, tool_use_id, which)
+    payload = lcq.read_located_payload(loc, tool_use_id, mode)
     if payload is None:
         return {"status": "gone", "tool_use_id": tool_use_id, "which": which}
     return {"status": "ok", **payload}

package/bin/_lib_conversation_query.py

@@ -54,6 +54,11 @@ from _lib_conversation import (
     _is_compaction_body, _is_notification_body, _is_bash_echo_body,
     _strip_remote_control_prefix,
 )
+# Backgrounded-MCP recovery (spec 2026-07-31): the placeholder/notification
+# parsers AND the fail-closed selection rule. The finalize-stage join and
+# locate_tool_payload's background_result mode both call select_background_joins
+# so a card can never display one capped response and load a different full one.
+import _lib_background_mcp as _bg
 
 # ── Opt-in phase instrumentation (issue #276, Session C / M5) ────────────────
 # This kernel is imported DIRECTLY by several tests (tests/test_conversation_*),
@@ -1685,6 +1690,7 @@ def _assemble_session(conn, session_id):
     turn_index = {}                # (msg_id, req_id) -> index into items
     tooluse_index = {}             # tool_use id -> (item, block_dict)
     tool_result_items = []         # placeholder items deferred to Phase 2
+    _bg_placeholder_claims_all = []  # canonical pre-fold claimant pairs
 
     def _index_tool_uses(item):
         # Index every tool_use id -> its (item, block). Idempotent: re-scanning
@@ -1714,6 +1720,8 @@ def _assemble_session(conn, session_id):
             it = _build_simple(row)
             items.append(it)
             tool_result_items.append(it)
+            _bg_placeholder_claims_all.extend(
+                _bg_placeholder_claims(it["blocks"]))
         else:
             it = _build_simple(row)
             items.append(it)
@@ -2051,6 +2059,87 @@ def _assemble_session(conn, session_id):
         if _link is not None and _link[0] in subagent_meta:
             subagent_meta[_link[0]]["status"] = _status   # upgrades async_launched -> completed
 
+    # Backgrounded-MCP completion (spec 2026-07-31 §2). The sibling join above
+    # handles shape A — a subagent/Monitor notification carrying <tool-use-id>.
+    # Shape B (an MCP call Claude Code moved to the background after 120s)
+    # carries <task-id> and NO <tool-use-id>, so the bridge is the PLACEHOLDER
+    # tool_result, which names the task twice in two independently worded
+    # places. Runs here, on the UNSLICED item list, so a match can never depend
+    # on page boundaries (get_conversation slices downstream).
+    # Read the canonical PRE-FOLD claims. Phase 2 can fold more than one physical
+    # result into one tool call, and the visible result slot necessarily keeps
+    # only one; collecting there would already have lost conflicting claimants.
+    # The payload resolver independently reconstructs this same canonical-row
+    # population, so capped display and full lookup feed identical claims into
+    # the pure fail-closed selector. Collection rides the existing Phase-1
+    # parse; this finalize stage never reparses the session.
+    _ph_claims = _bg_placeholder_claims_all
+
+    _notifs = []                  # BackgroundNotification, document order
+    _notif_src = {}               # id(notification) -> (item, block)
+    _notif_by_task = {}           # task_id -> [block, …] (status stamping only)
+    for it in items:
+        if it["kind"] != "meta":
+            continue
+        for b in it["blocks"]:
+            # Shared extraction (exact header strip included) so the read-time
+            # join and the full-payload resolver can never diverge.
+            _n = _eligible_bg_notification(it["kind"], it.get("ts"), b)
+            if _n is None:
+                continue
+            _notifs.append(_n)
+            _notif_src[id(_n)] = (it, b)
+            _notif_by_task.setdefault(_n.task_id, []).append(b)
+
+    _joined = _bg.select_background_joins(_ph_claims, _notifs)
+    _bg_drop = set()
+    for _tuid, _n in _joined.items():
+        _hit = tooluse_index.get(_tuid)
+        if _hit is None:
+            continue
+        _owner, _block = _hit
+        _src_item, _src_block = _notif_src[id(_n)]
+        _block["result"] = {
+            "text": _n.result_text,
+            "truncated": bool(_src_block.get("result_truncated")),
+            "full_length": _src_block.get("result_full_length"),
+            "is_error": False,
+        }
+        _block["background_status"] = "completed"
+        _block["background_completed_at"] = _src_item.get("ts")
+        # The Phase-4b fold precedent: the folded row's uuid joins the owner's
+        # member_uuids so jump/permalink ownership, outline mapping and
+        # sidechain-parent lookup all keep resolving.
+        _owner["member_uuids"].append(_src_item["anchor"]["uuid"])
+        _bg_drop.add(id(_src_item))
+    if _bg_drop:
+        items = [it for it in items if id(it) not in _bg_drop]
+
+    # Stamp the status on every call we did NOT recover, so the client renders an
+    # in-flight state rather than a false "ok" (CodexCard reports '✓ ok' for any
+    # non-null non-error result). These notifications stay VISIBLE — a
+    # non-completed one is the only remaining evidence of what happened.
+    _unambiguous_tasks = _bg.unambiguous_placeholder_tasks(_ph_claims)
+    for _tuid in dict.fromkeys(tuid for tuid, _task in _ph_claims):
+        if _tuid in _joined:
+            continue
+        _hit = tooluse_index.get(_tuid)
+        if _hit is None:
+            continue
+        _task = _unambiguous_tasks.get(_tuid)
+        if _task is None:
+            # Conflicting task claims cannot choose a notification or status,
+            # but this is still visibly a background placeholder. Keep the
+            # client in its honest pending state instead of falling through to
+            # the generic non-error "ok" rendering.
+            _hit[1]["background_status"] = "running"
+            continue
+        _cands = _notif_by_task.get(_task) or []
+        _statuses = {c.get("background_status") for c in _cands
+                     if c.get("background_status")}
+        _hit[1]["background_status"] = (
+            _statuses.pop() if len(_statuses) == 1 else "running")
+
     # Derived totals: any child still missing a count gets it from its own
     # subagent_key bucket. tool-count = tool_call/tool_use blocks; duration =
     # (max_ts - min_ts) ms; tokens = sum of per-turn token totals (now stamped).
@@ -3922,11 +4011,170 @@ def _manual_snippet(text, q, width=80):
 _FULL_PAYLOAD_CEILING = 1_000_000   # serve up to ~1 MB; protects the HTTP server / browser
 
 
+def _bg_notification_from_block(b):
+    """``BackgroundNotification`` for a stored background-notification block,
+    else ``None``.
+
+    ONE extraction, shared by the finalize-stage join and the full-payload
+    resolver — including the exact header strip: the stored text is
+    ``header\\n\\nresult`` and ``result_offset`` is where the result begins, so
+    the card always receives the bare ``{"threadId":…,"content":…}`` envelope its
+    parser decodes."""
+    if not isinstance(b, dict):
+        return None
+    task = b.get("task_id")
+    if not task:
+        return None
+    off = b.get("result_offset")
+    res = (b.get("text") or "")[off:] if isinstance(off, int) else None
+    return _bg.BackgroundNotification(
+        task, b.get("background_status") or "", b.get("summary") or "",
+        res or None)
+
+
+def _bg_placeholder_claims(blocks):
+    """Every background placeholder claim in one canonical stored row."""
+    out = []
+    if not isinstance(blocks, list):
+        return out
+    for block in blocks:
+        if not isinstance(block, dict) or block.get("kind") != "tool_result":
+            continue
+        task_id = _bg.parse_placeholder_task_id(block.get("text") or "")
+        tool_use_id = block.get("tool_use_id")
+        if task_id and tool_use_id is not None:
+            out.append((tool_use_id, task_id))
+    return out
+
+
+def _eligible_bg_notification(item_kind, timestamp, block):
+    """Assembly/payload shared eligibility for a stored notification row."""
+    if item_kind != "meta" or not isinstance(timestamp, str) or not timestamp:
+        return None
+    return _bg_notification_from_block(block)
+
+
+# Cheap SQL prefilters for the two block shapes the background scan cares about.
+# Both are literal substrings of what must be present, so they can only
+# over-select — a false negative would break the fail-closed guarantee by hiding
+# a second claimant of the same task id.
+_BG_PLACEHOLDER_PROBE = "is still running after "
+_BG_TASK_ID_PROBE = '"task_id":'
+
+
+def _scan_background_session(conn, session_id):
+    """``(placeholders, notifications, {id(notification): (source_path, offset)})``
+    over one session's LOGICAL messages.
+
+    Reproduces ``_assemble_session``'s view rather than approximating it: the
+    physical rows are deduped by uuid keeping the earliest ``(timestamp_utc,
+    id)``, exactly as assembly does, so the full-payload path and the rendered
+    card can never disagree about which notification won. The canonical-row
+    decision is made over the WHOLE session (an id/uuid-only read) before the
+    content prefilter is applied — deciding it inside the prefiltered set would
+    let a later physical row become canonical for a uuid whose earliest row
+    assembly actually chose."""
+    canonical = {}
+    for rid, uuid in conn.execute(
+        "SELECT id, uuid FROM conversation_messages WHERE session_id=? "
+        "ORDER BY timestamp_utc, id", (session_id,)
+    ):
+        if uuid not in canonical:
+            canonical[uuid] = rid
+    keep = set(canonical.values())
+
+    placeholders, notifications, loc_by_notif = [], [], {}
+    for rid, source_path, byte_offset, entry_type, timestamp, blocks_json in conn.execute(
+        "SELECT id, source_path, byte_offset, entry_type, timestamp_utc, blocks_json "
+        "FROM conversation_messages WHERE session_id=? "
+        "AND (instr(blocks_json, ?) > 0 OR instr(blocks_json, ?) > 0) "
+        "ORDER BY timestamp_utc, id",
+        (session_id, _BG_PLACEHOLDER_PROBE, _BG_TASK_ID_PROBE)
+    ):
+        if rid not in keep:
+            continue
+        try:
+            blocks = _json.loads(blocks_json)
+        except (ValueError, TypeError):
+            continue
+        if not isinstance(blocks, list):
+            continue
+        placeholders.extend(_bg_placeholder_claims(blocks))
+        for b in blocks:
+            if not isinstance(b, dict):
+                continue
+            if b.get("kind") == "tool_result":
+                continue
+            n = _eligible_bg_notification(entry_type, timestamp, b)
+            if n is not None:
+                notifications.append(n)
+                loc_by_notif[id(n)] = (source_path, byte_offset)
+    return placeholders, notifications, loc_by_notif
+
+
+def locate_result_payload(conn, session_id, tool_use_id):
+    """``(mode, location)`` for a PUBLIC ``which='result'`` request.
+
+    ``mode`` is one of:
+
+    - ``'result'`` — an ordinary tool_result; ``location`` is
+      ``locate_tool_payload(..., 'result')`` (``None`` for an unknown id -> 404).
+    - ``'background_result'`` — the id is a backgrounded-MCP placeholder whose
+      completion notification resolves unambiguously; ``location`` is a THREE
+      -tuple ``(source_path, byte_offset, task_id)`` addressing the
+      NOTIFICATION's JSONL line. The task id rides along because the re-read at
+      that offset must prove it landed on THIS task's notification.
+    - ``'background_gone'`` — a KNOWN background placeholder whose notification
+      cannot be resolved (deleted, rotated, still running, or ambiguous). The
+      handler maps this to 410, distinct from the 404 an unknown id returns.
+
+    ``background_result`` is INTERNAL: the response ``read_full_payload`` builds
+    keeps the public ``which: "result"`` discriminant, so neither the client
+    contract nor the endpoint's accepted input surface changes."""
+    has_background_placeholder = conn.execute(
+        "SELECT 1 FROM conversation_messages WHERE session_id=? "
+        "AND instr(blocks_json, ?) > 0 LIMIT 1",
+        (session_id, _BG_PLACEHOLDER_PROBE),
+    ).fetchone()
+    if has_background_placeholder is None:
+        return ("result", locate_tool_payload(conn, session_id, tool_use_id,
+                                              "result"))
+    placeholders, notifications, loc_by_notif = _scan_background_session(
+        conn, session_id)
+    if not any(tuid == tool_use_id for tuid, _task_id in placeholders):
+        return ("result", locate_tool_payload(conn, session_id, tool_use_id,
+                                              "result"))
+    # The SAME fail-closed rule assembly applied — called, never re-derived — so
+    # a card showing the placeholder can't load somebody else's full response.
+    n = _bg.select_background_joins(placeholders, notifications).get(tool_use_id)
+    if n is None:
+        return ("background_gone", None)
+    return ("background_result", loc_by_notif[id(n)] + (n.task_id,))
+
+
+def read_located_payload(loc, tool_use_id, which):
+    """``read_full_payload`` for a location a locator produced.
+
+    The ``background_result`` location is a 3-tuple whose third element is the
+    task id the re-read line must carry; every other mode is a plain
+    ``(source_path, byte_offset)``. Unpacking lives here so both payload routes
+    stay one call and neither can forget the identity check."""
+    return read_full_payload(
+        loc[0], loc[1], tool_use_id, which,
+        expected_task_id=(loc[2] if len(loc) > 2 else None))
+
+
 def locate_tool_payload(conn, session_id, tool_use_id, which):
     """``(source_path, byte_offset)`` for the JSONL line holding the tool_use
     (``which='input'``) or tool_result (``which='result'``) carrying this
     ``tool_use_id`` in this session, else ``None``.
 
+    ``which='background_result'`` is the internal backgrounded-MCP mode: it
+    resolves the placeholder for ``tool_use_id``, reads its task id, and
+    addresses the winning NOTIFICATION row instead — returning the 3-tuple
+    ``(source_path, byte_offset, task_id)`` that mode carries (see
+    ``locate_result_payload``).
+
     The prefilter uses ``instr(blocks_json, ?) > 0`` — NOT ``LIKE`` (Codex P1.4):
     tool_use_ids contain ``_`` (e.g. ``toolu_01SEQ…``), which ``LIKE`` treats as a
     single-char wildcard, so a near-miss id would false-match. ``instr`` is a
@@ -3937,6 +4185,9 @@ def locate_tool_payload(conn, session_id, tool_use_id, which):
     same deterministic ``ORDER BY timestamp_utc, id`` as ``get_conversation``. The
     SELECT runs here (not via ``get_conversation``) because that reader omits
     ``byte_offset`` (Codex P2.5)."""
+    if which == "background_result":
+        mode, loc = locate_result_payload(conn, session_id, tool_use_id)
+        return loc if mode == "background_result" else None
     rows = conn.execute(
         "SELECT source_path, byte_offset, blocks_json FROM conversation_messages "
         "WHERE session_id=? AND instr(blocks_json, ?) > 0 "
@@ -3959,7 +4210,8 @@ def locate_tool_payload(conn, session_id, tool_use_id, which):
     return None
 
 
-def read_full_payload(source_path, byte_offset, tool_use_id, which):
+def read_full_payload(source_path, byte_offset, tool_use_id, which, *,
+                      expected_task_id=None):
     """Re-read the raw JSONL line at ``(source_path, byte_offset)`` and return the
     FULL (un-capped) payload for ``tool_use_id``:
 
@@ -3974,7 +4226,23 @@ def read_full_payload(source_path, byte_offset, tool_use_id, which):
     JSONL — the documented 410 path) or the id is no longer present in that line.
     ``full_length``/``truncated`` describe the payload against ``_FULL_PAYLOAD_CEILING``
     — honoring #178's "un-capped" spirit for real payloads while bounding the
-    degenerate multi-MB case."""
+    degenerate multi-MB case.
+
+    ``expected_task_id`` is REQUIRED by ``which='background_result'`` and ignored
+    otherwise. That line carries no ``tool_use_id`` to match on, so the task id is
+    the only identity it has: without the check, a rotated file whose stored
+    offset now lands on a DIFFERENT task-notification would serve a foreign
+    result under this call's id. A MISMATCH -> ``None`` (the 410 path), the same
+    fail-closed shape the ``result``/``input`` branches get from their exact id
+    match. An ABSENT one is different in kind: it is a wiring mistake, not a
+    rotation, and it would fail closed for EVERY recovered background result
+    while being indistinguishable in a log from the genuine article — so it
+    raises ``TypeError`` instead of degrading silently."""
+    if which == "background_result" and not expected_task_id:
+        raise TypeError(
+            "read_full_payload(which='background_result') requires a non-empty "
+            "expected_task_id — the notification line has no tool_use_id to "
+            "match on, so the task id is its only identity")
     try:
         with open(source_path, "rb") as fh:
             fh.seek(byte_offset)
@@ -3984,6 +4252,30 @@ def read_full_payload(source_path, byte_offset, tool_use_id, which):
         return None
     if not isinstance(obj, dict):
         return None
+    if which == "background_result":
+        # A backgrounded-MCP completion is an attachment record: it has NO
+        # ``message.content``, which is exactly why the public which='result'
+        # path could never serve it. Re-extract <result> from the raw wrapper.
+        # ``tool_use_id`` is not present in this line at all — it is echoed back
+        # only because the client keyed its request by it, so the TASK ID is the
+        # only identity available and it is checked below.
+        att = obj.get("attachment")
+        if not isinstance(att, dict):
+            return None
+        n = _bg.parse_task_notification(att.get("prompt"))
+        if n is None or not n.result_text:
+            return None      # rotated onto a non-notification line -> 410
+        if n.task_id != expected_task_id:
+            # Rotated onto a DIFFERENT task's notification: well-formed, with a
+            # well-formed <result>, and NOT ours. Serving it would attach a
+            # foreign response to this call. (An absent id never reaches here —
+            # it raised at the top as the wiring bug it is.)
+            return None
+        raw = n.result_text
+        return {"which": "result", "tool_use_id": tool_use_id,
+                "text": raw[:_FULL_PAYLOAD_CEILING], "full_length": len(raw),
+                "truncated": len(raw) > _FULL_PAYLOAD_CEILING,
+                "is_error": False}
     content = (obj.get("message") or {}).get("content")
     if not isinstance(content, list):
         return None