@sema-agent/server 7.2.0 → 7.3.0

package/dist/plugins/store-backend.d.ts

@@ -8,6 +8,7 @@ import { FileRunStore } from "./file-run-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { type ApprovalExemptionStore } from "./approval-exemption-store.js";
+import { type ApprovalAskStore as ApprovalAskStoreType } from "./approval-ask-store-sql.js";
 import { type SendFileLedger } from "./send-file-ledger.js";
 import { TiDBResumeAnchorStore, PgResumeAnchorStore } from "./resume-anchor-store-sql.js";
 import type { ServiceConfig } from "../config-types.js";
@@ -27,6 +28,9 @@ export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
  *  FileResumeAnchorStore is the FILE-backed local twin (P0.5 variant-1; survives restart). */
 export type ResumeAnchorStore = TiDBResumeAnchorStore | PgResumeAnchorStore | FileResumeAnchorStore;
 export type { ApprovalExemptionStore } from "./approval-exemption-store.js";
+/** #151(design/172 v3.1 §3.0-§3.2 流内审批协议持久层):`ApprovalAskStore` 接口 + 行/补丁类型。
+ *  车3 刀 3a 起 `StoreBackend.approvalAsk()` 已在(见接口体的那条注)。 */
+export type { ApprovalAskStore, AskRow, NewAskRow, AskTransitionPatch, DecideAskInput, DecideResult, ExpireResult, BindGateInput, BatchRow, AskDecision } from "./approval-ask-store-sql.js";
 /** E6 SessionPolicyStore — core's interface PLUS the service `deleteBySession` (E21 purge; only the durable twins carry
  *  it, core's InMemory omits it → optional). tidb/pg = durable twins; local = core's InMemorySessionPolicyStore (works
  *  local — rules need no cloud-only infra). The shared env-gated equivalence suite keeps the twins byte-matched to InMemory. */
