cctally 1.88.2 → 1.89.1

package/bin/_cctally_record.py

@@ -169,6 +169,7 @@ import fcntl
 import json
 import math
 import os
+import re
 import sqlite3
 import sys
 import time
@@ -4627,27 +4628,135 @@ def _hook_tick_format_log_line(
     )
 
 
+#: A token that is unmistakably a filesystem path: an absolute POSIX path, a
+#: `~`-relative one, or a Windows drive path. The negative lookbehind is what
+#: keeps `Input/output error` and `disk I/O error` intact — a separator with a
+#: word character in front of it is prose, not a root.
+#:
+#: It deliberately does NOT match a RELATIVE path (`.codex/sessions/…`): every
+#: separator in one is preceded by a word character, so widening the lookbehind
+#: to reach it is the same edit that starts eating prose. That is acceptable
+#: because of what the two rules are each for — a relative path carries no
+#: username and no home directory, so the only identifier it can leak is the
+#: conversation id, which the UUID rule below redacts wherever it appears.
+_HOOK_LOG_PATHISH = re.compile(r"(?<!\w)(?:[A-Za-z]:[\\/]|~?/)[^\s'\"]*")
+
+#: A conversation identifier, in or out of path form. Codex names its rollouts
+#: `rollout-<timestamp>-<uuid>.jsonl`, and the `OSError` narrowing only drops
+#: the one that arrives as `filename` — any OTHER exception type quoting a
+#: rollout relatively, or a bare conversation key in one of our own
+#: `ValueError(f"… {key}")` messages, escapes the path rule entirely. A
+#: canonical UUID cannot occur in prose, so this one needs no lookbehind.
+_HOOK_LOG_UUIDISH = re.compile(
+    r"(?<![0-9a-fA-F])[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}"
+    r"-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(?![0-9a-fA-F])")
+
+#: `hook-tick.log` free text is read back by a LAST-WINS `k=v` comprehension,
+#: so the value may not contain a separator of its own.
+_HOOK_LOG_FIELD_SEPARATOR_SUBSTITUTE = ":"
+
+
+def _hook_log_safe_free_text(value: str, *, limit: int = 200) -> str:
+    """Collapse one free-text hook-tick log value and defuse it.
+
+    Four transforms, in order: whitespace collapses so a multi-line message
+    cannot split the record; path-shaped tokens are redacted; UUID-shaped ones
+    are redacted separately, because a relative or bare conversation id never
+    reaches the path rule; and ``=`` is substituted so the value cannot
+    impersonate a field. See ``_hook_log_error_detail`` for why each is
+    load-bearing.
+    """
+    collapsed = " ".join(str(value).split())
+    collapsed = _HOOK_LOG_PATHISH.sub("<path>", collapsed)
+    collapsed = _HOOK_LOG_UUIDISH.sub("<uuid>", collapsed)
+    collapsed = collapsed.replace("=", _HOOK_LOG_FIELD_SEPARATOR_SUBSTITUTE)
+    return collapsed[:limit]
+
+
+def _hook_log_error_detail(exc: BaseException, *, limit: int = 200) -> str:
+    """One bounded, privacy-safe ``<class>: <message>`` for a hook-tick line.
+
+    Two things the plain ``f"{type(exc).__name__}: {exc}"`` emits that this
+    durable, deliberately-bounded diagnostic must not.
+
+    A FILESYSTEM PATH. The whole ``OSError`` family puts ``filename`` in its
+    ``str()``, so one ``PermissionError: [Errno 13] Permission denied:
+    '/Users/<name>/.codex/sessions/…/rollout-…-<uuid>.jsonl'`` writes a username
+    AND a conversation identifier into the log — the same exposure for which a
+    traceback was already rejected, without the traceback. The family is
+    narrowed to ``errno``/``strerror``, which is the diagnostic half, and
+    whatever remains is additionally scrubbed of path-shaped AND UUID-shaped
+    tokens: the callers are blanket ``except`` blocks that can catch anything,
+    including our own ``ValueError(f"… {path}")``. The two scrubs are separate
+    rules because the path one recognises only an ABSOLUTE or ``~``-relative
+    root — a relative ``.codex/sessions/…`` spelling escapes it, and so does a
+    bare conversation key, neither of which the ``OSError`` narrowing can reach
+    on a non-``OSError`` type. Between them: a username or home directory can
+    only appear under an absolute or ``~`` root, and a conversation id is a UUID
+    wherever it appears.
+
+    An ``=``. The only real reader of these lines is a LAST-WINS
+    ``{k: v for token in tokens if "=" in token}`` comprehension
+    (``_codex_lifecycle_activity_24h``), so a message containing
+    ``provider=claude`` or ``result=success`` overrides the true field — the
+    record is dropped from doctor's view, or an errored tick is counted as a
+    success. Appending the free text LAST does not protect the fixed columns
+    from that parser; last-wins means it is precisely the position that loses.
+    """
+    detail = (
+        f"[Errno {exc.errno}] {exc.strerror}"
+        if isinstance(exc, OSError) and exc.strerror
+        else str(exc)
+    )
+    return _hook_log_safe_free_text(
+        f"{type(exc).__name__}: {detail}".strip(), limit=limit)
+
+
 def _codex_lifecycle_log_line(
     *, source_root_key: str, event: str, sync: str, result: str,
     blocks: int, milestones: int, alert_eligible_roots: int,
-    quota_alerts: int, budget_alerts: int, dur_ms: int,
+    quota_alerts: int, budget_alerts: int, dur_ms: int, backlog: int = 0,
+    error: str = "",
 ) -> str:
     """Render one privacy-safe root-qualified Codex lifecycle outcome.
 
     Native hook input can contain session paths and conversation identifiers;
     this durable diagnostic deliberately carries only the bounded event label,
-    opaque source root key, aggregate reconciliation counts, and duration.
+    opaque source root key, aggregate reconciliation counts, duration, and — on
+    an errored tick — a DEFUSED exception class and message.
+
+    ``error`` is the one free-text field. It carries the class and message from
+    the hook's blanket except, never a traceback and never anything derived from
+    hook stdin, because a `result=error` tick with nothing else recorded is
+    undiagnosable and has already cost one debugging round.
+
+    Its position is last for readability, NOT for safety, and the comment that
+    claimed otherwise had it backwards. The only real reader of this line is a
+    LAST-WINS `k=v` comprehension (`_codex_lifecycle_activity_24h`), against
+    which last position is the WINNING one — a message containing
+    `provider=claude` dropped the whole record from doctor's view, and one
+    containing `result=success` counted an errored tick as a success. Safety
+    comes from `_hook_log_safe_free_text`, which is what keeps every fixed
+    column authoritative and every path out of the file. A caller holding the
+    exception should pass `_hook_log_error_detail(exc)`, so the `OSError`
+    family's embedded `filename` is narrowed away at the source as well.
     """
     safe_event = "".join(
         char for char in str(event)[:40] if char.isalnum() or char in "-_"
     ) or "unknown"
