@sema-agent/server 7.4.0 → 7.6.0

package/dist/run-local.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { type Brain } from "@sema-agent/core";
+import { type Brain, type OnAsk, type TaskSpec } from "@sema-agent/core";
+import { type ApprovalBaselineConfigView, type DeploymentGovernanceConfigView } from "./deployment-governance.js";
 import { type ServiceConfig } from "./config.js";
 import { type Logger } from "./observability/logger.js";
 /** Parsed CLI invocation. */
@@ -33,6 +34,12 @@ export interface RunLocalDeps {
     print?: (line: string) => void;
     /** stderr sink for the "you still need to set …" guidance (defaults to console.error). */
     printErr?: (line: string) => void;
+    /** design/181 件三: override the TTY detection behind the {@link createLocalApprover} seat
+     *  (defaults to `process.stdin.isTTY === true`) — lets a test drive BOTH arms deterministically. */
+    isTty?: boolean;
+    /** design/181 件三: the TTY arm's prompt (defaults to a readline `y/N` on stdin/stderr);
+     *  `signal` = core `OnAsk` 的取消(EOF/abort 决断臂见 {@link promptYesNoOnTty})。 */
+    askYesNo?: (prompt: string, signal?: AbortSignal) => Promise<boolean>;
 }
 /** Parse argv (everything AFTER `node run-local.js`). Throws a clear Error on a missing objective. */
 export declare function parseArgs(argv: string[]): RunLocalArgs;
