@sema-agent/server 7.4.0 → 7.6.0

package/dist/env-facts.js

@@ -113,7 +113,9 @@ export async function ensureScratchpadDir(localDataRoot, sessionId) {
  *   - 绝对路径 + ≤{@link MAX_PATH}(core 渲染上限同源,超限=core 只能给模型假路径)+ canonical
  *     深度 ≥3(裸 /、/tmp、/home 一整块系统目录不能当豁免域;穿越形按 resolve 归一后判);
  *   - mkdir -p 确保存在(gate 的 canonicalize 与 core 根围栏都要真目录)。
- *  敏感路径的最后一道在 core gate 折叠里(sensitivePatterns deny 恒赢,exemptDirs 越不过)。 */
+ *  敏感路径的最后一道**不在**写门折叠里(#177 起搬家):守卫集 `SENSITIVE_WRITE_PATTERNS` 由
+ *  governance 拍(boot/resolve-spec.ts → applyRuntimeGovernance)无条件铸成 DENY 基线,经 tightenTaskSpec
+ *  与写门 deny-wins 折叠 —— 结论不变(deny 恒赢,本函数放出的 exemptDirs 越不过它),但施加点已换。 */
 export async function acceptShellScratchpadDir(raw, opts) {
     if (typeof raw !== "string" || raw.length === 0)
         return undefined; // additive 常态:键缺席/异形,零告警

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

@@ -1,4 +1,4 @@
-import type { TaskNotificationPayload } from "@sema-agent/core";
+import type { TaskNotificationPayload, WorkflowRun } from "@sema-agent/core";
 /** [2687-cli] 幽灵行案的单源判别:一条 `task_notification` 只有在 **agent 族 × 终态** 时才允许打
  *  `onChildTerminal`(fleet「subagent 树」只渲 agent 子代)。`background_bash`/`monitor`/`external`
  *  不属 agent fleet 树——它们此前每条都打,fleet-bus 的「无 tick 无 claim」臂给 b\* 与 m\* handle 合成
@@ -153,6 +153,16 @@ export interface FleetWorkflowRow {
     elapsedMs?: number;
     tokens?: number;
 }
+/**
+ * durable {@link WorkflowRun} → 一条 fleet workflow 行的**纯投影**(`build*`=纯数据,无行为、不发布)。
+ *
+ * 从 `JournalingWorkflowRunStore.publishFleet` **原样**抽出,因为它现在有两个调用点,而两处各写一遍
+ * 必然漂移(本仓在 startedCount 口径上已吃过同款):
+ *  ① 活写路径 —— put/update 的写观察点(行的唯一写者,见该类注);
+ *  ② `/v1/fleet/stream` 连接时快照的**有界终态行窗**(#189 修方向 1)—— 引擎重启后 boot 扫描把前世
+ *     running run 判死,终帧与撤行在同一同步栈内背靠背发出,之后才连上的客户端连快照都看不见那一行。
+ */
+export declare function buildFleetWorkflowRow(id: string, run: WorkflowRun): FleetWorkflowRow;
 /** A push frame on the fleet stream. `snapshot` = the full current state on connect; `task`/`workflow` = a single
  *  row upsert (the row transitioned); `task_remove`/`workflow_remove` = the row left the active set (terminal +
  *  swept). Stable identity (`id`) lets the UI update/remove the right row in place. */
@@ -318,7 +328,12 @@ export declare class FleetEventBus {
         type: "snapshot";
     }>;
     /** Subscribe to deltas. Returns an unsubscribe thunk. The caller typically sends `snapshot()` first, then every
-     *  delta this delivers — the snapshot+delta sequence is the live fleet view. */
+     *  delta this delivers — the snapshot+delta sequence is the live fleet view.
+     *
+     *  每个回调各自隔离(#183 复审 R3 HIGH):扇出是同步的,修前一个抛错的订阅方会把异常传回**发布方**——
+     *  而发布方是 JournalingWorkflowRunStore.put/update 的投影点,core 持久化对 put 抛错 catch{} 且不推进
+     *  storeRev ⇒ durable 行冻在 running 而 notify 已 ack,无恢复路径。投影消费方永远不该能楔死 durable
+     *  写路;抛错记 {@link recordFailOpen}(F 类,登记闸),不上抛、不影响其余订阅方。 */
     subscribe(cb: (frame: FleetFrame) => void): () => void;
     /** Live counts (test/observability). */
     get size(): {

package/dist/fleet/fleet-bus.js

@@ -21,6 +21,8 @@
  * replica-local). A cross-replica fleet roll-up is a fleet-token-gated trace-API concern (separate), not this.
  */
 import { EventEmitter } from "node:events";
+import { deriveAgentDisplayStatus } from "@sema-agent/core";
+import { recordFailOpen } from "../observability/fail-open.js";
 import { redactSecrets } from "../trace/redact.js";
 /** [2687-cli] 幽灵行案的单源判别:一条 `task_notification` 只有在 **agent 族 × 终态** 时才允许打
  *  `onChildTerminal`(fleet「subagent 树」只渲 agent 子代)。`background_bash`/`monitor`/`external`
@@ -32,6 +34,48 @@ import { redactSecrets } from "../trace/redact.js";
 export function isFleetAgentTerminalNotification(n) {
     return n.task_type === "background_agent" && (n.status === "completed" || n.status === "failed" || n.status === "killed" || n.status === "cancelled");
 }
+/**
+ * durable {@link WorkflowRun} → 一条 fleet workflow 行的**纯投影**(`build*`=纯数据,无行为、不发布)。
+ *
+ * 从 `JournalingWorkflowRunStore.publishFleet` **原样**抽出,因为它现在有两个调用点,而两处各写一遍
+ * 必然漂移(本仓在 startedCount 口径上已吃过同款):
+ *  ① 活写路径 —— put/update 的写观察点(行的唯一写者,见该类注);
+ *  ② `/v1/fleet/stream` 连接时快照的**有界终态行窗**(#189 修方向 1)—— 引擎重启后 boot 扫描把前世
+ *     running run 判死,终帧与撤行在同一同步栈内背靠背发出,之后才连上的客户端连快照都看不见那一行。
+ */
+export function buildFleetWorkflowRow(id, run) {
+    const agents = run.agents ?? [];
+    // [2336] doneCount 与 failedCount **不相交**:done 只数 completed。契约以此为前提(本文件 startedCount
+    // 注的回退式 done+failed ≤ started);把 failed 也计进 done 会让全失败 workflow 的终帧渲成 "N done"
+    // (cli 4.1.3 实测 done=2 failed=2 started=2)。
+    const done = agents.filter((a) => a.status === "completed").length;
+    const failed = agents.filter((a) => a.status === "failed").length;
+    // cli [1726] 二①:CC 规模告警的分母是 **started**(已启动),而 `totalCount`(= agents.length)是**计划总数**
+    // (含排队中)。判别口径走 core 导出的 `deriveAgentDisplayStatus` —— 一个 agent 已在 `run.agents` 里但
+    // `startedAt` 未置就是排队中。**不自己写 `startedAt !== undefined`**:那是 core 的显示契约,两端各写一遍
+    // 必然漂移,用它的函数则 core 一改、两端同时跟随。
+    const started = agents.filter((a) => deriveAgentDisplayStatus(a, run.status) !== "queued").length;
+    return {
+        id,
+        // [WF2-A parity] redact the workflow label surfaces for parity with the run + subagent-child names (below):
+        // a tool-launched (LLM-authored) workflow's meta.name/description is task-controlled and could carry a secret shape.
+        name: redactSecrets(run.name ?? "Dynamic workflow"),
+        ...(run.description ? { description: redactSecrets(run.description) } : {}),
+        scope: run.scope,
+        // codex-6 F2:sessionId 必须随行——streamFleet 对无 sessionId 的行按「同 principal 全会话可见」
+        // 兜底,漏发=A 会话的 workflow 名/进度/token 泄进 B 会话的 ?session= 过滤流。
+        ...(run.originatingSessionId ? { sessionId: run.originatingSessionId } : {}),
+        status: run.status,
+        doneCount: done,
+        totalCount: agents.length,
+        failedCount: failed,
+        startedCount: started,
+        tokens: (run.stats?.tokens ?? 0) + (run.stats?.nested?.tokens ?? 0),
+        // [1294]:跑动中也带时长(1.232 只在 endedAt 后带——clay 验收轮实锚面板恒显 0s)。终态用
+        // endedAt 定格,活跑用 now-startedAt(每次 put/update 观察点刷新,壳侧读帧即当前时长)。
+        elapsedMs: (run.endedAt ?? Date.now()) - run.startedAt,
+    };
+}
 /**
  * The process-local fleet aggregation bus. Holds the current active set + fans out deltas to SSE subscribers.
  * Upserts MERGE (a partial delta patches the existing row), so a publisher can emit just the field that changed
@@ -121,10 +165,31 @@ export class FleetEventBus {
         return { type: "snapshot", tasks: [...this.tasks.values()], workflows: [...this.workflows.values()], ts: this.now() };
     }
     /** Subscribe to deltas. Returns an unsubscribe thunk. The caller typically sends `snapshot()` first, then every
-     *  delta this delivers — the snapshot+delta sequence is the live fleet view. */
+     *  delta this delivers — the snapshot+delta sequence is the live fleet view.
+     *
+     *  每个回调各自隔离(#183 复审 R3 HIGH):扇出是同步的,修前一个抛错的订阅方会把异常传回**发布方**——
+     *  而发布方是 JournalingWorkflowRunStore.put/update 的投影点,core 持久化对 put 抛错 catch{} 且不推进
+     *  storeRev ⇒ durable 行冻在 running 而 notify 已 ack,无恢复路径。投影消费方永远不该能楔死 durable
+     *  写路;抛错记 {@link recordFailOpen}(F 类,登记闸),不上抛、不影响其余订阅方。 */
     subscribe(cb) {
-        this.emitter.on("frame", cb);
-        return () => this.emitter.off("frame", cb);
+        const isolated = (frame) => {
+            try {
+                cb(frame);
+            }
+            catch (err) {
+                // detail 构造自身也包住:抛出值若带会抛错的 toString,String() 本身会抛并逃出隔离层(fresh 复审观察项)。
+                let detail = "subscriber threw a value whose String() also threw";
+                try {
+                    detail = String(err);
+                }
+                catch {
+                    /* keep the fallback detail */
+                }
+                recordFailOpen("server.fleet.subscriber-callback-threw", detail);
+            }
+        };
+        this.emitter.on("frame", isolated);
+        return () => this.emitter.off("frame", isolated);
     }
     /** Live counts (test/observability). */
     get size() {

package/dist/fleet/fleet-terminal-window.d.ts

@@ -0,0 +1,98 @@
+/**
+ * #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 { type WorkflowRunStore } from "@sema-agent/core";
+import { type FleetWorkflowRow } from "./fleet-bus.js";
+/**
+ * 窗长 —— 10 分钟,**不做旋钮**。
+ *
+ * 它覆盖的是一段具体的人机时长:「引擎重启 → 客户端重连 → 人看一眼面板上刚才那条 workflow 怎么了」。
+ * 比它短会漏掉重连慢一步的壳(即本 issue 的病灶);比它长就变成「拿 SSE 快照当历史列表」——而历史面
+ * 本来就有真源(`GET /v1/workflows`:durable、可分页、带 scope/session 过滤),不该在这里长出第二个。
+ * 两侧边界都由语义定死,旋钮只会让部署方去调一个没有正确取值的数;fleet 面现有零旋钮,从之。
+ */
+export declare const FLEET_SNAPSHOT_TERMINAL_WINDOW_MS: number;
+/** 同一快照里终态行的行数上限(窗长之外的第二道界)。快照是面板首屏,不是历史列表——超出的部分归
+ *  `GET /v1/workflows`。 */
+export declare 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 declare const FLEET_SNAPSHOT_TERMINAL_SCAN_LIMIT = 100;
+/** durable 读的时间预算。超时=**放弃这段增益**(记 F 类 fail-open),绝不让一次慢查询把整条 SSE 握手
+ *  拖住——面板少一条历史行是难看,连不上流是坏掉。 */
+export declare const FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS = 2000;
+/**
+ * (原 `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 declare const FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS = 10000;
+/** fleet 行上的 `status` 是自由字符串(wire 面容忍未知词),而"是不是终态"必须与上面那张**同一张**
+ *  闭集表说同一句话 —— 供路由判断一条 workflow 行帧是否终态(不做裸 cast:词表就是判据)。 */
+export declare function isTerminalWorkflowRowStatus(status: string): boolean;
+export declare function seedTerminalWorkflowRow(row: FleetWorkflowRow): void;
+/** 测试缝:清 seed 缓存(与 clearTerminalWindowCooldownForTest 同姿势,生产零调用)。 */
+export declare function clearSeededTerminalRowsForTest(): void;
+export declare function recentTerminalWorkflowRows(store: WorkflowRunStore | undefined, scope: string | null, pullScope?: string): Promise<readonly FleetWorkflowRow[]>;
+/**
+ * test-only:把熔断冷却**提前**到现在(等价于"冷却期已过"),**不动**在飞读的登记。
+ *
+ * 为什么只清冷却:冷却期是墙钟(10s),测试不该真等;而"在飞读的复用是否会把毒 promise 传给后来者"
+ * 恰恰是要被测的行为,清掉它就等于把待测对象删了。生产路径不引用本函数(与
+ * `resetFailOpenRecorderForTest` 同一姿势:测试面显式,不给生产留旁路)。
+ */
+export declare function clearTerminalWindowCooldownForTest(store: WorkflowRunStore, scope: string): void;
+/** test-only:这个 store 目前还记着几个 scope(codex R4-M2 的空闲销号有没有真的销)。 */
+export declare function trackedTerminalWindowScopesForTest(store: WorkflowRunStore): number;
+//# sourceMappingURL=fleet-terminal-window.d.ts.map

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/governance-ask-marks.d.ts

@@ -0,0 +1,31 @@
+/** 标记通道的活对象(CLAUDE.md 工厂命名律:有方法 ⇒ `create*`)。**一格 scope 的视图**。 */
+export interface GovernanceAskMarks {
+    /**
+     * 写下「这次工具调用的门**当前**是不是治理层给的」。
+     *
+     * 🔴 为什么是 set 而不是只加不减(codex 交叉复审 round2 [medium],验真):**同一个 `toolCallId` 会被
+     * 复查**。core 的 `recheckApprovedEdit`(`prepare-task.js`)在人编辑了 args 之后拿**同一个**
+     * `creq.toolCallId` 重跑策略链,并可能就此再产一只 ask。若只加不减,「原始 args 治理层要问 / 编辑后
+     * 治理层放行、由**别的**策略提出第二问」这条真实路径会让第二张卡挂着一个陈旧的治理标 —— 而
+     * `isMarked` 又是非消费式的,这个假出处会一直传下去。所以每次治理层裁决都**如实覆写**本格。
+     */
+    setMarked(toolCallId: string, marked: boolean): void;
+    /** 回查(**非消费式**)。空串/缺席一律 false —— 没有身份就没有证据。 */
+    isMarked(toolCallId: string | undefined): boolean;
+    /** 测试用:清掉本视图能看到的格。 */
+    clear(): void;
+    /** 测试/可观测:本视图内的标记数。 */
+    size(): number;
+}
+/** 一张独立的标记表(不进程共享)。生产路径用的是下面 `governanceAskMarksFor` 给出的**分格视图**;
+ *  本工厂给测试(与将来的多实例形)一个不依赖任何环境的干净表。 */
+export declare function createGovernanceAskMarks(opts?: {
+    max?: number;
+}): GovernanceAskMarks;
+/** 进入一条 run 腿的标记作用域(唯一调用点 = `ToolApprovalCoordinator.runWithContext`)。 */
+export declare function runWithGovernanceAskScope<T>(scope: string, fn: () => T): T;
+/** **写侧**入口:当前异步作用域那一格的视图;作用域外 = `undefined`(写 no-op,见顶注)。 */
+export declare function currentGovernanceAskMarks(): GovernanceAskMarks | undefined;
+/** **读侧**入口:按**显式** scope 取视图(读侧不读 ALS —— 理由见顶注 round5 那段)。 */
+export declare function governanceAskMarksFor(scope: string): GovernanceAskMarks;
+//# sourceMappingURL=governance-ask-marks.d.ts.map