+    suffix = ""
+    if error:
+        collapsed = _hook_log_safe_free_text(error)
+        if collapsed:
+            suffix = f" error={collapsed}"
     return (
         f"{now_utc_iso()} provider=codex source_root_key={source_root_key} "
         f"event={safe_event} sync={sync} blocks={int(blocks)} "
         f"milestones={int(milestones)} "
         f"alert_eligible_roots={int(alert_eligible_roots)} "
         f"quota_alerts={int(quota_alerts)} budget_alerts={int(budget_alerts)} "
-        f"dur_ms={max(0, int(dur_ms))} result={result}"
+        f"backlog={max(0, int(backlog))} "
+        f"dur_ms={max(0, int(dur_ms))} result={result}{suffix}"
     )
 
 
@@ -4656,7 +4765,54 @@ def _codex_lifecycle_roots():
     return codex_hook_roots(_cctally()._codex_home_roots())
 
 
-def _cmd_hook_tick_codex(args: argparse.Namespace, *, event: str = "unknown") -> int:
+def _stats_epoch_rebuild_pending() -> bool:
+    """Would opening stats.db right now trigger a whole-journal rebuild?
+
+    Side-effect-free: a raw read-only ``PRAGMA user_version``, the same probe
+    ``resolve_stats_epoch_mismatch`` re-checks under the maintenance lock.
+
+    Deliberately narrow. A MISSING stats.db is a fresh install, where building
+    the index is cheap and skipping it would leave the hook with nothing to do
+    forever. An UNREADABLE one belongs to the corruption auto-heal path, not
+    here. A LEGACY index (``user_version <= LEGACY_STATS_HEAD``) takes the
+    migration route rather than the epoch rebuild, and predates every epoch
+    this decision is about. Only a readable, post-legacy, wrong-epoch index —
+    exactly what an upgrade across a ``STATS_INDEX_EPOCH`` bump produces —
+    answers True.
+    """
+    path = _cctally_core.DB_PATH
+    try:
+        if not path.exists():
+            return False
+    except OSError:
+        return False
+    try:
+        import _cctally_store
+        version = _cctally_store._raw_user_version(path)
+    except Exception:
+        return False
+    if version < 0 or version <= _cctally_core.LEGACY_STATS_HEAD:
+        return False
+    return version != _cctally_core.STATS_INDEX_EPOCH
+
+
+def _defer_stats_epoch_rebuild() -> str:
+    """Hand a pending stats.db epoch rebuild to the detached quota worker.
+
+    Reuses ``_codex-quota-verify`` rather than adding a third worker: its
+    ``force_full`` pass opens stats.db, which is what performs the rebuild, and
+    the whole-history pass it then runs is exactly the one the freshly rebuilt
+    index needs anyway. Sharing the worker also shares its attempt-stamped
+    throttle, so a rebuild that keeps dying cannot spawn one worker per tick.
+    """
+    from _cctally_quota import _defer_codex_quota_verification
+    return _defer_codex_quota_verification()
+
+
+def _cmd_hook_tick_codex(
+    args: argparse.Namespace, *, event: str = "unknown",
+    transcript_path: str = "",
+) -> int:
     """Run one quiet, foreground Codex lifecycle tick.
 
     Native Codex Stop/SubagentStop hooks may fire concurrently.  Per-root
@@ -4679,6 +4835,7 @@ def _cmd_hook_tick_codex(args: argparse.Namespace, *, event: str = "unknown") ->
 
     def log_outcome(
         *, sync: str, result: str, projection=None, budget_alerts: int = 0,
+        backlog: int = 0, error: str = "",
     ) -> None:
         blocks = int(getattr(projection, "blocks_upserted", 0) or 0)
         milestones = int(getattr(projection, "milestones_upserted", 0) or 0)
@@ -4695,10 +4852,30 @@ def _cmd_hook_tick_codex(args: argparse.Namespace, *, event: str = "unknown") ->
                 alert_eligible_roots=len(due_root_keys),
                 quota_alerts=quota_alerts,
                 budget_alerts=budget_alerts,
+                backlog=backlog,
                 dur_ms=dur_ms,
+                error=error,
             ))
         _hook_tick_log_rotate_if_needed()
 
+    # public #5: a pending stats.db epoch rebuild is the one operation on this
+    # path that neither the ingest budget nor the projection's `defer` can
+    # bound, because it happens inside `open_db()` before any of this code gets
+    # a say. Measured on a real 211K-observation / 1,859-rollout store, the
+    # first tick after the epoch bump cost 82.05s wall — 76.45s of it the
+    # journal rebuild — against Codex's 30-second hook timeout. A killed rebuild
+    # commits nothing, so the next tick repeats it: a non-converging
+    # 30-second-per-turn loop, which is the reported defect delivered by the
+    # fix. Hand it to the same detached worker the periodic verification uses
+    # (its `force_full` pass opens stats.db and therefore performs the rebuild)
+    # and acknowledge this tick as a no-op. No lifecycle marker is stamped, so
+    # the next Codex turn re-checks immediately; the spawn itself is throttled.
+    if _stats_epoch_rebuild_pending():
+        _defer_stats_epoch_rebuild()
+        log_outcome(sync="deferred", result="noop")
+        release_lifecycle_locks(locks)
+        return 0
+
     try:
         # Hook stdout/stderr is contractually silent.  Cache migration and
         # ingest diagnostics remain available to explicit CLI operations.
@@ -4707,10 +4884,26 @@ def _cmd_hook_tick_codex(args: argparse.Namespace, *, event: str = "unknown") ->
             cache = c.open_cache_db()
             try:
                 cache_mod = c._load_sibling("_cctally_cache")
+                # public #5 spec §4: the hook's ingest leg is BUDGETED and
+                # resumable, and it ingests the active rollout first so live
+                # numbers stay correct while history lags. Only this caller
+                # passes a budget — an explicit `cctally cache-sync` still runs
+                # to completion.
+                import _cctally_config as _cfg_codex
+                budget_seconds = _cfg_codex.resolve_codex_hook_ingest_budget(
+                    c.load_config())
                 stats, cache = cache_mod._run_cache_operation_with_recovery(
                     cache,
                     lambda active_conn: c.sync_codex_cache(
-                        active_conn, lock_timeout=0
+                        active_conn, lock_timeout=0,
+                        budget_seconds=budget_seconds,
+                        active_transcript_path=transcript_path or None,
+                        # public #5 spec §4: ONE reconcile per tick. The
+                        # explicit alert-eligible reconcile below can never
+                        # take the certificate short-circuit (it is guarded by
+                        # `not alert_eligible_roots`), so the sync-internal one
+                        # was pure duplicated cost.
+                        quota_reconcile="defer",
                     ),
                     origin="hook.codex_quota.sync",
                 )
@@ -4723,6 +4916,18 @@ def _cmd_hook_tick_codex(args: argparse.Namespace, *, event: str = "unknown") ->
                 source_root_keys=all_root_keys,
                 alert_eligible_root_keys=due_root_keys,
                 now=dt.datetime.now(dt.timezone.utc),
+                # public #5 spec §2/§4: the hook path NEVER runs a
+                # whole-history quota pass inline — not the once-a-day
+                # verification, and not a rebuilt stats index, an interpretation
+                # bump, a missing reverse map, a reset ledger or a dirty-unit
+                # burst either. On a hook-only install no dashboard tick or
+                # `codex quota` invocation reaches any of them first, so each
+                # would land here as a ~14-30s reconcile on a blocking path
+                # against Codex's 30-second timeout. `defer` hands every one of
+                # them to the detached `_codex-quota-verify` worker; the bounded
+                # ingest above stays foreground, so fresh observations still
+                # precede the turn.
+                full_pass="defer",
             )
             # Vendor-scoped spend is intentionally evaluated once per
             # successful due-set tick, not once per root. Task 7 Item 4: the
@@ -4743,15 +4948,47 @@ def _cmd_hook_tick_codex(args: argparse.Namespace, *, event: str = "unknown") ->
             _jr_codex.run_stats_ingest(
                 mode="authoritative", codex_apply=_codex_budget_leg)
             budget_alerts = _budget_holder["n"]
+        if getattr(stats, "deferred_reason", None) == "replay_pending":
+            # public #5: the budgeted tick declined a byte-zero replay, and on
+            # a hook-only install nothing else would ever perform one — no
+            # dashboard, no `codex quota`, no `cache-sync`. Every following tick
+            # would return at the same decline and Codex ingest would freeze
+            # permanently. Hand the unbudgeted drain to a detached worker.
+            # Outside the cache flocks by construction (the sync released them
+            # before returning) and after the connection closed, so the worker
+            # is not racing this tick for the writer lock.
+            cache_mod._defer_codex_replay_drain()
         mark_lifecycle_success(locks)
         log_outcome(
-            sync="ok", result="success", projection=projection,
+            # A byte-zero Codex replay is not sliceable, so a budgeted tick
+            # declines it outright and hands the unbudgeted drain to a detached
+            # worker (above). Say so in the lifecycle line rather than reporting
+            # a sync that did not walk anything as "ok".
+            sync="deferred" if getattr(stats, "deferred_reason", None) else "ok",
+            result="success", projection=projection,
             budget_alerts=budget_alerts,
+            backlog=int(getattr(stats, "backlog_files", 0) or 0),
         )
-    except Exception:
+    except Exception as exc:
         # A failed sync, projection, or budget evaluation must acknowledge no
         # root.  Hooks are best-effort and remain a successful no-op to Codex.
-        log_outcome(sync="error", result="error")
+        #
+        # The class and message go into the lifecycle line. Discarding them
+        # already cost a debugging round: a changed keyword signature raised
+        # TypeError inside this block and presented as a silent `result=error`
+        # tick indistinguishable from a database failure. No traceback (this is
+        # a durable, privacy-bounded diagnostic and a traceback carries paths),
+        # and nothing reaches stdout or stderr — those stay contractually
+        # silent.
+        #
+        # `_hook_log_error_detail`, not a bare f-string: rejecting the traceback
+        # for carrying paths and then interpolating `str(exc)` was the same leak
+        # one layer down, because the whole `OSError` family embeds `filename`
+        # — a rollout path is a username plus a conversation UUID.
+        log_outcome(
+            sync="error", result="error",
+            error=_hook_log_error_detail(exc),
+        )
         return 0
     finally:
         release_lifecycle_locks(locks)
@@ -4781,7 +5018,10 @@ def cmd_hook_tick(args: argparse.Namespace) -> int:
         # probes may only drain stdin.  Do not turn an absent payload into a
         # hook failure merely because event observability is unavailable.
         event = meta.get("event", "unknown") if isinstance(meta, dict) else "unknown"
-        return _cmd_hook_tick_codex(args, event=event)
+        transcript = (
+            meta.get("transcript_path", "") if isinstance(meta, dict) else "")
+        return _cmd_hook_tick_codex(
+            args, event=event, transcript_path=str(transcript or ""))
     explain = bool(getattr(args, "explain", False))
     foreground = bool(getattr(args, "foreground", False))
     no_oauth = bool(getattr(args, "no_oauth", False))

package/bin/_cctally_setup.py

@@ -1477,15 +1477,24 @@ def _setup_recent_log_stats(seconds: float = 24 * 3600) -> dict:
                     continue
                 if ts < cutoff:
                     continue
-                counts["fires"] += 1
-                last_ts = max(last_ts, ts)
-                # event=NAME
-                ev = "unknown"
+                # event=NAME. Its ABSENCE now means the line is not a hook fire
+                # at all: `hook-tick.log` also carries the detached Codex
+                # workers' outcomes (`op=quota-verify`, `op=quota-verify-spawn`,
+                # `op=replay-drain`), which are `provider=codex op=… result=…`
+                # and name no event. Counting them inflated `fires` and piled
+                # them into `by_event["unknown"]`, which is meant to report hook
+                # payloads whose `hook_event_name` cctally could not read.
+                ev = None
                 for tok in ln.split():
                     if tok.startswith("event="):
                         ev = tok.split("=", 1)[1]
                         break
-                counts["by_event"][ev] = counts["by_event"].get(ev, 0) + 1
+                if ev is None:
+                    continue
+                counts["fires"] += 1
+                last_ts = max(last_ts, ts)
+                counts["by_event"][ev or "unknown"] = (
+                    counts["by_event"].get(ev or "unknown", 0) + 1)
                 if "oauth=ok(" in ln:
                     counts["oauth_ok"] += 1
                 elif "oauth=throttled" in ln:

package/bin/_cctally_store.py

@@ -275,7 +275,22 @@ def would_block_prod_stats_cutover(path) -> bool:
 #
 # Bump ``_STATS_OPEN_FIXUPS_VERSION`` when a NEW open-time backfill is added, so
 # existing installs re-run the fixups once to pick it up.
-_STATS_OPEN_FIXUPS_VERSION = 1
+#
+# 1 -> 2 (public #5): the quota-projection schema gained
+# ``quota_window_blocks.physical_group_key`` / ``physical_group_digest`` and the
+# ``quota_projection_ledger_state`` row. An epoch-mismatched index resolves that
+# by REBUILD, but a LEGACY index (``user_version <= LEGACY_STATS_HEAD``) takes
+# the in-place cutover instead, and the cutover relies on this open-time schema
+# apply — which a stamped marker skips outright. Without the bump such a DB is
+# stamped at the new epoch while still missing the columns, and every subsequent
+# open returns at the steady-state gate before any schema work could add them:
+# a permanent `no such column: physical_group_key`.
+#
+# 2 -> 3 (public #5, I2 review): the same seam, one column later. The periodic
+# verification adds `quota_projection_ledger_state.last_full_pass_at`, and a
+# legacy index that already ran the fixups at version 2 would skip the schema
+# apply that adds it.
+_STATS_OPEN_FIXUPS_VERSION = 3
 
 
 def stats_open_fixups_current(conn: sqlite3.Connection) -> bool:

package/bin/_cctally_tui.py

@@ -2286,7 +2286,13 @@ def _snapshot_data_version(sig) -> str:
     # account switch with zero new rows still flips the SSE change-signal. Empty
     # for every <=1-account install (byte-neutral — never appended).
     acct = getattr(sig, "accounts_digest", "")
-    return out if not acct else f"{out}.a{acct}"
+    out = out if not acct else f"{out}.a{acct}"
+    # public #5: a budgeted tick can change the Codex ingest backlog while every
+    # other leg stays flat, and the envelope publishes that backlog. Folding it
+    # in is what leaves the idle short-circuit so the source bundle is rebuilt
+    # at all. Empty once the backlog has drained, so it is byte-neutral there.
+    backlog = getattr(sig, "codex_ingest_backlog_sig", "")
+    return out if not backlog else f"{out}.b{backlog}"
 
 
 def _tui_source_copy(value: object) -> object:
@@ -2618,10 +2624,18 @@ def _tui_build_source_bundle(
             accounts_digest=accounts_digest,
         )
         _acct_suffix = f":a{accounts_digest}" if accounts_digest else ""
+        # public #5: the hook's budgeted ingest can change what the Codex
+        # envelope owes without moving `codex_physical_mutation_seq` — a tick
+        # whose walk consumed only deduped or non-`token_count` bytes commits
+        # no row. Without this leg `reuse_coherent_source_state` hands back the
+        # prior Codex object and the `ingest_backlog` field never reaches the
+        # wire. Empty (and so byte-neutral) once the backlog has drained.
+        _backlog = getattr(signature, "codex_ingest_backlog_sig", "")
+        _backlog_suffix = f":b{_backlog}" if _backlog else ""
         codex_version = (
             f"codex:{signature.max_codex_id}:"
             f"{signature.codex_physical_mutation_seq}:{stats_digest}:"
-            f"{semantics.codex_identity}{_acct_suffix}"
+            f"{semantics.codex_identity}{_acct_suffix}{_backlog_suffix}"
         )
         claude_version = (
             f"claude:{signature.max_entry_id}:{signature.entry_mutation_seq}:"

package/bin/_cctally_update.py

@@ -1328,9 +1328,15 @@ def _do_update_check() -> None:
         c._save_update_state(state)
 
 
-def _spawn_detached(command: str) -> None:
+def _spawn_detached(command: str) -> bool:
     """Fire-and-forget a hidden self-subcommand as a detached worker.
 