@@ -49,6 +56,71 @@ export declare class UsageError extends Error {
  * this check in that case — the check is about a REAL run, not the assembly.
  */
 export declare function missingGatewayRequirements(config: ServiceConfig): string[];
+/** 本腿读的部署配置切面(`ServiceConfig` 结构满足;两个构造口各自的切面之和)。 */
+export interface LocalGovernanceConfigView extends DeploymentGovernanceConfigView, ApprovalBaselineConfigView {
+}
+/**
+ * design/181 件三:run-local 腿的**部署治理链装配**(#180)。
+ *
+ * 与另外两条腿(HTTP 的 `resolveSpec`、durable park 的赎回腿)装的是**同一条**链,经**同一个**构造口:
+ * 审批基线作 base 的 `toolPolicy` 座,再经**折叠属主** `applyRuntimeGovernance`(→ core `tightenTaskSpec`)
+ * 叠上部署治理段(autonomy / commandPolicy / MANUAL_MODE_SHELL_GATE / 守卫集)。本函数一条 policy 都不
+ * 自己合成。
+ *
+ * · **审批基线 = adjudicated allow-all**:一次性 CLI 没有 durable 审批设施(没有 `/decide` 腿可赎回),
+ *   所以 `createApprovalBaselinePolicy` 走 durable 缺席那一臂。它是一条**在场的** effect-aware 策略
+ *   (满足 core 的 `hasEffectAwareGate`),运维照旧用 `AUTONOMY` / `commandPolicy` / 守卫集在其上收紧。
+ * · **裁决 env 恒 host 形,锚 `workspaceDir`**:run-local 的手就跑在这台机器的这个目录上
+ *   (`--workspace` / config.d workdir / cwd 三选一,调用方已解析好),所以 `cwd` 恒在场 —— 相对形写目标
+ *   由 core 按 `rootPath` 解析进真身裁决,构造口的词法补层(沙箱腿那条)在这里自动不铺。
+ *   ✅ **旧残余面已收口(core 5.19.0 #108,2026-08-08 校正)**:`rootPath` 是装配期的**静态**值,而 core
+ *   的写工具解析相对形用的是被 Bash `cd` 就地改写的活 cwd —— 于是 `cd .git/hooks` 之后
+ *   `Write("pre-commit")` 落进守卫段却判不出来(两条 host 腿同形,本腿与 resolve-spec)。5.19.0 起守卫
+ *   按 `ToolCallRequest.cwd`(引擎每次调用从同一只 tracked cwd 盖戳)解析写目标,本腿零改动即得保护;
+ *   **不对称是 core 故意的**:目标跟活 cwd 走,守卫自己配置的目录仍锚静态根,`cd` 搬不动栅栏。全文与
+ *   证据见 `deployment-governance.ts` 的 `RelativeTargetLexicalEnv` 顶注,端到端正控钉见
+ *   test/run-local.test.ts(该钉已由 🟡 特征化翻成 🔴 正控)。
+ * · **禁 memoize**:四个旋钮都是热改字段,每次装配现读活 config(与另两条腿同一姿势)。
+ */
+export declare function applyLocalGovernance(base: TaskSpec, config: LocalGovernanceConfigView, workspaceDir: string): TaskSpec;
+/** {@link createLocalApprover} 的 io 面(全部可注入,所以两条臂都测得动)。 */
+export interface LocalApproverIo {
+    /** 这次调用是不是接在一个人面前(生产里 = `process.stdin.isTTY`)。 */
+    readonly isTty: boolean;
+    /** TTY 臂的问人器(默认 {@link promptYesNoOnTty} 的 readline y/N;`signal`=core 取消透传)。 */
+    readonly askYesNo: (prompt: string, signal?: AbortSignal) => Promise<boolean>;
+    /** 非 TTY 臂的告知面(stderr)。 */
+    readonly printErr: (line: string) => void;
+}
+/**
+ * design/181 件三:**onAsk 座**(§0 潜雷 / §5 锁 6)。
+ *
+ * 🔴 为什么这个座位是接治理链的**同窗必做项**:run-local 有 checkpointStore(file backend),所以
+ * `AUTONOMY=ask` ⇒ `shellGate:"always"` ⇒ Bash 进 `irreversibleTools` ⇒ park lane effective ⇒ **每一次
+ * shell 调用都 durable park 成一张永远没人 resume 的 checkpoint**,任务挂起、CLI 退 1。一次性 CLI 里
+ * 没有任何赎回腿,那不是「等人来批」,是卡死。core 的 `isLiveApproverSeat(onAsk)` 为真时 `suspendAsk`
+ * 早退(prepare-task dist 亲读),ask 于是落回本回调 —— 把 park 换成「问人 / 当场拒」的唯一正当接法。
+ *
+ * ⛔ **不在 toolPolicy 层做 ask→deny 映射**:core 自己就有 headless auto-deny 的语义与文案,在策略层
+ * 复刻一份 = 同源谎(两处判据日后各改各的)。裁决归 core,座位归这里。
+ *
+ * 🔴 非 TTY 臂答 `false`(真 deny),**绝不答 `"unavailable"`**:后者被 core 读成「席位够不到」并**改道
+ * `suspendAsk`**(dist `core/hooks.js:296` 的 `approverUnavailable` 重投),上面那颗雷会原样回来。
+ */
+export declare function createLocalApprover(io: LocalApproverIo): OnAsk;
+/** 默认的 TTY 问人器:一问一答,回答写 **stderr**(stdout 是任务结果的专用管道,别污染它)。
+ *  streams 可注入=EOF/abort 两臂测得动(默认 process.stdin/stderr)。
+ *
+ *  🔴 决断三臂(codex 验收轮 high,红先修):`readline/promises` 的 `question` 在输入流 EOF/close 时
+ *  **不决**(promise 悬挂)——Ctrl-D、关闭的 stdin、任务取消都会把 runLocal 永久挂住,文件后端的锁
+ *  跟着被拖住,下一次同 root 调用直接卡死。三臂全部 fail-closed 决 false:
+ *   · `signal` abort(core `OnAsk` 递进来的取消,含预先 aborted);
+ *   · readline `close`(输入流 end/close 时 readline 自关);
+ *   · `question` 自身 reject(abort throw / 流错误)。 */
+export declare function promptYesNoOnTty(prompt: string, signal?: AbortSignal, streams?: {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}): Promise<boolean>;
 /**
  * Boot the engine in LOCAL mode, run ONE task to completion, print the result. Returns the process exit
  * code (0 = completed, 1 = the task did not complete / a fatal error, 2 = bad usage / unmet env). Pure of

package/dist/run-local.js

@@ -13,7 +13,18 @@
  * applyEffective (config.d/.env drives models/roles/mcp), and the `host` exec lane (run on THIS machine,
  * no container) — identical building blocks to the server path so behavior matches (no drift). It reuses
  * main.ts's helpers verbatim; the only thing it skips is the server-only surface (createHttpServer, listen,
- * auth/rateLimit/quota/run-store/leader/durable-checkpoint/reapers).
+ * auth/rateLimit/quota/run-store/leader/durable-approval-decide/reapers).
+ *
+ * 🔴 **DEPLOYMENT GOVERNANCE IS NOT IN THAT SKIP LIST** (design/181 件三 / #180). Until 7.4.x this file
+ * assembled its `TaskSpec` with the governance chain entirely ABSENT — `loadConfig` + `applyEffective` had
+ * already parsed `autonomy` / `commandPolicy` / `sensitiveWritePatterns` into the config, and the spec
+ * literal simply never read them (compute-then-discard), so the same operator knob was live on the HTTP leg
+ * and structurally non-existent here. It now goes through the SAME single construction port as the other two
+ * legs ({@link applyLocalGovernance} → `src/deployment-governance.ts` → `applyRuntimeGovernance` → core's
+ * `tightenTaskSpec`). What this leg genuinely does NOT have is the **durable approval** face (a one-shot CLI
+ * has no `/v1/approvals/:id/decide` leg to resume from), so the approval baseline is the adjudicated
+ * allow-all arm and a gated `ask` is answered by {@link createLocalApprover} — the TTY human, or a
+ * fail-closed deny — instead of parking a checkpoint nobody will ever redeem.
  *
  *   Usage:  run-local "<objective>"  [--root <dir>] [--json] [--scenario <name>]
  *
@@ -24,10 +35,14 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { loadRemoteExec } from "@sema-agent/registry-core/node";
-import { Runner, uuidv7, parseModelMention, FileStorageBackend, NodeLspManager, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore } from "@sema-agent/core";
+import { Runner, uuidv7, parseModelMention, FileStorageBackend, NodeExecutionEnv, NodeLspManager, TtlSessionStore, CenterPromptSource, FilePromptArtifactStore, FilePromptSourceStateStore, MemoryPromptArtifactStore, MemoryPromptSourceStateStore } from "@sema-agent/core";
+import { hasOperatorGateIntent } from "./approval.js";
 import { createBrain } from "./brain.js";
+import { assertGuardPatternsUsable, buildOnlySensitiveBaselineWarning, createApprovalBaselinePolicy, createDeploymentGovernanceInputs, } from "./deployment-governance.js";
+import { applyRuntimeGovernance } from "./runtime-governance.js";
 import { ForkRoutingSessionStore } from "./plugins/fork-routing-session-store.js";
 import { taskWallClockSec } from "./task-workflow.js";
 import { applyCatalogToSource } from "./capabilities/center-prompts.js";
@@ -147,6 +162,89 @@ export function missingGatewayRequirements(config) {
     }
     return missing;
 }
+/**
+ * design/181 件三:run-local 腿的**部署治理链装配**(#180)。
+ *
+ * 与另外两条腿(HTTP 的 `resolveSpec`、durable park 的赎回腿)装的是**同一条**链,经**同一个**构造口:
+ * 审批基线作 base 的 `toolPolicy` 座,再经**折叠属主** `applyRuntimeGovernance`(→ core `tightenTaskSpec`)
+ * 叠上部署治理段(autonomy / commandPolicy / MANUAL_MODE_SHELL_GATE / 守卫集)。本函数一条 policy 都不
+ * 自己合成。
+ *
+ * · **审批基线 = adjudicated allow-all**:一次性 CLI 没有 durable 审批设施(没有 `/decide` 腿可赎回),
+ *   所以 `createApprovalBaselinePolicy` 走 durable 缺席那一臂。它是一条**在场的** effect-aware 策略
+ *   (满足 core 的 `hasEffectAwareGate`),运维照旧用 `AUTONOMY` / `commandPolicy` / 守卫集在其上收紧。
+ * · **裁决 env 恒 host 形,锚 `workspaceDir`**:run-local 的手就跑在这台机器的这个目录上
+ *   (`--workspace` / config.d workdir / cwd 三选一,调用方已解析好),所以 `cwd` 恒在场 —— 相对形写目标
+ *   由 core 按 `rootPath` 解析进真身裁决,构造口的词法补层(沙箱腿那条)在这里自动不铺。
+ *   ✅ **旧残余面已收口(core 5.19.0 #108,2026-08-08 校正)**:`rootPath` 是装配期的**静态**值,而 core
+ *   的写工具解析相对形用的是被 Bash `cd` 就地改写的活 cwd —— 于是 `cd .git/hooks` 之后
+ *   `Write("pre-commit")` 落进守卫段却判不出来(两条 host 腿同形,本腿与 resolve-spec)。5.19.0 起守卫
+ *   按 `ToolCallRequest.cwd`(引擎每次调用从同一只 tracked cwd 盖戳)解析写目标,本腿零改动即得保护;
+ *   **不对称是 core 故意的**:目标跟活 cwd 走,守卫自己配置的目录仍锚静态根,`cd` 搬不动栅栏。全文与
+ *   证据见 `deployment-governance.ts` 的 `RelativeTargetLexicalEnv` 顶注,端到端正控钉见
+ *   test/run-local.test.ts(该钉已由 🟡 特征化翻成 🔴 正控)。
+ * · **禁 memoize**:四个旋钮都是热改字段,每次装配现读活 config(与另两条腿同一姿势)。
+ */
+export function applyLocalGovernance(base, config, workspaceDir) {
+    return applyRuntimeGovernance({ ...base, toolPolicy: createApprovalBaselinePolicy(config) }, createDeploymentGovernanceInputs(config, { env: new NodeExecutionEnv({ cwd: workspaceDir }), cwd: workspaceDir }));
+}
+/**
+ * design/181 件三:**onAsk 座**(§0 潜雷 / §5 锁 6)。
+ *
+ * 🔴 为什么这个座位是接治理链的**同窗必做项**:run-local 有 checkpointStore(file backend),所以
+ * `AUTONOMY=ask` ⇒ `shellGate:"always"` ⇒ Bash 进 `irreversibleTools` ⇒ park lane effective ⇒ **每一次
+ * shell 调用都 durable park 成一张永远没人 resume 的 checkpoint**,任务挂起、CLI 退 1。一次性 CLI 里
+ * 没有任何赎回腿,那不是「等人来批」,是卡死。core 的 `isLiveApproverSeat(onAsk)` 为真时 `suspendAsk`
+ * 早退(prepare-task dist 亲读),ask 于是落回本回调 —— 把 park 换成「问人 / 当场拒」的唯一正当接法。
+ *
+ * ⛔ **不在 toolPolicy 层做 ask→deny 映射**:core 自己就有 headless auto-deny 的语义与文案,在策略层
+ * 复刻一份 = 同源谎(两处判据日后各改各的)。裁决归 core,座位归这里。
+ *
+ * 🔴 非 TTY 臂答 `false`(真 deny),**绝不答 `"unavailable"`**:后者被 core 读成「席位够不到」并**改道
+ * `suspendAsk`**(dist `core/hooks.js:296` 的 `approverUnavailable` 重投),上面那颗雷会原样回来。
+ */
+export function createLocalApprover(io) {
+    return async (req, signal) => {
+        if (!io.isTty) {
+            io.printErr(`denied "${req.toolName}" (${req.message}) — this run-local invocation has no TTY, so there is nobody to ask. ` +
+                `The gate comes from this deployment's governance knobs: AUTONOMY, MANUAL_MODE_SHELL_GATE, ` +
+                `runtime.commandPolicy (config.d/governance.json). Run it in a terminal to answer interactively, or relax the knob.`);
+            return false;
+        }
+        return io.askYesNo(`approve "${req.toolName}"? ${req.message} [y/N] `, signal);
+    };
+}
+/** 默认的 TTY 问人器:一问一答,回答写 **stderr**(stdout 是任务结果的专用管道,别污染它)。
+ *  streams 可注入=EOF/abort 两臂测得动(默认 process.stdin/stderr)。
+ *
+ *  🔴 决断三臂(codex 验收轮 high,红先修):`readline/promises` 的 `question` 在输入流 EOF/close 时
+ *  **不决**(promise 悬挂)——Ctrl-D、关闭的 stdin、任务取消都会把 runLocal 永久挂住,文件后端的锁
+ *  跟着被拖住,下一次同 root 调用直接卡死。三臂全部 fail-closed 决 false:
+ *   · `signal` abort(core `OnAsk` 递进来的取消,含预先 aborted);
+ *   · readline `close`(输入流 end/close 时 readline 自关);
+ *   · `question` 自身 reject(abort throw / 流错误)。 */
+export async function promptYesNoOnTty(prompt, signal, streams = { input: process.stdin, output: process.stderr }) {
+    if (signal?.aborted)
+        return false;
+    const rl = createInterface({ input: streams.input, output: streams.output });
+    try {
+        return await new Promise((resolve) => {
+            const settle = (v) => {
+                rl.off("close", onClosed);
+                signal?.removeEventListener("abort", onAborted);
+                resolve(v);
+            };
+            const onClosed = () => settle(false);
+            const onAborted = () => settle(false);
+            rl.on("close", onClosed);
+            signal?.addEventListener("abort", onAborted, { once: true });
+            rl.question(prompt).then((answer) => settle(/^y(es)?$/i.test(answer.trim())), () => settle(false));
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * Boot the engine in LOCAL mode, run ONE task to completion, print the result. Returns the process exit
  * code (0 = completed, 1 = the task did not complete / a fatal error, 2 = bad usage / unmet env). Pure of
@@ -248,6 +346,28 @@ export async function runLocal(argv, deps = {}) {
         printErr(`config.d/remote-exec.json is invalid: ${String(err)}`);
         return 2;
     }
+    // ── design/181 件三 boot 期两件(与 HTTP 腿同一只判据)────────────────────────────────────────
+    // ① 守卫集的**可编译性**门:编译发生在每一次装配上,一条「一个路径段都没有」的模式(`"/"`)会 THROW,
+    //    运维从那条错误里看不出是自己的 env 写错了。共享 .env 的坏值必须炸在启动上——这条腿按 run-local 的
+    //    既定 UX 落地(doctor 文案 + 退 2),而不是把栈抛给用户。
+    try {
+        assertGuardPatternsUsable(config);
+    }
+    catch (e) {
+        printErr(e instanceof Error ? e.message : String(e));
+        printErr(`(local config root: ${root} — fix it in ${join(root, ".env")} or your shell env; \`SENSITIVE_WRITE_PATTERNS=off\` disables the guard set)`);
+        return 2;
+    }
+    // ② UNGATED 补偿:接上审批基线后 core 的 `hasEffectAwareGate` 恒真 ⇒ 它那条 "write-capable hand tools
+    //    are present but UNGATED" 的信号在这条腿上结构性消失。判据与文案是**同一只**构造口的
+    //    (buildOnlySensitiveBaselineWarning),两个座位量按本腿的真形取:durable 门恒不在场(一次性 CLI
+    //    没有 /decide 赎回腿),单用户 auto-accept 基线的适用性判据与 main.ts 逐字同源。
+    const ungatedCompensation = buildOnlySensitiveBaselineWarning(config, {
+        durableEnabled: false,
+        singleUserAutoAcceptBaseline: config.requirePrincipal !== true && !hasOperatorGateIntent(config),
+    });
+    if (ungatedCompensation)
+        logger.warn(ungatedCompensation.event, ungatedCompensation.fields);
     // ── Pre-flight: with a REAL brain, validate the gateway + key and print the doctor-style guidance instead
     //    of crashing on the first brain call. With an injected mock brain, no real call happens → skip. ──
     if (!deps.brain) {
@@ -361,6 +481,20 @@ export async function runLocal(argv, deps = {}) {
     catch (e) {
         logger.warn("center_prompts_catalog_restore_failed", { err: String(e), note: "catalog candidate absent — built-ins serve" });
     }
+    // design/181 件三:**onAsk 座**(全文理由见 {@link createLocalApprover})。两只 Runner 同装 —— 委派出去
+    // 的子任务也在同一台机器上动手,少装一只就是「主任务问人、子任务 park 卡死」。
+    const onAsk = createLocalApprover({
+        isTty: deps.isTty ?? process.stdin.isTTY === true,
+        askYesNo: deps.askYesNo ?? promptYesNoOnTty,
+        printErr,
+    });
+    /** core 的 `RunnerDeps.onError` 座(两只 Runner 共用一只闭包 —— 两处各写一份正是漂移的成因)。 */
+    const engineOnError = (err, ctx) => logger.warn("engine_error", {
+        phase: ctx.phase,
+        sessionId: ctx.sessionId,
+        ...(ctx.classification !== undefined ? { classification: ctx.classification } : {}),
+        err: String(err),
+    });
     const runner = new Runner({
         brain,
         models: config.models,
@@ -372,6 +506,11 @@ export async function runLocal(argv, deps = {}) {
         sessionStore,
         ...(memoryEngine ? { memoryBackend: memoryEngine.backend, memoryEngineDir: memoryEngine.root } : {}),
         checkpointStore: fileBackend.checkpointStore,
+        // design/181 件三:core 的降级/配置类告警此前被 `deps.onError?.()` 的可选链整条吞掉(这条腿从不接这
+        // 个座),包括那条 "write-capable hand tools are present but UNGATED"。接上 stderr(logger.warn 走
+        // stderr)后其余告警——compaction / prompt-cache / mcp / memory / hook 的降级——也不再无声。
+        onError: engineOnError,
+        onAsk,
         // core 1.219 (dogfood: "ReadToolResult(ref) 恒空"): durable tool-result refs on the TOC CLI
         // lane too — offloaded full text survives a process restart (one file per ref under the data root).
         toolResultStore: fileBackend.toolResultStore,
@@ -389,7 +528,7 @@ export async function runLocal(argv, deps = {}) {
     // [1367]① fork server half(main.ts subRunner 同款):ForkRoutingSessionStore——fork/resume 形
     // (requireExisting)→ host 文件店优先(core 1.350 hostSessionFork 在宿主店 fork,拆店=响亮
     // resume.session_not_found),普通子任务 → 私有 TTL 店(throwaway 姿势保留)。
-    const subRunner = new Runner({ brain, models: config.models, roles: config.roles, pricing, promptSource, sessionStore: new ForkRoutingSessionStore(sessionStore, new TtlSessionStore({ defaultTtlDays: 1 / 24 })), ...(executionEnvFactory ? { executionEnvFactory } : {}), ...(lspManager ? { lspManager } : {}) });
+    const subRunner = new Runner({ brain, models: config.models, roles: config.roles, pricing, promptSource, sessionStore: new ForkRoutingSessionStore(sessionStore, new TtlSessionStore({ defaultTtlDays: 1 / 24 })), onError: engineOnError, onAsk, ...(executionEnvFactory ? { executionEnvFactory } : {}), ...(lspManager ? { lspManager } : {}) });
     // Capability layer (loadSkills + buildScenarios + selectScenario) — assembled exactly like main.ts.
     const skills = loadSkills(config.skillsDir);
     const repoClient = config.gitApiBaseUrl ? new GiteaClient(config.gitApiBaseUrl, config.gitApiToken) : undefined;
@@ -451,7 +590,9 @@ export async function runLocal(argv, deps = {}) {
     const taskTimeoutSec = Math.max(0, Math.floor(numEnv("TASK_TIMEOUT_SEC", "0")));
     const timeoutSec = taskWallClockSec(taskTimeoutSec, false, scenarioName === "team");
     const mcp = mcpForScenario(config.mcpServers, scenarioName);
-    const spec = {
+    // design/181 件三:自建的 spec 字面量经**同一条**部署治理链(见 {@link applyLocalGovernance})——
+    // 审批基线 + autonomy/commandPolicy/MANUAL_MODE_SHELL_GATE/守卫集,tighten-only,折叠属主仍是 core。
+    const spec = applyLocalGovernance({
         objective: mention.cleanedText || args.objective,
         sessionId,
         // design/129: run-local IS the pure TOC lane → session-scoped background children
@@ -471,7 +612,7 @@ export async function runLocal(argv, deps = {}) {
         ...(mcp ? { mcp } : {}),
         // core 5.8.0:timeoutSec 键退役 → maxWalltimeMs(毫秒);taskWallClockSec 仍产秒,此处换算一次。
         ...(timeoutSec !== undefined ? { limits: { maxWalltimeMs: timeoutSec * 1000 } } : {}),
-    };
+    }, config, workspaceDir);
     logger.info("run_local_start", { scenario: scenarioName, model: spec.model, sessionId, exec: config.remoteExec?.provider ?? "in-process" });
     // ── Run ONE task to completion (the sync /v1/tasks path: plain runTask, no verify/cascade). ──
     let result;

package/dist/runs.d.ts

@@ -80,6 +80,14 @@ export declare function taskHandleStop(registry: typeof defaultTaskRegistry, han
     content: string;
     details: unknown;
 }>;
+/**
+ * Attribute this signal's abort as a USER stop for the owner's task-scoped children.
+ *
+ * 🔴 已经 abort 的信号在这里**立刻**记账,不是静默无操作(#168 件3 的配套)。调用点在 #168 件3 之后
+ * 一律挪到了「run 认领成功之后」—— 认领是一次 await,断连完全可能落在它之前。`addEventListener` 对一个
+ * 已 fire 的信号永不回调,那样一次真实的人为断连会被吞成「无归因」(子代 settle 时记成 system)。
+ * 语义上这两种时序是同一件事:本请求赢下了这条 session,而这条 session 的连接是被人断掉的。
+ */
 export declare function markChildrenStoppedByUserOnAbort(signal: AbortSignal, taskId: string, principal: string | null | undefined): void;
 /**
  * A session CAS conflict is swallowed by core into a failed `TaskResult` (it is not thrown from
@@ -176,7 +184,9 @@ export declare class TurnAnchorCapture {
  * Strip the durable-resume capability token from a result before it is persisted to the replayable event
  * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
  * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
- * NESTED suspend under verify/cascade to status:"failed" + errorCode "suspended.awaiting_approval"(core 5.9.0 W1 改名)while still
+ * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended"(inner status
+ * "needs_review" ⇒ "unexpected.needs_review";core `agents/suspend-guard.js` `mapNestedSuspend`,由 verify.js
+ * 191/201/208 与 cascade.js:125 调用)while still
  * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
  * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
  * non-secret and intentionally kept.

package/dist/runs.js

@@ -111,15 +111,28 @@ export async function taskHandleStop(registry, handle, access, agentStore) {
     registry.markStopSource(handle, "user");
     return registry.stopTask(handle, access);
 }
+/**
+ * Attribute this signal's abort as a USER stop for the owner's task-scoped children.
+ *
+ * 🔴 已经 abort 的信号在这里**立刻**记账,不是静默无操作(#168 件3 的配套)。调用点在 #168 件3 之后
+ * 一律挪到了「run 认领成功之后」—— 认领是一次 await,断连完全可能落在它之前。`addEventListener` 对一个
+ * 已 fire 的信号永不回调,那样一次真实的人为断连会被吞成「无归因」(子代 settle 时记成 system)。
+ * 语义上这两种时序是同一件事:本请求赢下了这条 session,而这条 session 的连接是被人断掉的。
+ */
 export function markChildrenStoppedByUserOnAbort(signal, taskId, principal) {
-    signal.addEventListener("abort", () => {
+    const mark = () => {
         try {
             defaultTaskRegistry.markStopSourceForOwner({ owner: taskId, scope: principal ?? "default" }, "user", { skipSessionScoped: true });
         }
         catch {
             /* attribution is advisory — the cancel itself must never fail on it */
         }
-    }, { once: true });
+    };
+    if (signal.aborted) {
+        mark();
+        return;
+    }
+    signal.addEventListener("abort", mark, { once: true });
 }
 /**
  * A session CAS conflict is swallowed by core into a failed `TaskResult` (it is not thrown from
@@ -249,7 +262,9 @@ export class TurnAnchorCapture {
  * Strip the durable-resume capability token from a result before it is persisted to the replayable event
  * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
  * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
- * NESTED suspend under verify/cascade to status:"failed" + errorCode "suspended.awaiting_approval"(core 5.9.0 W1 改名)while still
+ * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended"(inner status
+ * "needs_review" ⇒ "unexpected.needs_review";core `agents/suspend-guard.js` `mapNestedSuspend`,由 verify.js
+ * 191/201/208 与 cascade.js:125 调用)while still
  * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
  * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
  * non-secret and intentionally kept.

package/dist/runtime-governance.d.ts

@@ -24,6 +24,7 @@
  * name). Real isolation is the `executionEnv` sandbox. Same caveat core documents on `createCoarseCommandNamePolicy`.
  */
 import { type TaskSpec, type ToolPolicy } from "@sema-agent/core";
+import { type GovernanceAskMarks } from "./governance-ask-marks.js";
 /** A per-command governance rule (registry `runtime.commandPolicy[]`). */
 export type CommandRule = {
     command: string;
@@ -106,10 +107,27 @@ export declare function autonomyOverrides(autonomy: Autonomy | undefined): Parti
  * ⇒ 旋钮静默失效(clay 实机 Monitor 案「门根本没铸」);bypassPermissions 一句话掀掉部署闸;非 host lane
  * fsWriteGate wiring 不建 ⇒ 沙箱 lane 全失效。governance 层与 autonomy 同拍施加后三者全闭。rank 合成:
  * autonomy 派生值与旋钮取大(ask→"always" 压过 "classify"),再对 base 只升不降(防 tightenTaskSpec throw)。
+ *
+ * #177([2951] issue #29,**邻仓 test AI 的 46 格真机矩阵**实证——不是本仓的钉,别到本仓文件里数 46;
+ * 本仓的类级门是 test/operator-knob-client-posture-matrix.test.ts 的 旋钮×表态×lane 矩阵):
+ * `SENSITIVE_WRITE_PATTERNS` 是 #153 那次搬家漏下的兄弟旋钮——同一个病灶原样复发在 sensitive-path
+ * DENY 腿上(唯一合成点在 deriveSettingsPolicy 的 fsWriteGate 闭包,bypassPermissions/键缺席/settings
+ * 整缺席三形整条腿不建)。同方修:调用方(resolve-spec)把 operator 守卫集预铸成 `sensitivePathPolicy`
+ * 从这里**无条件施加**——它只在守卫段上产 deny(core 语义 deny/"safety"),对其余目标返回的是
+ * `action:"allow"`(**不是**「无意见」这种第三态:core 的 ToolPolicy 没有弃权值。它在
+ * `combinePolicies` 的 deny/ask 优先折叠里不构成一票,所以在**折叠语境**下等价于弃权;若日后有人把
+ * 这条策略单独当成唯一 policy 用,那个 allow 就是真放行——别照抄这句话去别的语境)。于是对 bypass
+ * 只挡守卫段、不给普通目标加 ask 门([820] 表第四行「bypass=不加门非开门」保持逐字)。策略在这里
+ * 只组合不构造:裁决 env 的 lane 分形(host 真 fs / 沙箱 deferred 代理)是 resolve-spec 的属主知识,
+ * governance 层不重复它。
  */
 export declare function applyRuntimeGovernance(base: TaskSpec, governance: {
     autonomy?: Autonomy;
     commandPolicy?: CommandRule[];
     manualModeShellGate?: "always" | "classify";
+    sensitivePathPolicy?: ToolPolicy;
+    /** [2942]/[2943] `governanceForced` 的标记表(缺省 = **当前 run 腿的 ALS 表**,见
+     *  `governance-ask-marks.ts` 顶注「作用域」段)。注入口只为测试与将来的多实例形。 */
+    askMarks?: GovernanceAskMarks;
 }): TaskSpec;
 //# sourceMappingURL=runtime-governance.d.ts.map

package/dist/runtime-governance.js

@@ -24,6 +24,7 @@
  * name). Real isolation is the `executionEnv` sandbox. Same caveat core documents on `createCoarseCommandNamePolicy`.
  */
 import { combinePolicies, createCoarseCommandNamePolicy, DEFAULT_SUBAGENT_TOOL_NAME, parseLeadingCommandName, tightenTaskSpec, } from "@sema-agent/core";
+import { currentGovernanceAskMarks } from "./governance-ask-marks.js";
 /** True when `name` names a DELEGATION tool — the subagent tool(CC-187 canonical `"Agent"`,core
  *  `DEFAULT_SUBAGENT_TOOL_NAME`)。5.0.0 RB-476:折叠面退役,RAW 比对 core 单源常量——旧名("Task")
  *  在 core roster 层响亮 miss,不再需要归一;单源常量本身就防了当年 1.202 改名时裸字符串失配的
@@ -178,7 +179,14 @@ export function compileCommandPolicy(rules) {
         policies.push(createCoarseCommandNamePolicy({ allow, deny, defaultAction: "ask" }));
     }
     else {
-        // Blocklist mode: only `deny` blocks; per-command `ask` via the ask-list; unlisted pass through.
+        // Blocklist mode: only `deny` blocks; per-command `ask` via the ask-list; an unlisted **simple** command
+        // passes through.
+        // ⚠️ #184([3038]/[3047] 双探针实证):「unlisted pass through」只对**单纯命令**成立。带 shell 运算符的
+        // 复合命令(`a && b`、管道、`;`)`parseLeadingCommandName` 判 reject,而 `createCoarseCommandNamePolicy`
+        // 的 `defaultAction` **缺省就是 `"ask"`**(core tool-policy.js:`opts.defaultAction ?? "ask"`)—— 于是它们
+        // 在 deny 门上折 **ask**,不是放行(无 command 串的调用同理)。这与 allowlist 模式那句「fall to
+        // defaultAction」是同一个兜底,只是这里没显式传参所以容易读漏。上方 docblock 的「Un-parseable bypass
+        // commands fail toward `ask` in both the deny gate and the ask-list」说的就是这一条。零行为码改动。
         // (NOTE: never pass `allow: []` to the coarse helper — an empty array is truthy there and would turn it
         //  into an allowlist that asks on EVERYTHING. Omit allow entirely instead.)
         if (deny.length > 0)
@@ -211,6 +219,56 @@ export function autonomyOverrides(autonomy) {
             return {};
     }
 }
+/**
+ * [2942]/[2943] `governanceForced` 的**写侧** —— 把内层策略(治理层自己合成的那些)产的 `ask` 记进标记表。
+ *
+ * 决议本身**逐字透传**:本包装器只观察,不改 action / message / updatedInput / decisionReason,也不吞异常
+ * (内层抛就照抛,fail-closed 的属主仍是内层)。同步内层保持同步返回(不无谓地把一条同步策略异步化)。
+ *
+ * 为什么标在这一层而不是让 `decisionReason` 上 wire:core 的 ask 铸造点不透传 `PermissionResult`
+ * (侦察结论逐字见 `governance-ask-marks.ts` 顶注),这条缝在当前 core 上根本不存在。
+ */
+function createGovernanceAskMarkingPolicy(inner, marksOf) {
+    // 🔴 codex 交叉复审 round2 [medium](验真):**如实覆写**,不是只加不减 —— core 的
+    // `recheckApprovedEdit` 拿同一个 `toolCallId` 重跑策略链(人编辑 args 之后),「原始 args 治理层要问 /
+    // 编辑后治理层放行、由别的策略提第二问」会让第二张卡挂陈旧治理标。理由全文见 GovernanceAskMarks.setMarked。
+    const note = (d, req) => {
+        // 表在**裁决那一刻**解析(不是构造时):策略闭包铸于 resolveSpec,真正的作用域要到 run 腿跑起来才在。
+        marksOf()?.setMarked(req.toolCallId, d.action === "ask");
+        return d;
+    };
+    return {
+        check(req, signal) {
+            const decision = inner.check(req, signal);
+            return decision instanceof Promise ? decision.then((d) => note(d, req)) : note(decision, req);
+        },
+    };
+}
+/**
+ * [2942]/[2943] shellGate 腿的写侧 —— **纯观察器**(恒 `allow` = `combinePolicies` 折叠里的弃权,见
+ * `applyRuntimeGovernance` 顶注对 sensitivePathPolicy 那段 allow 语义的同款说明)。
+ *
+ * 只在治理层把 shellGate 抬到 **`"always"`** 时装:该档下 core 对**每一次** shell 调用都要人批
+ * (`prepare-task.js` 把 Bash/Monitor 的 irreversibility tier 置 `"always"`),所以「这是一次 shell 调用」
+ * 与「这只 ask 是治理层门出来的」等价——推断是紧的,零错标。
+ *
+ * 🔴 `"classify"` 档**故意不装**:那一档由 core 的分类器逐调用裁决,一次 shell ask 可能来自分类器
+ * (治理),也可能来自 `APPROVAL_REQUIRE` 这类别的门(非治理),在 `AskRequest` 上无从分辨。按本信号
+ * 「只做正向断言」的语义,分不清就**让键缺席**,不去猜(`governance-ask-marks.ts` 语义 1)。
+ */
+function createGovernanceShellGateMarkPolicy(marksOf, tools = COARSE_SHELL_TOOLS) {
+    const shellTools = new Set(tools);
+    return {
+        check(req) {
+            // 只对 shell 工具**置位**,非 shell 一格不碰(那格的属主是上面的 ask 观察器)。本策略在合成里
+            // 恒排在 ask 观察器**之后**(见 applyRuntimeGovernance 的 combinePolicies 顺序):`always` 档下
+            // 每一次 shell 调用都被治理层门住,所以它对 shell 那一格的裁定压过「治理策略这次没产 ask」。
+            if (shellTools.has(req.toolName))
+                marksOf()?.setMarked(req.toolCallId, true);
+            return { action: "allow" };
+        },
+    };
+}
 /** core `tighten-task-spec` 的 SHELL_GATE_RANK 镜像(单一属主:#153 搬家后本文件是 server 侧唯一副本;
  *  task-settings 的旧副本随 settings 折叠臂一并拆除)。tightenTaskSpec 的契约是「override 自身必须收紧」
  *  而非「取两者较严」——低于 base 的 override 直接 throw,所以施加前要按 rank 只升不降。 */
@@ -229,12 +287,34 @@ const SHELL_GATE_RANK = { off: 0, classify: 1, always: 2 };
  * ⇒ 旋钮静默失效(clay 实机 Monitor 案「门根本没铸」);bypassPermissions 一句话掀掉部署闸;非 host lane
  * fsWriteGate wiring 不建 ⇒ 沙箱 lane 全失效。governance 层与 autonomy 同拍施加后三者全闭。rank 合成:
  * autonomy 派生值与旋钮取大(ask→"always" 压过 "classify"),再对 base 只升不降(防 tightenTaskSpec throw)。
+ *
+ * #177([2951] issue #29,**邻仓 test AI 的 46 格真机矩阵**实证——不是本仓的钉,别到本仓文件里数 46;
+ * 本仓的类级门是 test/operator-knob-client-posture-matrix.test.ts 的 旋钮×表态×lane 矩阵):
+ * `SENSITIVE_WRITE_PATTERNS` 是 #153 那次搬家漏下的兄弟旋钮——同一个病灶原样复发在 sensitive-path
+ * DENY 腿上(唯一合成点在 deriveSettingsPolicy 的 fsWriteGate 闭包,bypassPermissions/键缺席/settings
+ * 整缺席三形整条腿不建)。同方修:调用方(resolve-spec)把 operator 守卫集预铸成 `sensitivePathPolicy`
+ * 从这里**无条件施加**——它只在守卫段上产 deny(core 语义 deny/"safety"),对其余目标返回的是
+ * `action:"allow"`(**不是**「无意见」这种第三态:core 的 ToolPolicy 没有弃权值。它在
+ * `combinePolicies` 的 deny/ask 优先折叠里不构成一票,所以在**折叠语境**下等价于弃权;若日后有人把
+ * 这条策略单独当成唯一 policy 用,那个 allow 就是真放行——别照抄这句话去别的语境)。于是对 bypass
+ * 只挡守卫段、不给普通目标加 ask 门([820] 表第四行「bypass=不加门非开门」保持逐字)。策略在这里
+ * 只组合不构造:裁决 env 的 lane 分形(host 真 fs / 沙箱 deferred 代理)是 resolve-spec 的属主知识,
+ * governance 层不重复它。
  */
 export function applyRuntimeGovernance(base, governance) {
+    // 显式注入(测试/将来的多实例形)优先;否则**每次裁决时**取当前 run 腿的 ALS 表(顶注「作用域」段)。
+    const marksOf = () => governance.askMarks ?? currentGovernanceAskMarks();
     const overrides = { ...autonomyOverrides(governance.autonomy) };
     const coarse = compileCommandPolicy(governance.commandPolicy);
-    if (coarse)
-        overrides.toolPolicy = coarse;
+    const governancePolicies = [coarse, governance.sensitivePathPolicy].filter((p) => p !== undefined);
+    // [2942]/[2943]:治理层自己产的 `ask` 打标 —— 包在**合成之后**,于是 commandPolicy 的两模式
+    // (allowlist 的 defaultAction:"ask" / blocklist 的 ask-list)与 sensitivePathPolicy 走同一个铸点,
+    // 不会漏掉将来加进这个数组的第四条腿。
+    const governancePolicy = governancePolicies.length > 0
+        ? createGovernanceAskMarkingPolicy(governancePolicies.length === 1 ? governancePolicies[0] : combinePolicies(...governancePolicies), marksOf)
+        : undefined;
+    if (governancePolicy !== undefined)
+        overrides.toolPolicy = governancePolicy;
     if (governance.manualModeShellGate !== undefined) {
         const candidate = overrides.shellGate !== undefined && SHELL_GATE_RANK[overrides.shellGate] >= SHELL_GATE_RANK[governance.manualModeShellGate]
             ? overrides.shellGate
@@ -249,6 +329,13 @@ export function applyRuntimeGovernance(base, governance) {
         else
             delete overrides.shellGate;
     }
+    // [2942]/[2943] shellGate 腿:治理层**自己**把门抬到 `"always"` 时,挂上纯观察器给 shell 调用打标
+    // (理由与 `"classify"` 为何不装,见 createGovernanceShellGateMarkPolicy 顶注)。判据取
+    // `overrides.shellGate` 而不是有效档 —— base 已经更严时上面那支会 `delete`,那时门不是治理层给的。
+    if (overrides.shellGate === "always") {
+        const shellObserver = createGovernanceShellGateMarkPolicy(marksOf);
+        overrides.toolPolicy = governancePolicy === undefined ? shellObserver : combinePolicies(governancePolicy, shellObserver);
+    }
     if (overrides.toolPolicy === undefined && overrides.handsReadOnly === undefined && overrides.shellGate === undefined) {
         return base; // nothing to govern → avoid a needless tightenTaskSpec pass
     }

package/dist/security.d.ts

@@ -208,6 +208,18 @@ export declare function principalFrom(req: IncomingMessage, config: ServiceConfi
 /** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
  *  verifies). The trusted twin of `config.principalHeader` (the latter is client-spoofable on a direct door). */
 export declare const PRINCIPAL_TOKEN_HEADER = "x-approval-principal-token";
+/**
+ * direct-door 决策证明三件套的另外两个头名(JWT 在上面那个常量里)。
+ *
+ * 为什么也具名(2026-08-08,#176 二轮扫描 finding):这三个头名此前在
+ * `http/routes/approvals-assistant.ts` 的两个 `verifyDirectDoorProof` 调用点、以及 `http/server.ts` 的
+ * CORS `access-control-allow-headers` 串里**各手抄一份**——而 CORS 那一行同一句里已经在用
+ * `${principalHeader}` 插值另一个头名,证明具名写法在该处本就可用。改任一头名时漏改 CORS 串的后果
+ * 是**静默的**:浏览器预检把该头挡下,请求到不了 handler ⇒ 表现成「direct-door 上审批面莫名失效」,
+ * 而不是任何一处报错。低危(改头名本身即 wire BREAKING、不太可能单边发生),但零成本可消。
+ */
+export declare const APPROVAL_MAC_HEADER = "x-approval-mac";
+export declare const APPROVAL_MAC_KID_HEADER = "x-approval-mac-kid";
 export declare function setSsoPrincipal(req: IncomingMessage, principal: string): void;
 export declare function ssoVerifiedPrincipal(req: IncomingMessage): string | undefined;
 export declare function setSsoScope(req: IncomingMessage, scope: string): void;

package/dist/security.js

@@ -279,6 +279,18 @@ export function principalFrom(req, config) {
 /** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
  *  verifies). The trusted twin of `config.principalHeader` (the latter is client-spoofable on a direct door). */
 export const PRINCIPAL_TOKEN_HEADER = "x-approval-principal-token";
+/**
+ * direct-door 决策证明三件套的另外两个头名(JWT 在上面那个常量里)。
+ *
+ * 为什么也具名(2026-08-08,#176 二轮扫描 finding):这三个头名此前在
+ * `http/routes/approvals-assistant.ts` 的两个 `verifyDirectDoorProof` 调用点、以及 `http/server.ts` 的
+ * CORS `access-control-allow-headers` 串里**各手抄一份**——而 CORS 那一行同一句里已经在用
+ * `${principalHeader}` 插值另一个头名,证明具名写法在该处本就可用。改任一头名时漏改 CORS 串的后果
+ * 是**静默的**:浏览器预检把该头挡下,请求到不了 handler ⇒ 表现成「direct-door 上审批面莫名失效」,
+ * 而不是任何一处报错。低危(改头名本身即 wire BREAKING、不太可能单边发生),但零成本可消。
+ */
+export const APPROVAL_MAC_HEADER = "x-approval-mac";
+export const APPROVAL_MAC_KID_HEADER = "x-approval-mac-kid";
 /** The DIRECT-DOOR-SAFE principal — the VERIFIED identity for governance + cost + isolation. On a BFF/gated deployment
  *  the header is already verified upstream (return it); on a direct-door worker the `principalHeader` is client-
  *  spoofable, so identity comes from the crypto-verified `x-approval-principal-token` JWT (the issuer's private key

package/dist/session-sync-kernel.d.ts

@@ -66,6 +66,19 @@ export declare function stagingIdFor(realSessionId: string, token: string): stri
 export declare const STAGING_ID_MARKER = "#stg-";
 /** Recover the real session id from a staging id (everything before the `#stg-` marker), or null if not a staging id. */
 export declare function realIdOfStaging(stagingId: string): string | null;
+/**
+ * Staging-row reaper grace window — a staging session's rows are GC'able only if it has NO `session_meta` (never
+ * committed) AND its OLDEST row is older than this (an in-flight stream keeps appending fresh rows → safe).
+ * Mirrors the file-snapshot store's `BLOB_GC_GRACE_MS` discipline (an in-flight import must never be reaped
+ * mid-stream).
+ *
+ * 🔴 住在 kernel 里而不是任一个店里(2026-08-08,#176 二轮扫描 finding):TiDB 与 PG 两个孪生店原先**各
+ * 抄一份**同值常量,PG 那份的注释甚至自称「twin of the TiDB store's STAGING_GC_GRACE_MS」——明知孪生却
+ * 不共享。单边改值的后果是两个后端对「同一个中断的导入还能不能收」判定分家,而两边都按自己的常量静默
+ * 正确工作。这里是两个店**本就都 import** 的那个叶子模块(店契约纪律:适配器不许 import 自己的孪生,
+ * 共享常量必须落在中立处),同族先例见 `checkpoint-store-sql.ts` 的 `export const TERMINAL_GRACE_MS`。
+ */
+export declare const STAGING_GC_GRACE_MS = 3600000;
 /**
  * §7 — the relationship between a SOURCE bundle's entry log and the DESTINATION's CURRENT entry log, the gate that
  * decides whether an import is a safe sync or a data-losing overwrite. Five exhaustive cases:

package/dist/session-sync-kernel.js

@@ -10,6 +10,19 @@ export function realIdOfStaging(stagingId) {
     const i = stagingId.indexOf(STAGING_ID_MARKER);
     return i < 0 ? null : stagingId.slice(0, i);
 }
+/**
+ * Staging-row reaper grace window — a staging session's rows are GC'able only if it has NO `session_meta` (never
+ * committed) AND its OLDEST row is older than this (an in-flight stream keeps appending fresh rows → safe).
+ * Mirrors the file-snapshot store's `BLOB_GC_GRACE_MS` discipline (an in-flight import must never be reaped
+ * mid-stream).
+ *
+ * 🔴 住在 kernel 里而不是任一个店里(2026-08-08,#176 二轮扫描 finding):TiDB 与 PG 两个孪生店原先**各
+ * 抄一份**同值常量,PG 那份的注释甚至自称「twin of the TiDB store's STAGING_GC_GRACE_MS」——明知孪生却
+ * 不共享。单边改值的后果是两个后端对「同一个中断的导入还能不能收」判定分家,而两边都按自己的常量静默
+ * 正确工作。这里是两个店**本就都 import** 的那个叶子模块(店契约纪律:适配器不许 import 自己的孪生,
+ * 共享常量必须落在中立处),同族先例见 `checkpoint-store-sql.ts` 的 `export const TERMINAL_GRACE_MS`。
+ */
+export const STAGING_GC_GRACE_MS = 3_600_000;
 /**
  * §7 — classify how importing `srcEntries` into a destination holding `dstEntries` would relate the two logs. PURE
  * (no I/O); the §7 fork detector. The comparison is over the ENTRY-ID SETS, not leaf_id: