@sema-agent/server 7.43.0 → 7.44.0

package/dist/fleet/fleet-reconciler.js

@@ -1,85 +1,17 @@
-/**
- * #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;
@@ -88,26 +20,12 @@ function rotate(rows, cursor) {
         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) => {
@@ -125,14 +43,9 @@ export function createFleetReconciler(deps) {
         }
         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++;
-            // A-067 C5(F7):竞速一结束就 clearTimeout(A-002.10 同款,approval-reconciler withDeadline 正形)
-            // ——unref 只保证不吊住进程退出,不回收定时器本身;每周期最多 FLEET_RECONCILE_MAX_ROWS 次点读,
-            // 不清就是同数量级带闭包定时器的逐周期累积。finally 对胜败两路都清。
             let t;
             const rec = await Promise.race([
                 deps.runs.getRun(id),
@@ -148,8 +61,6 @@ export function createFleetReconciler(deps) {
             return rec;
         };
         const snap = deps.bus.snapshot();
-        // 静默钟的**首见播种**:本腿起动之前就已在 bus 上的行(重启/迟接线)没有帧记录,给它们记一个
-        // "从现在开始静默"的起点 —— 否则首轮就会把一屏历史行当成静默满一周期的幽灵。
         for (const r of snap.tasks)
             if (!lastFrameAt.has(r.id))
                 lastFrameAt.set(r.id, nowMs);
@@ -165,8 +76,6 @@ export function createFleetReconciler(deps) {
             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 } : {}) });
@@ -174,10 +83,7 @@ export function createFleetReconciler(deps) {
                 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),
@@ -190,7 +96,6 @@ export function createFleetReconciler(deps) {
             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 } : {}) });
@@ -202,18 +107,11 @@ export function createFleetReconciler(deps) {
             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;
@@ -224,9 +122,9 @@ export function createFleetReconciler(deps) {
                 if (!rec) {
                     watch.delete(id);
                     continue;
-                } // 行被 reap 掉了:没有终局可投影,诚实丢弃
+                }
                 if (!isTerminalRunStatus(rec.status))
-                    continue; // 还没定局 —— 下个周期再看
+                    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);
@@ -234,39 +132,31 @@ export function createFleetReconciler(deps) {
                 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; // 子代行:随父(下面 ③ 收孤儿)
+                    continue;
                 tally.scanned++;
                 if (deps.isLiveOnThisReplica(row.id)) {
-                    // 登记面在场 ⇒ 活。**含 turn 卡死形** —— 诊断不驱逐(§1)。一次 durable 读都不发。
                     tally.skippedLive++;
                     continue;
                 }
                 if (!deps.runs)
-                    continue; // 无 durable run 店的部署(memory 车道):没有可投影的判决,整格不动
+                    continue;
                 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 了):无事可做
+                    continue;
                 if (nowRow.cycleSeq !== row.cycleSeq)
-                    continue; // 代际翻过 = 已复活,活发布方接管
+                    continue;
                 if (rec === undefined) {
-                    // durable 无行。**必须**静默满一个周期才退场:`a*` 子代行在父链接未解析时同样无 parentId,
-                    // 与顶层行结构同形,而 `getRun(a*)` 必然 miss(见模块头收窄段)。还在出帧 = 活着的证据。
                     if (idle(row.id))
                         orphanExit(row, "durable_row_absent");
                     continue;
@@ -275,42 +165,31 @@ export function createFleetReconciler(deps) {
                     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,留着
+                    continue;
                 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; // 已是终态行:活写路径自己会撤
+                        continue;
                     if (!budgetLeft()) {
                         wfCursor = wf.id;
                         break;
                     }
                     tally.reads++;
-                    // A-067 C5(F7):同上 readRun——竞速一结束 finally 清(A-002.10 同款)。
                     let wfTimer;
                     const run = await Promise.race([
                         wfGet(wf.id),
@@ -325,8 +204,6 @@ export function createFleetReconciler(deps) {
                     });
                     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));
@@ -337,12 +214,8 @@ export function createFleetReconciler(deps) {
             }
         }
         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;
@@ -352,18 +225,8 @@ export function createFleetReconciler(deps) {
         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;
@@ -378,13 +241,10 @@ export function startFleetReconciler(deps) {
                 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(() => {