+    Returns whether the spawn was issued. The two update/telemetry callers
+    ignore it — they have no alternative to fall back on — but the deferred
+    Codex quota verification needs to distinguish "handed off" from "could not
+    hand off", because the operation it is deferring is one it must NOT then
+    run inline.
+
     Detached `subprocess.Popen` with `start_new_session=True` so a parent
     exit (the user closes the shell) doesn't propagate SIGHUP to the child;
     stdin/stdout/stderr all `/dev/null` so the child can't pollute the
@@ -1349,9 +1355,10 @@ def _spawn_detached(command: str) -> None:
             start_new_session=True,
             close_fds=True,
         )
+        return True
     except Exception:
         # Fire-and-forget: never let a spawn failure propagate.
-        pass
+        return False
 
 
 def _spawn_background_update_check() -> None:

package/bin/_lib_background_mcp.py

@@ -0,0 +1,168 @@
+"""Pure kernel for recovering backgrounded-MCP results (no I/O).
+
+Claude Code moves an MCP call that exceeds 120s to a background task. The
+completion is persisted ONLY as an attachment/queued_command record with
+commandMode=="task-notification" carrying <task-id> — never as a type:"user"
+line and never with a <tool-use-id>. The bridge back to the originating call is
+the placeholder tool_result, which names the task twice in two independently
+worded places.
+
+Two notification shapes exist and only one of them already works:
+
+  A  subagent / Monitor   type:"user" line     joins on <tool-use-id>
+  B  backgrounded MCP     attachment record    carries <task-id> ONLY
+
+Shape A is classified META at ingest and joined in ``_assemble_session``'s
+finalize stage today. Shape B never appears as a ``type:"user"`` line, so
+nothing rescues it — this module is the parser + selection half of that rescue.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Gate: only a real harness placeholder may yield a task id. Ordinary prose that
+# happens to contain "as task X" must never match.
+_PLACEHOLDER_GATE = re.compile(r'\AMCP tool "[^"]+" is still running after ')
+_AS_TASK = re.compile(r"moved to the background as task (\S+?)[\s.,;]")
+_TASK_ID_QUOTED = re.compile(r'task_id "([^"]+)"')
+
+_TASK_ID_TAG = re.compile(r"<task-id>([^<]*)</task-id>")
+_STATUS_TAG = re.compile(r"<status>([^<]*)</status>")
+_SUMMARY_TAG = re.compile(r"<summary>([^<]*)</summary>")
+
+# Every field copied from the notification wrapper into the transcript store is
+# bounded. Task ids are identities, so an oversized one is rejected rather than
+# truncated; status/summary are presentation metadata and may be clipped.
+MAX_TASK_ID_CHARS = 256
+MAX_STATUS_CHARS = 64
+MAX_SUMMARY_CHARS = 1024
+
+
+@dataclass(frozen=True)
+class BackgroundNotification:
+    task_id: str
+    status: str
+    summary: str
+    result_text: "str | None"
+
+
+def parse_placeholder_task_id(text) -> "str | None":
+    """Task id from a backgrounded-MCP placeholder tool_result, else None.
+
+    BOTH spellings are read and must AGREE. Disagreement returns None rather
+    than picking one — a wrong id would attach a response to the wrong call,
+    which is worse than leaving the placeholder visible. Either spelling ALONE
+    is sufficient (the harness wording is not contractual), but the leading
+    ``MCP tool "…" is still running after`` gate must match, so ordinary prose
+    quoting a task id can never be mistaken for a placeholder.
+    """
+    if not text or not _PLACEHOLDER_GATE.match(text):
+        return None
+    a = _AS_TASK.search(text)
+    b = _TASK_ID_QUOTED.search(text)
+    ids = {m.group(1) for m in (a, b) if m is not None}
+    if len(ids) != 1:
+        return None
+    task_id = ids.pop()
+    return task_id if len(task_id) <= MAX_TASK_ID_CHARS else None
+
+
+def _extract_result(body: str) -> "str | None":
+    """Span between the FIRST <result> and the wrapper's LAST </result>.
+
+    Delimiter contract: the result carries arbitrary MCP text that may itself
+    contain a literal ``</result>``, so a non-greedy match would truncate it.
+    ``rfind`` deliberately takes the last close tag BEFORE the closing
+    ``</task-notification>``. Content after that wrapper is foreign and cannot
+    extend the result.
+    """
+    start = body.find("<result>")
+    if start == -1:
+        return None
+    wrapper_end = body.find("</task-notification>", start + len("<result>"))
+    if wrapper_end == -1:
+        return None
+    end = body.rfind("</result>", start + len("<result>"), wrapper_end)
+    if end == -1 or end <= start:
+        return None
+    return body[start + len("<result>"):end].strip() or None
+
+
+def parse_task_notification(body) -> "BackgroundNotification | None":
+    """Parse a <task-notification> body. None when it carries no task id.
+
+    <summary> deliberately carries a TRUNCATED task id (kravg1b9 for task
+    kravg1b9s) and is never used as an identity.
+    """
+    if not body:
+        return None
+    m = _TASK_ID_TAG.search(body)
+    if m is None or not m.group(1).strip():
+        return None
+    task_id = m.group(1).strip()
+    if len(task_id) > MAX_TASK_ID_CHARS:
+        return None
+    status = _STATUS_TAG.search(body)
+    summary = _SUMMARY_TAG.search(body)
+    return BackgroundNotification(
+        task_id=task_id,
+        status=(status.group(1).strip()[:MAX_STATUS_CHARS] if status else ""),
+        summary=(summary.group(1).strip()[:MAX_SUMMARY_CHARS] if summary else ""),
+        result_text=_extract_result(body),
+    )
+
+
+def unambiguous_placeholder_tasks(placeholders):
+    """Return one task per tool id only when every claim agrees.
+
+    ``placeholders`` may be a mapping for legacy callers or an iterable of
+    ``(tool_use_id, task_id)`` claims. The iterable form preserves conflicting
+    claimants that a dictionary would silently collapse last-writer-wins.
+    Repeated identical claims are harmless; distinct claims fail closed.
+    """
+    claims = placeholders.items() if hasattr(placeholders, "items") else placeholders
+    by_tool = {}
+    for tool_use_id, task_id in claims:
+        by_tool.setdefault(tool_use_id, set()).add(task_id)
+    return {
+        tool_use_id: next(iter(task_ids))
+        for tool_use_id, task_ids in by_tool.items()
+        if len(task_ids) == 1
+    }
+
+
+def select_background_joins(placeholders, notifications):
+    """``{tool_use_id: BackgroundNotification}`` for UNAMBIGUOUS matches only.
+
+    ``placeholders`` is a mapping or an iterable of claimant pairs. Background
+    task ids carry no session-uniqueness guarantee comparable to Anthropic tool
+    ids, and a resumed session is assembled across every source file, so this
+    FAILS CLOSED: one tool id claiming conflicting tasks, one task id claimed by
+    more than one tool id, or more than one completed notification joins
+    NOTHING. A visible placeholder is a recoverable disappointment; a response
+    attached to the wrong call is a correctness failure.
+
+    This is the ONE selection rule — the full-payload resolver calls it too, so
+    a card can never display one capped response and load a different full one.
+    """
+    by_task: "dict[str, list]" = {}
+    for tuid, task_id in unambiguous_placeholder_tasks(placeholders).items():
+        by_task.setdefault(task_id, []).append(tuid)
+
+    usable: "dict[str, list]" = {}
+    for n in notifications:
+        if n.status != "completed" or not n.result_text:
+            continue
+        usable.setdefault(n.task_id, []).append(n)
+
+    out = {}
+    for task_id, tuids in by_task.items():
+        if len(tuids) != 1:
+            continue                      # ambiguous placeholder side
+        cands = usable.get(task_id) or []
+        if len(cands) != 1:
+            continue                      # absent or ambiguous notification side
+        out[tuids[0]] = cands[0]
+    return out