@sema-agent/server 7.2.0 → 7.4.0

package/dist/http/wire-types.d.ts

@@ -230,12 +230,27 @@ export interface TaskRequestBody {
     /** [1144]/[1146] (core 1.328 R2): 提示词双形轴——simple(CC 212 短形,引擎缺省)| classic(长形,可按
      *  任务/模型试分)。纯呈现轴无租户门;枚举 fail-loud at submit;缺省不挂键。 */
     promptProfile?: "simple" | "classic";
+    /** [2856]②(core 5.14.0 座已在,`TaskSpec.toolMaterializeStrategy`):deferred 工具在**激活之后**怎么给
+     *  模型供 schema。`static` = 占位符形不变(激活只改可调用性,广告的 schema 仍是空对象);`swap` = 激活
+     *  后下一轮把占位符换成真 schema。
+     *  为什么要上 wire:cli 的 #181 取证表明,忠实跟随广告 schema 解码的 provider(openai-completions 车道)
+     *  在 `static` 下会**无界循环** —— 每轮发 `{}` → invalidArgumentsRejection → 下一轮广告仍空,纠错回路
+     *  结构上无效。core 的缺省是 `spec.toolMaterializeStrategy ?? env ?? "static"`,进程级 env 说不了
+     *  「每个模型」的话(模型目录车道 per-model api 可混),所以必须有一个**按任务**的位子。
+     *  缺省不挂键(交给 core 的 env/缺省链);未知词 400 fail-loud(与 promptProfile/permissionMode 同姿势 ——
+     *  静默折缺省会让调用方以为切了策略却没切)。 */
+    toolMaterializeStrategy?: "static" | "swap";
     /** R4 (CC parity): the LIGHT top-level per-turn permission-mode intent (CC `permissionMode`). The shell sends
-     *  the RAW mode (axis-agnostic, no client-side interpretation); the SERVICE interprets it tighten-only: `plan` ⇒
-     *  read-only hands + `present_plan` (EnterPlanMode parity); `acceptEdits`/`bypassPermissions` LOOSEN → coerced to
-     *  `default` (never honored remotely; the client enforces them on its own machine). Folds onto the SAME tighten-only
-     *  governance as `settings.permissions.defaultMode` (the heavier bundle), so it's a lighter alias, not a second path. */
-    permissionMode?: string;
+     *  the RAW mode (axis-agnostic, no client-side interpretation); the SERVICE interprets it tighten-only vs the
+     *  deployment baseline. Post-[816] all FIVE modes are honored as gate-SHAPE choices (`plan` ⇒ read-only hands +
+     *  `present_plan`; `acceptEdits`/`bypassPermissions`/`auto` select how much the mode-derived fs-write ask gate
+     *  asks — they can never subtract from deployment/operator policy, tightenTaskSpec deny-wins; the old "LOOSEN →
+     *  coerced to default" note was pre-[816] doc-rot). Folds onto the SAME tighten-only governance as
+     *  `settings.permissions.defaultMode` (the heavier bundle), so it's a lighter alias, not a second path.
+     *  #157-②: CLOSED enum on the wire — an unknown word 400s at submit (`request.field_invalid`, sibling of
+     *  promptProfile) instead of silently coercing to `default`; resume replay of a stored body stays lenient
+     *  (coercePermissionMode). */
+    permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions" | "auto";
     /** MF-30 memory PAUSE (shell-host contract, option B per-request — clay 2026-06-27): `false` makes THIS run
      *  read-only over long-term memory (`TaskSpec.memory.writeScope:null` — the design/138 memory ENGINE materializes/
      *  reads but its harvest commits nothing). Absent/`true` ⇒ normal read+write. The shell's `/memory` pause carries

package/dist/main.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { Runner, TtlSessionStore, uuidv7, defaultTaskRegistry, combinePolicies, createAllowDenyPolicy, workflowsCapability, createWebFetchSummarizer, resolveTaskModel as coreResolveTaskModel, probeSearchBackend } from "@sema-agent/core";
+import { Runner, TtlSessionStore, uuidv7, defaultTaskRegistry, combinePolicies, createAllowDenyPolicy, workflowsCapability, createWebFetchSummarizer, resolveTaskModel as coreResolveTaskModel, probeSearchBackend, describeStaticWiring } from "@sema-agent/core";
 import { createSessionTitler } from "./session-titler.js";
 import { posIntEnv } from "./session-watch.js";
 import { selectEnvironmentTool } from "./capabilities/select-environment-tool.js";
@@ -13,7 +13,7 @@ import { drainNumEnvWarnings } from "./plugins/remote-shell.js";
 import { ensureChildSessionDurableWithPromotion } from "./plugins/session-store.js";
 import { ForkRoutingSessionStore } from "./plugins/fork-routing-session-store.js";
 import { webSearchConfigFromEnv, createWebSearchBackend, setWebSearchBadPayloadObserver, shouldProbeWebSearchOnBoot } from "./plugins/web-search.js";
-import { createAuthorizer } from "./security.js";
+import { createAuthorizer, encodeCheckpointScope } from "./security.js";
 import { assertGateIntentServiceable, createDurableAskPolicy, hasOperatorGateIntent } from "./approval.js";
 import { loadSkills } from "./capabilities/skills.js";
 import { GiteaClient } from "./capabilities/repo-tools.js";
@@ -22,6 +22,7 @@ import { createLogger } from "./observability/logger.js";
 import { createToolTracer, createPermissionDeniedMeter } from "./observability/tool-trace.js";
 import { createRegistryJwtVerifier } from "./auth-bridge.js";
 import { createMetrics } from "./observability/metrics.js";
+import { installFailOpenRecorder } from "./observability/fail-open.js";
 import { setRedactionObserver, redactSecrets } from "./trace/redact.js";
 import { RateLimiter } from "./observability/rate-limit.js";
 import { createHttpServer, explicitOperatorOk } from "./http/server.js";
@@ -49,6 +50,7 @@ import { createRunnerDeps, createSharedRunnerDeps } from "./boot/runner-deps.js"
 import { createOrgMemoryAdmissionWiring } from "./boot/org-memory.js";
 import { createSessionFaces } from "./boot/session-faces.js";
 import { createLeaderFace } from "./boot/leader.js";
+import { assertStaticWiringConsistent } from "./http/routes/diagnostics.js";
 import { installShutdownHandlers } from "./boot/shutdown.js";
 /** Service version for GET /v1/capabilities — read from the package.json shipped next to src/ in the
  *  image (Dockerfile COPYs it). Best-effort: an unreadable file reports "unknown", never crashes boot. */
@@ -105,6 +107,10 @@ async function main() {
     }
     const logger = createLogger(config.logLevel);
     const metrics = createMetrics();
+    // #157 fail-open 治理:把 logger/metrics 接到进程级 failOpen 记录器上(见 observability/fail-open.ts)。
+    // 排在这里而不是更晚:兜底臂遍布装配链,越早接上,越少的 fail-open 只剩探针行没有结构化痕迹。
+    // 装配前已累计的计数与已喊过的 tag 由 install 继承,不重置也不重喊。
+    installFailOpenRecorder({ logger, metrics });
     // S20 (SILENT-FALLBACK P1) + [792]④ boot notices: config parsing runs before the logger exists — drain both
     // pre-logger collectors via the shared helper (F10: run-local uses the same one, so entrypoints can't drift).
     logConfigDiagnostics(logger);
@@ -181,7 +187,7 @@ async function main() {
     const { sqlWorkflowRunStore, workflowNotifyJournal, workflowCompletionInbox, deliverWorkflowCompletion, workflowNotifyGate, fleetBus, workflowRunStore, workflowJournalStore, outcomeSink, workflowAgentRegistry, subagentSteerRegistry, } = createWorkflowOrchestration({ config, logger, metrics, localRoot, backend, getRunStore: () => runStore });
     // design/158 A10:活体协调器 + SendUserFile 工具面搬到 src/boot/coordinators.ts(逐字;durableEnabled 的
     // 「必须早于 runnerDeps 求值」次序契约见该文件头注)。
-    const { elicitation, question, toolApproval, durableEnabled, sendUserFileEmitter, sendFileLedger, sendUserFileToolSpec } = createLiveCoordinators({ config, logger, backend, sendUserFileTaskEnvs });
+    const { elicitation, question, toolApproval, durableEnabled, streamApprovalGate, sendUserFileEmitter, sendFileLedger, sendUserFileToolSpec } = createLiveCoordinators({ config, logger, backend, sendUserFileTaskEnvs });
     // design/158 A10:per-principal caps 段搬到 src/boot/runtime-caps.ts(逐字)。
     const { principalCaps, centerRuntimeCapsResolver, runtimeCapsResolver } = createRuntimeCaps({ config, logger });
     // design/170 件A(#148 件3③):org 记忆准入装配(目录源三态选择+C12 能力探测,坏配置在此拒启动)。
@@ -658,7 +664,7 @@ async function main() {
         config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore,
         rateLimiter, costQuota, toolResultStore, fileSnapshotStore, taskAttachmentStore, imageBakes, worktreeReap,
         workflowNotifyGate, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore,
-        backgroundAgentStore, mailboxStore,
+        backgroundAgentStore, mailboxStore, toolApproval,
         getRunDenySweep: () => runDenySweep,
     });
     // Optional OTLP/HTTP metrics export (1.37). Periodically pushes the registry to an OTel collector;
@@ -704,6 +710,30 @@ async function main() {
     // asyncRewake wake 管道 holder:server 启动时装 deliver(session→本副本活流 steer);createTaskHooks 的
     // ctx.wake 闭包经它投递(main 建壳/server 填实,双向不循环依赖)。
     const hookWakeBus = {};
+    // ═══════════ #154 件二:启动期静态装配自检(coordinators 构造后、listen 之前)═══════════
+    // core 的 `describeStaticWiring` 与本仓的装配谓词是**两个独立实现**在回答同一组问题。答案矛盾 =
+    // 装配谎言(不是「配置不理想」:是服务端对自己接了什么线有两套互斥说法),fail-loud 拒启 ——
+    // 与 memory+durable 两条既有拒启同族。判据本体在 http/routes/diagnostics.ts(诊断读面与拒启判据同源)。
+    //
+    // specTemplate = resolve-spec 对**每一条**任务腿都会盖的那两个 durable 键(它的 durableEnabled 分支)。
+    // 静态半场只读它们的**在场性**(`parkDurableApprovalOptIn = spec.durableApproval !== undefined`),
+    // 所以这里给的是那个形,而不是某条腿的 principal 真值。
+    const wiringSpecTemplate = durableEnabled
+        ? { checkpointStore, durableApproval: { scope: encodeCheckpointScope(undefined) } }
+        : {};
+    const staticWiring = describeStaticWiring(runnerDeps, wiringSpecTemplate);
+    // `parkFacility` 传的必须是**协调器真喂给 `resolveStreamApprovalGate` 的那个实参**(durableEnabled),
+    // 不是在这里重算一遍 —— 重算会把「两个站点算出了不同答案」这件正要被查的事抹平。
+    assertStaticWiringConsistent({ manifest: staticWiring, parkFacility: durableEnabled, backendKind: backend?.kind }, logger);
+    // operator 日志面(**非 wire**)。`configFingerprint` 只有 effective 半场才铸(core 按腿算),静态半场
+    // 没有这一位 ⇒ 诚实报 null,不自造一个服务端哈希(那会是一个要跨仓对表的新语义)。
+    logger.info("wiring_static", {
+        fingerprint: staticWiring.configFingerprint ?? null,
+        parkEffective: staticWiring.parkLane.effective,
+        sessionDurability: staticWiring.session.store,
+        posture: staticWiring.interaction.posture,
+        streamApproval: streamApprovalGate.active ? "active" : streamApprovalGate.reason,
+    });
     // ═══════════ design/158 A8:ServiceDeps 分组装配(七组窄接口)═══════════
     // 每组一个**带类型标注**的中间 const —— 标注位触发 TS 多余属性检查,键放错组当场编译红。
     // (平铺形做不到:69 键的全可选面里任何键名都「属于」它,于是键落错家/从未接线只能靠源码钉
@@ -823,6 +853,7 @@ async function main() {
         modelReady: () => configCenter.modelReady(), // boot ready 门:roster 未落地=计费提交 503+health ready:false
         scenarioDetails, // 场景详情只读面(内建+center 同判定源)
         workflowsCapable, // ① core split: capabilities.workflows = engine-can (workflowsCapability); workflowsList = store (below)
+        staticWiring, // #154 件三:GET /v1/diagnostics/wiring 的 static 半场(与上面的拒启自检同一份产物)
         instanceId,
         // Capability discovery: the deployment facts only main knows. Store-derived booleans
         // (asyncRuns/artifacts/approvals/leader) are computed inside the server from the deps themselves.

package/dist/observability/fail-open.d.ts

@@ -0,0 +1,98 @@
+import type { Logger } from "./logger.js";
+import type { Metrics } from "./metrics.js";
+/** 登记项:`cls` 是判据表的分类(见模块头——只有这两类允许走本封装),`note` 说清"放行的最坏后果"。 */
+export interface FailOpenTagEntry {
+    /** `F`=纯体验/缓存回退,放行最坏后果只是"难看/不够好";`P-DEBT`=保护型欠账,方向明知不对、显式记债。 */
+    readonly cls: "F" | "P-DEBT";
+    /** 这条兜底放行了什么、最坏后果是什么。写给未来读遥测的人,不写来历。 */
+    readonly note: string;
+}
+/** 闭集 tag 词表。形=`<repo>.<domain>.<site>`(跨仓同形,便于三仓遥测并表)。 */
+export declare const FAIL_OPEN_TAGS: {
+    readonly "server.hitl.frame-undelivered-stream-closed": {
+        readonly cls: "P-DEBT";
+        readonly note: "HITL 的 **open** 帧(question / elicitation)写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,问到 TTL 才按无人应答结算。方向(no-op 而非 throw)是既有的刻意决定,本条只保证它不再无声。";
+    };
+    readonly "server.stream.frame-dropped-stream-closed": {
+        readonly cls: "F";
+        readonly note: "非 HITL-open 的运行流帧写向已断连接 ⇒ 丢弃。连接都没了,这一帧本就无人可看;单独立项是为了不让它挤进上面那条保护型计数。";
+    };
+    readonly "server.question.open-frame-undelivered": {
+        readonly cls: "P-DEBT";
+        readonly note: "AskUserQuestion 的 open 帧投递失败 ⇒ 按 headless 默认结算,模型不问人自己往下判。方向是刻意的产品姿态(绝不把 run 挂死),但一次投递故障确实让人在环这道门被跳过——记债,不当合法兜底。";
+    };
+    readonly "server.elicitation.open-frame-undelivered": {
+        readonly cls: "F";
+        readonly note: "MCP elicitation 的 open 帧投递失败 ⇒ 结算 decline。方向本身是 fail-closed(问不到人就是拒),缺的只是留痕。";
+    };
+    readonly "server.question.complete-breadcrumb-dropped": {
+        readonly cls: "F";
+        readonly note: "question_complete 面包屑(对话框消解提示)持久化失败。答案本身走的是另一条路且早已返回,丢的只是壳里一次收尾渲染。";
+    };
+    readonly "server.elicitation.complete-breadcrumb-dropped": {
+        readonly cls: "F";
+        readonly note: "elicitation_complete 面包屑持久化失败。同上——答案已经在壳手里,丢的是收尾渲染。";
+    };
+    readonly "server.prompts.artifact-cache-write-failed": {
+        readonly cls: "F";
+        readonly note: "已验签的提示词工件回填本地缓存失败。工件本身已返回给调用方;代价是下次同 digest 还要再取一次网络。";
+    };
+};
+/** 词表键推导的闭集类型——未登记的 tag 传不进 {@link recordFailOpen}(编译期拒)。 */
+export type FailOpenTag = keyof typeof FAIL_OPEN_TAGS;
+/**
+ * 断流丢帧该记哪个 tag —— **按帧型分类**,纯函数(与写流的那条闭包解耦,才单测得动)。
+ *
+ * 一刀切记同一个 tag 是错的:承载 HITL 帧的那条闭包同时驮着完成面包屑与其它运行流帧,于是**一次**
+ * 断连会让保护型计数涨两次(open 一次、complete 又一次),真正的 open 失败率被面包屑的假阳性盖住。
+ * 只有 open 帧是"人在环这道门被跳过"的证据,其余都是体验损失。
+ */
+export declare function failOpenTagForDroppedFrame(frameType: string): FailOpenTag;
+/** {@link createFailOpenRecorder} 返回的活对象(有行为、有状态 ⇒ `create*` 而非 `build*`)。 */
+export interface FailOpenRecorder {
+    /** 走到一条登记过的兜底臂。总不抛——观测本身绝不能变成故障(见 reapers 同族判据)。 */
+    record(tag: FailOpenTag, detail?: string): void;
+    /** 本进程各 tag 的累计次数(逐次计数,与一次性 warn 无关)。 */
+    counts(): ReadonlyMap<FailOpenTag, number>;
+    /** 已经喊过 stderr 契约行的 tag 集合——装配时由新实例继承,避免 install 让同一 tag 再喊一次。 */
+    warnedTags(): ReadonlySet<FailOpenTag>;
+    /** 还没进过任何 metrics 汇的次数(装配前命中的欠账)。install 用它补账,补完清零。 */
+    metricsBacklog(): ReadonlyMap<FailOpenTag, number>;
+    /** 已经进过结构化日志的 tag 集合。与 {@link warnedTags} **分开**:stderr 契约行装配前就能喊,
+     *  结构化 warn 却要等 logger 到场——两者共用一个集合会让装配前命中的 tag 永远拿不到结构化痕迹。 */
+    loggedTags(): ReadonlySet<FailOpenTag>;
+}
+/** 探针文件的 env 名(跨仓同名同形:`audits/failopen-governance-176.md` §2-r2,壳/引擎同认)。 */
+export declare const FAIL_OPEN_PROBE_ENV = "SEMA_FAILOPEN_PROBE";
+export interface FailOpenRecorderDeps {
+    logger?: Logger;
+    metrics?: Metrics;
+    /** 探针文件路径。缺省=读 `SEMA_FAILOPEN_PROBE`(读一次,不每次调用都碰 env)。 */
+    probePath?: string;
+    /** 继承自上一个实例的状态(install 换实例时不重置计数、不重喊 warn、不丢欠账)。 */
+    seedCounts?: ReadonlyMap<FailOpenTag, number>;
+    seedWarned?: ReadonlySet<FailOpenTag>;
+    seedBacklog?: ReadonlyMap<FailOpenTag, number>;
+    seedLogged?: ReadonlySet<FailOpenTag>;
+    /** 测试注入:替掉 stderr 契约行的落点。缺省直写 `process.stderr`。 */
+    writeStderr?: (line: string) => void;
+    /** 测试注入:替掉探针文件追加。缺省 `appendFileSync`(同步=进程猝死也不丢已记的行)。 */
+    appendProbe?: (path: string, line: string) => void;
+}
+export declare function createFailOpenRecorder(deps?: FailOpenRecorderDeps): FailOpenRecorder;
+/**
+ * 装配层接线:把 logger/metrics 接到进程单例上。搬四份状态过去,各有各的理由:
+ *  - `seedCounts` —— 逻辑总数续算,不从 0 重来;
+ *  - `seedWarned` —— boot 期已喊过的 stderr 契约行不再喊(「每进程每 tag 一次」是它的全部价值);
+ *  - `seedBacklog` —— 装配**前**命中的次数还没进任何 metrics 汇,交给新实例补账(补完清零,
+ *    所以第二次 install 不会重放);
+ *  - `seedLogged` —— 已真发出去的结构化 warn 不重发;没发过的由新 logger 补一条。
+ */
+export declare function installFailOpenRecorder(deps: Omit<FailOpenRecorderDeps, "seedCounts" | "seedWarned" | "seedBacklog" | "seedLogged">): FailOpenRecorder;
+/** 兜底臂的调用口。`tag` 必须已登记(闭集类型),`detail` 是可选的一行现场(路径/原因,不放密钥)。 */
+export declare function recordFailOpen(tag: FailOpenTag, detail?: string): void;
+/** 本进程各 tag 累计次数——`/metrics` 之外的进程内读数(测试与自检面用)。 */
+export declare function failOpenCounts(): ReadonlyMap<FailOpenTag, number>;
+/** test-only:换一个全新单例(计数与 warn 集合清零),让每个用例都从"第一次"看起。 */
+export declare function resetFailOpenRecorderForTest(deps?: FailOpenRecorderDeps): FailOpenRecorder;
+//# sourceMappingURL=fail-open.d.ts.map

package/dist/observability/fail-open.js

@@ -0,0 +1,216 @@
+/**
+ * #157 fail-open 治理专项 —— 兜底路径的**响亮化**工具(server 半场;跨仓方案见 sema-comms
+ * `audits/failopen-governance-176.md` §2,三仓语义对齐、实现各自)。
+ *
+ * ## 它解决的问题
+ * 「走了兜底」与「一切正常」在外部**同形**——成功回执一样、日志一样、指标一样。于是一个静默降级
+ * 能带病运行数周,只能靠"该发生的事没发生"这种间接症状发现。本模块给每条合法兜底臂一个**登记过的
+ * tag**,走到即留痕三件套:
+ *
+ *  1. **计数(逐次)** —— `fail_open_total{tag,cls}`;
+ *  2. **探针文件(逐次)** —— `SEMA_FAILOPEN_PROBE=<path>` 在场时逐次追加 `fail-open <tag> <detail>`。
+ *     逐次是承重的:同进程多腿时"第二腿起无行"会让「无行=没走兜底」的黑盒断言变成假绿;
+ *  3. **一次性 warn(每进程每 tag 一次)** —— 防刷屏。**只有这一件是一次性的**,计数与探针都逐次。
+ *
+ * ## 它**不**解决的问题(封装不是合法化通道)
+ * 词表的 `cls` 只有 `F` 与 `P-DEBT` 两种,**结构性**地把 P/Z 类挡在外面:
+ *  - **P 保护型**(权限门/判定词表/凭证/车道选择):正解是 fail-closed,不是"留痕后继续放行"。
+ *    确实一时改不动的,才允许以 `P-DEBT` 登记——让债在遥测里显形,而不是让它消失。
+ *  - **Z 计量型**(重试/预算/超时/清理范围):正解是归零 + 自己的节流告警
+ *    (先例:`boot/reapers.ts` 的 `createThrottledReaperCatch`),不走本封装。
+ *
+ * ## 词表是闭集
+ * {@link FailOpenTag} 由 {@link FAIL_OPEN_TAGS} 的键推导,未登记的 tag 是**编译期错误**——
+ * "新 tag 须登记"因此是机器执法的,不靠自觉。新增 tag 同时要在 `docs/FAIL-OPEN-CENSUS.md` 补行。
+ *
+ * ## 进程级而非注入级
+ * 三件套里有两件(一次性 warn、进程计数)天然是**进程**范围的,且真正的兜底臂往往在没有 logger/
+ * metrics 句柄的深处(`question.ts` / `elicitation.ts` 全文零观测通道)。所以对外主口是自由函数
+ * {@link recordFailOpen},装配层用 {@link installFailOpenRecorder} 把 logger/metrics 接上即可;
+ * 装配之前的调用不会丢——探针与 stderr 契约行不依赖注入,计数也照常累加并在装配时继承过去。
+ */
+import { appendFileSync } from "node:fs";
+/** 闭集 tag 词表。形=`<repo>.<domain>.<site>`(跨仓同形,便于三仓遥测并表)。 */
+export const FAIL_OPEN_TAGS = {
+    "server.hitl.frame-undelivered-stream-closed": {
+        cls: "P-DEBT",
+        note: "HITL 的 **open** 帧(question / elicitation)写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,问到 TTL 才按无人应答结算。方向(no-op 而非 throw)是既有的刻意决定,本条只保证它不再无声。",
+    },
+    "server.stream.frame-dropped-stream-closed": {
+        cls: "F",
+        note: "非 HITL-open 的运行流帧写向已断连接 ⇒ 丢弃。连接都没了,这一帧本就无人可看;单独立项是为了不让它挤进上面那条保护型计数。",
+    },
+    "server.question.open-frame-undelivered": {
+        cls: "P-DEBT",
+        note: "AskUserQuestion 的 open 帧投递失败 ⇒ 按 headless 默认结算,模型不问人自己往下判。方向是刻意的产品姿态(绝不把 run 挂死),但一次投递故障确实让人在环这道门被跳过——记债,不当合法兜底。",
+    },
+    "server.elicitation.open-frame-undelivered": {
+        cls: "F",
+        note: "MCP elicitation 的 open 帧投递失败 ⇒ 结算 decline。方向本身是 fail-closed(问不到人就是拒),缺的只是留痕。",
+    },
+    "server.question.complete-breadcrumb-dropped": {
+        cls: "F",
+        note: "question_complete 面包屑(对话框消解提示)持久化失败。答案本身走的是另一条路且早已返回,丢的只是壳里一次收尾渲染。",
+    },
+    "server.elicitation.complete-breadcrumb-dropped": {
+        cls: "F",
+        note: "elicitation_complete 面包屑持久化失败。同上——答案已经在壳手里,丢的是收尾渲染。",
+    },
+    "server.prompts.artifact-cache-write-failed": {
+        cls: "F",
+        note: "已验签的提示词工件回填本地缓存失败。工件本身已返回给调用方;代价是下次同 digest 还要再取一次网络。",
+    },
+};
+/**
+ * 断流丢帧该记哪个 tag —— **按帧型分类**,纯函数(与写流的那条闭包解耦,才单测得动)。
+ *
+ * 一刀切记同一个 tag 是错的:承载 HITL 帧的那条闭包同时驮着完成面包屑与其它运行流帧,于是**一次**
+ * 断连会让保护型计数涨两次(open 一次、complete 又一次),真正的 open 失败率被面包屑的假阳性盖住。
+ * 只有 open 帧是"人在环这道门被跳过"的证据,其余都是体验损失。
+ */
+export function failOpenTagForDroppedFrame(frameType) {
+    switch (frameType) {
+        case "question":
+        case "elicitation":
+            return "server.hitl.frame-undelivered-stream-closed";
+        case "question_complete":
+            return "server.question.complete-breadcrumb-dropped";
+        case "elicitation_complete":
+            return "server.elicitation.complete-breadcrumb-dropped";
+        default:
+            return "server.stream.frame-dropped-stream-closed";
+    }
+}
+/** 探针文件的 env 名(跨仓同名同形:`audits/failopen-governance-176.md` §2-r2,壳/引擎同认)。 */
+export const FAIL_OPEN_PROBE_ENV = "SEMA_FAILOPEN_PROBE";
+/** 计数器名。`cls` 进标签:一眼分得出"合法兜底"与"保护型欠账"两种曲线,后者应当只降不升。 */
+const FAIL_OPEN_COUNTER = "fail_open_total";
+export function createFailOpenRecorder(deps = {}) {
+    const counts = new Map(deps.seedCounts ?? []);
+    const warned = new Set(deps.seedWarned ?? []);
+    const logged = new Set(deps.seedLogged ?? []);
+    const backlog = new Map(deps.seedBacklog ?? []);
+    const probePath = deps.probePath ?? process.env[FAIL_OPEN_PROBE_ENV];
+    const writeStderr = deps.writeStderr ?? ((line) => void process.stderr.write(line));
+    const appendProbe = deps.appendProbe ?? ((path, line) => appendFileSync(path, line));
+    deps.metrics?.counter(FAIL_OPEN_COUNTER, "fallback (fail-open) arms traversed, by registered tag — see docs/FAIL-OPEN-CENSUS.md");
+    // 补账:装配前(无 metrics/无 logger)命中的那几次不能凭空消失——否则 `fail_open_total` 永久
+    // 少算,少的还正是 boot 期兜底。metrics 到场即把欠账一次性灌进去并清零(所以再 install 一次不会重放),
+    // 结构化 warn 同理按 tag 补一条。stderr 契约行**不补**:它在装配前就已经喊过了,一 tag 一次是它的全部价值。
+    // 🔴 记账**后于**投递(codex R2 复审 MEDIUM):先清 backlog / 先 `logged.add` 再投递,等于把一次
+    // 投递失败记成"已送达"——欠账从此无法重放,而它保的正是最需要补的那批 boot 期兜底。
+    if (deps.metrics !== undefined && backlog.size > 0) {
+        for (const [tag, n] of [...backlog]) {
+            try {
+                deps.metrics.inc(FAIL_OPEN_COUNTER, { tag, cls: FAIL_OPEN_TAGS[tag].cls }, n);
+                backlog.delete(tag); // 只有真进了汇才销账
+            }
+            catch {
+                /* 留在 backlog 里,下一次装配再补 */
+            }
+        }
+    }
+    // 补痕的起算集=**观测到的 tag 全集**(`counts`),不是"stderr 喊成功过的那批"(`warned`)——
+    // 后者在"装配前命中 + stderr 正断裂"这条组合路上恒空,那次兜底的结构化痕迹就永久没了(codex R3)。
+    if (deps.logger !== undefined) {
+        for (const tag of counts.keys()) {
+            if (logged.has(tag))
+                continue;
+            try {
+                deps.logger.warn("fail_open", { tag, cls: FAIL_OPEN_TAGS[tag].cls, note: FAIL_OPEN_TAGS[tag].note, backfilled: true });
+                logged.add(tag); // 同上:warn 真发出去才算已报
+            }
+            catch {
+                /* 不记 logged,下一次装配/下一次命中再补 */
+            }
+        }
+    }
+    return {
+        record: (tag, detail) => {
+            // 三件套逐件独立 try:一件的失败(坏路径的探针文件、抛错的 logger 传输)绝不能让**另外两件**
+            // 也丢,更不能让调用方的兜底臂变成抛错——那等于把"降级"换成"故障",正是本模块要消灭的方向。
+            const entry = FAIL_OPEN_TAGS[tag];
+            counts.set(tag, (counts.get(tag) ?? 0) + 1);
+            if (deps.metrics === undefined) {
+                backlog.set(tag, (backlog.get(tag) ?? 0) + 1); // 记欠账,等 install 补
+            }
+            else {
+                try {
+                    deps.metrics.inc(FAIL_OPEN_COUNTER, { tag, cls: entry.cls });
+                }
+                catch {
+                    // 汇在场但这一次没进去 ⇒ 同样记欠账(而不是蒸发),等下一次装配补。
+                    backlog.set(tag, (backlog.get(tag) ?? 0) + 1);
+                }
+            }
+            if (probePath !== undefined && probePath !== "") {
+                try {
+                    appendProbe(probePath, `fail-open ${tag}${detail !== undefined && detail !== "" ? ` ${detail}` : ""}\n`);
+                }
+                catch {
+                    /* 探针路径不可写(只读盘/权限)⇒ 静默放弃,不牵连本次兜底 */
+                }
+            }
+            // 只有**真发出去**才记进 logged —— 没有 logger 时记了,会让日后 install 的补账把这条当成
+            // "已经报过"而跳过,那正是本轮复审要修的漏账形。
+            if (deps.logger !== undefined && !logged.has(tag)) {
+                try {
+                    deps.logger.warn("fail_open", { tag, cls: entry.cls, note: entry.note, ...(detail !== undefined ? { detail } : {}) });
+                    logged.add(tag); // 记账后于投递:没发出去就不算已报,下一次命中重试
+                }
+                catch {
+                    /* 观测不得成为故障 */
+                }
+            }
+            if (warned.has(tag))
+                return;
+            try {
+                // 跨仓约定的黑盒锚,逐字 `[sema] fail-open: <tag>`。**不依赖** logger 是否装配上——
+                // 评测线的断言打的就是这一行,它在 boot 之前的兜底上也必须成立。
+                writeStderr(`[sema] fail-open: ${tag}\n`);
+                warned.add(tag); // 同上。stderr 永久断裂时代价=每次命中试写一次(有界),不是丢掉这条契约行
+            }
+            catch {
+                /* 断裂的 stderr(EPIPE 族)⇒ 丢这行,不丢进程 */
+            }
+        },
+        counts: () => counts,
+        warnedTags: () => warned,
+        metricsBacklog: () => backlog,
+        loggedTags: () => logged,
+    };
+}
+/** 进程单例。装配前也可用(探针+stderr 契约行照常,计数照常;只是没有结构化 warn/metric)。 */
+let current = createFailOpenRecorder();
+/**
+ * 装配层接线:把 logger/metrics 接到进程单例上。搬四份状态过去,各有各的理由:
+ *  - `seedCounts` —— 逻辑总数续算,不从 0 重来;
+ *  - `seedWarned` —— boot 期已喊过的 stderr 契约行不再喊(「每进程每 tag 一次」是它的全部价值);
+ *  - `seedBacklog` —— 装配**前**命中的次数还没进任何 metrics 汇,交给新实例补账(补完清零,
+ *    所以第二次 install 不会重放);
+ *  - `seedLogged` —— 已真发出去的结构化 warn 不重发;没发过的由新 logger 补一条。
+ */
+export function installFailOpenRecorder(deps) {
+    current = createFailOpenRecorder({
+        ...deps,
+        seedCounts: current.counts(),
+        seedWarned: current.warnedTags(),
+        seedBacklog: current.metricsBacklog(),
+        seedLogged: current.loggedTags(),
+    });
+    return current;
+}
+/** 兜底臂的调用口。`tag` 必须已登记(闭集类型),`detail` 是可选的一行现场(路径/原因,不放密钥)。 */
+export function recordFailOpen(tag, detail) {
+    current.record(tag, detail);
+}
+/** 本进程各 tag 累计次数——`/metrics` 之外的进程内读数(测试与自检面用)。 */
+export function failOpenCounts() {
+    return current.counts();
+}
+/** test-only:换一个全新单例(计数与 warn 集合清零),让每个用例都从"第一次"看起。 */
+export function resetFailOpenRecorderForTest(deps = {}) {
+    current = createFailOpenRecorder(deps);
+    return current;
+}
+//# sourceMappingURL=fail-open.js.map

package/dist/observability/prompt-manifest.d.ts

@@ -31,6 +31,12 @@ export interface PromptManifestRecord {
         shapeDigest: string;
         wireSchemaDigest: string;
     }>;
+    /** core 5.15.0(#181):deferred 披露策略自证三键(诊断值,零内容)。缺席=core <5.15 或无 deferred。 */
+    toolDisclosure?: {
+        deferredTools: number;
+        strategy: string;
+        source: string;
+    };
     totalChars: number;
 }
 /** Whitelist one `prompt.assembled` trace event into a {@link PromptManifestRecord} (v1 face required,
@@ -61,6 +67,13 @@ export declare function promptManifestRecordOf(e: {
         shapeDigest: string;
         wireSchemaDigest: string;
     }>;
+    /** core 5.15.0(#181,[2872] 提货②):deferred 工具的披露策略自证——{deferredTools(数), strategy
+     *  ("static"|"swap"), source(四值:spec/env/api-default/default)}。诊断三键(数+两闭集词,零内容)。 */
+    toolDisclosure?: {
+        deferredTools: number;
+        strategy: string;
+        source: string;
+    };
     totalChars: number;
 }): PromptManifestRecord;
 /**

package/dist/observability/prompt-manifest.js

@@ -14,6 +14,14 @@ export function promptManifestRecordOf(e) {
         ...(Array.isArray(e.tools)
             ? { tools: e.tools.map((t) => ({ wireName: String(t.wireName), aliases: (Array.isArray(t.aliases) ? t.aliases : []).map(String), contractId: String(t.contractId), implementationRevision: String(t.implementationRevision), cardId: String(t.cardId), shapeDigest: String(t.shapeDigest), wireSchemaDigest: String(t.wireSchemaDigest) })) }
             : {}),
+        // toolDisclosure(core 5.15.0 #181,[2872] 提货②):三键逐挑——数值有限、两词字符串非空才铸;
+        // 畸形按缺席(不铸假值,与 sections/tools 的 additive 同规)。
+        ...(typeof e.toolDisclosure === "object" && e.toolDisclosure !== null &&
+            typeof e.toolDisclosure.deferredTools === "number" && Number.isFinite(e.toolDisclosure.deferredTools) &&
+            typeof e.toolDisclosure.strategy === "string" && e.toolDisclosure.strategy.length > 0 &&
+            typeof e.toolDisclosure.source === "string" && e.toolDisclosure.source.length > 0
+            ? { toolDisclosure: { deferredTools: e.toolDisclosure.deferredTools, strategy: e.toolDisclosure.strategy, source: e.toolDisclosure.source } }
+            : {}),
         totalChars: e.totalChars,
     };
 }

package/dist/plugins/approval-ask-store-memory.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `InMemoryApprovalAskStore` —— #151 车1,`ApprovalAskStore` 的语义真源(twin 对拆基准)+ LOCAL
+ * 车道占位(File 形不在本车,见设计定稿 §7)。单进程内两个 `Map`,方法体全同步(不含 `await` 中断点)——
+ * Node 单线程下这就是天然原子:`Promise.all` 发起的并发调用不会在方法体内部交错执行,与
+ * `approval-ask-store-sql.ts` 的 CAS UPDATE 语义逐字段一致(SQL twin 对拆套件的基准就是这份实现）。
+ *
+ * 行为口径与 `SqlApprovalAskStore` 逐条对齐:
+ *  - ensureAsk 幂等 upsert(ask_id 已在 ⇒ 返回既有行,不改写;batch 行若不存在则以 OPEN 补齐）。
+ *  - transitionAsk 先过 machine 层 `canAskTransition`(非法转移 throw，不返回 false）。
+ *  - decideAsk/expireAsk/bindBatch/abortBatch 的双/三步判定顺序与 SQL twin 的事务步骤一一对应
+ *    (哪一步先判、判什么、失败时是否触碰另一半状态——照抄，不是「反正内存里原子就随便」）。
+ *  - resolveProvisional 故意不经 canAskTransition(同 SQL twin 头注：这是版本化补偿的例外通道）。
+ */
+import { type AskState, type BatchState } from "../approval-ask-machine.js";
+import type { AskDecision, AskRow, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, DecideResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
+export declare class InMemoryApprovalAskStore implements ApprovalAskStore {
+    private readonly asks;
+    private readonly batches;
+    ensureAsk(row: NewAskRow): Promise<AskRow>;
+    transitionAsk(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
+    decideAsk(askId: string, batchId: string, decision: DecideAskInput): Promise<DecideResult>;
+    expireAsk(askId: string, batchId: string): Promise<ExpireResult>;
+    bindBatch(batchId: string, askId: string, gate: BindGateInput): Promise<BindResult>;
+    deferReconcile(askId: string, expectedState: AskState, expectedVersion: number, nowMs: number): Promise<boolean>;
+    abortBatch(batchId: string): Promise<string[]>;
+    listByState(state: AskState, limit: number): Promise<AskRow[]>;
+    /** `signal` 的 twin 语义(车3 刀 3b):同步实现里没有「在飞」这回事,所以能做也只需做**入口复核** ——
+     *  已 abort 就一条都不读、如实抛,与 SQL twin 的第①条语义逐字一致(第②条在这里天然平凡成立)。 */
+    listPendingByTask(taskId: string, signal?: AbortSignal): Promise<AskRow[]>;
+    listPendingBySession(sessionId: string, owner: string | null, signal?: AbortSignal): Promise<AskRow[]>;
+    getAsk(askId: string): Promise<AskRow | null>;
+    getByIdempotencyKey(taskId: string, key: string): Promise<AskRow | null>;
+    resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
+    deleteByTask(taskId: string): Promise<void>;
+    getBatch(batchId: string): Promise<BatchRow | null>;
+}
+export type { AskDecision, AskState, BatchState };
+//# sourceMappingURL=approval-ask-store-memory.d.ts.map