@sema-agent/server 1.323.0 → 2.0.1

package/dist/fleet/fleet-bus.js

@@ -1,6 +1,34 @@
+/**
+ * MF-Fleet (shell-host data-contract, the dynamic-stream obligation) — the SERVICE-side live fleet
+ * aggregation bus + state, backing `GET /v1/fleet/stream`.
+ *
+ * The fleet view (CC 187 0616_053) animates a MULTI-ROW tree: every active task's `status/elapsedMs/tokens/
+ * queuedCount` and every workflow's `doneCount N/M · failedCount` TRANSITION over time. That is a *push* stream,
+ * not a one-shot read: the backend must emit every transition for as long as a run is live, with STABLE per-row
+ * identity so the UI updates the right row in place.
+ *
+ * This bus is the in-process aggregator: the run lifecycle (createRun → queued/running, per-turn token accrual,
+ * terminal → completed/failed) and the workflow lifecycle (WorkflowRun put/update → doneCount/status) publish
+ * their per-row deltas here; `GET /v1/fleet/stream` subscribes, sends a SNAPSHOT on connect, then forwards every
+ * delta. Identity: tasks keyed by `id` (the durable runId/taskId), workflows by their workflow runId, subagent
+ * sub-rows (round 5, pending core's `task_progress` arm) by `parentId`+agent id (E2 `parentToolCallId`).
+ *
+ * 🔒 boundary (design/99 §0): the FLEET aggregation + the SSE wire is **service** (UI/deployment-state view over
+ * the runs ledger + workflow store). The engine semantics (a run's own events, a subagent's usage ticks) are
+ * core's — the bus only AGGREGATES what the lifecycle already produces. It carries NO new engine state.
+ *
+ * NOT durable / NOT cross-replica: a live fleet is this replica's active runs (mirrors `steerableRuns` —
+ * replica-local). A cross-replica fleet roll-up is a fleet-token-gated trace-API concern (separate), not this.
+ */
 import { EventEmitter } from "node:events";
 import { canonicalToolName } from "@sema-agent/core";
 import { redactSecrets } from "../trace/redact.js";
