@sema-agent/server 7.5.0 → 7.6.0

package/dist/deployment-governance.js

@@ -0,0 +1,206 @@
+/**
+ * design/181 件一:**部署治理链的单一构造口**。
+ *
+ * 三条腿要装同一条「部署 ⊇ 操作员」治理链 —— HTTP 的 `resolveSpec`(boot/resolve-spec.ts)、durable park
+ * 的赎回腿(main.ts 的父约束重建)、`run-local`。此前只有第一条腿真装,另外两条各自手拼一小截,于是
+ * 「同一个部署旋钮在这条腿上生效、在那条腿上不存在」成了结构性可能。本文件把**构造**收成单一属主。
+ *
+ * 🔒 **折叠属主不在这里**:合成仍是 core 的 `tightenTaskSpec`,经由既有的 `applyRuntimeGovernance`
+ * (src/runtime-governance.ts)。本口**只产入参与基线**,一条 policy 都不合成 —— 折叠有六条规则
+ * (excludeTools/deferTools 并集、handsReadOnly/shellGate 放松即 throw、onAsk/hooks 冲突、键存在性
+ * profile),且 `applyRuntimeGovernance` 的 shellGate delete 臂读的是 `base.shellGate`、`governanceForced`
+ * 观察器包在其内部 —— 一个 base-free 的「已折好」新口复现不了这些,照抄=在 server 侧重写 core 的折叠。
+ *
+ * ⚠️ **禁 memoize**:`autonomy` / `commandPolicy` / `manualModeShellGate` / `sensitiveWritePatterns` 都是
+ * 热改字段(registry 热应用换 config 引用,resume 腿按**当前** config 重折 —— 与审批基线读活
+ * `config.approvalRequire` 同一姿势)。每次调用现取,boot 期缓存一份 = 把热改静默冻住。
+ */
+import { posix } from "node:path";
+import { FileError, StubExecutionEnv, combinePolicies, createAllowDenyPolicy, createDurableQuestionPolicy, createSensitivePathPolicy, err, ok, } from "@sema-agent/core";
+import { createDurableAskPolicy } from "./approval.js";
+/**
+ * #152([2703] 案二):durable 部署上的 AskUserQuestion 门。活体面(QuestionCoordinator)缺席 ⇒ 原形
+ * `createDurableQuestionPolicy()`(恒 ask ⇒ 恒 durable park)。在场 ⇒ **判决时**按活流上下文分腿:
+ * 活流腿(bg/SSE,coordinator.runWithContext 包裹且投递面此刻可达,ALS 判)allow——工具执行落到
+ * RunnerDeps.onQuestion 的 coordinator,问正在 tail 流的活人;无活流腿(sync /v1/tasks、verify/cascade、
+ * durable resume 驱动、断连后的 detach 腿)ask——durable park 原语义逐字保留(#166 后无活流腿放行执行
+ * 也不会产出空答:coordinator 无 ALS ctx ⇒ 冻结 `{kind:"unavailable"}`(src/question.ts),永不悬挂;
+ * park 仍是把问题送到人面前的唯一那条腿,正当性不变、只是反事实前提换了)。
+ * 工具名字面量与 server.ts 的 pre-CAS 守卫同源("AskUserQuestion",core 未根导出常量)。
+ * ⚠️ **单一属主**(复审 A2):AskUserQuestion 的 durable 判决只有这一处。任何需要「同参重建」这条判决的
+ * 地方(main.ts 的 parkedReviveInheritedGate 父约束链)必须调本工厂,不得自折 core 原形——两份拷贝里
+ * 只改一份正是本条 finding 的成因。**登记豁免一处**:leader worker 腿(src/leader/wire.ts provisionWorker)
+ * 自折 core 原形——该腿无活体问答面可装且 leader 不 import boot 层(分层),core 原形+sentinel 即其完整
+ * 语义;豁免注在彼处互指,接活体面之日必须并回本工厂。
+ */
+export function createDurableQuestionGate(live) {
+    if (live === undefined)
+        return createDurableQuestionPolicy();
+    return {
+        check(req) {
+            if (req.toolName !== "AskUserQuestion")
+                return { action: "allow" };
+            return live.hasLiveContext()
+                ? { action: "allow" }
+                : { action: "ask", message: "AskUserQuestion: awaiting a human answer (durable)" };
+        },
+    };
+}
+/**
+ * 沙箱 lane 上**相对形**写目标的守卫补层用 env(codex 对抗复审 round1 finding 1,红先复现)。
+ *
+ * 缺口:沙箱 lane 的守卫策略拿不到 `rootPath`(沙箱 cwd 不是 server 能猜的,#165 裁定 1),而
+ * `DeferredSandboxPathEnv.absolutePath` 对相对形一律报错。core 的 `canonicalizeTarget` 在
+ * **absolutePath 失败**这一支不置 `unresolvedSymlink`,于是守卫策略走的是
+ * 「判不了就弃权」的 `allow`(dist 亲读)。写门在场时这条腿被门的 `ask` 兜住;而
+ * `bypassPermissions` / settings 缺席这几形**根本没有门**,于是 `Write(file_path: ".env")` 一路放行——
+ * 而 core 的结构化写工具会把相对形按 engine 跟踪的 cwd 解析后真写下去(fs-write.js `resolveKey`)。
+ *
+ * 补法:**同一只**守卫策略工厂再铸一个实例,只把「路径→canonical key」这一步换成
+ * 纯词法基准(本 env)。判定与提取(哪个参数是写目标、NotebookEdit 的 notebook_path 优先、段匹配)
+ * 全部仍是 core 的,server 侧零复刻——复刻 core 的裁决逻辑正是「同源谎」那一类错误。
+ *
+ * 三条不可动的边界:
+ *  · **绝对形一律弃权**(absolutePath 报错 ⇒ canon 失败且非 unresolvedSymlink ⇒ core 判 allow):
+ *    绝对形归真身裁决那一层,#165「真身胜过名字」的裁定(域内良性软链名叫 `.ssh` 只 ask)不受影响。
+ *  · **只会 deny,不会放行**:相对形自身拼写里出现的段,解析成绝对路径后仍在,所以词法命中即真命中;
+ *    反过来一条名叫 `.env` 而真身良性的相对软链会被误 deny —— 方向是 fail-closed,与守卫集语义同向。
+ *  · **覆盖面(2026-08-08 按 core 5.19.0 #108 校正;旧文见下方「历史」段)**:本层只在
+ *    `ToolCallRequest.cwd` **缺席**那一形上说话。core 5.19.0 起每条路径解析型守卫按 `req.cwd ?? rootPath`
+ *    解析写目标(dist `core/sensitive-path-policy.js`),而 `canonicalizeTarget` 拿到 baseCwd 后会先把
+ *    相对形**拼成绝对形**再交给 env(dist `tools/fs/safety.js` 的 `baseCwd && !isAbsolutePathForm(...)`
+ *    分支)—— 本层的 `absolutePath` 对绝对形一律报错弃权 ⇒ **有戳时本层自动让位**,由真身那一层
+ *    (沙箱 `DeferredSandboxPathEnv` / host `NodeExecutionEnv`)按活 cwd 裁决,cwd 里的守卫段现在真看得见。
+ *    ⇒ 本层今天的射程 = 「引擎没盖戳」的调用:相对形**自身拼写**里带守卫段的那一类(`Write(".env")`、
+ *    `Write("cfg/.ssh/id_rsa")`),仍由本层 fail-closed 兜住。**不删臂**:让位与冗余不是一回事——
+ *    删掉它等于把「缺戳即无守卫」写死,而缺戳形在契约上是 core 明确保留的回落语义(直接调用形)。
+ *    两处特征化钉现在各带两臂(带戳 deny / 缺戳 allow):test/task-settings.test.ts 与
+ *    test/run-local.test.ts(后者是真引擎端到端,已翻成 🔴 正控)。
+ *
+ *    📜 **历史(留档,别当现状读)**:2026-08-08 之前本层的覆盖面到「cwd 里的守卫段看不见」为止——
+ *    本层把相对形挂在 `/` 上,而工具挂在 engine 活 cwd 上,`cd .git` 后 `Write("config")` 真写
+ *    `<root>/.git/config` 而本层只看得到 `/config` ⇒ 弃权。design/181 刀3 的口径更正查明这条残余面
+ *    **不是沙箱 lane 局部的**:host 腿虽供了 `rootPath`,那也是装配期的静态值,一样追不上被 Bash `cd`
+ *    就地改写的 `cwdRef.current`(run-local 端到端真复现:`cd .git/hooks` 后 `Write("pre-commit")` 真落盘)。
+ *    当年判定属主是引擎那条缝(不是任何一条消费腿——在消费腿里自己拿静态 cwd 追 `cd`,是拿会漂的复制品
+ *    追引擎的真值,本文件反复点名的病),并把两条钉写成「引擎缝落地后一起翻面」。**该缝即 core backlog
+ *    #108,已在 5.19.0 到货**,两条钉按上述翻面完毕。另一条备选收口(守卫集开启即把沙箱 lane 相对写
+ *    一律 deny,有真受损方且无对应旋钮)因此作废,无需部署方拍板。
+ */
+export class RelativeTargetLexicalEnv extends StubExecutionEnv {
+    /** 相对形 → `/<词法归一>`;绝对形 / 空串 / 含 NUL 一律报错(= 弃权,见类注)。 */
+    absolutePath(path) {
+        if (path.length === 0 || path.startsWith("/") || path.includes("\u0000")) {
+            return Promise.resolve(err(new FileError("not_supported", "this guard layer only adjudicates RELATIVE write targets (absolute forms are adjudicated against the real sandbox filesystem)", path)));
+        }
+        return Promise.resolve(ok(posix.normalize(`/${path}`)));
+    }
+    /** 恒「不存在」⇒ core 的 `canonicalizeNewPath` 逐级回退,最终把词法归一形当 canonical key 交给段匹配。
+     *  这里绝不能报错:报错会被 core 读成 `unresolvedSymlink` 而对**每一个**相对目标 deny(含普通文件)。 */
+    exists(_path, _abortSignal) {
+        return Promise.resolve(ok(false));
+    }
+}
+/**
+ * boot 期的守卫集**可编译性**门(#177 收口①,随 design/181 件一搬进本口 —— 三条消费腿同得)。
+ *
+ * 守卫集的编译发生在**每个请求**上。core 的 `compilePatterns` 对「一个路径段都没有」的模式(`"/"`、
+ * `"//"`)THROW,那条 throw 会变成**每一个任务一条 500**,且运维从错误里看不出是自己的 env 写错了。
+ * 消费腿在装配期先编译一次:非法旋钮值当场炸在启动上(与 config.ts 的 env fail-loud 同族),指名键与
+ * core 的原因。env 只是编译期的占位(compilePatterns 不碰它),真裁决用的是每请求按 lane 铸的那一个。
+ */
+export function assertGuardPatternsUsable(config) {
+    if (config.sensitiveWritePatterns.length === 0)
+        return;
+    try {
+        createSensitivePathPolicy({ env: new StubExecutionEnv(), patterns: config.sensitiveWritePatterns });
+    }
+    catch (e) {
+        throw new Error(`SENSITIVE_WRITE_PATTERNS is not a usable guard set: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/**
+ * UNGATED 信号的**补偿**(design/181 件一收编 / 件三三腿同得)。
+ *
+ * 审批基线铺开之后 core 的 `hasEffectAwareGate` 恒真,于是它那条 "write-capable hand tools are present
+ * but UNGATED" 的 onError 不再触发(判据是 `policyLayers.length > 0`,prepare-task dist 亲读)。那条信号
+ * 此前是「这个部署一个门都没接」这个 misconfig 的**唯一**提示,而守卫集只挡那二十来个路径段、其余写
+ * 目标照旧无裁决 —— 信号不能因为我们铺了基线就静默消失,所以由我们自己按同一判据说一次。
+ *
+ * 判据(与信号消失的条件逐字互补):守卫集在场 ∧ 两条产**真**门的腿都不在场(durable 门关 ∧ 单用户
+ * auto-accept 基线不适用)。三个量都是部署常量 ⇒ 消费腿在 boot 期说一次,不是每任务一次。
+ *
+ * ⚠️ 单一属主(design/181 件三):HTTP 腿与 run-local 腿共用本判据与文案。两处各写一份 = 一处改了另一处
+ * 没改,而两份都长得像对的 —— 那正是本文件存在的理由。
+ */
+export function buildOnlySensitiveBaselineWarning(config, seat) {
+    if (config.sensitiveWritePatterns.length === 0 || seat.durableEnabled || seat.singleUserAutoAcceptBaseline)
+        return undefined;
+    return {
+        event: "tool_policy_only_sensitive_baseline",
+        fields: {
+            detail: "the sensitive-path DENY baseline (SENSITIVE_WRITE_PATTERNS) is this deployment's ONLY tool policy — writes outside the guarded segments are unadjudicated, and core's own UNGATED warning no longer fires because a policy is now always present",
+            remedy: "wire an approval face (DURABLE_APPROVAL / APPROVAL_REQUIRE with a store) or accept the single-user auto-accept baseline",
+            guardedPatterns: config.sensitiveWritePatterns.length,
+        },
+    };
+}
+/**
+ * `applyRuntimeGovernance` 的 governance 实参预铸(design/181 件一)。
+ *
+ * 键存在性 profile 逐字保持消费腿原样:`autonomy`/`commandPolicy` 恒在场(值可为 `undefined`),
+ * `manualModeShellGate`/`sensitivePathPolicy` 按在场性条件展开 —— `applyRuntimeGovernance` 的
+ * `!== undefined` 判据对两者等价,但 profile 是折叠面的可观测字节,搬家不许顺手改。
+ */
+export function createDeploymentGovernanceInputs(config, pathAdjudication) {
+    const sensitivePathPolicy = config.sensitiveWritePatterns.length > 0
+        ? (() => {
+            const realTarget = createSensitivePathPolicy({
+                env: pathAdjudication.env,
+                patterns: config.sensitiveWritePatterns,
+                ...(pathAdjudication.cwd !== undefined ? { rootPath: pathAdjudication.cwd } : {}),
+            });
+            // cwd 在场(host 形)⇒ 相对形已被 core 按 rootPath 解析进真身裁决,一层就够。
+            // cwd 缺席(沙箱形)⇒ 相对形在真身那一层是「判不了 ⇒ 弃权 allow」,而写门恰恰在
+            // bypass/settings 缺席这几形不在场 ⇒ 补一层纯词法的相对形守卫(见 RelativeTargetLexicalEnv)。
+            if (pathAdjudication.cwd !== undefined)
+                return realTarget;
+            return combinePolicies(realTarget, createSensitivePathPolicy({ env: new RelativeTargetLexicalEnv(), patterns: config.sensitiveWritePatterns }));
+        })()
+        : undefined;
+    return {
+        autonomy: config.autonomy,
+        commandPolicy: config.commandPolicy,
+        ...(config.manualModeShellGate ? { manualModeShellGate: config.manualModeShellGate } : {}),
+        ...(sensitivePathPolicy ? { sensitivePathPolicy } : {}),
+    };
+}
+/**
+ * 审批基线 —— `applyRuntimeGovernance` 那个 base 的 `toolPolicy` 座(design/181 件一)。**恒非
+ * `undefined`**:治理层是 tighten-only 的叠加层,没有基线可叠时它自己也产不出「门在场」这件事。
+ *
+ * 两形:
+ *  · `durable` 在场 ⇒ durable 轴 = AskUserQuestion 判决门 + F4 高危写审批门(deny/neverAuto/预算/
+ *    会话豁免全在 `createDurableAskPolicy` 里)。gated `ask` 由 core 变成 durable checkpoint suspend。
+ *  · `durable` 缺席 ⇒ **adjudicated allow-all**(`createAllowDenyPolicy({})`):一条**在场的**、
+ *    effect-aware 的策略。CC 的信任模型是 auto-accept,但门**机制**必须在场(core 原则「机制留、默认
+ *    可更宽」)—— 满足 core 的 `hasEffectAwareGate`,恢复可观测性与 hook/tighten 点,而运维照旧用
+ *    `AUTONOMY`/`commandPolicy` 收紧不可逆操作(由 `applyRuntimeGovernance` tighten-only 叠上)。
+ *
+ * ⚠️ 「零门意图才铺 allow-all」这条准入判据**不在本口**:它是消费腿的部署形判断(单用户/多租户、
+ * 有无 checkpoint 店),属主是 `hasOperatorGateIntent`/`assertGateIntentServiceable`(src/approval.ts)。
+ * 本口只按调用方给的形铸策略,绝不替它判「这个部署该不该有门」。
+ */
+export function createApprovalBaselinePolicy(config, durable) {
+    if (durable === undefined)
+        return createAllowDenyPolicy({});
+    return combinePolicies(createDurableQuestionGate(durable.question), createDurableAskPolicy({
+        requireApproval: config.approvalRequire,
+        deny: config.approvalDeny,
+        autoBudget: config.approvalAutoBudget,
+        neverAuto: config.approvalNeverAuto,
+        ...(durable.exempt ? { exempt: durable.exempt } : {}),
+        ...(durable.onExempted ? { onExempted: durable.onExempted } : {}),
+    }));
+}
+//# sourceMappingURL=deployment-governance.js.map

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. */

package/dist/fleet/fleet-bus.js

@@ -21,6 +21,7 @@
  * 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 族 × 终态** 时才允许打
@@ -33,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

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