@sema-agent/server 7.5.0 → 7.6.0

package/dist/fleet/fleet-terminal-window.js

@@ -0,0 +1,316 @@
+/**
+ * #189 修方向 1(黑板 [3112] 定谳)—— `/v1/fleet/stream` 连接时快照要并入的**近期终态 workflow 行窗**。
+ *
+ * ## 它修什么
+ * 引擎重启后 boot 扫描判死前世 `running` run,`publishWorkflow`(终帧)与 `removeWorkflow` 在**同一同步
+ * 调用栈内**背靠背执行;fleet bus 是纯内存 EventEmitter、无重放,`snapshot()` 只读活跃 Map ⇒ **重启之后
+ * 才连上的客户端连增量带快照都结构性看不见那一行**(cli 七轮正控实证)。durable 真源一直是对的
+ * (`GET /v1/workflows` 可达),缺的只是把它接到面板这一路上——所以这里是 **pull**:读同一份 durable
+ * store,**不碰 bus 的活跃 Map**(活行的单写者不变量、增量帧语义逐字不动)。
+ *
+ * ## 五条界(任何一条失手都只是少几行历史 ⇒ 整体 F 类 fail-open,登记 tag,不静默)
+ *  · 窗长 {@link FLEET_SNAPSHOT_TERMINAL_WINDOW_MS} · 行数 {@link FLEET_SNAPSHOT_TERMINAL_MAX_ROWS}
+ *  · 扫描面 {@link FLEET_SNAPSHOT_TERMINAL_SCAN_LIMIT} · 读预算 {@link FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS}
+ *  · 熔断冷却 {@link FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS}
+ *
+ * ## 为什么本模块有进程级可变状态(路由域刻意保持零状态,故不放在 `routes/fleet.ts`)
+ * 三件都长在同一个事实上——**`WorkflowRunStore` 契约没有取消面**,`Promise.race` 只结束等待、撤不回
+ * 已发出的查询:合流(重连风暴不按连接数放大,R1-H2)、合流窗有限(不把陈旧结果发给后来者、也不让
+ * 一条永不 settle 的读把后续连接全钉死,R2-H1/R3-M2)、熔断冷却(挂死的后端不被每周期继续加压,
+ * R3-H1)。真解是店侧查询超时/取消 —— 要动契约与四个后端,已作移交项。
+ *
+ * ## scope
+ * `WorkflowRunStore` 契约**没有跨 scope 枚举**(见 `orchestration/workflow-notify-journal.ts` 头注),
+ * 所以窗恒按**调用者自己的 principal scope** 读:fleet-wide 观察者看到的是「全租户活行 + 自己 scope 的
+ * 终态窗」。这是诚实的不对称(读不到的东西不编),方向安全(绝不多给);真行的租户/会话可见性仍由
+ * 路由的 `visW` 统一执法,本模块不自行放行。
+ */
+import { isTerminalWorkflowStatus } from "@sema-agent/core";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { buildFleetWorkflowRow } from "./fleet-bus.js";
+/**
+ * 窗长 —— 10 分钟,**不做旋钮**。
+ *
+ * 它覆盖的是一段具体的人机时长:「引擎重启 → 客户端重连 → 人看一眼面板上刚才那条 workflow 怎么了」。
+ * 比它短会漏掉重连慢一步的壳(即本 issue 的病灶);比它长就变成「拿 SSE 快照当历史列表」——而历史面
+ * 本来就有真源(`GET /v1/workflows`:durable、可分页、带 scope/session 过滤),不该在这里长出第二个。
+ * 两侧边界都由语义定死,旋钮只会让部署方去调一个没有正确取值的数;fleet 面现有零旋钮,从之。
+ */
+export const FLEET_SNAPSHOT_TERMINAL_WINDOW_MS = 10 * 60_000;
+/** 同一快照里终态行的行数上限(窗长之外的第二道界)。快照是面板首屏,不是历史列表——超出的部分归
+ *  `GET /v1/workflows`。 */
+export const FLEET_SNAPSHOT_TERMINAL_MAX_ROWS = 20;
+/**
+ * 每个终态**扫描面**的行数(店侧下推的 limit)。它比 {@link FLEET_SNAPSHOT_TERMINAL_MAX_ROWS} 大是有
+ * 具体病灶的(codex R1-M3,红先复现):店侧分页按 `createdAt DESC` 排(core 契约 + 两个 SQL 实现皆然),
+ * 而本窗的判据是**结束时刻**——一条跑了三天、刚刚才结束的 workflow(正是用户此刻要看的那条)会被 20 条
+ * 更晚创建的行挤出首页。留这段余量是在现有契约内能给的最好答案;彻底解法是店侧加一个 `ended_at DESC`
+ * 的窄查询(要过真双库门,已作移交项记在发车说明里)。
+ *
+ * 残余(如实记档):同 scope 同一终态下,若有超过本值条**更晚创建**的行,那条"早创建、刚结束"的行仍会
+ * 被挤掉。此时用户仍可从 `GET /v1/workflows` 看到真相——丢的只是面板首屏的一行。
+ */
+export const FLEET_SNAPSHOT_TERMINAL_SCAN_LIMIT = 100;
+/** durable 读的时间预算。超时=**放弃这段增益**(记 F 类 fail-open),绝不让一次慢查询把整条 SSE 握手
+ *  拖住——面板少一条历史行是难看,连不上流是坏掉。 */
+export const FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS = 2_000;
+/**
+ * (原 `FLEET_SNAPSHOT_TERMINAL_COALESCE_MS` 已删)⚖️ 「同时只有一支探针」与「结果别太陈旧」的取舍
+ * —— codex R3-M2 与 R4-H1 是两轮方向相反的 finding,这里成文定案。
+ *
+ * 后来者**加入**在飞的那支读,只要它还在自己的预算之内({@link FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS})。
+ *  · 曾短暂改成 250ms 的窄窗(想压小"采到"与"交付"的时差):实测判据下更坏 —— 慢而健康的店(比如
+ *    1.9s)配错峰重连,会变成每 250ms 起一批新读(2 次 list + ≤20 点读),而熔断要等某个调用方 2s
+ *    超时才开;单飞的意义被自己抵消(R4-H1)。
+ *  · 保留的代价:刚好在探针尾巴上加入的调用方,可能拿到一份最多约"两倍预算"之前采到的行集(R3-M2)
+ *    —— 后果是这条连接首屏少一条**刚刚**结束的行(且只有跨副本翻转才补不上帧),与本模块整体的 F 类
+ *    姿态同级;而 R4-H1 的后果是给一个已经很慢的库继续加压。取小害。
+ * 过了预算的在飞读 = 已被放弃的一代(等待方全走光了),不再加入:那一代由熔断收尾,新调用方在冷却期
+ * 外开新一代。
+ */
+/**
+ * 熔断冷却期:一次读失败/超预算之后,同 (store, scope) 在这段时间内**不再发起新读**(直接放弃这段增益,
+ * 记 F 类 fail-open)。
+ *
+ * 为什么必须有(codex R3-H1,红先复现 4→2):`WorkflowRunStore` 契约没有取消面 —— 发出去的查询撤不回。
+ * 后端挂死时,只按"复用窗过期就再起一次"办,等于每个周期给那个已经挂死的后端再加两笔永不回来的活,
+ * 连接不断则永远堆下去(池/内存/驱动队列迟早耗尽),这正是"故障期被自己的重试放大"那一族。冷却期把
+ * 新增速率钉在「每 scope 每 10s 至多一次探针」,并且**自愈**:冷却一过,下一条连接就是一次真实探测。
+ * 残余(如实记档):挂死那几笔仍在后端占着;真解=店侧查询超时/取消(要动契约与四个后端,移交项)。
+ */
+export const FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS = 10_000;
+/** 终态词表:从 {@link WorkflowRunStatus} 闭集**穷举**(缺一个键或多一个键都是编译期错误)后按 core 的
+ *  {@link isTerminalWorkflowStatus} 判定——集合的闭合由类型执法、终态的**语义**仍是 core 单源。core 若
+ *  加一个状态,这里编译期就红,而不是悄悄漏进/漏出终态窗。 */
+const TERMINAL_WORKFLOW_STATUSES = (() => {
+    const all = { running: true, completed: true, failed: true };
+    return Object.keys(all).filter((s) => isTerminalWorkflowStatus(s));
+})();
+/** fleet 行上的 `status` 是自由字符串(wire 面容忍未知词),而"是不是终态"必须与上面那张**同一张**
+ *  闭集表说同一句话 —— 供路由判断一条 workflow 行帧是否终态(不做裸 cast:词表就是判据)。 */
+export function isTerminalWorkflowRowStatus(status) {
+    return TERMINAL_WORKFLOW_STATUSES.some((s) => s === status);
+}
+const stateByStore = new WeakMap();
+function scopeState(store, scope) {
+    let byScope = stateByStore.get(store);
+    if (!byScope) {
+        byScope = new Map();
+        stateByStore.set(store, byScope);
+    }
+    let st = byScope.get(scope);
+    if (!st) {
+        st = {};
+        byScope.set(scope, st);
+    }
+    return st;
+}
+/** 开熔断,并挂一个 unref 的到期回调自清 + 销号 —— 否则「读超时 2.0s、查询 2.1s 才落地」这条常见路径会
+ *  留下一条永久驻留的 scope 记录(冷却记号没人清、`evictIfIdle` 又因为冷却未过而不动手,codex R5-M2)。
+ *  代际校验(`coolingUntil === until`)保证到期回调只清自己开的那一次。 */
+function openCooldown(store, scope, st) {
+    // codex R6-M:同一支探针失败的 N 个等待者各自到点都会走到这里——冷却语义是 per-probe-failure,不是
+    // per-waiter,首开者赢:已在冷却期内就不续期、不再铸第二支定时器(风暴+挂库时 O(连接数) 定时器与
+    // 闭包正好压在依赖已经退化的时刻)。
+    if (st.coolingUntil !== undefined && st.coolingUntil > Date.now())
+        return;
+    const until = Date.now() + FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS;
+    st.coolingUntil = until;
+    const t = setTimeout(() => {
+        if (st.coolingUntil !== until)
+            return; // 期间又开过新的一次冷却:那次自己管自己
+        st.coolingUntil = undefined;
+        evictIfIdle(store, scope, st);
+    }, FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS);
+    if (typeof t.unref === "function")
+        t.unref(); // 观测性的收尾绝不该拖住进程退出
+}
+/** 无事可记的 scope 就地销号(codex R4-M2):否则每一个**曾经**开过流的 principal 都会在这张强引用表里
+ *  永久留一条——多租户长跑进程下,租户流动/高基数身份会把它变成一条只增不减的内存线。 */
+function evictIfIdle(store, scope, st) {
+    if (st.inFlight !== undefined)
+        return;
+    if (st.coolingUntil !== undefined && Date.now() < st.coolingUntil)
+        return;
+    const byScope = stateByStore.get(store);
+    if (byScope?.get(scope) === st)
+        byScope.delete(scope);
+}
+/**
+ * 取该 scope 的近期终态行窗。**永不抛**:任何失败/超预算都收成"少几行历史"并记 F 类 fail-open。
+ *
+ * ⚠️ 调用方仍须对每一行施加与活行**同一套**可见性判据(`visW`:scope + `?session=`)——本函数按 scope
+ * 读,但会话轴刻意留给调用方,好与活行"无 sessionId 的行 fail-open 可见"的既有语义逐字一致。
+ */
+/** [3156] 轮2 真红的修:进程内终态行 seed 缓存 —— **写路径顺手喂**(publishFleet 的 terminal 臂),
+ *  读侧零库查询零时序竞态。存在理由:durable pull 的查询键是 caller 的 scope,而 fleetWide 连接
+ *  (无 auth 部署恒是)的可见性判据放行**全部** scope —— 查询键与可见性判据不同源,引擎铸行的
+ *  scope("anon:shell-live")永远不等于 caller 侧的 "default",pull 恒 miss。seed 缓存按「发生过什么」
+ *  记(与订阅方无关),读侧再过各连接自己的 visW。不是活跃集:bus 的 Map 零触碰,单写者不变量原样。
+ *  有界:行数 ≤ MAX_ROWS×2、窗长同 WINDOW_MS,超界丢最旧。 */
+const seededTerminalRows = [];
+export function seedTerminalWorkflowRow(row) {
+    const now = Date.now();
+    seededTerminalRows.push({ row, at: now });
+    // 双界修剪:窗长 + 行数(常数级,每次 seed 顺手)
+    while (seededTerminalRows.length > 0 && (now - seededTerminalRows[0].at > FLEET_SNAPSHOT_TERMINAL_WINDOW_MS || seededTerminalRows.length > FLEET_SNAPSHOT_TERMINAL_MAX_ROWS * 2)) {
+        seededTerminalRows.shift();
+    }
+}
+/** 测试缝:清 seed 缓存(与 clearTerminalWindowCooldownForTest 同姿势,生产零调用)。 */
+export function clearSeededTerminalRowsForTest() {
+    seededTerminalRows.length = 0;
+}
+/** 窗内 seed 行(同 id 取最新一条;窗外的顺手剪掉)。 */
+function seededRowsInWindow() {
+    const now = Date.now();
+    const byId = new Map();
+    for (const e of seededTerminalRows) {
+        if (now - e.at <= FLEET_SNAPSHOT_TERMINAL_WINDOW_MS)
+            byId.set(e.row.id, e.row);
+    }
+    return [...byId.values()];
+}
+export async function recentTerminalWorkflowRows(store, scope, pullScope) {
+    // [3156]:seed 缓存 = 本进程生命周期内全部终态(含 boot recover 判死)的同源可达径——fleetWide 连接
+    // (scope=null,可见性判据放行全 scope)取 seed **全量**,并以 `pullScope`(caller principal,尽力形)
+    // 做 durable pull 兜底:pull 的查询键与引擎铸行 scope 可能不同源(cli 轮2 实测 "default" vs
+    // "anon:shell-live" 恒 miss),中了是增益、中不了还有 seed——两径并集,谁都不当唯一真源。
+    // scoped 连接:seed 按本 scope 滤 + durable pull 本 scope(跨进程兜底)。
+    // [3193] 病理3:seed 侧不再按 caller scope 预滤——那是第二份可见性判据(F1 病族),与引擎铸行
+    // scope("anon:shell-live" vs caller "default")恒 miss。本函数只产**候选集**;可见/擦除由路由的
+    // visW/stripW 同一套判据裁(与快照活行、增量帧同源),窗与 MAX_ROWS 双界仍在。
+    const seeded = seededRowsInWindow();
+    const effectiveScope = scope ?? pullScope;
+    if (effectiveScope === undefined)
+        return seeded;
+    const scopeForPull = effectiveScope;
+    if (!store)
+        return seeded; // 无 durable store 的部署(memory 后端/未开自编排):seed 缓存仍工作
+    const cooling = scopeState(store, scopeForPull);
+    if (cooling.coolingUntil !== undefined && Date.now() < cooling.coolingUntil) {
+        // 熔断中:上一代读超预算(后端卡住),这段时间内连探都不探(见 FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS)。
+        recordFailOpen("server.fleet.snapshot-terminal-window-unavailable", "cooling down after an over-budget read");
+        return seeded; // 熔断只熔 durable 读;seed 是进程内的,照常(scope=null 的 fleetWide 形=全量,勿再按 null 过滤)
+    }
+    cooling.coolingUntil = undefined; // 冷却已到期:销掉这个记号,好让空闲 scope 能被回收
+    evictIfIdle(store, scopeForPull, cooling);
+    let timer;
+    const probe = sharedRead(store, scopeForPull);
+    try {
+        const budget = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error(`terminal-window read exceeded ${FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS}ms`)), FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS);
+            if (typeof timer.unref === "function")
+                timer.unref();
+        });
+        const pulled = await Promise.race([probe.rows, budget]);
+        // scoped 腿 = durable pull ∪ seed(同 id durable 优先 —— 库行是 CAS 后真源,seed 是投影快照)
+        const pulledIds = new Set(pulled.map((r) => r.id));
+        return [...pulled, ...seeded.filter((r) => !pulledIds.has(r.id))];
+    }
+    catch (err) {
+        // 熔断**只由自己这一代开**(codex R4-H1):判据是「我等的那一代到现在还挂在飞」——那才是"后端卡住、
+        // 再发就是加压"。两个反例都被这条判据排除:① 我等的那代其实已经完成/失败并销号(快失败的店不累积
+        // 在飞的活,没有加压问题,不该罚 10 秒);② 我超时时表上挂的已经是**别人**开的新一代(我这代早settle
+        // 了),拿它当证据会让一个已经健康的 scope 被上一代的迟到超时按住。
+        const st = scopeState(store, scopeForPull);
+        if (st.inFlight === probe)
+            openCooldown(store, scopeForPull, st);
+        // detail 用 `err.message` 而不是 `String(err)`:后者会调用抛出值自己的 toString,而那本身可能再抛
+        // (逃出本兜底,把降级变成故障)。非 Error 抛出值就如实说"不是 Error",不去问它任何问题。
+        recordFailOpen("server.fleet.snapshot-terminal-window-unavailable", err instanceof Error ? err.message : "terminal-window read threw a non-Error value");
+        return seeded; // durable 读失败只失去跨进程兜底;本进程 seed 照常(读它不碰后端)
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * test-only:把熔断冷却**提前**到现在(等价于"冷却期已过"),**不动**在飞读的登记。
+ *
+ * 为什么只清冷却:冷却期是墙钟(10s),测试不该真等;而"在飞读的复用是否会把毒 promise 传给后来者"
+ * 恰恰是要被测的行为,清掉它就等于把待测对象删了。生产路径不引用本函数(与
+ * `resetFailOpenRecorderForTest` 同一姿势:测试面显式,不给生产留旁路)。
+ */
+export function clearTerminalWindowCooldownForTest(store, scope) {
+    scopeState(store, scope).coolingUntil = undefined;
+}
+/** test-only:这个 store 目前还记着几个 scope(codex R4-M2 的空闲销号有没有真的销)。 */
+export function trackedTerminalWindowScopesForTest(store) {
+    return stateByStore.get(store)?.size ?? 0;
+}
+/** 合流层:同 (store, scope) 上**同时只有一代**在飞的读;后来者加入仍在预算内的那一代,settle 即销号。 */
+function sharedRead(store, scope) {
+    const st = scopeState(store, scope);
+    const existing = st.inFlight;
+    // 加入仍在预算内的那一代(见上方取舍段);更老的那代已被放弃,不加入。
+    if (existing && Date.now() - existing.startedAt < FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS)
+        return existing;
+    const entry = {
+        startedAt: Date.now(),
+        rows: readRecentTerminalWorkflowRows(store, scope).finally(() => {
+            // 只销自己那一号:一次慢读期间可能已经开始了下一代(本次先 settle 的竞态下,清空会误删新号)。
+            if (st.inFlight === entry) {
+                st.inFlight = undefined;
+                evictIfIdle(store, scope, st);
+            }
+        }),
+    };
+    // 所有等待方都可能因为超预算先走(race),没有 catch 的 promise 会变成 unhandledRejection 把进程带下去。
+    entry.rows.catch(() => undefined);
+    st.inFlight = entry;
+    return entry;
+}
+/**
+ * `Promise.all` 的**等齐**版:等**每一支**都落地,再决定成败(有失败就抛第一个失败原因)。
+ *
+ * 为什么不能用 `Promise.all`(codex R5-H1):它在**第一支**失败时立刻 reject,而兄弟支还挂在后端上。
+ * 于是这一代探针提前销号,超时的调用方看到"我这代已经不在表上了"就不开熔断(那条判据本意是排除
+ * 快失败),下一条连接照样再发一批 —— 正是这套机制要防的放大。等齐之后,"探针还在飞"与"后端还有
+ * 我发出去的活"这两件事重新同义,代际熔断的判据才成立。
+ */
+async function allOrFirstFailureAfterAllSettled(work) {
+    const settled = await Promise.allSettled(work);
+    const values = [];
+    for (const r of settled) {
+        if (r.status === "rejected")
+            throw r.reason; // 第一支失败的原因原样上抛(调用方统一收成 fail-open)
+        values.push(r.value);
+    }
+    return values;
+}
+/** 读本体(抛错/超时由 {@link recentTerminalWorkflowRows} 统一收成 fail-open)。 */
+async function readRecentTerminalWorkflowRows(store, scope) {
+    const cutoff = Date.now() - FLEET_SNAPSHOT_TERMINAL_WINDOW_MS;
+    /** 窗判据的时间轴 = 「这一行最后变成现在这样是什么时候」:终态行恒有 `endedAt`,回落 `createdAt`
+     *  (与 core `reap` 的 `endedAt ?? createdAt` 同一口径——两处对「这行多老」必须给同一个答案)。 */
+    const settledAt = (r) => r.endedAt ?? r.createdAt;
+    // 每个终态各扫一页(店侧下推 status + limit),再按结束时刻归并。不用"一次不带 status 的取页":那会被
+    // 同 scope 里更新的 running 行挤掉真正要找的终态行。
+    const pages = await allOrFirstFailureAfterAllSettled(TERMINAL_WORKFLOW_STATUSES.map((status) => store.listByScope(scope, { status, limit: FLEET_SNAPSHOT_TERMINAL_SCAN_LIMIT })));
+    const windowed = pages
+        .flat()
+        .filter((s) => s.scope === scope && settledAt(s) >= cutoff)
+        .sort((a, b) => settledAt(b) - settledAt(a) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) // 同刻结束按 id 定序:快照不许随机
+        .slice(0, FLEET_SNAPSHOT_TERMINAL_MAX_ROWS);
+    // summary 不带 doneCount/startedCount(core `WorkflowRunSummary` 没有这两位),而面板行的其余供数都在
+    // 它上面——与其在这里另写一份"近似"投影(两份投影必漂,本仓在 startedCount 口径上已吃过一次),不如
+    // 取回整行走**同一个** {@link buildFleetWorkflowRow}。代价=每行一次主键点读,受行数上限硬界(≤20),
+    // 且只发生在开流那一拍、同 scope 并发还会合流。
+    const runs = await allOrFirstFailureAfterAllSettled(windowed.map((s) => store.get(s.id)));
+    const rows = [];
+    for (const [i, run] of runs.entries()) {
+        if (!run)
+            continue; // list 与 get 之间被 reap 掉:诚实跳过,不为一个不存在的 run 造行
+        // `store.get` 是**无 scope 门**的裸读(带门的是 core 的 `getWorkflowRun`)——id 虽然来自本 scope 的
+        // 列表,仍按真行的 scope 复核一次:租户轴上宁可多判一次,也不靠"来源可信"。
+        if (run.scope !== scope)
+            continue;
+        if (!isTerminalWorkflowStatus(run.status) || settledAt(run) < cutoff)
+            continue; // 读回时已不在窗内/已不是终态
+        rows.push(buildFleetWorkflowRow(windowed[i].id, run));
+    }
+    return rows;
+}
+//# sourceMappingURL=fleet-terminal-window.js.map

package/dist/http/routes/approvals-assistant.js

@@ -1,10 +1,10 @@
-import { principalFrom, decodeCheckpointScope } from "../../security.js";
+import { principalFrom, decodeCheckpointScope, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../../security.js";
 import { verifyDirectDoorProof } from "../../principal-jwt.js";
 import { MAX_APPROVAL_REASON_CHARS } from "../../approval-hmac.js";
 import { redactedPreview } from "../../trace/redact.js";
 import { fleetRunLabels } from "../../fleet/fleet-bus.js"; // [2069]④ §3 行展示名与 fleet 行同源(见用处的注)
 import { sleep } from "../sse-log.js";
-import { sendJson, sendError, sseHeaders } from "../send.js";
+import { sendJson, sendError, sseHeaders, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_MS } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, isOperator } from "../principal-gate.js";
 // design/80 seam #2 (assistant-scheduler): graceful preempt (durable yield) + resource_limit resume of one task.
 export const ASSISTANT_PREEMPT_RE = /^\/v1\/assistant\/tasks\/([^/]+)\/preempt$/;
@@ -427,7 +427,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             let deciderPrincipal = principal;
             if (deps.config.directDoorActive) {
                 const hdr = (n) => { const h = req.headers[n]; return Array.isArray(h) ? h[0] : h; };
-                const proof = verifyDirectDoorProof({ jwt: hdr("x-approval-principal-token"), mac: hdr("x-approval-mac"), kid: hdr("x-approval-mac-kid") }, 
+                const proof = verifyDirectDoorProof({ jwt: hdr(PRINCIPAL_TOKEN_HEADER), mac: hdr(APPROVAL_MAC_HEADER), kid: hdr(APPROVAL_MAC_KID_HEADER) }, 
                 // reason 入签:同一条规则也适用于身份绑定腿(两个绑定位为 null,第五位照常参与)。
                 { sessionId: run.sessionId, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config, { actionBinding: false });
                 if (!proof.ok) {
@@ -569,7 +569,7 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                     const h = req.headers[n];
                     return Array.isArray(h) ? h[0] : h;
                 };
-                const proof = verifyDirectDoorProof({ jwt: hdr("x-approval-principal-token"), mac: hdr("x-approval-mac"), kid: hdr("x-approval-mac-kid") }, 
+                const proof = verifyDirectDoorProof({ jwt: hdr(PRINCIPAL_TOKEN_HEADER), mac: hdr(APPROVAL_MAC_HEADER), kid: hdr(APPROVAL_MAC_KID_HEADER) }, 
                 // reason 入签(三方裁 (a) + clay 干净切):落账理由属于决定内容,与 decision 同受完整性保护。
                 { sessionId, boundCallId: binding.boundCallId, boundInputHash: binding.boundInputHash, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config);
                 if (!proof.ok) {
@@ -682,7 +682,6 @@ export async function streamApprovals(req, res, cs, scope, pollMs = APPROVALS_ST
     let closed = false;
     req.on("close", () => { closed = true; });
     const start = Date.now();
-    const MAX_MS = 15 * 60 * 1000;
     let lastBeat = Date.now();
     let prev = new Map();
     let first = true;
@@ -715,11 +714,11 @@ export async function streamApprovals(req, res, cs, scope, pollMs = APPROVALS_ST
                     res.write(`event: resolved\ndata: ${JSON.stringify({ type: "resolved", sessionId: p.sessionId, toolCallId: p.toolCallId })}\n\n`); // decided/expired/gone
         }
         prev = cur;
-        if (Date.now() - start > MAX_MS) {
+        if (Date.now() - start > SSE_MAX_STREAM_MS) {
             res.write(`event: error\ndata: ${JSON.stringify({ type: "error", errorCode: "STREAM_MAX_DURATION", message: "approvals stream reached its 15-minute cap — reconnect to continue" })}\n\n`);
             break;
         }
-        if (Date.now() - lastBeat > 15_000) {
+        if (Date.now() - lastBeat > SSE_HEARTBEAT_IDLE_MS) {
             res.write(`event: heartbeat\ndata: ${JSON.stringify({ type: "heartbeat" })}\n\n`);
             lastBeat = Date.now();
         }

package/dist/http/routes/fleet.js

@@ -1,3 +1,4 @@
+import { FLEET_SNAPSHOT_TERMINAL_MAX_ROWS, isTerminalWorkflowRowStatus, recentTerminalWorkflowRows } from "../../fleet/fleet-terminal-window.js";
 import { taskNotificationFoldKey } from "../../orchestration/workflow-completion-inbox.js";
 import { sendJson, sendError, sseHeaders } from "../send.js";
 import { gatedPrincipal } from "../principal-gate.js";
@@ -44,7 +45,12 @@ async function handleFleetBody(req, res, url, ctx, miss) {
         // (a non-shell observer following one session). Default (absent) keeps the frame-即-投递 semantics —
         // today's only session-bound consumer IS the model-injecting shell.
         const observeOnly = fleetParams.get("observe") === "1";
-        await streamFleet(req, res, deps.fleetBus, fleetWide ? null : (principal ?? "default"), callerSession || null, observeOnly ? undefined : deps.workflowCompletionInbox);
+        // #189:终态行窗的 durable 读交给 streamFleet 在**订阅注册之后**做(见那里的缓冲段)——放在这里
+        // (开流之前)会让"帧已扇出而本连接尚未订阅"的窗口凭空多出一个读的时长,codex R1-H1 红先复现过。
+        // [3156] 轮2 真红修:终态窗的查询键必须与可见性判据**同源**——fleetWide 连接(callerScope=null,
+        // visW 放行全 scope)此前窗却按 caller principal("default")查,而行的 scope 是引擎铸的
+        // ("anon:shell-live")⇒ durable pull 恒 miss。fleetWide ⇒ null(窗走进程内 seed 缓存,全 scope)。
+        await streamFleet(req, res, deps.fleetBus, fleetWide ? null : (principal ?? "default"), callerSession || null, observeOnly ? undefined : deps.workflowCompletionInbox, { store: deps.workflowRunStore, scope: fleetWide ? null : (principal ?? "default"), pullScope: principal ?? "default", ready: deps.fleetRecoveryDone });
         return;
     }
     miss.fell = true;
@@ -54,7 +60,7 @@ async function handleFleetBody(req, res, url, ctx, miss) {
  *  else owner-scoped (only rows whose `scope` matches). The tenant-internal `scope` field is STRIPPED from every
  *  emitted row (it's a gate input, never rendered). A removal is forwarded ONLY for a row this connection actually
  *  saw (no id-existence oracle for an unseen tenant's run). Heartbeat + dual-close cleanup unsubscribe the bus. */
-function streamFleet(req, res, bus, callerScope, callerSession = null, completionInbox) {
+function streamFleet(req, res, bus, callerScope, callerSession = null, completionInbox, terminal) {
     return new Promise((resolve) => {
         sseHeaders(res);
         // [1508] 1.247 `bgNotifyFailClosed` — the GENERATION marker cli asked for ([1500]📌/[1502] F2): declares
@@ -81,19 +87,68 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
         // subscriber gets a content-scrubbed projection (ids/status/progress/timing kept); a fleet-wide observer
         // (trace/dashboard, callerSession === null) keeps the full row. Rows tagged with the caller's own session
         // pass sessionOk and are never scrubbed (r.sessionId present ⇒ it equals callerSession here).
+        // codex R6:FleetTaskRow 逐键处置表——`satisfies Record<keyof FleetTaskRow,…>` 使**任何**行新键先在
+        // 编译期红(TS2741),强迫对跨会话可见性表态;"keep" 键必须同步进下方白名单构造,配套钉在
+        // test/fleet-bg-child.test.ts(R6 格:kept 键集 ⊆ 表内 keep∪rewrite 集)。
+        const SCOPED_TASK_KEY_DISPOSITION = {
+            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",
+            name: "rewrite", scope: "strip", sessionId: "strip",
+            description: "scrub", agentType: "scrub", agentName: "scrub", currentAction: "scrub",
+            currentTool: "scrub", transcriptId: "scrub", stoppedBy: "scrub", editedFiles: "scrub",
+        };
+        void SCOPED_TASK_KEY_DISPOSITION;
         const stripT = (r) => {
             const { scope: _s, sessionId: _sid, ...rest } = r;
             if (callerSession !== null && r.sessionId === undefined) {
-                const { description: _d, agentType: _at, agentName: _an, currentAction: _ca, ...keep } = rest;
-                return { ...keep, name: "(unattributed)" };
+                // [3136]②→codex R6(确认轮):黑名单形被两次击穿(currentTool、editedFiles)——同一信任边界的键
+                // 靠逐个想起来列,漏一个就是跨会话内容泄漏。改**白名单构造**:kept 对象逐键显式拼,未列键默认
+                // 不过;新键先过上方处置表的编译期门。
+                return {
+                    id: rest.id,
+                    status: rest.status,
+                    name: "(unattributed)",
+                    ...(rest.parentId !== undefined ? { parentId: rest.parentId } : {}),
+                    ...(rest.parentToolCallId !== undefined ? { parentToolCallId: rest.parentToolCallId } : {}),
+                    ...(rest.workflowRunId !== undefined ? { workflowRunId: rest.workflowRunId } : {}),
+                    ...(rest.startedAt !== undefined ? { startedAt: rest.startedAt } : {}),
+                    ...(rest.elapsedMs !== undefined ? { elapsedMs: rest.elapsedMs } : {}),
+                    ...(rest.tokens !== undefined ? { tokens: rest.tokens } : {}),
+                    ...(rest.queuedCount !== undefined ? { queuedCount: rest.queuedCount } : {}),
+                    ...(rest.awaitingPlanApproval !== undefined ? { awaitingPlanApproval: rest.awaitingPlanApproval } : {}),
+                    ...(rest.toolUses !== undefined ? { toolUses: rest.toolUses } : {}),
+                    ...(rest.usage !== undefined ? { usage: rest.usage } : {}),
+                    ...(rest.resumable !== undefined ? { resumable: rest.resumable } : {}),
+                    ...(rest.sourceLane !== undefined ? { sourceLane: rest.sourceLane } : {}),
+                };
             }
             return rest;
         };
+        // A-002.5(#194 病族 F2):workflow 行与 task 行同一条降权跨会话边界——stripT 的黑名单三次被
+        // 击穿后改了白名单,stripW 当时漏改(同函数体孪生)。处置表同姿势:行加新键先编译红强迫表态。
+        const SCOPED_WORKFLOW_KEY_DISPOSITION = {
+            id: "keep", status: "keep", doneCount: "keep", totalCount: "keep", failedCount: "keep",
+            startedCount: "keep", elapsedMs: "keep", tokens: "keep",
+            name: "rewrite", scope: "strip", sessionId: "strip",
+            description: "scrub",
+        };
+        void SCOPED_WORKFLOW_KEY_DISPOSITION;
         const stripW = (r) => {
             const { scope: _s, sessionId: _sid, ...rest } = r;
             if (callerSession !== null && r.sessionId === undefined) {
-                const { description: _d, ...keep } = rest;
-                return { ...keep, name: "(unattributed)" };
+                // 白名单构造:kept 逐键显式拼,未列键默认不过(与 stripT 同形;"keep" 键必须同步进处置表)。
+                return {
+                    id: rest.id,
+                    status: rest.status,
+                    name: "(unattributed)",
+                    ...(rest.doneCount !== undefined ? { doneCount: rest.doneCount } : {}),
+                    ...(rest.totalCount !== undefined ? { totalCount: rest.totalCount } : {}),
+                    ...(rest.failedCount !== undefined ? { failedCount: rest.failedCount } : {}),
+                    ...(rest.startedCount !== undefined ? { startedCount: rest.startedCount } : {}),
+                    ...(rest.elapsedMs !== undefined ? { elapsedMs: rest.elapsedMs } : {}),
+                    ...(rest.tokens !== undefined ? { tokens: rest.tokens } : {}),
+                };
             }
             return rest;
         };
@@ -102,14 +157,18 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
         // 单点注入:调用方已带 type 的帧(hook_notice/bg_notification)保持原值。
         const send = (event, data) => { if (!res.writableEnded)
             res.write(`event: ${event}\ndata: ${JSON.stringify({ type: event, ...data })}\n\n`); };
-        // connect-time snapshot (filtered + scope-stripped) — the visible rows become this connection's "seen" set.
-        const snap = bus.snapshot();
-        const tasks = snap.tasks.filter(visT);
-        const workflows = snap.workflows.filter(visW);
-        tasks.forEach((r) => seenTasks.add(r.id));
-        workflows.forEach((r) => seenWf.add(r.id));
-        send("snapshot", { tasks: tasks.map(stripT), workflows: workflows.map(stripW), ts: snap.ts });
-        const unsubscribe = bus.subscribe((frame) => {
+        /** #189:快照里那些**按窗保留**的 workflow 行 id(来自 durable 终态窗,或握手期间才翻终态的行)
+         *  —— 见 workflow / workflow_remove 两臂。 */
+        const retainedTerminalWf = new Set();
+        /** 现在是否正在重放握手期缓冲(只在这段里,终态行帧才升级为"保留行")。 */
+        let replayingBuffer = false;
+        /** [3193] codex R4:首见即终态的历史行保留**预算**(每连接)。retainedTerminalWf 本身不积累
+         *  (每个 id 的撤行帧即刻消费),真正会无界的是「被豁免撤行、留在面板与 seenWf 里的历史行数」。
+         *  预算=终态窗容量同阶(×2);耗尽后退回旧「终帧→撤行」契约(行瞬态可见)——有界降级,不吞帧。
+         *  快照径的保留行不占预算(已由窗的行数+窗龄双界)。 */
+        let retainedHistoryBudget = FLEET_SNAPSHOT_TERMINAL_MAX_ROWS * 2;
+        /** 一条增量帧的处理(**先注册订阅、后组装快照**,故与快照解耦成具名函数——见下方缓冲段)。 */
+        const handleFrame = (frame) => {
             switch (frame.type) {
                 case "task":
                     if (visT(frame.row)) {
@@ -119,6 +178,19 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                     break;
                 case "workflow":
                     if (visW(frame.row)) {
+                        // #189 / codex R4-M3 → [3193] ①a 泛化:**本连接首见即终态**的行(重放期或活径皆然)与终态窗
+                        // 里的行是同一件事——它对这条连接从来不是"活跃集成员",是历史;它的撤行帧描述的活跃集离场
+                        // 对本连接无意义,照发只会让"看不看得见刚结束的 workflow"取决于 recover 落在握手窗哪一侧
+                        // (cli [3193] 插桩实证:落在重放窗内=保留可见,落在重放窗后=终帧+撤行背靠背、行瞬现即消)。
+                        // ⇒ 判据=「重放期 ∪ 首见即终态」并集(#189 原判据的严格超集):重放期臂保住"快照见过
+                        // running、缓冲里才翻终态"的行(R4-M3);首见臂保住活径上 recover 晚到的行(①a)。见过
+                        // running 的行在活径仍按既有契约走(终帧→撤行),在线消费端语义不变。豁免仍一次性,集合有界如旧。
+                        // [3193] codex R5:已在保留集里的 id(快照径收的)不重复扣预算——否则握手重放把同一批行
+                        // 按"快照+重放"记两次账,40 预算被快照行白耗光,其后真正的首见历史行立刻失去豁免。
+                        if ((replayingBuffer || !seenWf.has(frame.row.id)) && isTerminalWorkflowRowStatus(frame.row.status) && !retainedTerminalWf.has(frame.row.id) && retainedHistoryBudget > 0) {
+                            retainedTerminalWf.add(frame.row.id);
+                            retainedHistoryBudget--;
+                        }
                         seenWf.add(frame.row.id);
                         send("workflow", { row: stripW(frame.row), ts: frame.ts });
                     }
@@ -128,6 +200,17 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                         send("task_remove", { id: frame.id, ts: frame.ts });
                     break;
                 case "workflow_remove":
+                    // 🔴 #189 / codex R2-M1:按窗**刻意保留**的历史行不受本连接的撤行帧影响。行在 durable 读
+                    // 期间翻终态时,活写路径的「终帧 + 撤行」会落进缓冲,重放到这里就会把快照刚保住的那一行
+                    // 又撤掉 —— 于是「看不看得见刚结束的 workflow」重新取决于连接时机(晚 1ms 连上的人看得见,
+                    // 撞上这一拍的人看不见),正是本 issue 要消灭的竞态。撤行帧描述的是**活跃集**离场,而这些
+                    // 行进快照时就已经是终态历史,不在活跃集语义里。id 不复用(runId 每次新铸,终态不回滚),
+                    // 故这层豁免既有界又不会误伤后来的真活行。
+                    // 豁免**一次性**:配对的那一帧撤行到达即消费(codex R5-M3)。否则这个 id 被永久噤声——
+                    // 同 id 若之后又出现活行(帧乱序/未来的行复用),它的撤行帧也会被吞,面板留一条撤不掉的死行;
+                    // 顺带,每条长连接的保留集不再随握手期完成数无界增长。
+                    if (retainedTerminalWf.delete(frame.id))
+                        break;
                     if (seenWf.delete(frame.id))
                         send("workflow_remove", { id: frame.id, ts: frame.ts });
                     break;
@@ -217,6 +300,21 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                 default:
                     break; // snapshot frames are connect-time only, never fanned out
             }
+        };
+        // 🔴 #189 / codex R1-H1:订阅**先于**快照注册,快照组装期间到达的帧先进缓冲、发完快照再按序重放。
+        // 快照第一次有了一段 await(durable 终态窗读),而 fleet bus 只扇给**当前**订阅者、不重放 —— 先读后
+        // 订阅就等于开了一个"这段时间的帧对本连接不存在"的窗口(bg_notification 是模型注入面,丢一帧=这次
+        // 完成回执要等到下次开流才由 durable inbox 补;task_remove/hook_notice 同理)。
+        // 顺序安全:`bus.snapshot()` 取在**读之后**,缓冲里的行帧描述的都是快照那一刻或更早的状态,重放
+        // 只会把同一状态再叠一次(upsert 幂等);撤行帧仍按 seen 集判(没见过的行不发撤除)。
+        // 缓冲无显式上限:窗口被读预算硬界在 2s,且缓冲存的是**帧对象引用**(不复制行);设一个会丢帧的
+        // 上限反而正好丢掉这段代码要保住的东西。
+        let buffered = [];
+        const unsubscribe = bus.subscribe((frame) => {
+            if (buffered !== null)
+                buffered.push(frame);
+            else
+                handleFrame(frame);
         });
         // Real frame (not an SSE comment) — a per-frame-parsing BFF drops comments (zero-frame window downstream)
         const hb = setInterval(() => { if (!res.writableEnded)
@@ -234,8 +332,56 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                 res.end();
             resolve();
         };
+        // 关闭钩子在 await **之前**挂上:快照还在组装时对端就断了,也照常收摊(不然那段时间的断连没人处理)。
         req.on("close", shutdown);
         res.on("close", shutdown);
+        void (async () => {
+            // [3193] 病理1:boot recover(判死前世 running 行)与快照组装赛跑——SIGKILL 后壳重连常抢在
+            // recover 之前,此刻 seed/durable 两径皆空,快照永远缺那一行。屏障=recovery 完成 promise
+            // (main.ts 铸,memory 后端/无 gate 部署=已 resolve),**有界**等待(帧订阅已挂上,等待期帧全
+            // 进缓冲不丢):超时=recover 真挂了,按旧行为出快照(可用性路径,行还有 first-sight-terminal
+            // 豁免与下次重连兜底),不无限拖住连接。
+            if (terminal?.ready !== undefined) {
+                await Promise.race([terminal.ready, new Promise((r) => { const t = setTimeout(r, 3000); if (typeof t.unref === "function")
+                        t.unref(); })]);
+                if (done || res.writableEnded)
+                    return;
+            }
+            // #189:durable 近期终态行窗(有界 + 永不抛;详见 fleet-terminal-window.ts)。
+            const terminalWindow = terminal === undefined ? [] : await recentTerminalWorkflowRows(terminal.store, terminal.scope, terminal.pullScope);
+            if (done || res.writableEnded)
+                return; // 组装期间断连:shutdown 已 unsubscribe,不再发任何东西
+            // connect-time snapshot (filtered + scope-stripped) — the visible rows become this connection's "seen" set.
+            const snap = bus.snapshot();
+            const tasks = snap.tasks.filter(visT);
+            const live = snap.workflows.filter(visW);
+            // #189:活行(bus 的活跃集)+ durable 终态窗。
+            //  · 一行一 id:同 id 两侧都有(行刚翻转的那一拍)时 **活行优先** —— 活行是唯一写者写的当前态,
+            //    终态窗是读时快照,后者覆盖前者会让面板倒退。
+            //  · 并入行同样过 `visW`(scope + `?session=`),与活行**同一套判据**:终态行泄跨租户是事故。
+            //  · bus 的 Map **不被触碰** —— 单写者不变量原样:活跃集里永远没有终态行,增量帧语义逐字不变。
+            const liveIds = new Set(live.map((r) => r.id));
+            const retained = terminalWindow.filter((r) => !liveIds.has(r.id) && visW(r));
+            retained.forEach((r) => retainedTerminalWf.add(r.id));
+            const workflows = [...live, ...retained];
+            tasks.forEach((r) => seenTasks.add(r.id));
+            workflows.forEach((r) => seenWf.add(r.id));
+            send("snapshot", { tasks: tasks.map(stripT), workflows: workflows.map(stripW), ts: snap.ts });
+            const pending = buffered ?? [];
+            buffered = null; // 自此直投(先置空再重放:重放期间新到的帧走直投,不会插到旧帧前面)
+            replayingBuffer = true;
+            try {
+                for (const frame of pending)
+                    handleFrame(frame);
+            }
+            finally {
+                replayingBuffer = false; // 重放一结束立刻恢复常态语义(哪怕上面抛了)
+            }
+        })().catch(() => shutdown());
+        // ⚠️ 上面这个 catch 不是"静默降级":快照组装本身抛错(写向已销毁的 socket 那一族)时**没有**可以继续
+        // 的语义——这条连接已经没救了,干净收摊即正解。它真正防的是把原先同步执行器里的抛错(会直接 reject
+        // 出去)变成一条 **unhandled rejection**(Node 默认带走整个进程)。订阅回调自身的抛错另有隔离层
+        // (fleet bus 的 subscribe,记 fail-open),不经这里。
     });
 }
 //# sourceMappingURL=fleet.js.map

package/dist/http/routes/runs.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { uuidv7, mintCheckpointToken, CheckpointError, validatePendingSteer } from "@sema-agent/core";
+import { isTerminalRunStatus } from "../../plugins/store-contracts.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { HttpError, verifiedPrincipal, isUuidV7, encodeCheckpointScope } from "../../security.js";
 import { runInBackground } from "../../runs.js";
@@ -575,7 +576,10 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             // 并发腿可能先终态化(如 approval.expired),我方写打空却仍答 "cancelled" 就是响应与账本不一致。
             // 写后复读,照实际行应答(锁一样释放了;谁先写赢谁的 errorCode)。
             const finalRow = await rs.getRun(taskId).catch(() => undefined);
-            if (finalRow && finalRow.errorCode !== "cancelled" && (finalRow.status === "failed" || finalRow.status === "completed" || finalRow.status === "blocked")) {
+            // 终局判据取自词表属主 `store-contracts.ts` 的穷举 `isTerminalRunStatus`(原地手抄的三连 `===`
+            // 对 core **增**一个终局态是静默的:新态会被判成「还没终局」⇒ 这里改答 "cancelled",与账本不一致,
+            // 正是本段注释要防的那件事)。
+            if (finalRow && finalRow.errorCode !== "cancelled" && isTerminalRunStatus(finalRow.status)) {
                 sendJson(res, 202, { taskId, status: finalRow.status, errorCode: finalRow.errorCode ?? null, note: `session unlocked; the run was terminalized concurrently (${finalRow.errorCode ?? finalRow.status}) before this cancel's write — reporting the actual ledger state` });
                 return;
             }