+/**
+ * The process-local fleet aggregation bus. Holds the current active set + fans out deltas to SSE subscribers.
+ * Upserts MERGE (a partial delta patches the existing row), so a publisher can emit just the field that changed
+ * (e.g. only `tokens`) and the row stays whole. Removal drops the row (terminal). Subscribers get a snapshot of
+ * the current set immediately, then every subsequent delta.
+ */
 export class FleetEventBus {
     now;
     emitter = new EventEmitter();
@@ -8,39 +36,51 @@ export class FleetEventBus {
     workflows = new Map();
     constructor(now = () => Date.now()) {
         this.now = now;
-        this.emitter.setMaxListeners(0);
+        this.emitter.setMaxListeners(0); // unbounded SSE subscribers (each /v1/fleet/stream connection)
     }
+    /** Upsert a task row (MERGE onto any existing row by `id`) + fan out the merged row. Publishers may send a
+     *  partial `{ id, tokens }` etc.; the row keeps its other fields. */
     publishTask(delta) {
         const merged = { ...(this.tasks.get(delta.id) ?? { id: delta.id, name: delta.id, status: "running" }), ...delta };
         this.tasks.set(delta.id, merged);
         this.emit({ type: "task", row: merged, ts: this.now() });
     }
+    /** 推一帧 hook 判定未完成的观测通知(事件语义,不进 snapshot —— 与 `bg_notification` 同族)。 */
     publishHookNotice(notice) {
         this.emit({ type: "hook_notice", notice, ts: this.now() });
     }
+    /** Drop a task row (terminal + swept) + fan out the removal. Idempotent (a no-op if already gone). */
     removeTask(id) {
         if (this.tasks.delete(id))
             this.emit({ type: "task_remove", id, ts: this.now() });
     }
+    /** Upsert a workflow row (MERGE by `id`) + fan out. */
     publishWorkflow(delta) {
         const merged = { ...(this.workflows.get(delta.id) ?? { id: delta.id, name: delta.id, status: "running" }), ...delta };
         this.workflows.set(delta.id, merged);
         this.emit({ type: "workflow", row: merged, ts: this.now() });
     }
+    /** Drop a workflow row + fan out the removal. Idempotent. */
     removeWorkflow(id) {
         if (this.workflows.delete(id))
             this.emit({ type: "workflow_remove", id, ts: this.now() });
     }
+    /** design/129-B 缺口②: fan out a background-child completion notification (EVENT — not stored, never in the
+     *  snapshot; a subscriber that connects later reads the durable inbox instead). */
     publishBgNotification(notification) {
         this.emit({ type: "bg_notification", notification, ts: this.now() });
     }
+    /** The current full state (the connect-time snapshot frame). */
     snapshot() {
         return { type: "snapshot", tasks: [...this.tasks.values()], workflows: [...this.workflows.values()], ts: this.now() };
     }
+    /** Subscribe to deltas. Returns an unsubscribe thunk. The caller typically sends `snapshot()` first, then every
+     *  delta this delivers — the snapshot+delta sequence is the live fleet view. */
     subscribe(cb) {
         this.emitter.on("frame", cb);
         return () => this.emitter.off("frame", cb);
     }
+    /** Live counts (test/observability). */
     get size() {
         return { tasks: this.tasks.size, workflows: this.workflows.size };
     }
@@ -48,18 +88,37 @@ export class FleetEventBus {
         this.emitter.emit("frame", frame);
     }
 }
+/** A run-scoped lifecycle publisher — wire it into a run's TaskEvent loop so the fleet row TRANSITIONS with the
+ *  run. `onStart()` adds the top-level row (running); `onEvent(ev)` accrues tokens (turn_end usage) + adds/updates
+ *  subagent CHILD rows (core `task_progress`, keyed by its `taskId`, nested under the run via `parentId`);
+ *  `onTerminal(status)` flips the row terminal + removes it (and its children) from the active set. No-op when no
+ *  bus is wired. The token accrual is CUMULATIVE across the run's turns (turn_end carries a per-turn delta). */
 export function fleetRunPublisher(bus, run) {
     if (!bus)
         return { onStart: () => undefined, onEvent: () => undefined, onForwardEvent: () => undefined, onChildTerminal: () => false, onTerminal: () => undefined };
     let tokens = 0;
     const startedAt = Date.now();
+    // #3 fleet per-session scope (clay 2026-06-30): tag every row of THIS run with its rootTaskId (= sessionId) so
+    // /v1/fleet/stream can filter to the caller's CURRENT session (a TUI footer no longer shows other sessions of the
+    // same principal). publishTask MERGEs, so tagging the CREATE frame suffices — status/token updates keep the field.
     const sessionField = run.rootTaskId ? { sessionId: run.rootTaskId } : {};
-    const children = new Set();
-    const childStartedAt = new Map();
+    const children = new Set(); // subagent child row ids (removed with the run)
+    const childStartedAt = new Map(); // [1332]④:child 行时长轴(首 tick 起表)
+    // codex R2:spawning tool-call id → cid。core 的失败/killed 收尾通知不带 sessionId(成功路径才有条件带),
+    // 此时 task_id(a*)解不到 uuid 键的 tick 行——但 tick 的 ident() 带 parentToolCallId,通知带同源 toolUseId,
+    // 这是两 id 域之外唯一贯穿 spawn→terminal 的关联轴。一次 Task 调用只 spawn 一个 child,键不撞。
     const childByToolCall = new Map();
+    // Once the leg SETTLED, a LATE subagent tick must not resurrect a child
+    // row — the settle's removeTask IS the shell's release signal (auto-exit watches the evict); a post-settle
+    // re-publish left a zombie "running" row with no terminal/remove ever coming. Freeze all publishes after
+    // onTerminal (a resume runs on a FRESH publisher — this leg's handle is done).
     let settledLeg = false;
     const childId = (taskId) => `${run.runId} ${taskId}`;
+    /** [1415]③:task_progress.status 值域映射(1.354 settle 终态 tick)——completed/failed 直译,其余(含
+     *  undefined/"running"/suspended 不发的诚实面)恒 running(旧 core 行为逐位不变)。 */
     const tickStatus = (st) => (st === "completed" ? "completed" : st === "failed" ? "failed" : "running");
+    /** [1748] 从一拍 usage 里取**累计**工具调用次数。与 `sumTokens` 同样防御式取值(该位在这两处的
+     *  静态类型是 `{}`)。⚠️ 缺席就返回 undefined —— 调用点据此**不发这个键**(缺席 ≠ 0)。 */
     const toolUsesOf = (usage) => {
         const t = usage?.toolUses;
         return typeof t === "number" ? t : undefined;
@@ -70,6 +129,12 @@ export function fleetRunPublisher(bus, run) {
             return 0;
         if (typeof u.totalTokens === "number")
             return u.totalTokens;
+        // #9 (workflow 2nd-pass re-review): a turn_end.usage has NO totalTokens → this field-sum. core's turn_end.inputTokens
+        // is the NORMALIZED TOTAL INPUT *INCLUDING CACHE* (usage-accounting promptTokensOf — input + cacheRead + cacheWrite
+        // for the Anthropic family; OpenAI already folds cacheRead into input). So inputTokens + outputTokens ALREADY is the
+        // turn total — the old code ALSO added cacheRead/cacheWrite, double-counting them (~2x with prompt caching, the
+        // normal case). Display-only (the leader fleet-row token number); billing (costMicroUsd) + context/compaction use
+        // totalTokens and were never affected; child rows use task_progress.usage.totalTokens (the early-return) — correct.
         return (u.inputTokens ?? 0) + (u.outputTokens ?? 0);
     };
     return {
@@ -78,44 +143,105 @@ export function fleetRunPublisher(bus, run) {
         },
         onEvent(ev) {
             if (settledLeg)
-                return;
+                return; // no post-settle publishes (zombie-row resurrection)
             if (ev.type === "turn_end" && !ev.parentToolCallId) {
-                tokens += sumTokens(ev.usage);
+                // #9 orchestration token attribution (core 1.180 TaskEventIdentity on turn_end): accrue ONLY the LEADER's own
+                // turns onto the run row. A turn_end WITH a parentToolCallId is an orchestration/subagent SUB-turn (a
+                // run_workflow agent or a spawned subagent) — its usage belongs to that child's own row / the workflow's
+                // budget, NOT the leader. Before core threaded the identity onto turn_end (1.121 left it the only boundary
+                // event without it), the leader row over-counted sub-turn usage on self-orchestration runs.
+                tokens += sumTokens(ev.usage); // turn_end carries a per-turn usage delta → accumulate
                 bus.publishTask({ id: run.runId, tokens, elapsedMs: Date.now() - startedAt });
             }
             else if (ev.type === "task_progress" && ev.taskId) {
+                // core 1.147 subagent usage tick (per-turn, cumulative) → a CHILD fleet row nested under the run.
                 const cid = childId(ev.taskId);
                 children.add(cid);
+                // BC-2 (core 1.151): use the subagent's sanitized display `name` (taskName/agent-type) for the child row;
+                // fall back to the taskId when absent (an anonymous subagent — core deliberately omits name rather than leak
+                // the delegated objective). The row IDENTITY stays `cid` (runId+taskId); only the display label improves.
+                // [WF2-A] redact the subagent display name for PARITY with the top-level run name (fleetRunLabels): core
+                // sanitizes it for RENDERING (ANSI/NUL strip + truncate) but does NOT secret-redact, so a secret-shaped
+                // taskName would leak verbatim on the child row without this.
+                // §K-7: `ev.name` IS the subagent TYPE (BC-2: taskName / selected agent-type) → ALSO surface it as
+                // `agentType` (the picker's short-label field), not only the display `name`. Absent name (anonymous
+                // subagent) → no agentType (the row falls back to name=taskId). One redacted value (name === agentType).
                 const childName = redactSecrets(ev.name ?? ev.taskId);
                 if (!childStartedAt.has(cid))
                     childStartedAt.set(cid, Date.now());
                 if (ev.parentToolCallId)
                     childByToolCall.set(ev.parentToolCallId, cid);
+                // [1415]③ 点亮半场:core 1.354 起 settle 时补终态 tick(status 值域 additive 扩 completed|failed;
+                // 此前恒 "running"=行为逐位不变)——workflow 子的 uuid 行终于有完成态可见(running→removed 的
+                // [1414]#3 形就此闭)。
                 bus.publishTask({ id: cid, name: childName, ...(ev.name ? { agentType: childName } : {}), parentId: run.runId, scope: run.scope, ...sessionField, status: tickStatus(ev.status), tokens: sumTokens(ev.usage), ...(() => { const t = toolUsesOf(ev.usage); return t !== undefined ? { toolUses: t } : {}; })(), elapsedMs: Date.now() - childStartedAt.get(cid) });
             }
             else if (ev.type === "tool_start" && ev.toolName) {
+                // BC-1 (clay 2026-06-27): the top-level run row's `description` = LIVE ACTIVITY (the tool now running), NOT
+                // the objective. `name` already carries an objective preview (fleetRunLabels); ALSO putting the objective in
+                // `description` showed it TWICE (the dup the shell flagged). So `description` tracks the current tool, CC-like.
+                // Tool NAME only — args are untrusted/redacted, a row label must never leak them. Subagent CHILD rows keep
+                // their task_progress display name (BC-2); this updates the TOP-LEVEL run row only.
+                // PascalCase double-belt (core 1.176): canonicalize so a legacy snake CONTROL verb (e.g. a
+                // pre-1.176 emit / a stray report_blocked) renders as its CC name (ReportBlocked) and the shell's PascalCase
+                // suppression Set still hides it — never re-leaking a control verb as fleet-row activity.
                 bus.publishTask({ id: run.runId, description: canonicalToolName(ev.toolName) });
             }
         },
         onForwardEvent(ev) {
+            // core 1.154 (design/99 nested-subagent live tree): a SUBAGENT's `task_progress` tick forwarded from its
+            // ISOLATED stream to the top run's opt-in sink (`RunInternals.onForwardEvent`). This is the ONLY path a
+            // subagent tick reaches the top consumer — the top run's own stream does NOT carry it (the tick lives in the
+            // child's stream, consumed by the parent's runTask). So this builds the fleet's per-subagent CHILD rows at ANY
+            // depth: `parentTaskId` names the spawner — the TOP run (= `rootTaskId` → nest under run.runId) or another
+            // subagent (→ nest under that subagent's row). core sets a child's `parentTaskId` = its spawner's task_progress
+            // `taskId` (prepare-task.ts), so the tree keys line up. Forwarded ticks are UNTRUSTED display hints (name is
+            // core-sanitized; we carry NAME + token rollup only, never args).
+            // 🟡 parentTaskId is NOT validated against known runs (documented as LOW). It needn't be: the
+            // isolation guarantee is the SCOPE BOUND, not a parentTaskId check — every child row we publish is tagged
+            // `scope: run.scope` (this run's owner) and id-prefixed with the real `run.runId`. So a tool forging a
+            // `parentTaskId` can at worst MIS-NEST a row WITHIN this run's own scope view (cosmetic); it can never cross
+            // into another run / tenant. (core corrected its prepare-task note that had over-promised "deployment
+            // validates parentTaskId" — the bound is structural here.) Validation would be optional defense-in-depth only.
             if (settledLeg)
-                return;
+                return; // a late forwarded tick must not resurrect a removed child row
             if (ev.type !== "task_progress" || !ev.taskId)
                 return;
             const cid = childId(ev.taskId);
             children.add(cid);
             const parentId = ev.parentTaskId && ev.parentTaskId !== run.rootTaskId ? childId(ev.parentTaskId) : run.runId;
+            // [WF2-A] redact the forwarded subagent name for parity with the top-level run name (see onEvent above).
+            // §K-7: ev.name IS the subagent type → also surface it as `agentType` (picker short label). Reuse the value.
             const fwdName = redactSecrets(ev.name ?? ev.taskId);
             if (!childStartedAt.has(cid))
                 childStartedAt.set(cid, Date.now());
             if (ev.parentToolCallId)
                 childByToolCall.set(ev.parentToolCallId, cid);
-            bus.publishTask({ id: cid, name: fwdName, ...(ev.name ? { agentType: fwdName } : {}), parentId, scope: run.scope, ...sessionField, status: tickStatus(ev.status), tokens: sumTokens(ev.usage), ...(() => { const t = toolUsesOf(ev.usage); return t !== undefined ? { toolUses: t } : {}; })(), elapsedMs: Date.now() - childStartedAt.get(cid) });
+            bus.publishTask({ id: cid, name: fwdName, ...(ev.name ? { agentType: fwdName } : {}), parentId, scope: run.scope, ...sessionField, status: tickStatus(ev.status), tokens: sumTokens(ev.usage), ...(() => { const t = toolUsesOf(ev.usage); return t !== undefined ? { toolUses: t } : {}; })(), elapsedMs: Date.now() - childStartedAt.get(cid) }); // [1415]③ 同上;[1748] toolUses 同 bg lane 口径
         },
         onChildTerminal(taskId, status, altId, toolUseId) {
+            // A background subagent/bash CHILD settles — task_progress never emits a terminal tick,
+            // so without this the child row sat "running" until the PARENT leg settled (the shell measured 93s of
+            // phantom running; its auto-exit release condition never fired). Flip the status so subscribers SEE the
+            // terminal frame, then remove (mirroring onTerminal's leave-the-fleet posture). Idempotent on an unknown
+            // child. ⚠️ the notification's task_id is the a* domain while ticks key by the child uuid — a live
+            // mid-turn flip can therefore miss the tick-built row (flip-through mints the a* row instead); id-domain
+            // unification is core's half. Post-settle: rows are ALREADY removed (the settle evict is the
+            // shell's release signal) — a flip-through here would mint a fresh orphan row. No-op.
             if (settledLeg)
                 return false;
+            // [1332]①:id 双域候选——tick 行键域(child sessionId uuid)与通知键域(a* task_id)因 core 版本/
+            // lane 而异,单键押注押错=真行永不落 completed(绿点不回,行滞留 running 到父 settle)。两候选谁
+            // 有活行翻谁;都没有才按首候选合成瞬态终帧(bash 无 tick 形,原语义)。
+            // codex R3:killed 保桶(与 a* 车道 fleetBackgroundChildPublisher 的终态映射一致)——操作员/系统
+            // 取消不得错报为执行失败;同一 child 两车道给订阅者的终态必须同色。
             const fleetStatus = status === "completed" ? "completed" : status === "killed" || status === "cancelled" ? "killed" : "failed";
+            // codex F1:两 id 域可能**同时**各有一行(重复/版本偏斜投递,onEvent 与 onForwardEvent 各按一域建)
+            // ——单选一行会漏掉另一域的行,滞留 running 到父 settle(绿点不回复发)。翻**全部**属本 publisher 的
+            // 候选行,逐一终帧+离场。
+            // codex R2:第三候选 = 通知 toolUseId 经 spawn 关联解出的 cid。core 的失败/killed 收尾通知缺 sessionId
+            // (subagent.js catch 分支两处只带 task_id;成功路径才条件带)——此时前两候选同为 a* 域,tick 建的 uuid
+            // 行押不中;toolUseId↔tick.parentToolCallId 是同一次 Task 调用的同源 id,把真行找回来。
             const candidateCids = [childId(taskId)];
             if (altId !== undefined && altId !== taskId)
                 candidateCids.push(childId(altId));
@@ -124,6 +250,7 @@ export function fleetRunPublisher(bus, run) {
                 candidateCids.push(viaToolCall);
             const liveCids = candidateCids.filter((c) => children.has(c));
             const hadRow = liveCids.length > 0;
+            // 都没活行 = bash 无 tick 形:按首候选合成瞬态终帧(建即离,诚实且无害)。
             for (const cid of hadRow ? liveCids : [childId(taskId)]) {
                 const startedAtChild = childStartedAt.get(cid);
                 bus.publishTask({ id: cid, ...(children.has(cid) ? {} : { name: taskId, parentId: run.runId, scope: run.scope, ...sessionField }), status: fleetStatus, ...(startedAtChild !== undefined ? { elapsedMs: Date.now() - startedAtChild } : {}) });
@@ -137,8 +264,9 @@ export function fleetRunPublisher(bus, run) {
             return hadRow;
         },
         onTerminal(status, residuals) {
-            settledLeg = true;
+            settledLeg = true; // freeze — nothing publishes on this leg's publisher after the settle
             const fleetStatus = runStatusToFleet(status);
+            // [1839]①/(a) 案:真终态帧带残局键(有源才带,键逐挑不 spread);parked 帧不带(行还活着)。
             const terminal = fleetStatus === "completed" || fleetStatus === "failed" || fleetStatus === "killed";
             const res = terminal && residuals
                 ? {
@@ -148,17 +276,27 @@ export function fleetRunPublisher(bus, run) {
                 }
                 : {};
             bus.publishTask({ id: run.runId, status: fleetStatus, tokens, elapsedMs: Date.now() - startedAt, ...res });
+            // Subagent CHILD rows leave on ANY settle — terminal OR parked (TOC review #8: a suspended/needs_review run
+            // keeps its row, but its subagents are NOT running while the parent is parked — their work is checkpointed; a
+            // task_progress never emits a terminal, so without this the child rows leak forever as stale "running" under a
+            // parked parent). On resume, fresh task_progress/onForwardEvent re-adds the active children.
             for (const cid of children)
                 bus.removeTask(cid);
             children.clear();
-            childStartedAt.clear();
-            childByToolCall.clear();
+            childStartedAt.clear(); // codex F2:长寿 bg child 的计时项不得随 publisher 句柄泄漏累积(晚到回调可达期)
+            childByToolCall.clear(); // codex R2 同理:spawn 关联表随叶 settle 清空
+            // A truly-terminal run LEAVES the fleet (the shell saw the terminal frame first). A PARKED run
+            // (suspended→waiting / needs_review→awaiting approval) is still active → its ROW STAYS in the fleet.
             if (terminal) {
                 bus.removeTask(run.runId);
             }
         },
     };
 }
+/** [1839]①/(a) 案:TaskResult → 终态行帧残局键映射(sync/background/resume 三条腿各自 settle,共用一处
+ *  映射——键名映射写三遍必漂移)。usage 与 {@link BgNotification.usage} 同形:stats.tokens→totalTokens、
+ *  stats.toolCalls→toolUses(名对齐,消费端一个形状)。errorCode "cancelled" ⇒ stoppedBy:"user"(与
+ *  markStopSource 的归因值同源);transcriptId 顶层 = run 的 sessionId([1840]§二拍)。缺源的键不铸。 */
 export function fleetRunResiduals(result) {
     if (!result)
         return {};
@@ -177,6 +315,22 @@ export function fleetRunResiduals(result) {
         ...(result.sessionId ? { transcriptId: result.sessionId } : {}),
     };
 }
+/**
+ * design/129-B (core 1.240.0) — the PROCESS-LEVEL background-child fleet publisher, wired once
+ * onto `RunnerDeps.onBackgroundChildEvent`. Unlike {@link fleetRunPublisher} (per-leg: dies at leg settle —
+ * the root cause: a session-scoped bg child outliving its turn had NO forward path, fleet showed zero
+ * child frames), this observer lives as long as the process and covers the child's WHOLE lifecycle:
+ *   spawn    → row appears the moment the child registers (launch→turn-tail 零帧 fixed: no more waiting for a
+ *              first tick that a slow child never emits inside the turn);
+ *   tick     → token rollup onto the row; ALSO best-effort removes the per-leg uuid-keyed TWIN row the leg's
+ *              onForwardEvent built for the same child (`${parentTaskId} ${progressTaskId}` composite — the
+ *              per-leg childId shape), so the child shows ONCE, keyed by its stable a* handle;
+ *   terminal → terminal frame under the a* row id, row leaves the fleet, and the contract
+ *              `bg_notification` frame rides the always-open stream (缺口②'s immediate idle delivery).
+ * Rows are tagged `scope` (tenant filter) from the registry scope and `sessionId` (the `?session=` filter)
+ * from the registry owner when session-scoped (owner IS the host sessionId; task-scoped children have no
+ * session attribution → unscoped, back-compat visible). Names ride the same redactSecrets discipline.
+ */
 export function fleetBackgroundChildPublisher(bus, log) {
     if (!bus)
         return () => undefined;
@@ -185,6 +339,7 @@ export function fleetBackgroundChildPublisher(bus, log) {
             log?.(msg, fields);
         }
         catch {
+            /* observability must never fault the observer */
         }
     };
     const meta = new Map();
@@ -194,6 +349,11 @@ export function fleetBackgroundChildPublisher(bus, log) {
         meta.delete(id);
         meta.set(id, m);
         if (meta.size > MAX) {
+            // codex 两轮([1338]④ 复审):逐出**只打墓碑**(done)。R1:逐最老会把在跑 child 的 spawnedAt 挤掉,
+            // 下个 tick lazy-mint 重起表=elapsedMs 归零。R2(更重):全活时垫底逐活儿,重生条目 tenantScope 落
+            // "default"、owner/parent 全失——**跨租户错归因**(scoped 流按 "default" 键还能收到别家 child 的终态
+            // 通知残料)。活溯源绝不逐出:无墓碑=不逐,活基数由 registry 真并发界定(每条 Meta 极小);病态膨胀
+            // 打一次 warn 供观测。墓碑仍受 MAX 界(terminal 后条目=墓碑,自然轮换)。
             let victim;
             for (const [k, v] of meta) {
                 if (v.done) {
@@ -210,12 +370,28 @@ export function fleetBackgroundChildPublisher(bus, log) {
             }
         }
     };
+    // [1338]③ 换算臂:core spawn emit 现把 hostSessionId 装进 parentTaskId(会话 id,非行 id)→ 子行
+    // parentId 指向不存在的行=孤儿伪影(值域修在 core)。server 兜:parentTaskId 不是现存行 id、却恰是
+    // 某 TOP-LEVEL run 行的 sessionId 时,换算成该 run 行 id。guard 式——core 修后 parentTaskId 直接命中
+    // 行 id,此臂自然失活;无命中(run 行未起/已离场)保持原值,孤儿顶格渲染,不误挂。
+    // codex R3(M1):首次**成功**解析即冻结进 Meta.resolvedParentId——逐拍重解会把跨 run 存活的长寿
+    // child 重挂到同会话后起的 run 行(launch 溯源被静默改写);孤儿(未成功)下拍再试。
     const resolveParentId = (parentInput, domain, childScope) => {
+        // codex R5:**每一条**解析分支都同租户校验(r.scope === childScope)——submit 收任意 sessionId,
+        // 碰撞可让 A 家的孙冻结到 B 家的行(fleet-wide 视图伪嵌套)。跨租户一律按未命中:孤儿顶格,fail-closed。
+        // codex(1.350 四轮):解析带**域标**——session 域链接(parentSessionLink)跳过行 id 直查与 uuid 别名
+        // 两分支(会话 id 由调用方任报,与既有 run 行 id 撞值时直查会把孩子冻到无关 run 上),只走 sessionId
+        // 匹配译臂;task 域三分支全走。
         const rows = bus.snapshot().tasks;
         if (domain === "task") {
             if (rows.some((r) => r.id === parentInput && r.scope === childScope))
                 return { id: parentInput, resolved: true };
         }
+        // codex R4(M-B)+ PAIR-REVIEW F-1:嵌套 bg 孙的父链接=父 **agent 的 uuid**——core 1.350+ 真实帧形里
+        // 该值落 **parentSessionId**(session 域;[1344]② 钳掉了洗域 parentTaskId),所以别名逆查必须对
+        // **两个域**开放(此前只挂 task 域=1.351 下三臂死代码,PAIR-REVIEW F-1 CONFIRMED)。scope-safe:
+        // 别名命中恒要求同租户(R5 的禁令针对**行 id 直查**分支——那才是任报值撞行的面;别名表是本
+        // publisher 自记的 spawn 事实,加租户校验后无跨户面)。
         for (const [aStar, pm] of meta) {
             if (pm.aliasUuid === parentInput && pm.tenantScope === childScope) {
                 if (rows.some((r) => r.id === aStar && r.scope === childScope))
@@ -224,14 +400,20 @@ export function fleetBackgroundChildPublisher(bus, log) {
         }
         let match;
         for (const r of rows) {
+            // codex R7(high):会话译只认**真 run 行**——排除一切本 publisher 记账的 a* child 行(meta 键)。
+            // session-scoped a* 孤儿行同样带 sessionId、R6 后无 parentId、同 scope,不排除则孤儿 tick 会把
+            // **自己**(或同门孤儿)选成父并冻结=自环树,晚到的真 run 行永远接不上。
             if (r.sessionId === parentInput && r.parentId === undefined && r.scope === childScope && !meta.has(r.id))
-                match = r.id;
+                match = r.id; // 后写覆盖=取最近的同租户 run 行
         }
         return match !== undefined ? { id: match, resolved: true } : { id: parentInput, resolved: false };
     };
     const rowTags = (m) => {
+        // codex R6:未解析成功=**不发 parentId**(原值只留 Meta 供下拍重试)。发原值就是 [1338]③ 伪影本身
+        // (悬空 parentId 指向不存在的行),且 fleet-wide 视图上一个撞值的外租户行 id 会在渲染端伪嵌套——
+        // 行早发孤儿顶格、解析成功后 MERGE 升级补 parentId,两边都诚实。
         let parentId;
-        const parentInput = m.parentTaskId ?? m.parentSessionLink;
+        const parentInput = m.parentTaskId ?? m.parentSessionLink; // 1.350 fallback 形:会话域链接同走解析臂(带域标)
         if (parentInput) {
             if (m.resolvedParentId !== undefined) {
                 parentId = m.resolvedParentId;
@@ -248,8 +430,8 @@ export function fleetBackgroundChildPublisher(bus, log) {
             ...(m.tenantScope ? { scope: m.tenantScope } : {}),
             ...(m.hostSessionId ? { sessionId: m.hostSessionId } : {}),
             ...(parentId !== undefined ? { parentId } : {}),
-            ...(m.workflowRunId !== undefined ? { workflowRunId: m.workflowRunId } : {}),
-            ...(m.parentToolCallId !== undefined ? { parentToolCallId: m.parentToolCallId } : {}),
+            ...(m.workflowRunId !== undefined ? { workflowRunId: m.workflowRunId } : {}), // [1440] 附注位透传
+            ...(m.parentToolCallId !== undefined ? { parentToolCallId: m.parentToolCallId } : {}), // P1-2(core 1.432)E2 原值域
             ...(m.spawnedAt !== undefined ? { startedAt: m.spawnedAt, elapsedMs: Date.now() - m.spawnedAt } : {}),
         };
     };
@@ -262,25 +444,51 @@ export function fleetBackgroundChildPublisher(bus, log) {
             return u.tokens;
         return undefined;
     };
+    // design/158 A13: the three event-kind branches below are named local functions — same closure scope/capture
+    // as when they were inline `if (e.kind === "...") { ... }` blocks in the returned dispatcher (behavior
+    // identical), alongside the already-named helpers above (dlog/remember/resolveParentId/rowTags/sumUsage).
     const handleSpawn = (e) => {
+        // PAIR-REVIEW F-3:revive spawn(spawn-after-tombstone)缺父字段时**继承墓碑 Meta 的父链**——
+        // 上一周期已解析冻结的 parentTaskId/resolvedParentId 不因重建丢失(core 1.351 revive spawn 不回放
+        // 父链;1.352 回放件到货后此臂自然让位,双保险)。只在新帧零父字段时继承,新值恒赢。
         const tomb = meta.get(e.taskId);
         const inheritParent = !e.parentTaskId && !e.parentSessionId && tomb?.done === true;
         const m = {
+            // codex 两轮(1.350 适配):core 1.350 起 fallback 形不再发洗域 parentTaskId([1364]②),补偿链接改走
+            // 声明字段 parentSessionId(/v1/tasks/stream 主车道 spec.taskId 未设=恰此形)。**两域分存**——
+            // parentTaskId=真任务域(可直出 wire),parentSessionLink=会话域(仅作行嵌套解析输入,绝不冒充
+            // 任务 id 出 bg_notification)。
             ...(e.parentTaskId ? { parentTaskId: e.parentTaskId } : {}),
             ...(!e.parentTaskId && e.parentSessionId ? { parentSessionLink: e.parentSessionId } : {}),
             ...(inheritParent && tomb?.parentTaskId !== undefined ? { parentTaskId: tomb.parentTaskId } : {}),
             ...(inheritParent && tomb?.parentSessionLink !== undefined ? { parentSessionLink: tomb.parentSessionLink } : {}),
             ...(inheritParent && tomb?.resolvedParentId !== undefined ? { resolvedParentId: tomb.resolvedParentId } : {}),
+            // session-scoped: registry owner IS the host sessionId (design/129 owner key); fork spawns also carry
+            // the child's uuid sessionId — that is the a*↔uuid cross-system anchor, NOT the host session, so it is not used here.
+            // [1522] LOW4:session-scoped 臂同样 root-first(另两臂 1.250 已升)——嵌套 session-scoped 形
+            // 的 owner=中间层子会话 uuid,标它=over-filter;显式 root 到货即锚 root(近死码但一处改齐)。
             ...(e.sessionScoped && e.owner ? { hostSessionId: e.rootSessionId ?? e.owner } : {}),
+            // 🔴 scope DOMAIN mapping: core's registry scope is `ctx.principal ?? deployment scope` —
+            // UNDEFINED on a single-user no-principal deployment — while the service fleet domain keys the
+            // no-principal caller as "default" (`gatedPrincipal ?? "default"`, streamFleet's callerScope). Without
+            // this map the row/notification carried NO scope and the scoped stream dropped EVERYTHING (fail-closed
+            // — the "terminal/bg_notification 零帧" repro). Same principal string in both domains when
+            // a principal exists, so the map is exact.
             tenantScope: e.scope ?? "default",
             sessionScoped: e.sessionScoped,
+            // core 1.367 δ:真 launch 锚(revive=wake 时刻)优先;旧 core 帧回落收帧时刻([1338]④ 原形)
             spawnedAt: e.startedAt ?? Date.now(),
             ...(e.rootSessionId ? { rootSessionId: e.rootSessionId } : {}),
-            ...(e.parentToolCallId ? { parentToolCallId: e.parentToolCallId } : {}),
-            ...(e.sessionId ? { aliasUuid: e.sessionId } : {}),
-            ...(e.workflowRunId ? { workflowRunId: e.workflowRunId } : {}),
+            ...(e.parentToolCallId ? { parentToolCallId: e.parentToolCallId } : {}), // P1-2(core 1.432,12 发射点全带)
+            ...(e.sessionId ? { aliasUuid: e.sessionId } : {}), // codex R4(M-B):uuid↔a* 别名(fork spawn 带 forkedId)
+            ...(e.workflowRunId ? { workflowRunId: e.workflowRunId } : {}), // [1440] wa* 归属附注
+            // codex 1.240-R1/R2(H 行半场):wa\* 帧 sessionScoped:false 无 host owner → 行无 sessionId=
+            // 「absent=同 principal 全会话可见」(bg 兼容语义,对 wa\* 是泄露面)。归属源两级:①**信任源**
+            // core 帧的 parentSessionId(发起会话,1.350 声明字段——R2:无 runStore 的瞬态 sync 部署没有宿主
+            // fleet 行,行查 fallback 必空);②宿主行 sessionId 查表(同租户)兜底。
             ...(e.workflowRunId && !(e.sessionScoped && e.owner)
                 ? (() => {
+                    // core 1.367 δ:显式 root 锚(spawnAttribution 把 root 传进每个 workflow-agent)——信任源第一
                     if (e.rootSessionId)
                         return { hostSessionId: e.rootSessionId };
                     if (e.parentSessionId)
@@ -289,6 +497,33 @@ export function fleetBackgroundChildPublisher(bus, log) {
                     return host?.sessionId ? { hostSessionId: host.sessionId } : {};
                 })()
                 : {}),
+            // [1493] cross-session isolation: a NON-session-scoped, non-wa* bg child (owner = the run taskId — the
+            // norm when backgroundScope!="session", i.e. every multi-tenant deployment, and any local path where the
+            // session isn't adopted at spawn) STILL carries a host session on core's declared parentSessionId
+            // (subagent.js registerBackgroundAgent). Without promoting it to hostSessionId the row/notification is
+            // session-UNTAGGED → streamFleet's `?session=` filter fails OPEN → the completion is broadcast (and
+            // model-injected) into every same-principal shell (clay's dual-shell repro). Promote it so the filter
+            // narrows precisely. (Session-scoped children already tag via the `owner` arm above; wa* via its own arm
+            // just above — both are excluded by this condition, so no double-write.) The terminal event does NOT
+            // repeat parentSessionId (core emits it on spawn only), so this MUST be captured into Meta here at spawn.
+            //
+            // codex R1 (nested-agent mis-tag): parentSessionId is core's `ctx.sessionId`, which for a NESTED bg child
+            // (spawned BY a subagent) is the PARENT AGENT's child-session uuid, NOT the shell's root session. Tagging
+            // that uuid as hostSessionId would make the outer host shell FAIL the ownerSessionId check (row +
+            // completion suppressed, durable ack fence keyed wrong). So resolve through the alias table (same reverse
+            // lookup resolveParentId uses): if some agent Meta's aliasUuid === parentSessionId, this is nested —
+            // inherit THAT agent's already-resolved hostSessionId (the root shell session), or stay UNTAGGED when the
+            // parent itself is untagged. Only a TOP-LEVEL bg child (parentSessionId is the shell root, aliased by no
+            // agent) uses parentSessionId directly. Tenant-scoped like every other alias/parent resolution (R5).
+            // fable5 R1 (honest residual): a nested child whose parent Meta is ABSENT (restart lazy-mint edge — live
+            // Meta is never evicted, so within one process the parent always exists at spawn time) is
+            // INDISTINGUISHABLE from top-level and gets tagged with the given uuid. That is still SAFE: a
+            // child-session uuid is never any shell's own session, so no scoped subscriber matches it — the failure
+            // direction is over-filtering (the true owner misses live delivery; durable inbox/stream-open drain
+            // compensate), never cross-delivery. Root fix = core carrying an explicit root-host-session (or a
+            // top-level/nested discriminator) on the spawn event — asked as a core seam follow-up ([1493]).
+            // core 1.367 δ:[1493] fable5-R1 注里请的 root fix **到货**——spawn 帧显式带 rootSessionId
+            // (固定点语义,嵌套孙代恒=root shell 会话),信任源直用;alias 反查臂降为旧 core 帧回落。
             ...(!(e.sessionScoped && e.owner) && !e.workflowRunId && (e.rootSessionId ?? e.parentSessionId)
                 ? (() => {
                     if (e.rootSessionId)
@@ -296,19 +531,34 @@ export function fleetBackgroundChildPublisher(bus, log) {
                     const childScope = e.scope ?? "default";
                     for (const pm of meta.values()) {
                         if (pm.aliasUuid === e.parentSessionId && (pm.tenantScope ?? "default") === childScope) {
-                            return pm.hostSessionId ? { hostSessionId: pm.hostSessionId } : {};
+                            return pm.hostSessionId ? { hostSessionId: pm.hostSessionId } : {}; // nested: inherit root (or stay untagged → Part B)
                         }
                     }
-                    return { hostSessionId: e.parentSessionId };
+                    return { hostSessionId: e.parentSessionId }; // top-level: parentSessionId IS the shell root session
                 })()
                 : {}),
         };
         remember(e.taskId, m);
+        // [1364]③:spawn 帧 1.349+ 也带 agentType(类型名)/name——行 name 位保 description(display 标签,
+        // 历史语义),TYPE 列自 spawn 即亮(此前要等首 tick 自愈)。
+        // [1827]①(cli):spawn 行也透传 transcriptId(委派 prompt 的映射,详情页运行中即可取件)。
+        // 现状 core 只在 terminal 事件带此键(三发射点亲核)⇒ 本透传对旧 core 惰性;core 停 spawn/tick
+        // 源头补上即通,tick 臂(下方 :78x)早已同姿。server 不自行以 sessionId 推导——fork lane 的
+        // forkTranscriptId 与 sessionId 的等价关系归 core 所有,不在消费端烙死。
         bus.publishTask({ id: e.taskId, name: redactSecrets(e.description ?? e.name ?? e.taskId), ...(e.agentType ? { agentType: redactSecrets(e.agentType) } : {}), ...rowTags(m), status: "running", tokens: 0, ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}) });
         dlog("bg_child_event", { kind: "spawn", taskId: e.taskId, sessionScoped: e.sessionScoped, scope: m.tenantScope, hostSessionId: m.hostSessionId ?? null, parentTaskId: m.parentTaskId ?? null });
     };
     const handleTick = (e, m) => {
+        // dedup the per-leg uuid-keyed twin ONCE: the leg's onForwardEvent keys the same child's rows by
+        // `${runId} ${uuid}` and on the /v1/runs path runId === the host canonical taskId (spec.taskId is the
+        // durable run id). The tick that carries the child's OWN frame has progressParentTaskId === the host
+        // taskId (a NESTED grandchild carries the child's uuid instead — never suppressed here). A miss is a
+        // no-op remove (best-effort; worst case = a transient duplicate row until the leg settles, old behavior).
         if (!m.suppressedTwin && e.progressTaskId && (!e.progressParentTaskId || e.progressParentTaskId === (m.parentTaskId ?? m.parentSessionLink))) {
+            // The per-leg childId is `${run.runId} ${uuid}` and runId ≠ the core hostTaskId on the
+            // sync-stream/resume paths (durableTaskId vs canonical sessionId), so a composite-key guess misses there.
+            // Scan-by-suffix instead: the uuid tail uniquely names the child across every leg's runId prefix. One-shot
+            // (suppressedTwin) so the O(rows) scan runs once per child.
             const tail = ` ${e.progressTaskId}`;
             for (const row of bus.snapshot().tasks) {
                 if (row.id.endsWith(tail))
@@ -316,6 +566,13 @@ export function fleetBackgroundChildPublisher(bus, log) {
             }
             m.suppressedTwin = true;
         }
+        // codex R8:普通(非 fork)bg producer 的 spawn 不带 sessionId,uuid 别名要等 terminal 才现——嵌套孙
+        // 在父运行期解析全 miss。但 child 本人的 tick 恒带 progressTaskId=其 uuid(与双生抑制同一判别形),
+        // 首 tick 即学别名;孙侧 retry-until-success 语义随后一拍自然接上(spawn 路径已带 sessionId 的 fork 形
+        // 不受影响,??= 只补缺)。
+        // codex R9:别名习得**即回填**——快孙可能已无后续帧(spawn+tick+terminal 全在父首 tick 前),等孙自己
+        // retry 就永远孤儿。习得此刻主动扫在场未解析孤儿,替它们把行升级(rowTags 内解析+冻结)。彻底闭窗
+        // (孙整个生命周期都在别名前走完的瞬态孤儿)在 core:普通形 spawn emit 补 sessionId(fork 形已带)。
         if (m.aliasUuid === undefined && e.progressTaskId && (!e.progressParentTaskId || e.progressParentTaskId === (m.parentTaskId ?? m.parentSessionLink))) {
             m.aliasUuid = e.progressTaskId;
             for (const [cid, cm] of meta) {
@@ -326,15 +583,30 @@ export function fleetBackgroundChildPublisher(bus, log) {
         }
         const tokens = sumUsage(e.usage);
         const name = e.name ? redactSecrets(e.name) : undefined;
+        // [1364]③ K-7 换位:TYPE 列取 tick 帧的行级 `agentType`(core 1.350 定谳:`name` 位=display 标签
+        // ——description 充是历史语义非 bug,类型名在 agentType 位)。缺省回落 name(旧 core 兼容,原行为)。
         const agentType = e.agentType ? redactSecrets(e.agentType) : name;
+        // The sink tick carries core's currentAction (its only attachment point today) —
+        // UNTRUSTED (tool argument head) → redact, same discipline as name. Additive; absent until a tool runs.
         const currentAction = e.currentAction ? redactSecrets(e.currentAction) : undefined;
+        // [1827]②/core 1.429:结构化同源体。字段 PICKED(不整对象 spread——future core 键不得裸骑);
+        // toolName verbatim,target 与 currentAction 同边界(redact + 300 bound,brainStatus.detail 同惯例)。
         const currentTool = e.currentTool
             ? { toolName: e.currentTool.toolName, ...(e.currentTool.target !== undefined ? { target: redactSecrets(e.currentTool.target).slice(0, 300) } : {}) }
             : undefined;
+        // cli [1748]:两个 additive 位。`toolUses` 是**累计值**(与 turn_end 的每轮增量相反)⇒ 直接上行不累加;
+        // 缺席时**不发这个键**(消费方不得把缺席当 0)。`transcriptId` 是委派 prompt 的**映射** ——
+        // prompt 本身不在 `BackgroundChildEvent` 上,server 收不到就不造。
         bus.publishTask({ id: e.taskId, ...rowTags(m), status: "running", ...(tokens !== undefined ? { tokens } : {}), ...(name ? { name } : {}), ...(agentType ? { agentType } : {}), ...(currentAction ? { currentAction } : {}), ...(currentTool ? { currentTool } : {}), ...(e.usage?.toolUses !== undefined ? { toolUses: e.usage.toolUses } : {}), ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}) });
     };
     const handleTerminal = (e, m) => {
+        // terminal: flip the row so subscribers SEE the terminal frame, then leave the fleet — and push the
+        // contract bg_notification on the always-open lane (缺口②: idle delivery is immediate; the durable
+        // inbox park stays as the offline/replay belt, shell dedups by (taskId,status)).
         const status = e.status === "completed" ? "completed" : e.status === "killed" ? "killed" : "failed";
+        // [1839]①/(a) 案:终态**行帧**同带残局键——此前只有 {id,status},看行卡(不订通知帧)的 idle 观察者
+        // 拿不到终局。与下方 bg_notification 同源同姿势:键逐挑不 spread、editedFiles path 过 redactSecrets
+        // + 100 界、缺席不铸。(recentSteps 不进行帧——通知卡语义,行卡不渲染步骤列表。)
         bus.publishTask({
             id: e.taskId, ...rowTags(m), status,
             ...(e.stoppedBy ? { stoppedBy: e.stoppedBy } : {}),
@@ -355,6 +627,9 @@ export function fleetBackgroundChildPublisher(bus, log) {
                 : {}),
         });
         bus.removeTask(e.taskId);
+        // codex 1.240-R1(M2):1.356 的回调序=bceTick 先于 host forward——tick 处的双生抑制扫在 uuid 双生
+        // 行发布**之前**,one-shot 空扫后置旗,双生行永存。terminal 补扫一次(aliasUuid=tick 学到的 child
+        // uuid),把 run-leg 的复合键行清场。
         if (m.aliasUuid) {
             const tail = ` ${m.aliasUuid}`;
             for (const row of bus.snapshot().tasks) {
@@ -362,19 +637,32 @@ export function fleetBackgroundChildPublisher(bus, log) {
                     bus.removeTask(row.id);
             }
         }
+        // codex 1.240-R1(H1):wa\*(workflowRunId 在)不走 bg_notification 契约——该帧族=后台任务完成通知
+        // (壳注入模型),workflow 的完成通知已有 workflow_complete 专链;且 1.356 wa\* 帧 sessionScoped:false
+        // 无 host owner → 通知无 ownerSessionId=同租户**全会话**可见(streamFleet 的 absent-放行是 bg 兼容位,
+        // 不是 wa\* 的授权)。per-agent 完成本就不该打断模型(CC 亦无此形)。
         if (m.workflowRunId !== undefined) {
-            m.done = true;
+            m.done = true; // codex 1.240-R2(M):早退分支必须先落墓碑——迟到/重放 tick 不得复活已离场的 wa* 行
             dlog("bg_child_event", { kind: "terminal-wa-no-notification", taskId: e.taskId, workflowRunId: m.workflowRunId });
             return;
         }
         bus.publishBgNotification({
             taskId: e.taskId,
             ...(e.sessionId ? { sessionId: e.sessionId } : {}),
+            // [1392]①(PAIR-REVIEW F-1@cli 的 wire 前置):终帧 seq(core 1.352 BackgroundChildEvent.terminal 补位,
+            // tolerate-absent——旧 core 无此位=不发,cli 键折 seq 的修依赖它区分 revive 周期)。
             ...(typeof e.seq === "number" ? { seq: e.seq } : {}),
             status: e.status ?? "failed",
             ...(e.summary ? { summary: redactSecrets(e.summary) } : {}),
             scope: (m.sessionScoped || e.sessionScoped) ? "session" : "task",
+            // codex(1.350 二轮):wire 的 parentTaskId 位只出真任务域;fallback 形出解析成功的 run 行 id
+            // (=durable run id,消费者拿它绑父行),解析未成=省略,绝不让会话 id 冒充任务 id 出 wire。
             ...(m.parentTaskId ? { parentTaskId: m.parentTaskId } : m.resolvedParentId ? { parentTaskId: m.resolvedParentId } : {}),
+            // The residual fields must ride THIS lane too (the "kill across turns" main line renders
+            // off it). Same posture as project.ts/inbox; fields picked, arrays defensively bounded.
+            // P1-3(core 1.452,[1925] 一轮批):completionId=子代完成的幂等锚,消费端(cli)按它对同一完成的
+            // 多路通知(bg_notification/task_notification/inbox 重放)去重。verbatim 透传,仅通知帧带
+            // (行帧不带——行的身份是 taskId,幂等锚是通知语义)。
             ...(e.completionId ? { completionId: e.completionId } : {}),
             ...(e.stoppedBy ? { stoppedBy: e.stoppedBy } : {}),
             ...(e.resumable !== undefined ? { resumable: e.resumable } : {}),
@@ -382,6 +670,7 @@ export function fleetBackgroundChildPublisher(bus, log) {
                 ? { recentSteps: e.recentSteps.slice(0, 10).map((s) => ({ tool: s.tool, target: redactSecrets(s.target), outcome: redactSecrets(s.outcome) })) }
                 : {}),
             ...(e.editedFiles !== undefined ? { editedFiles: e.editedFiles.slice(0, 100).map((f) => ({ path: redactSecrets(f.path), edits: f.edits })) } : {}),
+            // [1543]§二 LOW:usage/transcriptId 补齐(fields picked——usage 六数值键逐一挑,不整对象 spread)。
             ...(e.usage
                 ? {
                     usage: {
@@ -395,13 +684,14 @@ export function fleetBackgroundChildPublisher(bus, log) {
                 }
                 : {}),
             ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}),
-            ...(e.parentToolCallId ? { parentToolCallId: e.parentToolCallId } : {}),
+            ...(e.parentToolCallId ? { parentToolCallId: e.parentToolCallId } : {}), // P1-2(core 1.432)——通知帧同带,cli「全部生命周期事件在场」
             ...(m.tenantScope ? { ownerScope: m.tenantScope } : {}),
             ...(m.hostSessionId ? { ownerSessionId: m.hostSessionId } : {}),
             ...(m.rootSessionId ? { rootSessionId: m.rootSessionId } : {}),
         });
+        // One info line per terminal so the emit-vs-filter bisect is a log-grep, not a rerun.
         dlog("bg_child_event", { kind: "terminal", taskId: e.taskId, status, scope: m.tenantScope ?? null, hostSessionId: m.hostSessionId ?? null, childSessionId: e.sessionId ?? null, bgNotificationPublished: true });
-        m.done = true;
+        m.done = true; // tombstone (kept in the bounded map) — see Meta.done
         m.suppressedTwin = true;
     };
     return (e) => {
@@ -409,18 +699,20 @@ export function fleetBackgroundChildPublisher(bus, log) {
             handleSpawn(e);
             return;
         }
-        const m = meta.get(e.taskId) ?? { sessionScoped: e.sessionScoped, tenantScope: "default", spawnedAt: Date.now() };
+        const m = meta.get(e.taskId) ?? { sessionScoped: e.sessionScoped, tenantScope: "default", spawnedAt: Date.now() }; // scope domain map holds on the lazily-minted path too([1338]④ 首见起表)
         if (!meta.has(e.taskId)) {
-            remember(e.taskId, m);
+            remember(e.taskId, m); // tick/terminal without a seen spawn (restart/eviction edge) — row minted lazily
             dlog("bg_child_event", { kind: `${e.kind}-lazy-mint`, taskId: e.taskId, sessionScoped: e.sessionScoped });
         }
         else {
-            remember(e.taskId, m);
+            remember(e.taskId, m); // codex:活儿每拍刷新近度——LRU 兜底永远先挤最久没动静的,不挤在跑的
         }
         if (m.done) {
+            // tombstone: this child already settled — a late tick must not resurrect a running row (settle-freeze 同族).
             dlog("bg_child_event", { kind: `${e.kind}-after-terminal-ignored`, taskId: e.taskId });
             return;
         }
+        // P1-2(core 1.432):lazy-mint/spawn 前旧 core 帧路径——parentToolCallId「出生就在场」,首见即补
         if (m.parentToolCallId === undefined && e.parentToolCallId)
             m.parentToolCallId = e.parentToolCallId;
         if (e.kind === "tick") {
@@ -430,15 +722,26 @@ export function fleetBackgroundChildPublisher(bus, log) {
         handleTerminal(e, m);
     };
 }
+/** BC-1 (clay-decided 2026-06-27): a top-level run's fleet-row `name` = a SHORT, single-line **objective preview**
+ *  (the readable "what is this task" label) — NOT the full objective dumped in, and NOT duplicated into `description`.
+ *  `description` is left to the publisher's LIVE-ACTIVITY update (`onEvent` tool_start → the current tool), so the row
+ *  shows `name`=objective + `description`=current activity (two DISTINCT things, killing the earlier "objective shown
+ *  twice" dup). Whitespace-collapsed + capped ≤48. (A subagent CHILD row's name = its agent-type — BC-2.)
+ *  SECRET-SAFE: redact secret shapes (redactSecrets) BEFORE truncating — a secret in the objective must not leak in
+ *  the row name. The durable objective is already redacted; the name preview was asymmetric (raw) until this. */
 export function fleetRunLabels(objective) {
     const oneLine = redactSecrets((objective ?? "").replace(/\s+/g, " ")).trim();
     if (!oneLine)
         return { name: "task" };
+    // [1414]④:控制帧形 objective(注入 turn 的 `<task-notification>…` 等 XML 头)不得当行名——用户底部
+    // 会看到「<task-notifica…」尖括号伪影。以 `<` 开头且形如 XML tag 的 objective 给中性名;真实用户
+    // objective 以 `<` 开头的形(粘贴 HTML 片段)极罕且中性名无害。
     if (/^<[a-z][a-z0-9_-]*[\s>/]/i.test(oneLine))
         return { name: "(notification turn)" };
     const name = oneLine.length > 48 ? `${oneLine.slice(0, 47)}…` : oneLine;
     return { name };
 }
+/** Map a service run status onto the neutral fleet vocabulary the shell renders. */
 export function runStatusToFleet(status, opts) {
     if (opts?.awaitingPlanApproval)
         return "awaiting approval";
@@ -451,10 +754,13 @@ export function runStatusToFleet(status, opts) {
             return "completed";
         case "failed":
         case "error":
-        case "blocked":
+        case "blocked": // report_blocked = a non-success TERMINAL outcome (agent gave up) → the "failed" bucket (the
+            // neutral fleet vocab has no "blocked"). CRUCIAL: this also lets onTerminal REMOVE the row — the removal set is
+            // {completed,failed,killed}, so without mapping "blocked" here it fell through to the "idle" default and a
+            // terminal blocked run LEAKED a permanent stale "idle" row on the fleet (caught by on-box e2e, 2026-06-28).
             return "failed";
         case "suspended":
-            return "waiting";
+            return "waiting"; // a durable suspend = parked, awaiting resume
         case "needs_review":
             return "awaiting approval";
         case "killed":