@@ -107,6 +111,20 @@ export interface StoreBackend {
     /** Per-session per-toolName approval exemption ("本会话不再询问") — an approval MEMORY the F4
      *  ask-gate consults after deny/neverAuto. REQUIRED on all backends (works local, like resumeAnchor). */
     approvalExemption(): ApprovalExemptionStore;
+    /** #151(design/172 §3.0-§3.2)流内审批协议持久层:每个流内工具调用一行的 ask 状态机 + 批行。
+     *  REQUIRED on all backends — tidb/pg = SQL 双方言 twin;local = {@link InMemoryApprovalAskStore}。
+     *
+     *  🔴 local 形的代价必须在这里说清楚(而不是留给读者自己发现):InMemory 的 STREAM_PENDING/DECIDED/
+     *  PARKING 全在两个进程内 Map 里 ⇒ **重启同时丢重放基准、丢已接受的决议、丢审计**——「一次真实的人类
+     *  批准凭空消失」和「对账便利丢失」不是一个量级。因此协议在 local 车道**默认不上场**:能力面
+     *  (`streamApproval`)的判据带一条「ask 账必须是持久的」合取项,local 不报 true(诚实缺席,同
+     *  `park 设施缺席 ⇒ 协议不上场` 的姿势)。要在 local 真上协议,先落 File 形(现成模子 =
+     *  {@link FileApprovalExemptionStore}:core `AppendLog`/`readJsonlRecords`,内存索引 + 追加日志即可
+     *  满足单实例 boot-lock 下的 CAS),那时这里换成 File twin、能力面自然翻真。
+     *
+     *  无 backend 的 env-only worker 压根没有 `StoreBackend` ⇒ 协调器拿到 undefined askStore ⇒ 车2 的
+     *  D1 逐字现行为(store 缺席 = 现行 `tool_approval` 活卡腿一字不变)。 */
+    approvalAsk(): ApprovalAskStoreType;
     /** SendUserFile scope↔object ledger (multi-tenant list/revoke handle; the hashed key segment hides the
      *  mapping from URLs). REQUIRED on all backends (works local — one JSONL, like approvalExemption). */
     sendFileLedger(): SendFileLedger;

package/dist/plugins/store-backend.js

@@ -18,6 +18,8 @@ import { LocalSessionStore } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { TiDBApprovalExemptionStore, PgApprovalExemptionStore, FileApprovalExemptionStore } from "./approval-exemption-store.js";
+import { TiDBApprovalAskStore, PgApprovalAskStore } from "./approval-ask-store-sql.js";
+import { InMemoryApprovalAskStore } from "./approval-ask-store-memory.js";
 import { TiDBSendFileLedger, PgSendFileLedger, FileSendFileLedger } from "./send-file-ledger.js";
 import { TiDBResumeAnchorStore, PgResumeAnchorStore } from "./resume-anchor-store-sql.js";
 import { TiDBSessionPolicyStore, PgSessionPolicyStore } from "./session-policy-store-sql.js";
@@ -94,6 +96,7 @@ class TiDBBackend {
     run() { return new TiDBRunStore(this.pool); }
     resumeAnchor() { return new TiDBResumeAnchorStore(this.pool); }
     approvalExemption() { return new TiDBApprovalExemptionStore(this.pool); }
+    approvalAsk() { return new TiDBApprovalAskStore(this.pool); } // #151 流内审批协议持久层(无状态 store,每次新建同兄弟)
     sendFileLedger() { return new TiDBSendFileLedger(this.pool); }
     sessionPolicy() { return new TiDBSessionPolicyStore(this.pool); }
     fileSnapshot() { return new TiDBFileSnapshotStore(this.pool, snapshotBlobBackend(this.config, "tidb", this.pool), snapshotBoundsFromConfig(this.config)); }
@@ -127,6 +130,7 @@ class PgBackend {
     run() { return new PgRunStore(this.pool); }
     resumeAnchor() { return new PgResumeAnchorStore(this.pool); }
     approvalExemption() { return new PgApprovalExemptionStore(this.pool); }
+    approvalAsk() { return new PgApprovalAskStore(this.pool); } // #151 流内审批协议持久层(SQL twin)
     sendFileLedger() { return new PgSendFileLedger(this.pool); }
     sessionPolicy() { return new PgSessionPolicyStore(this.pool); }
     fileSnapshot() { return new PgFileSnapshotStore(this.pool, snapshotBlobBackend(this.config, "pg", this.pool), snapshotBoundsFromConfig(this.config)); }
@@ -178,6 +182,8 @@ class LocalBackend {
     sessionStore;
     resumeAnchorStore;
     approvalExemptionStore;
+    /** #151 —— 进程内易失(见 approvalAsk() 的注);File 形落地前它就是 local 车道的占位。 */
+    approvalAskStore = new InMemoryApprovalAskStore();
     sendFileLedgerStore;
     // SVC-2: FILE-backed durable journal (was core's InMemory — a TOC restart silently resolved
     // resumeFromRunId to an empty journal → full live re-run). Now restart-durable on one box; crash-safe JSONL,
@@ -223,6 +229,10 @@ class LocalBackend {
     run() { return this.runStore; }
     resumeAnchor() { return this.resumeAnchorStore; } // singleton — state lives in the instance (mirrors run()/session())
     approvalExemption() { return this.approvalExemptionStore; } // singleton — same posture
+    /** #151 流内审批协议持久层的 local 形。**必须**是 singleton:状态全在实例的两个 Map 里,每次
+     *  new 一个就等于每个消费者各拿一份互不可见的账(而 SQL twin 天然共享一张表)。易失代价 +
+     *  「local 车道默认不上协议」的裁定见 StoreBackend.approvalAsk() 的接口注。 */
+    approvalAsk() { return this.approvalAskStore; }
     sendFileLedger() { return this.sendFileLedgerStore; } // singleton — append fd lives in the instance
     /** Durable HITL / plan-review parking on the LOCAL lane. Lazy singleton (the inner core store holds
      *  an append fd). taskId join ← FileRunStore; E21 owner guard ← LocalSessionStore.ownerOf (same root). */

package/dist/plugins/tidb-pool.js

@@ -1,4 +1,5 @@
 import mysql from "mysql2/promise";
+import { TIDB_APPROVAL_ASK_STATEMENTS } from "./approval-ask-store-sql.js";
 /**
  * Shared TiDB (MySQL wire-compatible) connection pool for the durable Session center (L1).
  * Owned by `main.ts`; closed on shutdown.
@@ -244,11 +245,28 @@ export const SCHEMA_STATEMENTS = [
      -- D-1 TOCTOU binding guard is UNREACHABLE by the portal without it — it can then only do the unbound legacy
      -- fallback). NULL on PRE-D-1 rows ⇒ that unbound fallback.
      bound_input_hash VARCHAR(190) NULL,
-     -- pending_steer (design/80 D-A, durable steering): the parked steer ({text,trusted} JSON) set by
-     -- setPendingSteer on a STILL-PENDING checkpoint (last-writer-wins, CAS on status='pending'), surfaced via
-     -- get() as state.pendingSteer so core injects it on resume. NULL when no steer is parked.
-     -- Never touches status/resolve (design/80 inv #4).
+     -- pending_steer (design/80 D-A, durable steering):**队列化之前**的单座列,存 {text,trusted}。
+     -- core 5.14.0(#147 BREAKING)之后本服务**只读不写**它:存量行的那一座由 core readPendingSteerQueue
+     -- 折成 member 0,零迁移。NULL = 没有旧座。Never touches status/resolve (design/80 inv #4)。
      pending_steer TEXT         NULL,
+     -- pending_steer_queue:core 5.14.0(#147)的**有界有序队列**(PendingSteerEntry[] 的 JSON)。
+     -- 为什么队列另起一列、而不是把信封写回 pending_steer(codex 复审 2026-08-06 F3,采纳):滚动升级/
+     -- 回滚窗里旧副本仍在跑,它对 pending_steer 是**无条件覆盖**写 —— 队列若躺在同一列,旧副本接的下一条
+     -- steer 会把 5.14 排好的整队悄悄抹掉,正是 #147 要消灭的那种静默丢失换了个位置复发。分列之后:
+     -- 旧副本写它的单座 ⇒ 落 pending_steer,新读侧把它折成 member 0,**两边都活着**;旧副本读不到队列
+     -- 是 core 自己已披露的回滚代价(CHANGELOG:rolling back across the queue event loses steers),
+     -- 那半无法在店面消除,但**写侧互相清零**这半可以,且代价只是一个可空列。
+     -- 容量:core 的 PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES = 48000 字节是对 {pendingSteer,queue} 整信封的
+     -- 硬上界(越界 fail-loud steering.queue_full,绝不驱逐)⇒ 本列恒小于它,MySQL TEXT 的 65535 字节
+     -- 够用,**不升 LONGTEXT**(core 常量注里点名「under a MySQL TEXT column with UTF-8 headroom」)。
+     pending_steer_queue TEXT   NULL,
+     -- pending_steer_rev:pending_steer_queue 列**自己**的乐观锁计数(与 resolve/reopen 的 rev 是两个轴,
+     -- 刻意不复用)。队列化之后 setPendingSteer 从「一条无条件 UPDATE」变成「读-改-写」,中间那道窗必须
+     -- 有 CAS 守着,否则两个并发 steer 各读到同一份队列、后写者把前者的条目整个盖掉。
+     -- 🔴 为什么不拿队列列的旧值当守卫:本表没有显式 COLLATE,库默认多为 *_ci —— 字符串 <=> 在大小写
+     -- 不敏感的排序规则下会把两份只差字母大小写的 JSON 判等,CAS 假命中 = 丢一条指令。整数列没有这个面。
+     -- **绝不**用它做 resolve 的 OCC:bump 它不影响 core 的 rev 语义。
+     pending_steer_rev BIGINT  NOT NULL DEFAULT 0,
      -- risk_descriptor (design/80 riskDescriptor inbox): core's INERT CheckpointGate.riskDescriptor ({severity
      -- 1-5, axes, toolName, redacted summary, touchedPaths}), stamped at put() so listPending can surface it +
      -- triage-sort the supervisor inbox by severity DESC — WITHOUT parsing the checkpoint blob per row.
@@ -602,6 +620,11 @@ export const SCHEMA_STATEMENTS = [
      pool VARCHAR(32) NOT NULL,
      PRIMARY KEY (pool)
    )`,
+    // #151(design/172)流内审批协议持久层的两张表。真源 = approval-ask-store-sql.ts 的
+    // `TIDB_APPROVAL_ASK_STATEMENTS`(那里与 PG twin 并排,方言差异一眼可对);展开进这个数组是为了让它们
+    // 跟着中央 `ensureSchema` 在 **named-lock 的那条 conn** 上建 —— 把 pool 级 ensure 函数塞进执行循环
+    // 会绕开 DDL 串行化。挂进来同时也是「这张表算生产 schema」的声明(基线导出按定义只收录被执行的语句)。
+    ...TIDB_APPROVAL_ASK_STATEMENTS,
 ];
 /** Named MySQL/TiDB advisory lock that serializes the whole `ensureSchema` DDL run (see below). */
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";

package/dist/question.d.ts

@@ -11,6 +11,9 @@ export interface QuestionFrame {
     /** "question_complete" only: whether the human answered (`answered`) or the ask was released unanswered
      *  (`unanswered` — ttl/abort → the model got the headless default). Cosmetic dialog-dismiss. */
     outcome?: "answered" | "unanswered";
+    /** Server-signed emit timestamp (additive, [2805]§五→[2806]). Server-minted side-frame ⇒ no core-stream
+     *  `eventId` to carry (absence is honest); this is the frame's own time coordinate. */
+    serverNowMs?: number;
 }
 /** The per-run context `onQuestion` recovers via ALS. `emit` delivers a frame to the run's live stream; `abortSignal`
  *  (the run's own cancel signal) releases a question parked awaiting a human when the run aborts. */

package/dist/question.js

@@ -158,7 +158,7 @@ export class QuestionCoordinator {
         // fire-and-forget append can commit out of seq order and be skipped by the monotonic events-tail cursor). A FAILED
         // emit headless-defaults (nobody can answer) and must NOT burn the per-run total.
         try {
-            await ctx.emit({ type: "question", questionId: id, questions });
+            await ctx.emit({ type: "question", questionId: id, questions, serverNowMs: Date.now() });
             rc.total += 1;
         }
         catch {
@@ -168,7 +168,7 @@ export class QuestionCoordinator {
         // Completion breadcrumb (dialog dismiss) — FIRE-AND-FORGET so a slow durable append can never delay returning the
         // answer to core. Best-effort + ordering-uncritical (the shell already has the answer via respond).
         void Promise.resolve()
-            .then(() => ctx.emit({ type: "question_complete", questionId: id, outcome: lastOutcome }))
+            .then(() => ctx.emit({ type: "question_complete", questionId: id, outcome: lastOutcome, serverNowMs: Date.now() }))
             .catch(() => undefined);
         return answer;
     };

package/dist/runs.d.ts

@@ -5,6 +5,7 @@ import type { Metrics } from "./observability/metrics.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "./budget.js";
 import type { ElicitationCoordinator } from "./elicitation.js";
 import type { QuestionCoordinator } from "./question.js";
+import { type ToolApprovalCoordinator } from "./tool-approval.js";
 import { type FleetRunPublisher } from "./fleet/fleet-bus.js";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
 import type { VerifyRoundsSpec } from "./http/verify-rounds.js";
@@ -250,7 +251,21 @@ completionDiagLog?: (msg: string, meta?: Record<string, unknown>) => void,
 sendUserFile?: SendUserFileEmitter, 
 /** [998]② the shared prompt-manifest accumulator (tracer records at prepare; this leg drains the pending
  *  record into a durable `prompt_assembled` event — turns/stream read it). undefined ⇒ not wired. */
-promptManifests?: PromptManifestTracker): Promise<void>;
+promptManifests?: PromptManifestTracker, 
+/**
+ * #151 车3 刀 3b:**bg 腿的流内审批 ctx**(design/172 §4.3(b))。今天为止这条腿连 approval ALS 都没有
+ * ——`deps.onAsk` 拿不到 ctx ⇒ 恒 `"unavailable"` ⇒ durable park,一张卡都不产。接上之后,bg run 的
+ * 权限 ask 走本腿的 **durable events tail**(`GET /v1/runs/:id/events`,唯一带 SSE `id:` 的面)。
+ *
+ * `streamApprovalOn` = 协议上场判据(`resolveStreamApprovalGate`,由路由层求值后传进来 —— 本函数是纯
+ * 执行腿,不该自己读 backend/config)。为假 ⇒ 只接既有四键 ctx(呈卡口/腿轴都不接),本腿字节逐字不变。
+ */
+approval?: {
+    coordinator: ToolApprovalCoordinator;
+    streamApprovalOn: boolean;
+    windowMs: number;
+    windowMarginMs: number;
+}): Promise<void>;
 /** How often a running instance refreshes its run's updated_at (liveness, independent of events).
  *  Must stay strictly below `runStaleSec` (asserted at startup) or the reaper would race live runs. */
 export declare const HEARTBEAT_MS = 30000;

package/dist/runs.js

@@ -3,6 +3,7 @@ import { withPrincipal } from "./observability/principal-context.js";
 import { redactSecrets } from "./trace/redact.js";
 import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
+import { createApprovalCardEmitter, resolveApprovalLeg } from "./tool-approval.js";
 import { fleetRunResiduals, isFleetAgentTerminalNotification } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
@@ -331,7 +332,16 @@ completionDiagLog,
 sendUserFile, 
 /** [998]② the shared prompt-manifest accumulator (tracer records at prepare; this leg drains the pending
  *  record into a durable `prompt_assembled` event — turns/stream read it). undefined ⇒ not wired. */
-promptManifests) {
+promptManifests, 
+/**
+ * #151 车3 刀 3b:**bg 腿的流内审批 ctx**(design/172 §4.3(b))。今天为止这条腿连 approval ALS 都没有
+ * ——`deps.onAsk` 拿不到 ctx ⇒ 恒 `"unavailable"` ⇒ durable park,一张卡都不产。接上之后,bg run 的
+ * 权限 ask 走本腿的 **durable events tail**(`GET /v1/runs/:id/events`,唯一带 SSE `id:` 的面)。
+ *
+ * `streamApprovalOn` = 协议上场判据(`resolveStreamApprovalGate`,由路由层求值后传进来 —— 本函数是纯
+ * 执行腿,不该自己读 backend/config)。为假 ⇒ 只接既有四键 ctx(呈卡口/腿轴都不接),本腿字节逐字不变。
+ */
+approval) {
     const startedAt = Date.now();
     metrics?.addGauge("runs_active", 1);
     fleetPublisher?.onStart(); // MF-Fleet: the row goes live (running) the moment the background run starts
@@ -372,6 +382,21 @@ promptManifests) {
     // The owning principal is this run's owner — thread it as the single-DB-fleet null-safe owner guard on every
     // run-store mutation/poll below (the run row was created with owner = principal ?? null).
     const owner = principal ?? null;
+    // #151 车3 刀 3b(§7.3 + §8.3):本腿的审批装配裁定走**三腿共用**的那一份判据。
+    // 🔴 codex 交叉复审 F3(2026-08-06 真 finding)的修:此前本腿**无条件**包 ALS,只把新协议的口与轴挂在
+    // `streamApprovalOn` 后面 —— 于是 ①开关关时本腿的行为变了(此前它根本没有 approval ctx,每只 ask 恒
+    // `"unavailable"` ⇒ 恒 park;包上之后变成活卡并等满窗,A-1 当场破),②窗=0 在本腿上不生效(照样落行、
+    // 注册资源、发帧,再等一个 0ms 的表)。现在两件都由下面这一个裁定统一管。
+    // 取值点 = **本腿开始执行的时刻** = `runInBackground` 进入(路由层 `void runInBackground(...)` 之后
+    // 立刻),不是请求到达时刻(§3.3:按任务创建至今算会系统性算错)。
+    const approvalLeg = resolveApprovalLeg({
+        streamApprovalOn: approval?.streamApprovalOn === true,
+        windowMs: approval?.windowMs ?? 0,
+        windowMarginMs: approval?.windowMarginMs ?? 0,
+        ...(typeof spec.limits?.maxWalltimeMs === "number" ? { legWalltimeMs: spec.limits.maxWalltimeMs } : {}),
+        nowMonotonicMs: performance.now(),
+    });
+    const legDeadlineMonotonic = approvalLeg.legDeadlineMonotonic;
     const heartbeat = setInterval(() => {
         // 鲁棒性批5 A5(2026-08-05):与下面 cancel/preempt 两条兄弟同族——此前裸吞错,store 持续故障期间本 run
         // 的心跳每拍静默落空、运维零信号,直到某个副本的 reapStale 把它误判死亡(心跳失败正是那个误判的前兆)。
@@ -476,6 +501,15 @@ promptManifests) {
         const { type, ...rest } = frame;
         return append(type, rest);
     };
+    // #151 车3 刀 3b(design/172 §4.3(b)):同款 durable-append emit,服务**审批**帧 —— 既有
+    // `tool_approval`/`tool_approval_complete` 走它,新协议的 `approval_request` 也走它(同一条投递面、
+    // 两种帧,§4.3(a) 的「不新增出口」在这条腿上的落实)。`type` 是 SSE 事件名,其余是 data。
+    // 撤卡帧(`approval_revoke`)**不接**:它是 live-only 语义(不进账本 —— reaper/收敛器那类调用点没有
+    // seq 可分配),而本腿的唯一投递面就是账本;丢帧的结构补偿是重连 preamble 的全量对账基准。
+    const approvalEmit = (frame) => {
+        const { type, ...rest } = frame;
+        return append(type, rest);
+    };
     try {
         // P1 ①② follow-on (core): drain this session's async-workflow completion inbox at the START of the
         // background leg (before ANY branch — verify/cascade/plain-stream all get it; parity with the sync leg's
@@ -742,10 +776,34 @@ promptManifests) {
             const withQuestion = () => question
                 ? question.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: questionEmit, abortSignal: cancelCtrl.signal }, withElicit)
                 : withElicit();
+            // #151 车3 刀 3b:审批 ALS —— 本腿**首次**拿到卡面(此前 `deps.onAsk` 在这条腿上恒无 ctx ⇒
+            // `"unavailable"` ⇒ 恒 park)。嵌套序同样无关(各自独立 ALS)。
+            // 🔴 F3 修:包不包 ALS 由 `approvalLeg` 决定,不再是「协调器在场就包」。
+            //  · `active === false`(协议没上场)⇒ 不包 ⇒ `deps.onAsk` 找不到 ctx ⇒ `"unavailable"` ⇒ core
+            //    durable park —— 这正是本腿在协议之前的逐字行为(A-1)。
+            //  · `windowZero`(运维关窗 / 贴 deadline)⇒ 同样不包。本腿没有 per-task `spec.onAsk` 装配点,
+            //    「不包 ALS」就是 sync 腿那个 immediate-unavailable 闭包在这条腿上的**等价形**(§8.2 已亲证:
+            //    `approverUnavailable === true` 与「onAsk 缺席」在 park 结局上逐字等价)。
+            const withApproval = () => approval && approvalLeg.active && !approvalLeg.windowZero
+                ? approval.coordinator.runWithContext({
+                    taskId,
+                    owner: elicitOwner ?? owner,
+                    emit: approvalEmit,
+                    abortSignal: cancelCtrl.signal,
+                    ...(spec.sessionId ? { sessionId: spec.sessionId } : {}),
+                    // 同一条 durable tail(§4.3(b))。经共用的投递口工厂:账本 append 失败 ⇒ 如实算「这一路没
+                    // 接下」(本腿只有这一个 sink,于是=整条没送到),协调器据此走 park 而不是挂到窗到期(R2-1)。
+                    emitCard: createApprovalCardEmitter({ appendDurable: (f) => approvalEmit(f) }),
+                    // bg run 的这条腿恒是**首腿**(park→resume 走的是 server.ts 的 resume 腿,那条自己带
+                    // token 摘要);空串是首腿的真值,不是「未知」。
+                    legKey: "",
+                    ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}),
+                }, withQuestion)
+                : withQuestion();
             // SendUserFile 帧与 question 帧同投递面(durable events tail,web 渲染文件卡);嵌套序无关(ALS 互不相交)。
             return sendUserFile
-                ? sendUserFile.runWithContext({ taskId, emit: (frame) => { const { type, ...rest } = frame; return append(type, rest); } }, withQuestion)
-                : withQuestion();
+                ? sendUserFile.runWithContext({ taskId, emit: (frame) => { const { type, ...rest } = frame; return append(type, rest); } }, withApproval)
+                : withApproval();
         });
         // Cancelled mid-stream and the generator ended WITHOUT a terminal event (abort can end the stream cleanly
         // rather than throwing) — finalize cancelled here so the run isn't left "running" for the reaper to catch.

package/dist/runtime-caps-resolver.d.ts

@@ -30,6 +30,9 @@ import type { RuntimeCaps } from "@sema-agent/core";
 import type { EntitlementRuntimeCaps } from "@sema-agent/registry-core";
 import { fetchPrincipalCaps, type ExecutionRuling } from "./config-center/facade.js";
 import type { ScenarioRuling } from "./capabilities/scenarios.js";
+import { type Logger } from "./observability/logger.js";
+/** test-only: reset the once-per-process trace so each test observes a fresh "first hit". */
+export declare function resetExecutionLaneDefaultTraceForTest(): void;
 export interface EntitlementsResolverOpts {
     baseUrl: string;
     token: string;
@@ -99,8 +102,11 @@ export interface PrincipalEntitlementsClient {
  * allowlist + this worker's lane (machine code on the wire, prose stays with the shell/web).
  * No ruling / required=false / caps blip ⇒ pass (fail-open + audit). `allowedLanes` is an
  * OPEN domain — unknown names simply never match this worker's lane.
+ *
+ * `logger` (optional, defaults to this module's `defaultLogger`) is an injection seam purely for the
+ * once-per-process default trace below (test observability) — it does not change enforcement.
  */
-export declare function gateExecutionLane(ruling: ExecutionRuling | undefined, ownLane: string): void;
+export declare function gateExecutionLane(ruling: ExecutionRuling | undefined, ownLane: string, logger?: Logger): void;
 /**
  * Build the per-principal caps client: `resolveRuntimeCaps` matches core's seam signature
  * `(principal) => Promise<RuntimeCaps | undefined>`; `scenarioRuling` rides the SAME fetch/cache/in-flight

package/dist/runtime-caps-resolver.js

@@ -2,6 +2,48 @@ import { fetchPrincipalCaps } from "./config-center/facade.js";
 import { HttpError } from "./security.js";
 import { createLogger } from "./observability/logger.js";
 const defaultLogger = createLogger();
+/** #157 / [2762]§五(sema-comms `audits/failopen-governance-176.md` §7 "已知在办 1 条"):module-scope,
+ *  once-per-process record of which {@link gateExecutionLane} fail-open DEFAULT form has already been traced.
+ *  Two forms are counted SEPARATELY (both currently resolve to the same "pass" default, but they are different
+ *  facts about the world — a caller must be able to tell "we never got a ruling for this principal" apart from
+ *  "center ruled, and explicitly said not-required"):
+ *   - `"no_ruling"` — `ruling === undefined` (no principal / center absent-or-blip / older center missing the key).
+ *   - `"required_false"` — a ruling WAS resolved and it explicitly says `required: false`.
+ *  Each form logs ONCE per process at first hit (a debug line — this is an expected, non-alarming default, not a
+ *  warning); every subsequent hit of the SAME form only increments the counter (no repeat log line — this is a
+ *  per-task gate, so without the throttle a busy deployment would log once per task forever). Pure record-keeping:
+ *  never changes {@link gateExecutionLane}'s pass/deny outcome. */
+const executionLaneDefaultTrace = new Map();
+/** test-only: reset the once-per-process trace so each test observes a fresh "first hit". */
+export function resetExecutionLaneDefaultTraceForTest() {
+    executionLaneDefaultTrace.clear();
+}
+function traceExecutionLaneDefault(form, ownLane, logger) {
+    const hitCount = (executionLaneDefaultTrace.get(form) ?? 0) + 1;
+    executionLaneDefaultTrace.set(form, hitCount);
+    if (hitCount > 1)
+        return; // subsequent hits: silently counted only (see map above), no repeat log line
+    try {
+        // codex 交叉复审第二轮真发现(2026-08-05):a throwing `logger.debug` must NEVER turn this pure
+        // observability step into gateExecutionLane itself throwing — that would silently convert a fail-open
+        // PASS into an uncaught exception, the exact inversion this module's whole design fights elsewhere
+        // (see the FAIL-CLOSED/FAIL-OPEN posture doc above). The hit-count above already advanced, so a retry
+        // of the SAME form stays silent rather than storming — the trade-off is "lose one trace line", not
+        // "lose one task admission".
+        logger.debug("execution_lane_default_applied", {
+            dimension: "execution_lane",
+            form,
+            ownLane,
+            default: "pass",
+            note: form === "no_ruling"
+                ? "no execution-lane ruling was ever resolved for this principal (no principal / center absent-or-blip / older center without the key)"
+                : "center resolved a ruling and explicitly set required=false",
+        });
+    }
+    catch {
+        // tracing must never affect the fail-open admission outcome — see comment above.
+    }
+}
 /** Map center's `EntitlementRuntimeCaps` → the subset core's engine enforces. `allowUltracode` (shell/UX) is
  *  dropped on purpose (not a core primitive); `allowWorkflows` / `forceDurableGate` / `allowFork` are the three the
  *  engine enforces. Returns undefined when no enforceable cap is set (= no restriction). FAIL-CLOSED defense-in-depth:
@@ -60,10 +102,19 @@ export function scopedTokenNeedsWorker(token, worker) {
  * allowlist + this worker's lane (machine code on the wire, prose stays with the shell/web).
  * No ruling / required=false / caps blip ⇒ pass (fail-open + audit). `allowedLanes` is an
  * OPEN domain — unknown names simply never match this worker's lane.
+ *
+ * `logger` (optional, defaults to this module's `defaultLogger`) is an injection seam purely for the
+ * once-per-process default trace below (test observability) — it does not change enforcement.
  */
-export function gateExecutionLane(ruling, ownLane) {
-    if (!ruling?.required)
+export function gateExecutionLane(ruling, ownLane, logger = defaultLogger) {
+    if (!ruling) {
+        traceExecutionLaneDefault("no_ruling", ownLane, logger);
         return;
+    }
+    if (!ruling.required) {
+        traceExecutionLaneDefault("required_false", ownLane, logger);
+        return;
+    }
     if (!ruling.allowedLanes.includes(ownLane)) {
         throw new HttpError(403, `this worker's execution lane "${ownLane}" is not permitted for this principal (execution policy)`, {
             code: "execution_lane_not_allowed",
@@ -149,7 +200,18 @@ export function createPrincipalEntitlementsClient(opts) {
                 return entry;
             }
             catch (err) {
-                const e = err instanceof Error ? err : new Error(String(err));
+                // codex 交叉复审第三轮真发现(2026-08-05):a poison rejection reason (throwing `Symbol.toPrimitive`/
+                // `toString`) must not make THIS normalization line itself throw — this catch block exists to
+                // GUARANTEE the documented FAIL-CLOSED degrade below runs; if normalizing `err` throws, that
+                // guarantee is exactly what breaks (resolveRuntimeCaps/scenarioRuling/executionRuling would reject
+                // instead of resolving to their fail-closed/fail-open defaults on a degraded center response).
+                let e;
+                try {
+                    e = err instanceof Error ? err : new Error(String(err));
+                }
+                catch {
+                    e = new Error("center fetch failed with an unstringifiable rejection reason");
+                }
                 // Caps face FAIL CLOSED: deny the OPTIONAL amplification caps (workflows + fork); never force the durable
                 // gate on error. Scenario face FAIL OPEN: `scenario` stays undefined (no governance — never pin users to
                 // the default scenario on a center blip; deliberate posture split, see PrincipalEntitlementsClient). Cache the

package/dist/spec-fields.d.ts

@@ -85,6 +85,10 @@ export declare function toolNameListFromBody(raw: unknown): string[] | undefined
  *  ⇒ 无租户门(deferTools 同姿势);全委托树继承由 core 管。缺省不挂键(引擎缺省 simple,byte-compat)。
  *  DEFENSIVE(resume 重放不过 HTTP 400 门):非法值 ⇒ undefined;提交面另有 fail-loud 400(邻居姿势)。 */
 export declare function promptProfileFromBody(raw: unknown): "simple" | "classic" | undefined;
+/** [2856]②(core 5.14.0 `TaskSpec.toolMaterializeStrategy`):deferred 工具激活后的 schema 供给策略。
+ *  与 {@link promptProfileFromBody} 同姿势的**防御性归一**——提交面的 fail-loud 400 在 HTTP 门,这里
+ *  只负责 resume 重放存量 body 时把不认识的值静默 DROP(回落 core 的 env/缺省链),而不是把它带上 spec。 */
+export declare function toolMaterializeStrategyFromBody(raw: unknown): "static" | "swap" | undefined;
 /** [854]④ — 每键的运营方上限旋钮(env,缺省不设=不封顶)。 */
 export interface TaskLimitCaps {
     /** TASK_TIMEOUT_MAX_SEC(env 名不动,仍按**秒**配置;core 5.8.0 起封顶对象是 limits.maxWalltimeMs,

package/dist/spec-fields.js

@@ -351,6 +351,12 @@ export function toolNameListFromBody(raw) {
 export function promptProfileFromBody(raw) {
     return raw === "simple" || raw === "classic" ? raw : undefined;
 }
+/** [2856]②(core 5.14.0 `TaskSpec.toolMaterializeStrategy`):deferred 工具激活后的 schema 供给策略。
+ *  与 {@link promptProfileFromBody} 同姿势的**防御性归一**——提交面的 fail-loud 400 在 HTTP 门,这里
+ *  只负责 resume 重放存量 body 时把不认识的值静默 DROP(回落 core 的 env/缺省链),而不是把它带上 spec。 */
+export function toolMaterializeStrategyFromBody(raw) {
+    return raw === "static" || raw === "swap" ? raw : undefined;
+}
 /** core 5.8.0 时限重构的退役键(fresh-submit 在 HTTP 门 400 点名;resume 重放在 normalize 层 DROP)。 */
 const RETIRED_LIMIT_KEYS = ["timeoutSec", "deadlineNudge", "callCapByDeadline", "gracefulFinalize"];
 /** 在场的退役键(normalizeLimits/resolveTaskLimits 共用判据源:留痕事件的 droppedKeys 字段)。 */

package/dist/task-settings.d.ts

@@ -55,6 +55,10 @@ export type SettingsPermissionMode = "default" | "acceptEdits" | "plan" | "bypas
  * would FORCE the manual ask gate onto a caller that explicitly asked for less asking — with the gate live, the old
  * coercion would have been a behavior change for them, incl. a headless-deny regression for bypass callers). An
  * UNKNOWN string still coerces to `default` (fail-safe: the most-asking mode).
+ * #157-②: fresh submits can no longer REACH the unknown-word arm — the HTTP gate 400s a non-five-mode value
+ * (server.ts, sibling of promptProfile) and the wire type is a closed enum. This lenient fold stays for the one
+ * population the gate deliberately does not cover: RESUME replay of a persisted pre-gate body (outputStyle/model
+ * two-layer posture — bricking a resume over a value that was legal at submit time is worse than the quiet fold).
  */
 export declare function coercePermissionMode(raw: unknown): SettingsPermissionMode | undefined;
 /** L2 ultracode (design/111): the effective `thinking` level given the explicit `reasoningEffort` and the ultracode
@@ -143,31 +147,47 @@ export declare function hasConstitutionAnchors(text: unknown): boolean;
  *  (REPLACE_ALL_EXCLUDED strips role.append) → append-less true. */
 export declare function providerDropsAppend(provider: PromptProvider | undefined, userSystemPrompt: string | undefined): boolean;
 export declare function acceptAppendSystemPrompt(v: unknown, warn?: (detail: string) => void, packDropsAppend?: boolean): string | undefined;
-/** [1248]②/codex F2 — what the workflow ask leg needs from the deployment, on EVERY lane (unlike
- *  {@link FsWriteGateWiring}, which is host-lane-only because it adjudicates against a real fs; the workflow
- *  gate is name-keyed and fs-independent). */
+/** [1248]②/codex F2 — what the workflow ask leg needs from the deployment, on EVERY lane. It is name-keyed and
+ *  fs-independent, so it never had the lane split {@link FsWriteGateWiring} carried (that split is itself gone
+ *  since #156 — the sandbox lanes now wire a lexical-path gate instead of no gate). */
 export interface WorkflowGateWiring {
     /** The session "don't ask again" probe (approvalExemptionStore.has, canonical toolName key) — same store and
      *  key space as the fs-write gate's probe; one remember="session" grant serves both. */
     isExempt?: (toolName: string) => boolean | Promise<boolean>;
 }
-/** [816]/[820]① — everything the mode-derived fs-write ask gate needs from the deployment, provided by main.ts
- *  ONLY on a HOST-SEMANTICS lane (`REMOTE_EXEC` unset or "host"). Absent ⇒ no gate is derived (the pre-[816]
- *  behavior). WHY lane-gated: core's `createFsWriteGatePolicy` canonicalizes every target/dir through the given
- *  `env` (real `exists`/`canonicalPath`/`readLink` fs access — read in dist, 1.290 fs-write-gate-policy.js), so the
- *  env's fs MUST be the fs the hand tools write. On e2b/k8s/ssh/adb/local-docker the tools run OFF this box and the
- *  per-task sandbox env is minted inside core (executionEnvFactory) AFTER spec build — a worker-local env here would
- *  adjudicate against the WRONG fs (symlink/exists answers from the worker host). Honest absence over a wrong gate
- *  (same honest-facts axis as envFacts.scratchpadDir). */
+/** [816]/[820]① — everything the mode-derived fs-write ask gate needs from the deployment, provided by
+ *  `resolve-spec.ts`. Absent ⇒ no gate is derived (the pre-[816] behavior).
+ *
+ *  WHY the `env` matters: core's `createFsWriteGatePolicy` canonicalizes every target/dir through the given `env`
+ *  (real `exists`/`canonicalPath`/`readLink` fs access — read in dist, fs-write-gate-policy.js), so on a
+ *  HOST-SEMANTICS lane (`REMOTE_EXEC` unset or "host") the env MUST be the fs the hand tools write.
+ *
+ *  #156 — the sandbox lanes (e2b/k8s/ssh/adb/local-docker) now wire a gate TOO, but a different-shaped one: the
+ *  tools run OFF this box and the per-task sandbox env is minted inside core (executionEnvFactory) AFTER spec
+ *  build, so a worker-local env would adjudicate against the WRONG fs (a wrong ALLOW is worse than no gate — that
+ *  is why [816] left those lanes gate-less). The transitional shape instead supplies a `LexicalPathExecutionEnv`
+ *  (`src/boot/lexical-path-env.ts`): NO fs is consulted at all, absolute paths are judged by lexical
+ *  normalization and everything else fails closed to `ask`. Its residual surface (symlink form) and the endgame
+ *  seam (core [2751] read-only env face on HookToolContext) are documented on that module. */
 export interface FsWriteGateWiring {
-    /** The env whose fs the gate canonicalizes against — the worker host env on the host lane. */
+    /** The env the gate canonicalizes against — the worker host env on the host lane, the fs-less
+     *  `LexicalPathExecutionEnv` on the sandbox lanes (#156). */
     env: ExecutionEnv;
-    /** The task's working directory: the factory's `rootPath` (relative-path base) AND the acceptEdits accept domain. */
-    cwd: string;
+    /** The task's working directory: the factory's `rootPath` (relative-path base) AND the acceptEdits accept domain.
+     *  ABSENT on the sandbox lanes (#156): the sandbox cwd is not knowable at spec time and inventing one would mint
+     *  a bogus auto-allow domain. With it absent the gate gets no `rootPath` and no `acceptDirs`, so relative paths
+     *  fail to resolve (⇒ ask) and `acceptEdits` degrades to the `default` arm — the same fail-safe direction as the
+     *  host lane's never-created sentinel dir (resolve-spec 修5). */
+    cwd?: string;
     /** The session scratchpad dir (envFacts.scratchpadDir, [820]③) — writes there are always auto-allowed. */
     scratchpadDir?: string;
     /** [841]① / core 1.294 exemption seam: the session "don't ask again" probe (approvalExemptionStore.has),
-     *  consulted by the gate RIGHT BEFORE it would ask (after the exempt/accept dir layering — dist 亲读:true ⇒
+     *  called by core as `(canonicalToolName, canonicalPath)`. The host arm ignores the second argument (the key
+     *  comes from a real-fs canonicalize and the grant is deliberately name-keyed); the sandbox arm (#156) uses it
+     *  to confine the exemption to POSIX-absolute canonical keys — core's `canonicalizeTarget` short-circuits
+     *  backslash-UNC forms to `ok:true, key=raw` WITHOUT consulting the env, and an unconfined name-keyed grant
+     *  would turn those unresolvable forms into an allow (codex review 2026-08-05).
+     *  The probe is consulted by the gate RIGHT BEFORE it would ask (after the exempt/accept dir layering — dist 亲读:true ⇒
      *  allow with decisionReason "rule", a THROWN probe ⇒ not exempt = fail-closed to ask). Same canonical
      *  toolName key space as the ask-policy layer's exemption probe — ONE grant serves both layers; the gate-level
      *  check is what makes "allow all session" bite SAME-TURN for the parent and inherited child tasks (the ask

package/dist/task-settings.js

@@ -48,6 +48,10 @@ import { parseHooksConfig } from "./hooks/hook-runner.js";
  * would FORCE the manual ask gate onto a caller that explicitly asked for less asking — with the gate live, the old
  * coercion would have been a behavior change for them, incl. a headless-deny regression for bypass callers). An
  * UNKNOWN string still coerces to `default` (fail-safe: the most-asking mode).
+ * #157-②: fresh submits can no longer REACH the unknown-word arm — the HTTP gate 400s a non-five-mode value
+ * (server.ts, sibling of promptProfile) and the wire type is a closed enum. This lenient fold stays for the one
+ * population the gate deliberately does not cover: RESUME replay of a persisted pre-gate body (outputStyle/model
+ * two-layer posture — bricking a resume over a value that was legal at submit time is worse than the quiet fold).
  */
 export function coercePermissionMode(raw) {
     if (raw === "plan" || raw === "acceptEdits" || raw === "default" || raw === "bypassPermissions" || raw === "auto")
@@ -139,7 +143,12 @@ export function parseTaskSettings(raw) {
         deferred.push("env"); // present but malformed/empty → report
     const out = {};
     const perms = s.permissions;
-    if (perms !== null && typeof perms === "object") {
+    // F1(#157 复审留裁裁修):出现但形错(数组/标量)——本层是 RESUME 重放也走的宽容层,不 throw,但必
+    // 留痕 deferred(镜像 env/hooks malformed 姿势;fresh submit 已被 http 门 400 拦,这里护的是存量行)。
+    if (perms !== undefined && perms !== null && (typeof perms !== "object" || Array.isArray(perms))) {
+        deferred.push("permissions");
+    }
+    if (perms !== null && typeof perms === "object" && !Array.isArray(perms)) {
         const p = perms;
         const allow = cleanStringArray(p.allow);
         const deny = cleanStringArray(p.deny);
@@ -386,7 +395,9 @@ export function deriveSettingsPolicy(settings, gate, workflowGate) {
         policies.push(createAskListPolicy(ask));
     // The mode-derived fs-write ask gate (core 1.290 factory — real shape read in dist: {env, rootPath?, acceptDirs?,
     // exemptDirs?, defaultWrite}, gates Write/Edit/NotebookEdit, exempt→accept→default layering, canonicalize inside
-    // the given env, only ever allow/ask). undefined off the host lane / without wiring (see FsWriteGateWiring).
+    // the given env, only ever allow/ask). undefined without wiring (see FsWriteGateWiring). #156: the sandbox lanes
+    // supply wiring too — same factory, a lexical (fs-less) env and no cwd; the shape difference lives entirely in
+    // what `resolve-spec.ts` puts in the wiring, not in a second code path here.
     // ③ (core 1.295): the sensitive-path DENY policy (patterns from the wiring — config SENSITIVE_WRITE_PATTERNS,
     // default = core's RECOMMENDED set) composes into the SAME fold, deny-wins — core semantics deny/"safety", so
     // neither the gate's own allow legs (exemptDirs/acceptDirs/isExempt session exemption) nor a settings allow can
@@ -395,10 +406,13 @@ export function deriveSettingsPolicy(settings, gate, workflowGate) {
     const fsWriteGate = (acceptCwd) => {
         if (!gate)
             return undefined;
+        // #156: `cwd` is optional (absent on the sandbox lanes). Omitting `rootPath` makes core leave a relative
+        // target relative → its lexical env cannot resolve it → ask; omitting `acceptDirs` means acceptEdits mints
+        // no auto-allow domain at all. Both are the intended fail-safe, NOT a degraded copy of the host arm.
         const gatePolicy = createFsWriteGatePolicy({
             env: gate.env,
-            rootPath: gate.cwd,
-            ...(acceptCwd ? { acceptDirs: [gate.cwd] } : {}),
+            ...(gate.cwd !== undefined ? { rootPath: gate.cwd } : {}),
+            ...(acceptCwd && gate.cwd !== undefined ? { acceptDirs: [gate.cwd] } : {}),
             ...(gate.scratchpadDir ? { exemptDirs: [gate.scratchpadDir] } : {}),
             ...(gate.isExempt ? { isExempt: gate.isExempt } : {}), // 1.294 session-exemption probe (see FsWriteGateWiring)
             defaultWrite: "ask",
@@ -409,7 +423,7 @@ export function deriveSettingsPolicy(settings, gate, workflowGate) {
         // 亲读。回归锚保留在 test/task-settings.test.ts(NotebookEdit deny + 双向诱饵),现在锁的是 core 行为经
         // 我方折叠——core 若回退,锚变红。
         return gate.sensitivePatterns && gate.sensitivePatterns.length > 0
-            ? combinePolicies(createSensitivePathPolicy({ env: gate.env, patterns: gate.sensitivePatterns, rootPath: gate.cwd }), gatePolicy)
+            ? combinePolicies(createSensitivePathPolicy({ env: gate.env, patterns: gate.sensitivePatterns, ...(gate.cwd !== undefined ? { rootPath: gate.cwd } : {}) }), gatePolicy)
             : gatePolicy;
     };
     const compose = (...extra) => {