@sema-agent/server 7.24.0 → 7.25.0-rc.1

package/dist/boot/shutdown.d.ts

@@ -28,6 +28,14 @@ export interface ShutdownCtx {
     logger: Logger;
     server: ReturnType<typeof createHttpServer>;
     reaper: NodeJS.Timeout;
+    /** #261:fleet 存活对账腿(60s 定时器 + 总线订阅)。与 `reaper` 同列文件头契约 3 —— 收尾期不该再有
+     *  对账 tick 打向正在关闭的池,订阅也要摘(否则 bus 的扇出还在往一个已停的观察者写)。 */
+    fleetReconcile: {
+        timer: NodeJS.Timeout;
+        reconciler: {
+            stop(): void;
+        };
+    };
     otelExporter: ReturnType<typeof startOtlpExporter> | undefined;
     breakerState: ReturnType<BreakerStateStore["startRefresh"]> | undefined;
     costQuota: CostQuota | CostQuotaStore | undefined;

package/dist/boot/shutdown.js

@@ -18,7 +18,7 @@ import { createSighupIdleHandler } from "../sighup-idle.js";
 import { createParentWatch } from "../parent-watch.js";
 /** 注册 SIGTERM/SIGINT/SIGHUP 收尾链。**必须在 listen 之后调用**(见文件头「位置即契约」)。 */
 export function installShutdownHandlers(ctx) {
-    const { config, logger, server, reaper, otelExporter, breakerState, costQuota, rateLimiter, runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState, storeLiveProbe, configCenter, } = ctx;
+    const { config, logger, server, reaper, fleetReconcile, otelExporter, breakerState, costQuota, rateLimiter, runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState, storeLiveProbe, configCenter, } = ctx;
     let closing = false;
     /** #219:parent 监视腿(装配在本函数尾,`config.parentPid` 在场才建)。声明提前只为让 hardShutdown
      *  能把它一并停掉 —— 文件头契约 3 同族(收尾期不再有后台 tick)。 */
@@ -28,6 +28,8 @@ export function installShutdownHandlers(ctx) {
             return;
         closing = true;
         clearInterval(reaper);
+        clearInterval(fleetReconcile.timer); // #261:契约 3 同族——收尾期不再有对账 tick 打向正在关闭的池
+        fleetReconcile.reconciler.stop(); // 摘总线订阅(观察者已停,扇出不该再喂它)
         parentWatch?.stop(); // #219:契约 3 同族——收尾期不再探父进程
         storeLiveProbe?.stop(); // #131-2:契约 3 同族——收尾期不再有探针 tick 打向正在关闭的池
         configCenter?.stopRefreshLoop(); // #131-2:停机中途不再热应用配置

package/dist/fleet/fleet-bus.d.ts

@@ -134,6 +134,32 @@ export interface FleetTaskRow {
      *  自己发明「复合 id 首段==parentId 且撞 (parentId,name)」那类集合级判据(cli 侧的防御税)。
      *  ADDITIVE / tolerate-absent。 */
     sourceLane?: "run-leg";
+    /**
+     * #261 §2①(core 5.36.0 #258 供给,server 白名单透传):这一行的**代际号**。语义 = core 的
+     * stop-cycle 计数(fresh spawn IS cycle 1,每次复活翻转 +1),与 `bg_notification.seq` /
+     * `task_progress.seq` / `BackgroundChildEvent.seq` **同域同轴**(core 原话:一条轴,不是第三种拼法)。
+     *
+     * 消费端读法(定死,防两端各写):同 id 帧 `cycleSeq` **更大 ⇒ 复活**(新代际,行内累计量重置);
+     * **更小 ⇒ 前代迟到帧,忽略**(不回退——本仓在 {@link FleetEventBus.publishTask} 里 merge 前就判掉了,
+     * 消费端拿到的流已经是单调的);**缺席 ⇒ 回落现行为**(tolerate-absent)。
+     *
+     * 🔴 缺席是**事实**不是缺口(core [4043] 逐字定谳,以其措辞为准):没有 `a*` registry 行的 run
+     * ——同步委派子代、workflow `wa*` agent、**顶层 run 行**——根本没有代际概念,「缺席即『无此概念』,
+     * 非『第一代』」。任何把缺席读成 1 的消费端都会把「首帧迟到」误判成「复活」。
+     * ADDITIVE / tolerate-absent。
+     */
+    cycleSeq?: number;
+    /**
+     * #261 §2②:这一帧的终态**不是发布方亲报**,而是对账腿({@link ../fleet/fleet-reconciler.js})
+     * 从 durable run 行**投影**出来的 —— 发布方死了(事件环异常中断 / 引擎被壳 reuse 而旧 run 对象已死 /
+     * BCE 终态通知丢失),行本会永久僵在 `tasks` Map 里当幽灵。
+     *
+     * 词表现为**单词闭集**;读侧按 SDK 开集读纪律(未来若有第二个投影者,它会是一个新词而不是改义)。
+     * 发布方亲报的终态帧**恒不带**此键 —— 两种终态在 wire 上因此**可判**(消费端要区分「引擎说它完了」
+     * 与「我们从库里读出来它完了」时,这是唯一的判据)。只在终态帧出现。
+     * ADDITIVE / tolerate-absent。
+     */
+    retiredBy?: "reconcile";
 }
 /** One workflow row (wire subset of contract `FleetWorkflow`). */
 export interface FleetWorkflowRow {
@@ -185,6 +211,22 @@ export type FleetFrame = {
     type: "task_remove";
     id: string;
     ts: number;
+    /**
+     * #261 §2③:**陈述级退场** —— 行没了,但**没有**结算语义。对照:无此键的 remove = 终态之后的
+     * 常规清场(发布方亲报终态、或 `retiredBy:"reconcile"` 的投影退休,两者都先发过终态 `task` 帧)。
+     *
+     * 铸点只有对账腿:durable 说这条 run 还 `running`(reaper 宽限窗内)、或 claim 在他副本、或
+     * durable 行压根不存在 —— 三形共同点是**没有终局可投影**,而本副本的行必然陈旧。此时造一个终态
+     * 就是编:判死的属主始终是 durable 侧的 reaper。所以只陈述「这条行离场了」,不逼消费端结算。
+     * (cli 侧裁量 [4044]:渲「离场」**不清行** —— 行保留、中性离场形、active 扣除、折叠排后。)
+     * ADDITIVE / tolerate-absent。
+     */
+    removeReason?: "orphaned";
+    /** #261 §2 判死×判代合成规则:退场帧带**被退那一代**的 {@link FleetTaskRow.cycleSeq}。
+     *  消费端因此能把 `retire(gen=N)` 之后的 `frame(gen=N+1)` 读成**复活**(行重生,退休不粘住新代),
+     *  而 `retire(gen=N)` 之后的 `frame(gen=N)` 读成**前代迟到帧,忽略**。缺席同 {@link FleetTaskRow.cycleSeq}
+     *  ——「无此概念」,不是「第一代」。 */
+    cycleSeq?: number;
 } | {
     type: "workflow";
     row: FleetWorkflowRow;
@@ -299,6 +341,10 @@ export declare class FleetEventBus {
     private readonly emitter;
     private readonly tasks;
     private readonly workflows;
+    /** #261 / codex R1-F2:**代际墓碑** —— 已离场行的最后已知 `cycleSeq`(行本身已从 `tasks` 删掉,
+     *  代际状态却必须活得比行久一点,否则前代迟到帧会在空 Map 上把幽灵行重铸出来)。有界 LRU。 */
+    private readonly retiredGen;
+    private static readonly RETIRED_GEN_MAX;
     constructor(now?: () => number);
     /** 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. */
@@ -307,8 +353,15 @@ export declare class FleetEventBus {
     }): void;
     /** 推一帧 hook 判定未完成的观测通知(事件语义,不进 snapshot —— 与 `bg_notification` 同族)。 */
     publishHookNotice(notice: HookNotice): void;
-    /** Drop a task row (terminal + swept) + fan out the removal. Idempotent (a no-op if already gone). */
-    removeTask(id: string): void;
+    /** Drop a task row (terminal + swept) + fan out the removal. Idempotent (a no-op if already gone).
+     *
+     *  `opts`(#261,两键均 ADDITIVE):`removeReason:"orphaned"` = **陈述级退场**(没有结算语义,见
+     *  {@link FleetFrame} 的 `task_remove` 臂);`cycleSeq` = 被退那一代的代际号。发布方的常规清场
+     *  (`onTerminal`/`onChildTerminal`)不传 opts ⇒ 帧逐字节与本改动之前相同。 */
+    removeTask(id: string, opts?: {
+        removeReason?: "orphaned";
+        cycleSeq?: number;
+    }): void;
     private readonly bceClaims;
     private static readonly BCE_CLAIM_MAX;
     private static bceKey;
@@ -369,6 +422,7 @@ export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
         toolName?: string;
         parentToolCallId?: string;
         status?: string;
+        seq?: number;
     }) => void;
     onForwardEvent: (ev: {
         type?: string;
@@ -378,6 +432,7 @@ export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
         usage?: unknown;
         parentToolCallId?: string;
         status?: string;
+        seq?: number;
     }) => void;
     /** Flip + remove one subagent CHILD row when its background completion notification arrives
      *  (task_progress never emits a terminal tick — without this a bg child sat "running" until parent settle).

package/dist/fleet/fleet-bus.js

@@ -92,6 +92,10 @@ export class FleetEventBus {
     emitter = new EventEmitter();
     tasks = new Map();
     workflows = new Map();
+    /** #261 / codex R1-F2:**代际墓碑** —— 已离场行的最后已知 `cycleSeq`(行本身已从 `tasks` 删掉,
+     *  代际状态却必须活得比行久一点,否则前代迟到帧会在空 Map 上把幽灵行重铸出来)。有界 LRU。 */
+    retiredGen = new Map();
+    static RETIRED_GEN_MAX = 4096;
     constructor(now = () => Date.now()) {
         this.now = now;
         this.emitter.setMaxListeners(0); // unbounded SSE subscribers (each /v1/fleet/stream connection)
@@ -99,9 +103,30 @@ export class FleetEventBus {
     /** 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 existing = this.tasks.get(delta.id);
+        // 🔴 #261 §2 判代闸(**merge 前判**):同 id 上一个**更小**代际的帧 = 前代迟到帧 ⇒ 整帧忽略,
+        // 既不 merge 也不扇出。为什么必须在 merge 之前:MERGE 语义下一个迟到的前代 delta 会把行内累计量
+        // (tokens / elapsedMs / toolUses)**回退**到上一代的读数,而回退过的行再也没人会修正它 ——
+        // 消费端看到的是一条"复活之后 token 越跑越少"的行,且无从判别。判据只在**两边都有**代际号时生效:
+        // 缺席 = 「无此概念」(顶层 run 行恒缺席),不参与比较,行为逐字回落到本闸之前。
+        if (delta.cycleSeq !== undefined && existing?.cycleSeq !== undefined && delta.cycleSeq < existing.cycleSeq)
+            return;
+        // 🔴 同一条判据在**行已离场**之后的半场(codex 对抗复审 R1-F2 [high],红先复现)。上面那条闸只跟
+        // **内存行**比对,而 `removeTask` 顺手把行连同它的代际状态一起删了 —— 于是 `retire(N)` 之后一条
+        // `frame(N)` 会在空 Map 上把行**重新铸出来**,而那条行的发布方恰恰是已经死了(那就是我们退它的理由),
+        // 面板上于是又立起一条永不离场的幽灵行。墓碑补上这一半:行缺席时与**被退那一代**比,不前进的帧一律
+        // 不铸;更大代际(真复活)照常出生。
+        // ⚠️ 例外恰好一个:带 `retiredBy` 的帧**就是**对账腿对"被退那一代"的结算(行已不在 bus,故它必须
+        // 先瞬时重铸再撤 —— 见 fleet-reconciler.ts 的候补窗 flip-through)。它与墓碑说的是**同一代**,拦掉
+        // 它等于让"陈述级退场 → 后来 durable 翻终局 → 补发成对终帧"这条设计承诺静默失效(红先复现)。
+        if (existing === undefined && delta.retiredBy === undefined) {
+            const tomb = this.retiredGen.get(delta.id);
+            if (tomb !== undefined && delta.cycleSeq !== undefined && delta.cycleSeq <= tomb)
+                return;
+        }
         // [2070]③:懒铸底座**不带 name** —— 一条只有 `{id,…}` 的首帧此前会把行 id 铸成显示名,而这里
         // 恰恰是「谁都没给过名字」的位置。真名后到时照常 MERGE 上行(见本文件末的 [2070]③ 第 4 条钉)。
-        const merged = { ...(this.tasks.get(delta.id) ?? { id: delta.id, status: "running" }), ...delta };
+        const merged = { ...(existing ?? { id: delta.id, status: "running" }), ...delta };
         this.tasks.set(delta.id, merged);
         this.emit({ type: "task", row: merged, ts: this.now() });
     }
@@ -109,10 +134,42 @@ export class FleetEventBus {
     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() });
+    /** Drop a task row (terminal + swept) + fan out the removal. Idempotent (a no-op if already gone).
+     *
+     *  `opts`(#261,两键均 ADDITIVE):`removeReason:"orphaned"` = **陈述级退场**(没有结算语义,见
+     *  {@link FleetFrame} 的 `task_remove` 臂);`cycleSeq` = 被退那一代的代际号。发布方的常规清场
+     *  (`onTerminal`/`onChildTerminal`)不传 opts ⇒ 帧逐字节与本改动之前相同。 */
+    removeTask(id, opts) {
+        const existing = this.tasks.get(id);
+        // 🔴 **代际条件删**(codex 对抗复审 R1-F2 反向臂 [high],红先复现):调用方拿的是一份快照,而它
+        // 在 await 里等 durable 读的那几十毫秒里,同一 id 完全可能已经**复活成新一代**(BCE revive spawn /
+        // run-leg 新腿)。无条件删就是拿过期快照把一条**活着的新行**从面板上摘掉 —— 而顶层 run 行没有代际号,
+        // 那一格由调用方的 await-后复核兜(见 fleet-reconciler.ts);有代际号的子代行由这条闸兜。
+        // 请求方没带代际(发布方的常规清场:它就是行的属主,不存在"拿旧快照删新行")⇒ 照旧无条件删。
+        if (existing !== undefined && opts?.cycleSeq !== undefined && existing.cycleSeq !== undefined && existing.cycleSeq > opts.cycleSeq)
+            return;
+        if (this.tasks.delete(id)) {
+            // 代际墓碑:记下**被退那一代**(优先取行上的真值,退化取请求值)。见 publishTask 的墓碑臂。
+            const gen = existing?.cycleSeq ?? opts?.cycleSeq;
+            if (gen !== undefined) {
+                this.retiredGen.delete(id);
+                this.retiredGen.set(id, gen);
+                // 容量兜底:逐最老。丢一条墓碑 = 那个 id 退回本闸之前的行为(迟到帧可重铸,下一个对账周期再退它一次)
+                // —— 可见性回退,不是错行,与 bceClaims 同一条取舍。
+                if (this.retiredGen.size > FleetEventBus.RETIRED_GEN_MAX) {
+                    const oldest = this.retiredGen.keys().next();
+                    if (!oldest.done)
+                        this.retiredGen.delete(oldest.value);
+                }
+            }
+            this.emit({
+                type: "task_remove",
+                id,
+                ts: this.now(),
+                ...(opts?.removeReason !== undefined ? { removeReason: opts.removeReason } : {}),
+                ...(opts?.cycleSeq !== undefined ? { cycleSeq: opts.cycleSeq } : {}),
+            });
+        }
     }
     // ┌─ [2070]①/[2080] 让位登记簿(BCE 车道 → run-leg 车道的单向让位信号)────────────────────────────┐
     // 为什么登记簿而不是"查快照有没有 a* 行":两条车道用**不同 id 域**给同一个 agent 建行(BCE=`a*`/`wa*`
@@ -353,7 +410,8 @@ export function fleetRunPublisher(bus, run) {
                 // [1415]③ 点亮半场:core 1.354 起 settle 时补终态 tick(status 值域 additive 扩 completed|failed;
                 // 此前恒 "running"=行为逐位不变)——workflow 子的 uuid 行终于有完成态可见(running→removed 的
                 // [1414]#3 形就此闭)。
-                bus.publishTask({ id: cid, sourceLane: "run-leg", ...(childName !== undefined ? { name: childName, 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) });
+                // #261 §2:`seq` 透传成行的 `cycleSeq`(**缺席不铸** —— 旧 core 不发这一位,而「缺席禁读作 cycle 1」)。
+                bus.publishTask({ id: cid, sourceLane: "run-leg", ...(childName !== undefined ? { name: childName, agentType: childName } : {}), parentId: run.runId, scope: run.scope, ...sessionField, status: tickStatus(ev.status), tokens: sumTokens(ev.usage), ...(typeof ev.seq === "number" ? { cycleSeq: ev.seq } : {}), ...(() => { 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
@@ -399,7 +457,7 @@ export function fleetRunPublisher(bus, run) {
                 childStartedAt.set(cid, Date.now());
             if (ev.parentToolCallId)
                 childByToolCall.set(ev.parentToolCallId, cid);
-            bus.publishTask({ id: cid, sourceLane: "run-leg", ...(fwdName !== undefined ? { name: fwdName, 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 口径
+            bus.publishTask({ id: cid, sourceLane: "run-leg", ...(fwdName !== undefined ? { name: fwdName, agentType: fwdName } : {}), parentId, scope: run.scope, ...sessionField, status: tickStatus(ev.status), tokens: sumTokens(ev.usage), ...(typeof ev.seq === "number" ? { cycleSeq: ev.seq } : {}), ...(() => { const t = toolUsesOf(ev.usage); return t !== undefined ? { toolUses: t } : {}; })(), elapsedMs: Date.now() - childStartedAt.get(cid) }); // [1415]③ 同上;[1748] toolUses 同 bg lane 口径;#261 seq→cycleSeq 缺席不铸
         },
         onChildTerminal(taskId, status, altId, toolUseId) {
             // A background subagent/bash CHILD settles — task_progress never emits a terminal tick,
@@ -751,7 +809,9 @@ export function fleetBackgroundChildPublisher(bus, log) {
         // [2400] FLEET-WORKFLOWS-7:[2070]③「名不铸」的第四处——spawn 双缺 description/name 时此前 `?? e.taskId`
         // 拿 a* handle 冒充显示名;tick 臂只在 name 在场才发 + 总线 MERGE ⇒ 假名永久留行。缺席不铸,与其余三处同判。
         const spawnName = e.description ?? e.name;
-        bus.publishTask({ id: e.taskId, ...(spawnName !== undefined ? { name: redactSecrets(spawnName) } : {}), ...(e.agentType ? { agentType: redactSecrets(e.agentType) } : {}), ...rowTags(m), status: "running", tokens: 0, ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}) });
+        // #261 §2:core 5.36.0(#258)把 `seq` 从「只在 terminal 帧」放宽到 **spawn/tick 也带**(registry 行
+        // 的 stop-cycle 代际)。本车道是设计稿点名的第二条供给点 —— 三帧一律透传成行的 `cycleSeq`,**缺席不铸**。
+        bus.publishTask({ id: e.taskId, ...(spawnName !== undefined ? { name: redactSecrets(spawnName) } : {}), ...(e.agentType ? { agentType: redactSecrets(e.agentType) } : {}), ...rowTags(m), status: "running", tokens: 0, ...(typeof e.seq === "number" ? { cycleSeq: e.seq } : {}), ...(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) => {
@@ -806,7 +866,7 @@ export function fleetBackgroundChildPublisher(bus, log) {
         // 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 } : {}) });
+        bus.publishTask({ id: e.taskId, ...rowTags(m), status: "running", ...(tokens !== undefined ? { tokens } : {}), ...(name ? { name } : {}), ...(agentType ? { agentType } : {}), ...(currentAction ? { currentAction } : {}), ...(currentTool ? { currentTool } : {}), ...(typeof e.seq === "number" ? { cycleSeq: e.seq } : {}), ...(e.usage?.toolUses !== undefined ? { toolUses: e.usage.toolUses } : {}), ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}) }); // #261 seq→cycleSeq 缺席不铸
     };
     const handleTerminal = (e, m) => {
         // terminal: flip the row so subscribers SEE the terminal frame, then leave the fleet — and push the
@@ -818,6 +878,7 @@ export function fleetBackgroundChildPublisher(bus, log) {
         // + 100 界、缺席不铸。(recentSteps 不进行帧——通知卡语义,行卡不渲染步骤列表。)
         bus.publishTask({
             id: e.taskId, ...rowTags(m), status,
+            ...(typeof e.seq === "number" ? { cycleSeq: e.seq } : {}), // #261 §2:终帧带**被结算那一代**的代际号(缺席不铸)
             ...(e.stoppedBy ? { stoppedBy: e.stoppedBy } : {}),
             ...(e.resumable !== undefined ? { resumable: e.resumable } : {}),
             ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}),

package/dist/fleet/fleet-reconciler.d.ts

@@ -0,0 +1,149 @@
+/**
+ * #261(docs/DESIGN-261-fleet-liveness-reconcile.md v1.2,四方零驳定稿)—— fleet 总线**存活对账腿**。
+ *
+ * ## 它修什么(§0 病灶机制链)
+ * fleet 总线是进程内纯内存聚合(`fleet-bus.ts` 头注自陈 NOT durable / NOT cross-replica),行的**唯一**
+ * 离场路径是发布方主动打 `onTerminal`/`onChildTerminal`。发布方没走到终态臂(run 事件环异常中断、引擎
+ * 被壳 reuse 而旧 run 对象已死、BCE 终态通知丢失),行就**永久僵在** `tasks` Map 里 —— 此后每个订阅方
+ * (含 snapshot 新连接)看到一条永远 "running" 的幽灵行。壳侧只能靠 overlay 防御(cli 1.0.74 过渡件)。
+ *
+ * ## 核心裁定:**不造第二个判死者**(§1)
+ * 本腿**不判死**。它只做两件事:
+ *  (a) 副本本地活体登记面(`http/server.ts` 的 `inflightRuns` ∪ `steerableRuns`,经
+ *      {@link FleetReconcilerDeps.isLiveOnThisReplica} 探针注入 —— **不搬 Map**)在场 ⇒ 行活,跳过;
+ *  (b) 登记面无此 taskId ⇒ 读 durable run 行,把 durable **已有的判决**投影到总线上。
+ * 判死的属主始终是 durable 侧既有机制(心跳 → reaper finalize → 行翻终态);本腿是**投影腿**,
+ * 对 durable **恒只读**({@link FleetReconcileRunPort} 这只窄口连写方法都没有 —— 单写者不变量由类型执法)。
+ *
+ * `msSinceLastActivity` **显式排除**:它是「turn 卡死」诊断维,把它当退休输入会把真忙的后台 run 扫下
+ * 面板,方向错。卡死的 run 行**该**留着(它确实在占资源),诊断走 `GET /v1/runs/:id`。
+ *
+ * ## 对账矩阵(§1;每周期对 bus 的顶层 run 行逐行判)
+ * | 登记面 | durable 行 | 处置 |
+ * |---|---|---|
+ * | 在场 | 任意 | **跳过**(含 turn 卡死形) |
+ * | 无 | 终局 | **投影退休**:终态 `task` 帧(durable 真状态 + `retiredBy:"reconcile"` + 被退代际)→ `task_remove`,**结算级** |
+ * | 无 | `running`(本副本 claim / 他副本 claim) | **陈述级退场**:`task_remove` + `removeReason:"orphaned"`,**恒不造终态** |
+ * | 无 | 行不存在 | 陈述级退场(见下方"静默一周期"的收窄) |
+ *
+ * 🔴 **对"行不存在"这一格的收窄**(实施稿承重,设计稿 §3 的「拿不准的恒答最弱主张」同源):bus 上
+ * 一条 `parentId` 缺席的行**不一定**是顶层 run 行 —— BCE 车道的 `a*` 子代行在父链接尚未解析成功时
+ * 同样不发 `parentId`(`rowTags` 的 R6 臂),两者在总线上**结构同形**。而 `getRun(a*)` 必然 miss。
+ * 若照矩阵当周期就退场,一条**活着的**长寿 session-scoped bg 子代会被扫下面板。所以这一格额外要求
+ * 「**静默满一个对账周期**」(本腿订阅总线自记每行的最后帧时刻):还在出帧 = 活着的证据。
+ * durable 行**在场**的那三格没有这个歧义(`getRun` 命中 = 它就是一条 run 行),故照矩阵即时处置。
+ *
+ * ## 子代行(§1)
+ * 随父:父行退休/退场时**同扫**(与 `onTerminal` 的 removal 集同姿势)。子代**不读 durable** ——
+ * bg 子代的 durable 真源在 core 侧 registry,server 不越界重判。无父可循的孤儿子行(父行已不在 bus)
+ * 按「bus 内滞留超一个对账周期且无新帧」陈述级退场。
+ *
+ * ## workflow 行(§1)
+ * 只做同款「durable 终局投影」(#189 的 snapshot pull 腿 + reapers 的 workflow recover 腿已在场),
+ * **不加新判据**:活行恒不动,没有陈述级退场这一形。
+ *
+ * ## 五条界(任何一条失手都只是幽灵行多活一个周期 ⇒ 整体 F 类 fail-open,登记 tag,不静默)
+ *  · 节律 {@link FLEET_RECONCILE_INTERVAL_MS} · 每周期读上限 {@link FLEET_RECONCILE_MAX_ROWS}
+ *  · 读预算 {@link FLEET_RECONCILE_READ_BUDGET_MS} · 熔断冷却 {@link FLEET_RECONCILE_COOLDOWN_MS}
+ *  · 待终局候补窗 {@link FLEET_RECONCILE_WATCH_MAX} × {@link FLEET_RECONCILE_WATCH_TTL_MS}
+ * 任何读错/超预算 ⇒ `recordFailOpen("server.fleet.reconcile-read-failed")` + 熔断 + 本周期跳过。
+ *
+ * ## 为什么整套常数都不做旋钮
+ * 与 `fleet-terminal-window.ts` 同一论证:两侧边界都由语义定死(比周期短 = 幽灵行仍在面板上,比周期长 =
+ * 拿对账腿当历史列表),旋钮只会让部署方去调一个没有正确取值的数;fleet 面现有零旋钮,从之。
+ */
+import { type WorkflowRun, type WorkflowRunStore } from "@sema-agent/core";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
+import { type RunRecord } from "../plugins/store-contracts.js";
+import { type FleetEventBus } from "./fleet-bus.js";
+/** 对账节律 —— 60s 档。比它短 = 每分钟给 durable 加一批点读却换不来更快的面板真相(幽灵行的时间尺度
+ *  是"发布方已经死了",分钟级);比它长 = 壳的引擎温切门(cli engineSwapGate 读活行集)被幽灵行按住
+ *  太久。不做旋钮,理由见模块头。 */
+export declare const FLEET_RECONCILE_INTERVAL_MS = 60000;
+/** 每周期的**点读上限**。超出的行留到下一周期(顺序稳定 = bus 的插入序),不把一次扫描变成全表点读风暴。 */
+export declare const FLEET_RECONCILE_MAX_ROWS = 200;
+/** 一个周期的 durable 读**时间预算**。超时 = 放弃这一轮(记 F 类 fail-open),行留在面板上。
+ *  与 `FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS` 同值同理由:慢查询不该把整条腿钉死。 */
+export declare const FLEET_RECONCILE_READ_BUDGET_MS = 2000;
+/** 熔断冷却:一次读失败/超预算之后,这段时间内**不再发起任何读**。`RunStore`/`WorkflowRunStore` 契约
+ *  都没有取消面(发出去的查询撤不回),挂死的后端不该被每周期继续加压。冷却一过自动重探(自愈)。 */
+export declare const FLEET_RECONCILE_COOLDOWN_MS = 60000;
+/** 陈述级退场之后的**待终局候补窗**行数上限(§1 矩阵的「终局候 durable 翻转后由下一周期投影」半场:
+ *  行已不在 bus,故补发终态 `task` 帧 + remove 的**成对形**)。有界:超出即不再收新条目。 */
+export declare const FLEET_RECONCILE_WATCH_MAX = 200;
+/** 候补窗的存活时长。reaper 的孤儿宽限窗之外仍没翻终局的行 = 这条腿等不到了(它本来也只是投影),
+ *  丢弃并不损失真相:`GET /v1/runs/:id` 永远是那条 run 的真源。 */
+export declare const FLEET_RECONCILE_WATCH_TTL_MS: number;
+/** durable run 行的**只读**窄口(单写者不变量的类型执法面:这只接口上没有任何写方法,
+ *  所以"对账腿顺手改了一行"在本仓是编译期不可能,而不是靠注释约束)。 */
+export interface FleetReconcileRunPort {
+    getRun(taskId: string): Promise<RunRecord | undefined>;
+}
+/** durable workflow 行的只读窄口(同上;`WorkflowRunStore` 的 `get` 一面。`null` 在返回类型里是因为
+ *  core 契约的 `get` 用 `null` 表"没这一行",两种缺席一并容忍)。 */
+export interface FleetReconcileWorkflowPort {
+    get(id: string): Promise<WorkflowRun | null | undefined>;
+}
+export interface FleetReconcilerDeps {
+    bus: FleetEventBus;
+    /**
+     * 副本本地**活体谓词**(§4 件1 的"探针注入形"):`taskId` 是否在本副本的在飞/可 steer 登记面里。
+     * 由 `http/server.ts` 交出 `(taskId) => boolean`,**不搬 Map** —— 登记面的属主仍是 server,
+     * 对账腿只问一个是非题(搬 Map 会造出第二份活性判据,而两份判据必漂移)。
+     */
+    isLiveOnThisReplica: (taskId: string) => boolean;
+    runs?: FleetReconcileRunPort;
+    workflows?: FleetReconcileWorkflowPort | WorkflowRunStore;
+    /** 本副本 id(与 `RunRecord.instanceId` 同域)。只进日志/读数 —— 两条 `running` 臂的**处置相同**
+     *  (都是陈述级退场),分不分得出 claim 属谁不改变行为,故它不是判据。 */
+    instanceId?: string;
+    logger?: Logger;
+    metrics?: Metrics;
+    /** 测试缝:单调/可控时钟(默认 `Date.now`)。 */
+    now?: () => number;
+}
+/** 一个周期的读数(测试与遥测面;不上 wire)。 */
+export interface FleetReconcileTally {
+    /** 本周期判过的顶层候选行数(含跳过的)。 */
+    scanned: number;
+    /** 登记面在场而跳过的行数。 */
+    skippedLive: number;
+    /** durable 说 park(suspended / needs_review)而跳过的行数 —— 行还活着,不是孤儿(codex R1-F1)。 */
+    skippedParked: number;
+    /** durable 终局 ⇒ 投影退休的行数(结算级)。 */
+    retired: number;
+    /** 陈述级退场的行数(顶层 + 孤儿子行)。 */
+    orphaned: number;
+    /** 随父同扫的子行数。 */
+    childrenSwept: number;
+    /** durable 终局 ⇒ 投影退休的 workflow 行数。 */
+    workflowsRetired: number;
+    /** 本周期实际发出的 durable 点读次数。 */
+    reads: number;
+    /** 本周期因熔断整轮未跑。 */
+    cooling: boolean;
+    /** 本周期踩了 F 类兜底(读失败/超预算)。 */
+    failOpen: boolean;
+}
+/** 对账腿的活对象(有状态:静默钟 + 候补窗 + 熔断 ⇒ `create*` 而非 `build*`)。 */
+export interface FleetReconciler {
+    runOnce(nowMs: number): Promise<FleetReconcileTally>;
+    /** 解除对总线的订阅(收尾用;定时器由调用方 `clearInterval`)。 */
+    stop(): void;
+}
+export declare function createFleetReconciler(deps: FleetReconcilerDeps): FleetReconciler;
+/**
+ * 起对账定时器(60s 档,`unref`)+ 重入守卫。返回 handle 供收尾段 `clearInterval`。
+ *
+ * ⚠️ 装配点必须在 `createHttpServer` **之后** —— 活体谓词是 server 造出来的
+ * ({@link FleetReconcilerDeps.isLiveOnThisReplica});这也是本腿不并进 `boot/reapers.ts` 那只 tick 的
+ * 唯一原因(reaper 段按「位置即契约」必须在 server 之前建)。
+ *
+ * 重入守卫照 reapers 的四腿先例:本腿时长随 bus 行数与库延迟增长,短周期下无守卫会逐周期叠罗汉压同一批行。
+ */
+export declare function startFleetReconciler(deps: FleetReconcilerDeps): {
+    timer: NodeJS.Timeout;
+    reconciler: FleetReconciler;
+};
+//# sourceMappingURL=fleet-reconciler.d.ts.map

package/dist/fleet/fleet-reconciler.js

@@ -0,0 +1,385 @@
+/**
+ * #261(docs/DESIGN-261-fleet-liveness-reconcile.md v1.2,四方零驳定稿)—— fleet 总线**存活对账腿**。
+ *
+ * ## 它修什么(§0 病灶机制链)
+ * fleet 总线是进程内纯内存聚合(`fleet-bus.ts` 头注自陈 NOT durable / NOT cross-replica),行的**唯一**
+ * 离场路径是发布方主动打 `onTerminal`/`onChildTerminal`。发布方没走到终态臂(run 事件环异常中断、引擎
+ * 被壳 reuse 而旧 run 对象已死、BCE 终态通知丢失),行就**永久僵在** `tasks` Map 里 —— 此后每个订阅方
+ * (含 snapshot 新连接)看到一条永远 "running" 的幽灵行。壳侧只能靠 overlay 防御(cli 1.0.74 过渡件)。
+ *
+ * ## 核心裁定:**不造第二个判死者**(§1)
+ * 本腿**不判死**。它只做两件事:
+ *  (a) 副本本地活体登记面(`http/server.ts` 的 `inflightRuns` ∪ `steerableRuns`,经
+ *      {@link FleetReconcilerDeps.isLiveOnThisReplica} 探针注入 —— **不搬 Map**)在场 ⇒ 行活,跳过;
+ *  (b) 登记面无此 taskId ⇒ 读 durable run 行,把 durable **已有的判决**投影到总线上。
+ * 判死的属主始终是 durable 侧既有机制(心跳 → reaper finalize → 行翻终态);本腿是**投影腿**,
+ * 对 durable **恒只读**({@link FleetReconcileRunPort} 这只窄口连写方法都没有 —— 单写者不变量由类型执法)。
+ *
+ * `msSinceLastActivity` **显式排除**:它是「turn 卡死」诊断维,把它当退休输入会把真忙的后台 run 扫下
+ * 面板,方向错。卡死的 run 行**该**留着(它确实在占资源),诊断走 `GET /v1/runs/:id`。
+ *
+ * ## 对账矩阵(§1;每周期对 bus 的顶层 run 行逐行判)
+ * | 登记面 | durable 行 | 处置 |
+ * |---|---|---|
+ * | 在场 | 任意 | **跳过**(含 turn 卡死形) |
+ * | 无 | 终局 | **投影退休**:终态 `task` 帧(durable 真状态 + `retiredBy:"reconcile"` + 被退代际)→ `task_remove`,**结算级** |
+ * | 无 | `running`(本副本 claim / 他副本 claim) | **陈述级退场**:`task_remove` + `removeReason:"orphaned"`,**恒不造终态** |
+ * | 无 | 行不存在 | 陈述级退场(见下方"静默一周期"的收窄) |
+ *
+ * 🔴 **对"行不存在"这一格的收窄**(实施稿承重,设计稿 §3 的「拿不准的恒答最弱主张」同源):bus 上
+ * 一条 `parentId` 缺席的行**不一定**是顶层 run 行 —— BCE 车道的 `a*` 子代行在父链接尚未解析成功时
+ * 同样不发 `parentId`(`rowTags` 的 R6 臂),两者在总线上**结构同形**。而 `getRun(a*)` 必然 miss。
+ * 若照矩阵当周期就退场,一条**活着的**长寿 session-scoped bg 子代会被扫下面板。所以这一格额外要求
+ * 「**静默满一个对账周期**」(本腿订阅总线自记每行的最后帧时刻):还在出帧 = 活着的证据。
+ * durable 行**在场**的那三格没有这个歧义(`getRun` 命中 = 它就是一条 run 行),故照矩阵即时处置。
+ *
+ * ## 子代行(§1)
+ * 随父:父行退休/退场时**同扫**(与 `onTerminal` 的 removal 集同姿势)。子代**不读 durable** ——
+ * bg 子代的 durable 真源在 core 侧 registry,server 不越界重判。无父可循的孤儿子行(父行已不在 bus)
+ * 按「bus 内滞留超一个对账周期且无新帧」陈述级退场。
+ *
+ * ## workflow 行(§1)
+ * 只做同款「durable 终局投影」(#189 的 snapshot pull 腿 + reapers 的 workflow recover 腿已在场),
+ * **不加新判据**:活行恒不动,没有陈述级退场这一形。
+ *
+ * ## 五条界(任何一条失手都只是幽灵行多活一个周期 ⇒ 整体 F 类 fail-open,登记 tag,不静默)
+ *  · 节律 {@link FLEET_RECONCILE_INTERVAL_MS} · 每周期读上限 {@link FLEET_RECONCILE_MAX_ROWS}
+ *  · 读预算 {@link FLEET_RECONCILE_READ_BUDGET_MS} · 熔断冷却 {@link FLEET_RECONCILE_COOLDOWN_MS}
+ *  · 待终局候补窗 {@link FLEET_RECONCILE_WATCH_MAX} × {@link FLEET_RECONCILE_WATCH_TTL_MS}
+ * 任何读错/超预算 ⇒ `recordFailOpen("server.fleet.reconcile-read-failed")` + 熔断 + 本周期跳过。
+ *
+ * ## 为什么整套常数都不做旋钮
+ * 与 `fleet-terminal-window.ts` 同一论证:两侧边界都由语义定死(比周期短 = 幽灵行仍在面板上,比周期长 =
+ * 拿对账腿当历史列表),旋钮只会让部署方去调一个没有正确取值的数;fleet 面现有零旋钮,从之。
+ */
+import { isTerminalWorkflowStatus } from "@sema-agent/core";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { isParkedRunStatus, isTerminalRunStatus } from "../plugins/store-contracts.js";
+import { buildFleetWorkflowRow, fleetRunResiduals, runStatusToFleet } from "./fleet-bus.js";
+import { isTerminalWorkflowRowStatus } from "./fleet-terminal-window.js";
+/** 对账节律 —— 60s 档。比它短 = 每分钟给 durable 加一批点读却换不来更快的面板真相(幽灵行的时间尺度
+ *  是"发布方已经死了",分钟级);比它长 = 壳的引擎温切门(cli engineSwapGate 读活行集)被幽灵行按住
+ *  太久。不做旋钮,理由见模块头。 */
+export const FLEET_RECONCILE_INTERVAL_MS = 60_000;
+/** 每周期的**点读上限**。超出的行留到下一周期(顺序稳定 = bus 的插入序),不把一次扫描变成全表点读风暴。 */
+export const FLEET_RECONCILE_MAX_ROWS = 200;
+/** 一个周期的 durable 读**时间预算**。超时 = 放弃这一轮(记 F 类 fail-open),行留在面板上。
+ *  与 `FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS` 同值同理由:慢查询不该把整条腿钉死。 */
+export const FLEET_RECONCILE_READ_BUDGET_MS = 2_000;
+/** 熔断冷却:一次读失败/超预算之后,这段时间内**不再发起任何读**。`RunStore`/`WorkflowRunStore` 契约
+ *  都没有取消面(发出去的查询撤不回),挂死的后端不该被每周期继续加压。冷却一过自动重探(自愈)。 */
+export const FLEET_RECONCILE_COOLDOWN_MS = 60_000;
+/** 陈述级退场之后的**待终局候补窗**行数上限(§1 矩阵的「终局候 durable 翻转后由下一周期投影」半场:
+ *  行已不在 bus,故补发终态 `task` 帧 + remove 的**成对形**)。有界:超出即不再收新条目。 */
+export const FLEET_RECONCILE_WATCH_MAX = 200;
+/** 候补窗的存活时长。reaper 的孤儿宽限窗之外仍没翻终局的行 = 这条腿等不到了(它本来也只是投影),
+ *  丢弃并不损失真相:`GET /v1/runs/:id` 永远是那条 run 的真源。 */
+export const FLEET_RECONCILE_WATCH_TTL_MS = 30 * 60_000;
+const emptyTally = () => ({
+    scanned: 0, skippedLive: 0, skippedParked: 0, retired: 0, orphaned: 0, childrenSwept: 0, workflowsRetired: 0, reads: 0, cooling: false, failOpen: false,
+});
+/** 从 `cursor` 指的那一行开始的**环形**遍历(见 {@link createFleetReconciler} 里 `taskCursor` 的顶注)。
+ *  `cursor` 缺席/已不在集合里 ⇒ 从头开始(诚实回落)。返回新数组,调用方照常按序 `for…of`。 */
+function rotate(rows, cursor) {
+    if (cursor === undefined || rows.length === 0)
+        return rows;
+    const at = rows.findIndex((r) => r.id === cursor);
+    if (at <= 0)
+        return rows;
+    return [...rows.slice(at), ...rows.slice(0, at)];
+}
+/** 本周期该不该收这条行 —— 见模块头「对"行不存在"这一格的收窄」。 */
+const SILENT_FOR_A_CYCLE = FLEET_RECONCILE_INTERVAL_MS;
+export function createFleetReconciler(deps) {
+    const now = deps.now ?? (() => Date.now());
+    /**
+     * 每行的**最后帧时刻**。存在理由:「无新帧」是设计稿对孤儿子行(以及本实施稿对"durable 无行"格)
+     * 唯一诚实的活性证据 —— 长寿 session-scoped bg 子代在父 run 行离场之后照样出 tick,它必须留在面板上。
+     * 从总线订阅得到(而不是自己给行打时间戳):**行的单写者不变量**不许被观察者破坏。
+     */
+    const lastFrameAt = new Map();
+    /** 陈述级退场后的待终局候补窗(见 {@link FLEET_RECONCILE_WATCH_MAX})。 */
+    const watch = new Map();
+    let coolingUntil;
+    /**
+     * 🔴 轮转游标(codex 对抗复审 R1-F4 [medium],红先复现):读上限是**每周期**的,而扫描顺序是 bus 的
+     * 稳定插入序 —— 于是「超出的行留到下一周期」这句承诺在**行不会自己走**的形下是假的:200 条长期
+     * parked/活的行会把预算逐周期吃光,第 201 行往后**永远**读不到,它们的终局投影永不发生(而那正是本腿
+     * 存在的理由)。游标记住"上一周期停在哪一行",下一周期从它接着扫,一圈之后必然轮到每一行。
+     * 记 id(不是下标):行集会增删,下标会指到别的行上;id 找不到就从头开始(诚实回落,不猜)。
+     */
+    let taskCursor;
+    let wfCursor;
+    const unsubscribe = deps.bus.subscribe((frame) => {
+        if (frame.type === "task")
+            lastFrameAt.set(frame.row.id, now());
+        else if (frame.type === "task_remove")
+            lastFrameAt.delete(frame.id);
+    });
+    const wfGet = deps.workflows ? (id) => Promise.resolve(deps.workflows.get(id)) : undefined;
+    async function runOnce(nowMs) {
+        const tally = emptyTally();
+        if (coolingUntil !== undefined && nowMs < coolingUntil) {
+            tally.cooling = true;
+            return tally;
+        }
+        coolingUntil = undefined;
+        const deadline = now() + FLEET_RECONCILE_READ_BUDGET_MS;
+        /** 读闸:上限/预算任一到顶就停(**不是**熔断——本周期已做的处置全部有效,余下的行下周期再来)。 */
+        const budgetLeft = () => tally.reads < FLEET_RECONCILE_MAX_ROWS && now() < deadline;
+        /** 一次点读。抛错/超预算 ⇒ 抛 {@link ReadAborted},由 runOnce 统一收成 F 类 fail-open + 熔断。 */
+        const readRun = async (id) => {
+            tally.reads++;
+            const rec = await Promise.race([
+                deps.runs.getRun(id),
+                new Promise((_r, reject) => {
+                    const t = setTimeout(() => reject(new ReadAborted(`fleet reconcile read exceeded ${FLEET_RECONCILE_READ_BUDGET_MS}ms`)), Math.max(0, deadline - now()));
+                    if (typeof t.unref === "function")
+                        t.unref();
+                }),
+            ]);
+            return rec;
+        };
+        const snap = deps.bus.snapshot();
+        // 静默钟的**首见播种**:本腿起动之前就已在 bus 上的行(重启/迟接线)没有帧记录,给它们记一个
+        // "从现在开始静默"的起点 —— 否则首轮就会把一屏历史行当成静默满一周期的幽灵。
+        for (const r of snap.tasks)
+            if (!lastFrameAt.has(r.id))
+                lastFrameAt.set(r.id, nowMs);
+        const idle = (id) => nowMs - (lastFrameAt.get(id) ?? nowMs) >= SILENT_FOR_A_CYCLE;
+        const present = new Set(snap.tasks.map((r) => r.id));
+        const kids = new Map();
+        for (const r of snap.tasks) {
+            if (r.parentId === undefined)
+                continue;
+            const bucket = kids.get(r.parentId);
+            if (bucket)
+                bucket.push(r);
+            else
+                kids.set(r.parentId, [r]);
+        }
+        /** 随父同扫(与 `fleetRunPublisher.onTerminal` 的 removal 集同姿势)。子代恒**陈述级** ——
+         *  我们对它们没有任何终局证据(子代不读 durable),说"离场"是诚实的,说"完成/失败"是编。 */
+        const sweepChildren = (parentId) => {
+            for (const c of kids.get(parentId) ?? []) {
+                deps.bus.removeTask(c.id, { removeReason: "orphaned", ...(c.cycleSeq !== undefined ? { cycleSeq: c.cycleSeq } : {}) });
+                lastFrameAt.delete(c.id);
+                tally.childrenSwept++;
+            }
+        };
+        /** 投影退休(结算级):终态 `task` 帧 → `task_remove`,**成对且有序**。 */
+        const retire = (row, rec) => {
+            // 残局键走既有的**同一个** {@link fleetRunResiduals} 映射(键名映射写第二遍必漂;[1839]① 案:
+            // 只带 {id,status} 的终态帧让 idle 观察者从行卡上拿不到终局)。源恒是 durable 那份 result,不编。
+            deps.bus.publishTask({
+                id: row.id,
+                status: runStatusToFleet(rec.status),
+                retiredBy: "reconcile",
+                ...fleetRunResiduals(rec.result),
+            });
+            sweepChildren(row.id);
+            deps.bus.removeTask(row.id, { ...(row.cycleSeq !== undefined ? { cycleSeq: row.cycleSeq } : {}) });
+            lastFrameAt.delete(row.id);
+            tally.retired++;
+            deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "retired" });
+        };
+        /** 陈述级退场:只撤行,恒不造终态。行进候补窗,等 durable 翻终局后由后续周期补发成对终帧。 */
+        const orphanExit = (row, why) => {
+            sweepChildren(row.id);
+            deps.bus.removeTask(row.id, { removeReason: "orphaned", ...(row.cycleSeq !== undefined ? { cycleSeq: row.cycleSeq } : {}) });
+            lastFrameAt.delete(row.id);
+            if (deps.runs && watch.size < FLEET_RECONCILE_WATCH_MAX)
+                watch.set(row.id, { at: nowMs, row });
+            tally.orphaned++;
+            deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "orphaned" });
+            deps.logger?.info("fleet_row_reconciled", { taskId: row.id, disposition: "orphaned", why, instanceId: deps.instanceId ?? null });
+        };
+        try {
+            // ── ① 候补窗:陈述级退场过的行,等 durable 翻终局 ─────────────────────────────────────
+            // 为什么要补这一拍:cli 的裁量是「渲**离场**不清行」([4044])—— 陈述级退场之后壳把行**保留**在
+            // 面板上(中性离场形、active 扣除、折叠排后),所以那条行后来真的翻了终局时,补发的成对终帧是壳
+            // 唯一能把"离场"升级成"真终局"的信号。行已不在 bus,故 publish 会**瞬时重铸**再撤(flip-through,
+            // 与 `onChildTerminal` 的合成终帧同姿势);带上退场时记住的整行,可见性字段(scope/sessionId)
+            // 才不会丢 —— 丢了就变成 scoped 订阅方一律看不见(fail-closed 到没人收得到)。
+            for (const [id, w] of [...watch]) {
+                if (nowMs - w.at > FLEET_RECONCILE_WATCH_TTL_MS) {
+                    watch.delete(id);
+                    continue;
+                }
+                // 行又出现在 bus 上 = **复活**(更大代际的首帧 = 正常出生):活发布方接管,候补窗让位。
+                if (present.has(id)) {
+                    watch.delete(id);
+                    continue;
+                }
+                if (!budgetLeft())
+                    break;
+                const rec = await readRun(id);
+                if (!rec) {
+                    watch.delete(id);
+                    continue;
+                } // 行被 reap 掉了:没有终局可投影,诚实丢弃
+                if (!isTerminalRunStatus(rec.status))
+                    continue; // 还没定局 —— 下个周期再看
+                deps.bus.publishTask({ ...w.row, status: runStatusToFleet(rec.status), retiredBy: "reconcile", ...fleetRunResiduals(rec.result) });
+                deps.bus.removeTask(id, { ...(w.row.cycleSeq !== undefined ? { cycleSeq: w.row.cycleSeq } : {}) });
+                lastFrameAt.delete(id);
+                watch.delete(id);
+                tally.retired++;
+                deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "retired_deferred" });
+            }
+            // ── ② 顶层 run 行 ────────────────────────────────────────────────────────────────────
+            for (const row of rotate(snap.tasks, taskCursor)) {
+                if (row.parentId !== undefined)
+                    continue; // 子代行:随父(下面 ③ 收孤儿)
+                tally.scanned++;
+                if (deps.isLiveOnThisReplica(row.id)) {
+                    // 登记面在场 ⇒ 活。**含 turn 卡死形** —— 诊断不驱逐(§1)。一次 durable 读都不发。
+                    tally.skippedLive++;
+                    continue;
+                }
+                if (!deps.runs)
+                    continue; // 无 durable run 店的部署(memory 车道):没有可投影的判决,整格不动
+                if (!budgetLeft()) {
+                    taskCursor = row.id;
+                    break;
+                } // 轮转:下周期从这一行接着扫(见 rotate 顶注)
+                const rec = await readRun(row.id);
+                // 🔴 await 后**复核**(codex 对抗复审 R1-F3 [high],红先复现):`isLiveOnThisReplica` 在读之前只
+                // 问过一次,而 durable 读的那几十毫秒里 parked run 完全可能被 resume —— 它会重新登记进在飞面并
+                // 发出新行帧,而读回来的行还写着 `running`。不复核就等于把**刚复活**的顶层行删掉;顶层行按设计
+                // 恒无 `cycleSeq`(「无此概念」),总线那道代际条件删也救不了这一格,只能在这里问第二次。
+                if (deps.isLiveOnThisReplica(row.id)) {
+                    tally.skippedLive++;
+                    continue;
+                }
+                const nowRow = deps.bus.taskRow(row.id);
+                if (nowRow === undefined)
+                    continue; // 行在读期间自己走了(发布方终于 settle 了):无事可做
+                if (nowRow.cycleSeq !== row.cycleSeq)
+                    continue; // 代际翻过 = 已复活,活发布方接管
+                if (rec === undefined) {
+                    // durable 无行。**必须**静默满一个周期才退场:`a*` 子代行在父链接未解析时同样无 parentId,
+                    // 与顶层行结构同形,而 `getRun(a*)` 必然 miss(见模块头收窄段)。还在出帧 = 活着的证据。
+                    if (idle(row.id))
+                        orphanExit(row, "durable_row_absent");
+                    continue;
+                }
+                if (isTerminalRunStatus(rec.status)) {
+                    retire(row, rec);
+                    continue;
+                }
+                // 🔴 **park 不是孤儿**(codex 对抗复审 R1-F1 [high],红先复现):`suspended` / `needs_review` 的行
+                // 还活着 —— `task_active` claim 还占着、checkpoint 还能被决议,而 fleet 契约(`fleetRunPublisher`
+                // 的 `onTerminal`)明写 park 态的行**留在面板上**(waiting / awaiting approval)。它们恰恰**不在**
+                // 任何在飞登记面里(park 的 run 没有活腿),所以上面那道活体谓词接不住它们 —— 不在这里显式跳过,
+                // 每一轮对账都会把一条合法的待审批任务从面板上摘掉,而用户看到的是"任务凭空消失"。
+                if (isParkedRunStatus(rec.status)) {
+                    tally.skippedParked++;
+                    continue;
+                }
+                // durable 还 `running` 而本副本没有它:发布方死了、durable 还没定局(reaper 宽限窗内),
+                // 或 run 活在别的副本上。两形处置相同 —— **不造终态**,只陈述离场。
+                orphanExit(row, rec.instanceId !== null && rec.instanceId !== (deps.instanceId ?? null) ? "durable_running_other_replica" : "durable_running_no_local_leg");
+            }
+            // ── ③ 无父可循的孤儿子行 ─────────────────────────────────────────────────────────────
+            // 判据里**没有** durable 读:bg 子代的真源在 core 侧 registry,server 不越界重判。
+            for (const row of snap.tasks) {
+                if (row.parentId === undefined || present.has(row.parentId))
+                    continue;
+                if (!idle(row.id))
+                    continue; // 还在出帧 = 长寿 session-scoped 子代活过了父 leg,留着
+                deps.bus.removeTask(row.id, { removeReason: "orphaned", ...(row.cycleSeq !== undefined ? { cycleSeq: row.cycleSeq } : {}) });
+                lastFrameAt.delete(row.id);
+                tally.orphaned++;
+                deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "orphaned_child" });
+            }
+            // ── ④ workflow 行:只做 durable 终局投影 ─────────────────────────────────────────────
+            if (wfGet) {
+                for (const wf of rotate(snap.workflows, wfCursor)) {
+                    if (isTerminalWorkflowRowStatus(wf.status))
+                        continue; // 已是终态行:活写路径自己会撤
+                    if (!budgetLeft()) {
+                        wfCursor = wf.id;
+                        break;
+                    }
+                    tally.reads++;
+                    const run = await Promise.race([
+                        wfGet(wf.id),
+                        new Promise((_r, reject) => {
+                            const t = setTimeout(() => reject(new ReadAborted("fleet reconcile workflow read over budget")), Math.max(0, deadline - now()));
+                            if (typeof t.unref === "function")
+                                t.unref();
+                        }),
+                    ]);
+                    if (!run || !isTerminalWorkflowStatus(run.status))
+                        continue;
+                    // 租户复核:`store.get` 是**无 scope 门**的裸读(带门的是 core 的 `getWorkflowRun`)——
+                    // id 来自本进程的行,仍按真行的 scope 复核一次(同 fleet-terminal-window 的姿势)。
+                    if (wf.scope !== undefined && run.scope !== wf.scope)
+                        continue;
+                    deps.bus.publishWorkflow(buildFleetWorkflowRow(wf.id, run));
+                    deps.bus.removeWorkflow(wf.id);
+                    tally.workflowsRetired++;
+                    deps.metrics?.inc("fleet_rows_reconciled_total", { disposition: "workflow_retired" });
+                }
+            }
+        }
+        catch (err) {
+            // F 类:读不出来 ≠ 该退休。**只向留行一侧** fail-open —— 库抖一下就把一屏在跑的任务从面板上
+            // 抹掉,比多留一条幽灵行伤得多。本周期已经做完的处置全部有效(它们各自都有 durable 证据)。
+            coolingUntil = now() + FLEET_RECONCILE_COOLDOWN_MS;
+            tally.failOpen = true;
+            // detail 用 `err.message` 而不是 `String(err)`:后者会调用抛出值自己的 toString,而那本身可能再抛
+            // (逃出本兜底,把降级变成故障)。非 Error 抛出值就如实说"不是 Error",不去问它任何问题。
+            recordFailOpen("server.fleet.reconcile-read-failed", err instanceof Error ? err.message : "fleet reconcile read threw a non-Error value");
+        }
+        return tally;
+    }
+    return {
+        runOnce,
+        stop: unsubscribe,
+    };
+}
+/** 读预算到点的**具名**抛出值(与真实的店错误在日志里可分,且不会被误当成"店坏了"去查库)。 */
+class ReadAborted extends Error {
+}
+/**
+ * 起对账定时器(60s 档,`unref`)+ 重入守卫。返回 handle 供收尾段 `clearInterval`。
+ *
+ * ⚠️ 装配点必须在 `createHttpServer` **之后** —— 活体谓词是 server 造出来的
+ * ({@link FleetReconcilerDeps.isLiveOnThisReplica});这也是本腿不并进 `boot/reapers.ts` 那只 tick 的
+ * 唯一原因(reaper 段按「位置即契约」必须在 server 之前建)。
+ *
+ * 重入守卫照 reapers 的四腿先例:本腿时长随 bus 行数与库延迟增长,短周期下无守卫会逐周期叠罗汉压同一批行。
+ */
+export function startFleetReconciler(deps) {
+    const reconciler = createFleetReconciler(deps);
+    let inFlight = false;
+    const timer = setInterval(() => {
+        if (inFlight)
+            return;
+        inFlight = true;
+        void reconciler
+            .runOnce(Date.now())
+            .then((t) => {
+            if (t.retired > 0 || t.orphaned > 0 || t.workflowsRetired > 0) {
+                deps.logger?.info("fleet_reconcile_swept", { retired: t.retired, orphaned: t.orphaned, childrenSwept: t.childrenSwept, workflowsRetired: t.workflowsRetired, reads: t.reads });
+            }
+        }, (err) => {
+            // runOnce 自己已把读面的失败收成 fail-open;能到这里的只剩"对账腿自己有 bug"这一族。
+            // 观测绝不能变成故障(同 reapers 的 throttled catch 判据):整块 total/non-throwing。
+            try {
+                deps.logger?.warn("fleet_reconcile_failed", { err: err instanceof Error ? err.message : "non-Error throw" });
+            }
+            catch {
+                /* observability must never become the outage */
+            }
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    }, FLEET_RECONCILE_INTERVAL_MS);
+    timer.unref?.();
+    return { timer, reconciler };
+}
+//# sourceMappingURL=fleet-reconciler.js.map

package/dist/hooks/branch-transcript.d.ts

@@ -14,11 +14,11 @@ export declare const RENDERED_ENTRY_TYPES: readonly ["message", "compaction", "c
 /**
  * 跳过的理由逐型给(「纯控制型」不是一句话,是逐个核过模型看不见):
  * thinking_level_change / model_change / label / session_info / leaf / prompt_epoch /
- * announced_listing / workspace_state —— 控制面元数据,core 折 messages 时不产出内容;
+ * announced_listing / workspace_state / git_announcement —— 控制面元数据,core 折 messages 时不产出内容;
  * custom —— data-only(session.js 折 messages 只认 message/custom_message 两型),模型看不见它的
  * data;把它渲出来反而是把模型没见过的东西冒充成证据,与 [2092] 是同一判据的反方向。
  */
-export declare const SKIPPED_ENTRY_TYPES: readonly ["thinking_level_change", "model_change", "label", "session_info", "leaf", "prompt_epoch", "announced_listing", "workspace_state", "custom"];
+export declare const SKIPPED_ENTRY_TYPES: readonly ["thinking_level_change", "model_change", "label", "session_info", "leaf", "prompt_epoch", "announced_listing", "workspace_state", "git_announcement", "custom"];
 /** 渲染结果。**判别式**:证据不足时调用方拿不到 `text`,想用也用不了(见顶注)。 */
 export type BranchTranscript = {
     sufficient: true;

package/dist/hooks/branch-transcript.js

@@ -37,7 +37,7 @@ export const RENDERED_ENTRY_TYPES = ["message", "compaction", "custom_message"];
 /**
  * 跳过的理由逐型给(「纯控制型」不是一句话,是逐个核过模型看不见):
  * thinking_level_change / model_change / label / session_info / leaf / prompt_epoch /
- * announced_listing / workspace_state —— 控制面元数据,core 折 messages 时不产出内容;
+ * announced_listing / workspace_state / git_announcement —— 控制面元数据,core 折 messages 时不产出内容;
  * custom —— data-only(session.js 折 messages 只认 message/custom_message 两型),模型看不见它的
  * data;把它渲出来反而是把模型没见过的东西冒充成证据,与 [2092] 是同一判据的反方向。
  */
@@ -50,6 +50,11 @@ export const SKIPPED_ENTRY_TYPES = [
     "prompt_epoch",
     "announced_listing",
     "workspace_state",
+    // core 5.36.0(env-tail 迁移):git-status 帧的**已通告态**快照条目(`{kind,hash,entryId?,pending?}`)。
+    // 与上面两位同族、同理由 —— 它是控制面的「模型上次被展示的是哪一份 git 视图」记号,**不是**模型看见的
+    // 内容:真正被看见的那份帧正文骑在它 `entryId` 指的那条 `message` 上(已由渲染臂收下)。把这条快照渲进
+    // 证据面 = 把一串 sha256 摘要当成对话冒充给评估者,正是 [2092] 判据的反方向。
+    "git_announcement",
     "custom",
 ];
 /** 单次评估送进模型的 transcript 字符上限。超出保留**尾部**(最近的对话对"条件是否已达成"更相关)。 */

package/dist/http/routes/fleet.js

@@ -98,6 +98,11 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
             id: "keep", parentId: "keep", parentToolCallId: "keep", workflowRunId: "keep", status: "keep",
             startedAt: "keep", elapsedMs: "keep", tokens: "keep", queuedCount: "keep",
             awaitingPlanApproval: "keep", toolUses: "keep", usage: "keep", resumable: "keep", sourceLane: "keep",
+            // #261 §2:两键都是**结构事实**,零会话内容 —— `cycleSeq` 是 core registry 行的代际号
+            // (数值,消费端判「复活 vs 前代迟到帧」的唯一钥匙),`retiredBy` 说的是「这条终态是对账腿从
+            // durable 投影的、不是发布方亲报的」。降权投影里丢掉它们 = 未署名会话的行**判不了代**,而复活
+            // 与迟到帧在无代际号时不可区分(正是本 issue 要消灭的那类静默错判)。故 keep。
+            cycleSeq: "keep", retiredBy: "keep",
             name: "rewrite", scope: "strip", sessionId: "strip",
             description: "scrub", agentType: "scrub", agentName: "scrub", currentAction: "scrub",
             currentTool: "scrub", transcriptId: "scrub", stoppedBy: "scrub", editedFiles: "scrub",
@@ -125,6 +130,8 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                     ...(rest.usage !== undefined ? { usage: rest.usage } : {}),
                     ...(rest.resumable !== undefined ? { resumable: rest.resumable } : {}),
                     ...(rest.sourceLane !== undefined ? { sourceLane: rest.sourceLane } : {}),
+                    ...(rest.cycleSeq !== undefined ? { cycleSeq: rest.cycleSeq } : {}), // #261:代际号是结构事实(见处置表)
+                    ...(rest.retiredBy !== undefined ? { retiredBy: rest.retiredBy } : {}),
                 };
             }
             return rest;
@@ -200,8 +207,17 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                     }
                     break;
                 case "task_remove":
-                    if (seenTasks.delete(frame.id))
-                        send("task_remove", { id: frame.id, ts: frame.ts });
+                    // #261 §2③/§5 Q-d:两个 additive 键随帧透传。撤行帧本就**只投给见过这一行的连接**
+                    // (`seenTasks.delete` 的返回值即判据)—— 这正是 Q-d 那条边界钉的服务端半场:不持行的
+                    // 订阅方连撤行帧都收不到,自然没有"结算"义务。`removeReason` 缺席 = 终态之后的常规清场。
+                    if (seenTasks.delete(frame.id)) {
+                        send("task_remove", {
+                            id: frame.id,
+                            ts: frame.ts,
+                            ...(frame.removeReason !== undefined ? { removeReason: frame.removeReason } : {}),
+                            ...(frame.cycleSeq !== undefined ? { cycleSeq: frame.cycleSeq } : {}),
+                        });
+                    }
                     break;
                 case "workflow_remove":
                     // 🔴 #189 / codex R2-M1:按窗**刻意保留**的历史行不受本连接的撤行帧影响。行在 durable 读

package/dist/http/routes/runs.js

@@ -144,6 +144,51 @@ async function subagentReadGate(req, res, deps, runId) {
     }
     return { run, trusted };
 }
+/**
+ * #261 §3 —— a\* 句柄读腿的 **404 三分**(TaskOutput / tail / task-handle output+stop 四条腿共用)。
+ *
+ * ## 病灶(cli 原票的另一半)
+ * 这些腿的 404 此前把三件互不相干的事说成同一句话:(i) handle 从未存在(打错字);(ii) **引擎重启后
+ * registry 失忆** —— 句柄活在进程内 registry 里,宿主 run 一终局/进程一重启它就没了;(iii) **打错副本**
+ * —— run 正在别的 replica 上跑,句柄在**那边**的 registry 里。壳只能猜(cli 四刀里「断流判据修正」
+ * 就是在替这个缺口打补丁)。
+ *
+ * ## 判别材料从哪来(**零新增读**,这点是承重的)
+ * 全部来自 {@link subagentReadGate} 已经读到手、且**已证明属于调用方**的那条**宿主 run 行**:
+ *  · `isTerminalRunStatus(run.status)` ⇒ 宿主 run 已终局 ⇒ 它的进程内 registry 子代必然已随之离场
+ *    ⇒ `not_found.task_owner_settled`;
+ *  · `run.status === "running"` 且 `run.instanceId` 指向**别的**副本 ⇒ 它的句柄都在那边的 registry 里
+ *    ⇒ `not_found.task_owner_elsewhere`;
+ *  · 其余(本副本在跑 / park 中 / `instanceId` 为 null 的前列行)⇒ **最弱主张**,码与文案逐字不变。
+ *
+ * 🔴 **两个新码陈述的是「属主」,不是「这个句柄」**(codex 对抗复审 R1-F5 [medium],验真后采纳)。
+ * 走到这里的 `not_found` 同样可能来自**拼错的句柄**、错的 kind、或别的 run 的句柄 —— 本函数手上
+ * **没有**任何目标级证据能证明这个句柄存在过。首版的码名(`task_retired`)与文案(「它存在过,已终局」)
+ * 因此是**越权断言**:一个自动客户端会据此停止查找,而真相可能只是它把 id 打错了。现在两个码逐字只说
+ * 属主 run 的**状态与位置**(那是调用方本就有权读到的东西,`GET /v1/runs/:id` 直答),句柄本身仍是
+ * 那句最弱主张 "no such background task handle here" —— 判别性给到了(壳能分清「registry 失忆」与
+ * 「打错副本」),存在性一个字都没多说。
+ *
+ * 🔴 **A-041 反枚举不变式原样保留**:三分**只对自己人开**。跨 principal 的调用方在上面那道门就已经
+ * 被 `not_found.run` 挡掉(与 unknown 臂同码同文,#262 oracle 封口),根本走不到这里 —— 所以这三分
+ * 泄露的全部信息是「**你自己**这条 run 的状态」,而那本来就是 `GET /v1/runs/:id` 直答的东西。
+ *
+ * 🔴 **拿不准的恒答最弱主张**(§3 逐字):本函数不为判别性去造任何新证据 —— 不查 registry、不查
+ * durable background_agent 行。`instanceId === null`(建列之前的行)是"不知道"而不是"在本机",故落最弱臂。
+ */
+function sendHandleMiss(res, run, thisInstanceId) {
+    if (isTerminalRunStatus(run.status)) {
+        sendError(res, 404, "not_found.task_owner_settled", "no such background task handle here. Routing hint about its OWNER (not about this handle): the run has already settled, and background handles live in the replica-local registry for the parent's lifetime, so none of its handles are readable any more. Read the run's own outcome via GET /v1/runs/:id");
+        return true;
+    }
+    // `instanceId` 缺席(null,或建列之前/替身行上的 undefined)= **不知道它在哪**,不是"在别处" ——
+    // 落最弱主张。同理 `thisInstanceId` 缺席时本副本连自己是谁都说不上,更不能断言别人。
+    if (run.status === "running" && typeof run.instanceId === "string" && run.instanceId.length > 0 && thisInstanceId !== undefined && run.instanceId !== thisInstanceId) {
+        sendError(res, 404, "not_found.task_owner_elsewhere", "no such background task handle here. Routing hint about its OWNER (not about this handle): the run is executing on another replica, and this one's registry holds none of its handles. Ask the replica that owns the run, or read the run's own outcome via GET /v1/runs/:id");
+        return true;
+    }
+    return false;
+}
 async function streamRunEvents(req, res, deps, runStore, taskId, staleMs) {
     await streamSseLog(req, res, {
         // #151 车3 §5.1:durable tail 腿的开流重放 —— 本 run 的未决审批卡按 taskId 读回并投成
@@ -1242,7 +1287,10 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         // agent rows are OBSERVATION identities (never in the registry) — their read face is the workflow
         // journal (GET /v1/workflows/:id/journal), and they land in the not_found arm here by construction.
         if (details?.error === "not_found" || details?.type !== "background_agent") {
-            sendError(res, 404, "not_found.subagent", `no background agent "${target}" under this run (unknown handle, not this run's child, or already reaped — bg children live in the replica-local registry for the parent's lifetime; wa… workflow-agent rows are read via the workflow journal, not this verb)`);
+            // #261 §3:同 principal 前提下的 404 三分(材料全部来自已证属主的宿主 run 行,零新增读)。
+            // #261 §3:同 principal 前提下的 404 三分(材料全部来自已证属主的宿主 run 行,零新增读)。
+            if (!sendHandleMiss(res, run, deps.instanceId))
+                sendError(res, 404, "not_found.subagent", `no background agent "${target}" under this run (unknown handle, not this run's child, or already reaped — bg children live in the replica-local registry for the parent's lifetime; wa… workflow-agent rows are read via the workflow journal, not this verb)`);
             return;
         }
         // Pass the registry's honest projection through: status/retrieval_status/partial flags verbatim,
@@ -1287,7 +1335,9 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         const probeDetails = probe.details;
         if (probeDetails?.error === "not_found" || probeDetails?.type !== "background_agent") {
             void it.return?.();
-            sendError(res, 404, "not_found.subagent", `no background agent "${target}" under this run (unknown handle, not this run's child, or already reaped — bg children live in the replica-local registry for the parent's lifetime; wa… workflow-agent rows are read via the workflow journal, not this verb)`);
+            // #261 §3 三分(与 output 面同判据同码)
+            if (!sendHandleMiss(res, run, deps.instanceId))
+                sendError(res, 404, "not_found.subagent", `no background agent "${target}" under this run (unknown handle, not this run's child, or already reaped — bg children live in the replica-local registry for the parent's lifetime; wa… workflow-agent rows are read via the workflow journal, not this verb)`);
             return;
         }
         sseHeaders(res);
@@ -1400,7 +1450,9 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
             : await deps.taskHandleOutput(target, access);
         const details = out.details;
         if (details?.error === "not_found") {
-            sendError(res, 404, "not_found.task_handle", `no background task "${target}" under this run (unknown handle, not this run's task, already reaped — handles live in the replica-local registry for the parent's lifetime — or a workflow handle: workflow rows read via GET /v1/workflows/:id/journal; stopping a workflow is not on this wire)`);
+            // #261 §3 三分(GET output 与 POST stop 共这一处)
+            if (!sendHandleMiss(res, run, deps.instanceId))
+                sendError(res, 404, "not_found.task_handle", `no background task "${target}" under this run (unknown handle, not this run's task, already reaped — handles live in the replica-local registry for the parent's lifetime — or a workflow handle: workflow rows read via GET /v1/workflows/:id/journal; stopping a workflow is not on this wire)`);
             return;
         }
         // [1499] codex R3: a stop whose kill did NOT land must not read as success. Core keeps the handle

package/dist/http/server.d.ts

@@ -529,6 +529,7 @@ export declare function validateUserSkills(skills: unknown): string | null;
  */
 export declare function createHttpServer(rawDeps: ServiceDeps): http.Server & {
     denyExpiredApprovals: (now: number) => Promise<void>;
+    isRunLiveOnThisReplica: (taskId: string) => boolean;
 };
 /** POST endpoints that trigger BILLABLE work — the fail-closed auth guard must cover ALL of them (council: the
  *  guard's inline list had drifted from the handlers and missed `/v1/approvals/:id/decide`, which resumes a run

package/dist/http/server.js

@@ -3080,9 +3080,18 @@ export function createHttpServer(rawDeps) {
         if (parkedSkipped > 0)
             deps.logger?.info?.("deny_sweep_parked_skipped", { count: parkedSkipped });
     }
+    /**
+     * #261 §1(a):**副本本地活体谓词** —— 这条 taskId 现在是不是本副本手上的活腿。
+     *
+     * 交出的是一个 `(taskId) => boolean` **探针**,不是 Map:登记面的属主仍是本模块(它们是 cancel /
+     * steer / preempt 的权威表),对账腿只问一个是非题。搬 Map 会造出第二份活性判据,而两份判据必漂移。
+     * 并集口径与 `drainState.inflight` 逐字同源(`inflightRuns` = 在飞 durable 腿、`steerableRuns` =
+     * 持活 core 流的腿;一条 resume 腿同时在两表里),所以「本副本认为它活着」在两条消费线上是同一句话。
+     */
+    const isRunLiveOnThisReplica = (taskId) => inflightRuns.has(taskId) || steerableRuns.has(taskId);
     // Augment the http.Server with the D-D deny-sweep handle (back-compat: all 12 callers keep using the return
     // value AS an http.Server — listen/close/etc. — while main.ts's reaper reads server.denyExpiredApprovals).
-    return Object.assign(server, { denyExpiredApprovals });
+    return Object.assign(server, { denyExpiredApprovals, isRunLiveOnThisReplica });
 }
 const WORKER_SWAP_REDEEMABLE = {
     version_newer: true,

package/dist/main.js

@@ -43,6 +43,7 @@ import { createConfigCenterRuntime } from "./boot/config-center.js";
 import { createResolveSpec } from "./boot/resolve-spec.js";
 import { createParkedReviveInheritedGate } from "./boot/parked-revive-gate.js";
 import { startReapers } from "./boot/reapers.js";
+import { startFleetReconciler } from "./fleet/fleet-reconciler.js";
 import { openStores } from "./boot/stores.js";
 import { runAdoptionBootScan } from "./boot/adoption.js";
 import { auditDormantPermissionRules } from "./boot/permission-rules-audit.js";
@@ -1102,6 +1103,19 @@ async function main() {
     // D-D SLA-timer: wire the server's deny-sweep into the reaper holder declared above (the reaper is defined
     // before the server, so it calls through this late-bound reference).
     runDenySweep = server.denyExpiredApprovals;
+    // #261:fleet 总线存活对账腿。⚠️ 位置即契约 —— 必须在 `createHttpServer` **之后**:活体谓词
+    // (`inflightRuns` ∪ `steerableRuns` 的探针)是 server 造出来的,而 reaper 段按其自身的位置契约必须在
+    // server 之前起,所以本腿独立起表(60s 档,unref;判据/五条界全在 fleet-reconciler.ts)。
+    // 零写 durable:窄口 `getRun`/`get` 两个读方法,判死属主仍是 reaper。
+    const fleetReconcile = startFleetReconciler({
+        bus: fleetBus,
+        isLiveOnThisReplica: server.isRunLiveOnThisReplica,
+        ...(runStore ? { runs: runStore } : {}),
+        ...(workflowRunStore ? { workflows: workflowRunStore } : {}),
+        instanceId,
+        logger,
+        metrics,
+    });
     // [1934]:绑址旋钮 + 无鉴权自收窄(理由见 resolveBindHost 顶注)。undefined = Node 默认全接口。
     const bindHost = resolveBindHost(config);
     // [2062]③ HOST 继承暗通道告警:zsh 常把 HOST 设成机器名,`{...process.env}` 起底的壳会静默继承给
@@ -1232,7 +1246,7 @@ async function main() {
     // design/158 A10:收尾段搬到 src/boot/shutdown.ts(逐字)。⚠️ 调用点必须留在 listen 之后 —— 位置即契约,
     // 理由(信号注册时点/三信号相对次序/clearInterval 先于 server.close)见该文件头注。
     installShutdownHandlers({
-        config, logger, server, reaper, otelExporter, breakerState, costQuota, rateLimiter,
+        config, logger, server, reaper, fleetReconcile, otelExporter, breakerState, costQuota, rateLimiter,
         runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState,
         storeLiveProbe, configCenter, // #131-2:两个漏网的进程级后台环进收尾链
     });

package/dist/observability/fail-open.d.ts

@@ -69,6 +69,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "fleet bus 某订阅回调抛错 ⇒ 该回调本帧作废,其余订阅方与发布方不受影响。隔离是承重的:扇出同步,修前异常会传回发布方 put/update 投影点,core 持久化 catch{} 且不推进 storeRev ⇒ durable 行冻在 running 而 notify 已 ack(#183 复审 R3 HIGH)。丢的只是一个消费方的一帧渲染,故 F 类;但必须留痕——静默吞掉等于订阅方病灶永不显形。";
     };
+    readonly "server.fleet.reconcile-read-failed": {
+        readonly cls: "F";
+        readonly note: "#261 fleet 存活对账腿的一次 durable 读失败/超预算(2s)⇒ **本周期整轮跳过**并开熔断,不做任何投影。放行的最坏后果 = 幽灵行(发布方已死、行僵在内存 Map 里)在面板上多活几个周期,与本腿存在之前的行为等同(那时它永远活着),不是新损失;真源不受影响(`GET /v1/runs/:id` 照常)。方向刻意 fail-open 且**只向留行一侧**:读不出来 ≠ 该退休——库抖一下就把一屏在跑的任务从面板上抹掉,比多留一条幽灵行伤得多。必须留痕:静默吞掉之后「对账腿为什么一直没生效」在遥测里没有任何痕迹,而本腿的全部价值就是「幽灵行会自己走」。";
+    };
     readonly "server.fleet.run-status-unmapped": {
         readonly cls: "F";
         readonly note: "A-032 P1-④:`runStatusToFleet` 收到**词表外**的 run 状态词(闭集签名之外的唯一来路 = `rowToRun` 把无约束的 status 文本列裸 cast,滚动升级里更新的副本写的新词被旧副本读到)⇒ 折成 `idle`。放行的最坏后果 = 该行在 fleet 面板上**永久滞留**(removal 集 {completed,failed,killed} 收不到 idle),纯展示面、不影响 run 本身与任何执法判据,故 F 类。方向刻意不改(把 miss 折成终局会把一条还在跑的任务从面板上摘掉,误摘比多一行更伤)。留痕是承重的:2026-06-28 on-box e2e 逮到的 `blocked` 泄漏当年只能靠人眼在面板上发现——计数让下一次词表漂移在遥测里当场显形。编译期一侧已由闭集入参 + `never` 臂执法。";

package/dist/observability/fail-open.js

@@ -92,6 +92,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "fleet bus 某订阅回调抛错 ⇒ 该回调本帧作废,其余订阅方与发布方不受影响。隔离是承重的:扇出同步,修前异常会传回发布方 put/update 投影点,core 持久化 catch{} 且不推进 storeRev ⇒ durable 行冻在 running 而 notify 已 ack(#183 复审 R3 HIGH)。丢的只是一个消费方的一帧渲染,故 F 类;但必须留痕——静默吞掉等于订阅方病灶永不显形。",
     },
+    "server.fleet.reconcile-read-failed": {
+        cls: "F",
+        note: "#261 fleet 存活对账腿的一次 durable 读失败/超预算(2s)⇒ **本周期整轮跳过**并开熔断,不做任何投影。放行的最坏后果 = 幽灵行(发布方已死、行僵在内存 Map 里)在面板上多活几个周期,与本腿存在之前的行为等同(那时它永远活着),不是新损失;真源不受影响(`GET /v1/runs/:id` 照常)。方向刻意 fail-open 且**只向留行一侧**:读不出来 ≠ 该退休——库抖一下就把一屏在跑的任务从面板上抹掉,比多留一条幽灵行伤得多。必须留痕:静默吞掉之后「对账腿为什么一直没生效」在遥测里没有任何痕迹,而本腿的全部价值就是「幽灵行会自己走」。",
+    },
     "server.fleet.run-status-unmapped": {
         cls: "F",
         note: "A-032 P1-④:`runStatusToFleet` 收到**词表外**的 run 状态词(闭集签名之外的唯一来路 = `rowToRun` 把无约束的 status 文本列裸 cast,滚动升级里更新的副本写的新词被旧副本读到)⇒ 折成 `idle`。放行的最坏后果 = 该行在 fleet 面板上**永久滞留**(removal 集 {completed,failed,killed} 收不到 idle),纯展示面、不影响 run 本身与任何执法判据,故 F 类。方向刻意不改(把 miss 折成终局会把一条还在跑的任务从面板上摘掉,误摘比多一行更伤)。留痕是承重的:2026-06-28 on-box e2e 逮到的 `blocked` 泄漏当年只能靠人眼在面板上发现——计数让下一次词表漂移在遥测里当场显形。编译期一侧已由闭集入参 + `never` 臂执法。",

package/dist/trace/project.d.ts

@@ -159,6 +159,7 @@ export declare function taskProgressEventData(ev: {
     parentToolCallId?: string;
     workflowRunId?: string;
     workflowAgentLabel?: string;
+    seq?: number;
 }): Record<string, unknown>;
 /** The `task_notification` payload (core 1.202 design/115 P2: a background task finished — this event is the
  *  LEDGER/display projection of the OBSERVED terminal state, emitted the moment core observes it. It does NOT

package/dist/trace/project.js

@@ -196,6 +196,13 @@ export function toolEndEventData(ev) {
 export function taskProgressEventData(ev) {
     return {
         taskId: ev.taskId,
+        // core 5.36.0(#258,[4066] 提货①):这一拍所报的 registry 行**代际号**(fresh spawn = 1,每次
+        // 复活翻转 +1)—— 与 `TaskNotificationPayload.seq` / `BackgroundChildEvent.seq` **同一条轴**,
+        // core 原话「不是第三种拼法」。它回答的是消费端在帧迟到时otherwise判不了的那一个问题:
+        // 「这是我已知那一代的迟到首帧(同值),还是一次我还没折叠的复活(更大)?」
+        // 🔴 **缺席是事实不是缺口**:没有 `a*` registry 行的 run(同步委派子代 / workflow `wa*` / 顶层 run)
+        // 根本没有代际概念,缺席**禁**读作 cycle 1。core-mint 数值,无用户内容 ⇒ verbatim,缺席不铸键。
+        ...(typeof ev.seq === "number" ? { seq: ev.seq } : {}),
         // core 5.14.0([2854] 六车批②):委派种类判别键(core `DelegationTaskType` =
         // "background_agent" | "workflow")—— 消费端据此路由一条 progress 帧,不必再从 id 形状猜。
         // 形参取 `string` 而非闭枚举:该类型**没有**从 core 包根导出(亲验 index.d.ts 零命中,与发车帖

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.24.0",
+  "version": "7.25.0-rc.1",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.35.0",
+    "@sema-agent/core": "^5.36.0",
     "@sema-agent/registry-core": "^0.16.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",