@sema-agent/server 7.80.2 → 7.82.0

package/dist/plugins/approval-ask-store-file.js

@@ -0,0 +1,258 @@
+import { closeSync, copyFileSync, openSync, readSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { AppendLog, atomicWriteFile, ensureDir, readJsonlRecords } from "@sema-agent/core";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
+import { InMemoryApprovalAskStore, encodeDecideUpdatedInput, encodeStoreJsonPayload } from "./approval-ask-store-memory.js";
+export const APPROVAL_ASK_DIR = "approval-asks";
+export const APPROVAL_ASK_JOURNAL_FILE = "asks.jsonl";
+export const ASK_JOURNAL_COMPACT_MIN_RECORDS = 2_000;
+export const ASK_JOURNAL_COMPACT_GROWTH = 2;
+const JOURNAL_OPS = [
+    "ensureAsk",
+    "transitionAsk",
+    "decideAsk",
+    "claimTerminal",
+    "expireAsk",
+    "bindBatch",
+    "abortBatch",
+    "deferReconcile",
+    "resolveProvisional",
+    "deleteByTask",
+];
+const JOURNAL_OP_WORDS = new Set(JOURNAL_OPS);
+export const JOURNAL_OP_TABLE_GATE = true;
+function endsAtRecordBoundary(path) {
+    const size = statSync(path).size;
+    if (size === 0)
+        return true;
+    const fd = openSync(path, "r");
+    try {
+        const buf = Buffer.alloc(1);
+        readSync(fd, buf, 0, 1, size - 1);
+        return buf[0] === 0x0a;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export class FileApprovalAskStore {
+    core;
+    path;
+    tmpDir;
+    log;
+    records = 0;
+    pinnedNow = null;
+    replayRejectedCount = 0;
+    corruptLineCount = 0;
+    corruptQuarantinePath;
+    constructor(root) {
+        const dir = join(root, APPROVAL_ASK_DIR);
+        ensureDir(dir);
+        this.tmpDir = join(dir, ".tmp");
+        ensureDir(this.tmpDir);
+        this.path = join(dir, APPROVAL_ASK_JOURNAL_FILE);
+        this.core = new InMemoryApprovalAskStore({ now: () => this.clockRead() });
+        const tornTail = existsSync(this.path) && !endsAtRecordBoundary(this.path);
+        const records = readJsonlRecords(this.path, (info) => {
+            this.corruptLineCount += 1;
+            recordFailOpen("server.approval-ask-journal.corrupt-record-skipped", `path=${info.path} reason=${info.reason}`);
+        });
+        for (const rec of records)
+            this.replayRecord(rec);
+        this.records = records.length;
+        if (tornTail || this.corruptLineCount > 0) {
+            const quarantine = `${this.path}.corrupt-${Date.now()}`;
+            copyFileSync(this.path, quarantine);
+            this.corruptQuarantinePath = quarantine;
+            console.warn(`FileApprovalAskStore: approval ask journal ${this.path} had ${tornTail ? "a torn tail" : "no torn tail"} and ` +
+                `${this.corruptLineCount} unparseable line(s) — replayed every COMPLETE record, quarantined the original at ${quarantine}, ` +
+                `and rewrote the live journal from the replayed state. A dropped record is a LOST approval-ask transition: inspect the quarantined file.`);
+            this.compact();
+        }
+    }
+    clockRead() {
+        const pinned = this.pinnedNow;
+        if (pinned === null) {
+            throw new Error("FileApprovalAskStore: the in-memory core read its clock OUTSIDE a journalled window — a clock read after the " +
+                "first `await` cannot be replayed byte-identically. Move the read into the method's synchronous prefix " +
+                "(see the clock discipline in approval-ask-store-memory.ts).");
+        }
+        return pinned;
+    }
+    logFor() {
+        return (this.log ??= new AppendLog(this.path));
+    }
+    write(call, run) {
+        const t = Date.now();
+        const record = { v: 1, k: "op", t, ...call };
+        const encoded = encodeStoreJsonPayload(`${call.op} call`, record);
+        this.logFor().append(encoded, true);
+        this.records += 1;
+        this.pinnedNow = t;
+        let out;
+        try {
+            out = run(encoded);
+        }
+        finally {
+            this.pinnedNow = null;
+        }
+        try {
+            this.maybeCompact();
+        }
+        catch (e) {
+            recordFailOpen("server.approval-ask-journal.compaction-failed", `path=${this.path} err=${e instanceof Error ? e.message : String(e)}`);
+        }
+        return out;
+    }
+    maybeCompact() {
+        if (this.records < ASK_JOURNAL_COMPACT_MIN_RECORDS)
+            return;
+        const snapshot = this.core.exportRows();
+        if (this.records < (snapshot.asks.length + snapshot.batches.length) * ASK_JOURNAL_COMPACT_GROWTH)
+            return;
+        this.compact(snapshot);
+    }
+    compact(snapshot = this.core.exportRows()) {
+        const lines = [
+            ...snapshot.batches.map((row) => `${JSON.stringify({ v: 1, k: "batch", row })}\n`),
+            ...snapshot.asks.map((row) => `${JSON.stringify({ v: 1, k: "ask", row })}\n`),
+        ];
+        this.log?.closeForSwap();
+        atomicWriteFile(this.tmpDir, this.path, lines.join(""));
+        this.records = lines.length;
+    }
+    replayRecord(raw) {
+        if (raw === null || typeof raw !== "object") {
+            this.corruptLineCount += 1;
+            recordFailOpen("server.approval-ask-journal.corrupt-record-skipped", `path=${this.path} reason=record is not an object`);
+            return;
+        }
+        const probe = raw;
+        const refuse = (why) => {
+            throw new StoreBootRefusalError(`FileApprovalAskStore: approval ask journal ${this.path} carries a record this build cannot replay — ${why} ` +
+                `(v=${JSON.stringify(probe.v)} k=${JSON.stringify(probe.k)} op=${JSON.stringify(probe.op)}). ` +
+                "Replaying only the records it understands would resurrect decided asks or drop a human's approval. " +
+                "Run the server version that wrote this journal, or move the file aside (every approval on it is abandoned) to continue.");
+        };
+        if (probe.v !== 1)
+            refuse("unknown envelope version");
+        if (probe.k === "ask" || probe.k === "batch") {
+            const row = probe.row;
+            if (row === null || typeof row !== "object")
+                refuse("snapshot record without a row");
+            const key = probe.k === "ask" ? row.askId : row.batchId;
+            if (typeof key !== "string" || key.length === 0)
+                refuse(`snapshot record without a ${probe.k === "ask" ? "askId" : "batchId"}`);
+            if (probe.k === "ask")
+                this.core.importRows({ asks: [row] });
+            else
+                this.core.importRows({ batches: [row] });
+            return;
+        }
+        if (probe.k !== "op")
+            refuse("unknown record kind");
+        if (typeof probe.op !== "string" || !JOURNAL_OP_WORDS.has(probe.op))
+            refuse("verb outside this build's closed set (a DOWNGRADE: a newer server wrote it)");
+        if (typeof probe.t !== "number" || !Number.isFinite(probe.t))
+            refuse("call record without a clock reading");
+        const rec = raw;
+        this.pinnedNow = rec.t;
+        try {
+            void this.replayOp(rec).catch((e) => {
+                this.replayRejectedCount += 1;
+                console.warn(`FileApprovalAskStore: replaying ${rec.op} from ${this.path} was REFUSED by the store's own rules ` +
+                    `(${e instanceof Error ? e.message : String(e)}). The live call was refused the same way and changed nothing, ` +
+                    "so the state is faithful — but a record nobody can apply should not be on disk; inspect the journal.");
+            });
+        }
+        finally {
+            this.pinnedNow = null;
+        }
+    }
+    replayOp(rec) {
+        switch (rec.op) {
+            case "ensureAsk":
+                return this.core.ensureAsk(rec.row);
+            case "transitionAsk":
+                return this.core.transitionAsk(rec.askId, rec.from, rec.to, rec.patch);
+            case "decideAsk":
+                return this.core.decideAsk(rec.askId, rec.batchId, rec.decision);
+            case "claimTerminal":
+                return this.core.claimTerminal(rec.askId, rec.batchId, rec.intent);
+            case "expireAsk":
+                return this.core.expireAsk(rec.askId, rec.batchId);
+            case "bindBatch":
+                return this.core.bindBatch(rec.batchId, rec.askId, rec.gate);
+            case "abortBatch":
+                return this.core.abortBatch(rec.batchId);
+            case "deferReconcile":
+                return this.core.deferReconcile(rec.askId, rec.expectedState, rec.expectedRev, rec.nowMs);
+            case "resolveProvisional":
+                return this.core.resolveProvisional(rec.askId, rec.from, rec.to, rec.patch);
+            case "deleteByTask":
+                return this.core.deleteByTask(rec.taskId);
+            default: {
+                const unreachable = rec;
+                throw new Error(`FileApprovalAskStore: unreachable journal op ${JSON.stringify(unreachable)}`);
+            }
+        }
+    }
+    async ensureAsk(row) {
+        return this.write({ op: "ensureAsk", row }, (c) => this.core.ensureAsk(c.row));
+    }
+    async transitionAsk(askId, from, to, patch) {
+        return this.write({ op: "transitionAsk", askId, from, to, patch }, (c) => this.core.transitionAsk(c.askId, c.from, c.to, c.patch));
+    }
+    async decideAsk(askId, batchId, decision) {
+        const journalled = decision.updatedInput === undefined ? decision : { ...decision, updatedInput: encodeDecideUpdatedInput(decision.updatedInput) };
+        return this.write({ op: "decideAsk", askId, batchId, decision: journalled }, (c) => this.core.decideAsk(c.askId, c.batchId, c.decision));
+    }
+    async claimTerminal(askId, batchId, intent) {
+        return this.write({ op: "claimTerminal", askId, batchId, intent }, (c) => this.core.claimTerminal(c.askId, c.batchId, c.intent));
+    }
+    async expireAsk(askId, batchId) {
+        return this.write({ op: "expireAsk", askId, batchId }, (c) => this.core.expireAsk(c.askId, c.batchId));
+    }
+    async bindBatch(batchId, askId, gate) {
+        return this.write({ op: "bindBatch", batchId, askId, gate }, (c) => this.core.bindBatch(c.batchId, c.askId, c.gate));
+    }
+    async abortBatch(batchId) {
+        return this.write({ op: "abortBatch", batchId }, (c) => this.core.abortBatch(c.batchId));
+    }
+    async deferReconcile(askId, expectedState, expectedRev, nowMs) {
+        return this.write({ op: "deferReconcile", askId, expectedState, expectedRev, nowMs }, (c) => this.core.deferReconcile(c.askId, c.expectedState, c.expectedRev, c.nowMs));
+    }
+    async resolveProvisional(askId, from, to, patch) {
+        return this.write({ op: "resolveProvisional", askId, from, to, patch }, (c) => this.core.resolveProvisional(c.askId, c.from, c.to, c.patch));
+    }
+    async deleteByTask(taskId) {
+        return this.write({ op: "deleteByTask", taskId }, (c) => this.core.deleteByTask(c.taskId));
+    }
+    listByState(state, limit) {
+        return this.core.listByState(state, limit);
+    }
+    listPendingByTask(taskId, signal) {
+        return this.core.listPendingByTask(taskId, signal);
+    }
+    listPendingBySession(sessionId, owner, signal) {
+        return this.core.listPendingBySession(sessionId, owner, signal);
+    }
+    getAsk(askId) {
+        return this.core.getAsk(askId);
+    }
+    getByIdempotencyKey(taskId, key) {
+        return this.core.getByIdempotencyKey(taskId, key);
+    }
+    getBatch(batchId) {
+        return this.core.getBatch(batchId);
+    }
+    replayStats() {
+        return { rejected: this.replayRejectedCount, corruptLines: this.corruptLineCount, records: this.records };
+    }
+    dispose() {
+        this.log?.close();
+        this.log = undefined;
+    }
+}
+//# sourceMappingURL=approval-ask-store-file.js.map

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

@@ -1,9 +1,22 @@
 /**
- * `InMemoryApprovalAskStore` —— [ref] 车1,`ApprovalAskStore` 的语义真源(twin 对拆基准)+ LOCAL
- * 车道占位(File 形不在本车,见设计定稿 §7)。单进程内两个 `Map`,方法体全同步(不含 `await` 中断点)——
+ * `InMemoryApprovalAskStore` —— [ref] 车1,`ApprovalAskStore` 的语义真源(twin 对拆基准)。单进程内两个
+ * `Map`,方法体全同步(不含 `await` 中断点)——
  * Node 单线程下这就是天然原子:`Promise.all` 发起的并发调用不会在方法体内部交错执行,与
  * `approval-ask-store-sql.ts` 的 CAS UPDATE 语义逐字段一致(SQL twin 对拆套件的基准就是这份实现）。
  *
+ * 🔴 **S-384:本类同时是 `FileApprovalAskStore` 的内核**(local 车道的持久形不再是「第二份手抄」——
+ * 它把本类**原样**包起来,每次写前先把**调用本身**落 JSONL、重放时用同一只内核重放同一串调用)。
+ * 为此本类多了三件、且**只**多这三件(全是数据面,零转移判定):
+ *  · {@link InMemoryApprovalAskStore.constructor} 的可注入钟 `now` —— 五个动词(decideAsk / claimTerminal /
+ *    expireAsk / bindBatch / abortBatch)原先直读 `Date.now()`,那是重放路上唯一的不确定源:同一串调用
+ *    重放出来的 `updatedAtMs`/`decidedAtMs` 必须与当初**逐字节**相同,否则「重放等价」是假的。
+ *    ⚠️ **钟只许在方法体的同步前缀里读**(第一个 `await` 之前)—— File 形据此把钟钉在一次调用的同步窗口
+ *    内,窗口外读钟会被它的钟函数**响亮拒**(不是静默回落 `Date.now()`)。今天五个动词全部满足;
+ *    哪天有人把读钟挪到 `await` 之后,File 形的钟当场抛,而不是悄悄写出一条重放不出来的行。
+ *  · {@link InMemoryApprovalAskStore.exportRows} / {@link InMemoryApprovalAskStore.importRows} —— 压实用的
+ *    整本快照口(纯搬行,不经任何谓词)。压实要把「一串调用」折成「一串终局行」,没有这一对就只能在
+ *    File 形里另写一套「哪些行还算数」的判据 —— 那才是第二份手抄。
+ *
  * 行为口径与 `SqlApprovalAskStore` 逐条对齐:
  *  - ensureAsk 幂等 upsert(ask_id 已在 ⇒ 返回既有行,不改写;batch 行若不存在则以 OPEN 补齐）。
  *  - transitionAsk 先过 machine 层 `canAskTransition`(非法转移 throw，不返回 false）。
@@ -13,9 +26,54 @@
  */
 import { type AskState, type BatchState } from "../approval-ask-machine.js";
 import type { AskDecision, AskRow, AskTerminalClaimIntent, AskTerminalClaimOutcome, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, EnsureAskResult, DecideResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
+/**
+ * [ref] 的 `updatedInput` **入店编码**——两 twin 共用的那一只(本函数是唯一真源)。
+ *
+ * 语义:镜像 SQL twin 的「存 JSON 文本再解回来」(`dialectJsonEncoder` → `parseJsonColumn`)。BigInt /
+ * 循环引用 ⇒ `JSON.stringify` 抛(两侧同抛);顶层函数 / `undefined` ⇒ `stringify` 交出 `undefined`
+ * (「编出来什么都不是」)⇒ 本函数**响亮拒**,而不是让它在库里变成 NULL、在内存里变成活函数。
+ *
+ * 🔴 为什么必须是一只**导出**函数而不是 `decideAsk` 里的内联段(S-384):`FileApprovalAskStore` 要在
+ * **落日志之前**把这一步做掉 —— 它的日志本身就是 JSON,而 `JSON.stringify` 对顶层函数是**静默丢键**
+ * 不是抛。内联在 decideAsk 里的话,File 形只能在自己那侧再写一遍同样的判定(第二份手抄),或者
+ * 让「活路径抛 / 重放路径成功 DECIDE」这条真分岔活下来。
+ *
+ * ⚠️ 它与 File 形对**整条调用**做的那次 JSON round-trip 是两件事,别合并:round-trip 保证的是
+ * 「内核看见的 == 重放看见的」(把静默丢键变成两边一致);本函数保证的是「编出来什么都不是 ⇒ 响亮拒」,
+ * 而那条判据只在 `updatedInput` 这一格上成立 —— 它的**缺席**与**值为 null** 在 wire 上是两回事
+ * (`AskRow.updatedInput` 三态),所以「被 round-trip 静默丢成缺席」在这一格上不是无害的归一。
+ */
+export declare function encodeStoreJsonPayload(what: string, value: unknown): unknown;
+/** [ref] `updatedInput` 的入店编码 = 上面那只的一次具名调用(词固定在一处,两 twin 与 File 形账本共用)。 */
+export declare function encodeDecideUpdatedInput(updatedInput: unknown): unknown;
+/** {@link InMemoryApprovalAskStore.exportRows} 的产出 / {@link InMemoryApprovalAskStore.importRows} 的入参
+ *  —— **纯行**,零判定。压实(S-384 File 形)与测试的状态对拆共用。 */
+export interface ApprovalAskRowsSnapshot {
+    asks: readonly AskRow[];
+    batches: readonly BatchRow[];
+}
 export declare class InMemoryApprovalAskStore implements ApprovalAskStore {
     private readonly asks;
     private readonly batches;
+    /** 店钟(S-384)。缺省 = 本进程墙钟,与本类落地以来逐字同值;File 形注入一只**钉住的**钟,让
+     *  「同一串调用重放出同一份状态」成立。读钟纪律见类顶注(只许在同步前缀里读)。 */
+    private readonly now;
+    constructor(opts?: {
+        now?: () => number;
+    });
+    /**
+     * S-384:整本行快照(压实用)。**深拷到行级**(与每个读口交出 `{ ...row }` 同一条纪律:交出去的行
+     * 不再是店内那一份,调用方改它碰不到店)。行内的 `cardJson`/`updatedInput`/`decisionActor` 仍是引用 ——
+     * 与 `getAsk`/`listByState` 逐字同宽,不在这一口上单独加深拷(那会让快照口与读口对同一份 blob 给出
+     * 两种可变性)。
+     */
+    exportRows(): ApprovalAskRowsSnapshot;
+    /** S-384:把快照里的行**原样**装回两张 Map(同键覆盖)。零谓词、零状态机 —— 它不是一条转移,是重放
+     *  的起手状态。压实产物与本口是一对:压实写出 {@link exportRows} 的行,启动时由本口装回。 */
+    importRows(snapshot: {
+        asks?: readonly AskRow[];
+        batches?: readonly BatchRow[];
+    }): void;
     ensureAsk(row: NewAskRow): Promise<EnsureAskResult>;
     transitionAsk(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     decideAsk(askId: string, batchId: string, decision: DecideAskInput): Promise<DecideResult>;

package/dist/plugins/approval-ask-store-memory.js

@@ -20,9 +20,32 @@ function applyPatch(row, patch) {
     if (patch.provisional !== undefined)
         row.provisional = patch.provisional;
 }
+export function encodeStoreJsonPayload(what, value) {
+    const text = JSON.stringify(value);
+    if (text === undefined)
+        throw new Error(`approval-ask-store: ${what} is not JSON-encodable (encodes to nothing) — the SQL twin cannot hold it either`);
+    const decoded = JSON.parse(text);
+    return decoded;
+}
+export function encodeDecideUpdatedInput(updatedInput) {
+    return encodeStoreJsonPayload("updatedInput", updatedInput);
+}
 export class InMemoryApprovalAskStore {
     asks = new Map();
     batches = new Map();
+    now;
+    constructor(opts) {
+        this.now = opts?.now ?? Date.now;
+    }
+    exportRows() {
+        return { asks: [...this.asks.values()].map((r) => ({ ...r })), batches: [...this.batches.values()].map((b) => ({ ...b })) };
+    }
+    importRows(snapshot) {
+        for (const r of snapshot.asks ?? [])
+            this.asks.set(r.askId, { ...r });
+        for (const b of snapshot.batches ?? [])
+            this.batches.set(b.batchId, { ...b });
+    }
     async ensureAsk(row) {
         assertIntegralEpochMs("expiresAtMs", row.expiresAtMs);
         assertIntegralEpochMs("createdAtMs", row.createdAtMs);
@@ -90,7 +113,7 @@ export class InMemoryApprovalAskStore {
     async decideAsk(askId, batchId, decision) {
         if (decision.idempotencyKey != null)
             assertIdempotencyKeyShape(decision.idempotencyKey);
-        const now = Date.now();
+        const now = this.now();
         const batch = this.batches.get(batchId);
         if (!batch || batch.state !== "OPEN") {
             const row = this.asks.get(askId);
@@ -108,13 +131,8 @@ export class InMemoryApprovalAskStore {
             }
         }
         let encodedUpdatedInput;
-        if (decision.updatedInput !== undefined) {
-            const text = JSON.stringify(decision.updatedInput);
-            if (text === undefined)
-                throw new Error("approval-ask-store(memory): updatedInput is not JSON-encodable (encodes to nothing) — the SQL twin cannot hold it either");
-            const decoded = JSON.parse(text);
-            encodedUpdatedInput = decoded;
-        }
+        if (decision.updatedInput !== undefined)
+            encodedUpdatedInput = encodeDecideUpdatedInput(decision.updatedInput);
         batch.rev += 1;
         batch.updatedAtMs = now;
         ask.state = "DECIDED";
@@ -141,7 +159,7 @@ export class InMemoryApprovalAskStore {
             const scoped = this.asks.get(askId);
             if (scoped !== undefined && scoped.batchId !== batchId)
                 return { claimed: false, current: { state: "absent" } };
-            const won = await this.transitionAsk(askId, "STREAM_PENDING", "VOID", { updatedAtMs: Date.now() });
+            const won = await this.transitionAsk(askId, "STREAM_PENDING", "VOID", { updatedAtMs: this.now() });
             if (won)
                 return { claimed: true, voidedSiblings: [] };
         }
@@ -149,7 +167,7 @@ export class InMemoryApprovalAskStore {
         return { claimed: false, current: projectAskTerminalClaimTruth(cur !== undefined && cur.batchId === batchId ? { ...cur } : null) };
     }
     async expireAsk(askId, batchId) {
-        const now = Date.now();
+        const now = this.now();
         const batch = this.batches.get(batchId);
         if (!batch)
             return { won: false, voidedSiblings: [] };
@@ -176,7 +194,7 @@ export class InMemoryApprovalAskStore {
         return { won: true, voidedSiblings: voided };
     }
     async bindBatch(batchId, askId, gate) {
-        const now = Date.now();
+        const now = this.now();
         const batch = this.batches.get(batchId);
         if (!batch)
             return { ok: false, batchState: "MISSING" };
@@ -216,7 +234,7 @@ export class InMemoryApprovalAskStore {
         return true;
     }
     async abortBatch(batchId) {
-        const now = Date.now();
+        const now = this.now();
         const batch = this.batches.get(batchId);
         if (!batch || (batch.state !== "OPEN" && batch.state !== "ROUTING_UNBOUND"))
             return [];

package/dist/plugins/checkpoint-store-sql.d.ts

@@ -369,6 +369,28 @@ export declare const DECIDED_REPLAY_SCAN_CAP = 8;
  *     (plan_review / dry_run_review)的判词,那些门的决议入口不是本腿,回放它们等于跨门作答。
  */
 export declare function approvalDecisionOfWinner(winner: ResolvedOutcome | undefined, boundCallId: string): "approve" | "deny" | null;
+/**
+ * checkpoint blob → `pendingAction.toolCallId`。
+ *
+ * 🔴 三态、**不是**两态(真双库实跑抓到的缺陷,2026-08-06):「读不出」与「读出来了、但这条 park 本来就
+ * 没有 toolCallId」是两件事,压成同一个 `undefined` 会把每一条 `plan_review`/`task_done`/`resource_limit`
+ * 腿(core 的 `PendingAction` 联合里三个成员结构上就没有 toolCallId)都误报成坏行。前者应标 `unparseable`
+ * 交给收敛器当「不确定」,后者是**确定的不匹配**——干净地不是候选。
+ *  - `{ readable: false }`        —— JSON 坏 / 形状根本不是对象:真的读不出。
+ *  - `{ readable: true, toolCallId: null }` —— 读出来了,这条 park 无工具动作:确定不匹配。
+ *  - `{ readable: true, toolCallId: "…" }`  —— 读出来了,拿去比。
+ *
+ * 逐层 `typeof` 收窄,不做裸 `as` 断言:blob 是持久层读回来的 `unknown`,是信任边界(宪法 [ref])。
+ */
+export declare function pendingActionToolCallId(blob: unknown): {
+    readable: true;
+    toolCallId: string | null;
+    boundInputHash: string | null;
+    kind: string | null;
+    sourceTaskId: string | null;
+} | {
+    readable: false;
+};
 /** `pending_steer_queue` 列承载的 CheckpointState 字段(= core `appendPendingSteer` / `readPendingSteerQueue`
  *  的入参形)。列是**唯一**权威(suspend 时写的 blob 从不带它)。 */
 type SteerColumnState = Pick<CheckpointState, "pendingSteerQueue">;

package/dist/plugins/checkpoint-store-sql.js

@@ -166,7 +166,7 @@ export function approvalDecisionOfWinner(winner, boundCallId) {
         }
     }
 }
-function pendingActionToolCallId(blob) {
+export function pendingActionToolCallId(blob) {
     let parsed;
     try {
         parsed = typeof blob === "string" ? JSON.parse(blob) : blob;

package/dist/plugins/file-run-store.d.ts

@@ -1,6 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
-import type { RunRecord, SessionSummary, RunEvent, PersistedTaskResult, LatestRunRef } from "./store-contracts.js";
+import { StoreBootRefusalError, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 /**
@@ -13,8 +13,12 @@ import type { LedgerEventType } from "../trace/ledger-events.js";
  * catch 吞掉:operator 明确要的 **fail-closed 反而变成 fail-open**,而且丢的正是持久 run 账本(这根旋钮
  * 存在的全部理由)。判据锚在**类型**上,不在文案上 —— 文案会改,类型不会(同文件族先例:`AdoptionError`
  * 在同一个降级臂里也是按类型无条件重抛)。
+ *
+ * 🔴 **S-384:本类自此 `extends StoreBootRefusalError`**(族规基类,见那条顶注)。上面这段论证对
+ * **每一只**会在 `LocalBackend` 构造器里拒启的 File 店逐字成立,而逐个 `if instanceof` 手工登记会漏 ——
+ * S-384 的 ask 账本拒启就漏过一次。继承 = 自动落在正确的一侧。
  */
-export declare class RunStoreStrictHydrateError extends Error {
+export declare class RunStoreStrictHydrateError extends StoreBootRefusalError {
     readonly name = "RunStoreStrictHydrateError";
 }
 export declare class FileRunStore {

package/dist/plugins/file-run-store.js

@@ -6,6 +6,7 @@ import { randomBytes } from "node:crypto";
 import { terminalProjection } from "@sema-agent/core";
 import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprint, readJsonlRecords, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 import { notifyRunTerminal } from "../observability/run-terminal-log.js";
 import { migrateRetiredAskOrigin } from "./one-time-migrations.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
@@ -21,7 +22,7 @@ function readClaimRecord(recs, sessionId) {
     return c;
 }
 const PARK_ORPHAN_SETTLE_MS = 30_000;
-export class RunStoreStrictHydrateError extends Error {
+export class RunStoreStrictHydrateError extends StoreBootRefusalError {
     name = "RunStoreStrictHydrateError";
 }
 export class FileRunStore {

package/dist/plugins/local-checkpoint-store.d.ts

@@ -1,5 +1,5 @@
 import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ExecutionOutcomeRecordWord, type GateOutcome, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
-import { type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-sql.js";
+import { type CheckpointAskCandidate, type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-sql.js";
 export interface LocalCheckpointStoreOptions {
     /** taskId join for the pending card (the local FileRunStore's `getActiveTaskId`). Absent ⇒ `taskId: null`. */
     getActiveTaskId?: (sessionId: string) => Promise<string | undefined>;
@@ -130,6 +130,34 @@ export declare class LocalCheckpointStore {
      *    投了就是「SQL 车道有、local 车道没有」的键集分岔。
      */
     findDecidedApprovalsForBinding(sessionId: string, boundCallId: string): Promise<DecidedApprovalRecord[]>;
+    /**
+     * S-384 —— 对账收敛器**判据 1**(身份三元组 ∧ hash 双等 ⇒ `bindBatch`)的读口在 local 车道的形。
+     * 语义、判别纪律、`unparseable` 的含义,唯一属主 = SQL 孪生 `findCheckpointCandidatesForAsk` 的顶注与
+     * `CheckpointAskCandidate` 的字段注;这里只记**本形自己的三处差别**。
+     *
+     * 🔴 **为什么必须有这一口**(不是锦上添花):S-384 让 local 车道有了持久 ask 账,于是收敛器在这条车道上
+     * 第一次真的有行可扫。缺这一口 ⇒ 判据 1 结构性不命中 ⇒ **窗到期 park 的 ask 行永远停在 `PARKING`**,
+     * 而那个态在 wire 上是有后果的:`POST /v1/tool-approvals/:id/respond` 的 `PARKING` 臂答的是
+     * `202 parking_in_progress + retryAfterMs`(它的前提是「`bindBatch` 毫秒级就到」),在一台绑不了的机器上
+     * 那句「再试一次」**永远不会兑现**;run 跑到终局后判据 2 还会把它收成
+     * `DENIED(routing_failure_fail_closed)` ⇒ 迟到答拿到的判别位是 `denied` —— 对一条**人真的批准过**的 ask
+     * 撒谎。两条都是相对 7.80.2 的回归,根因同一个:**判据 1 的读口只有 SQL 孪生有**。修在源头 = 把这一口
+     * 补齐,而不是给下游那两处各加一条「这台机器绑不了」的特判。
+     *
+     * 形差(逐条,如实):
+     *  · **枚举面**走 [ref] 的 `sessionTokens` 索引(与 `hasExpiredBySession` / `findDecidedApprovalsForBinding`
+     *    同一条路),所以它那条**存量限制**在这里逐字同样成立:索引建立之前 put 的老行对本口不可见 ⇒ 判据 1
+     *    不命中 ⇒ 行落判据 ②③④⑤(保守方向,与读口缺席时的既有降级同向)。
+     *  · **没有列,所以没有列/blob 一致性门**:SQL 孪生的两道矛盾门(`tool_call_id` 与 `bound_input_hash`
+     *    的列 vs blob)在本形结构上不存在 —— 本形只有 blob 这一个真源,谈不上两份互相矛盾。判别力因此**不弱**:
+     *    那两道门防的是「外部改库 / schema 偏斜让列与 blob 分家」,而本形没有可分家的第二份。
+     *  · **没有行级版本闸**:本类 `peekScopeByToken` 顶注已亲核过这条事实 —— 本形的 `get()` 没有行级版本闸,
+     *    唯一的读不动形是账本重放级(整店同时读不动)。所以 SQL 孪生那道 `version > MAX_SUPPORTED` 的
+     *    `unparseable` 臂在这里没有对应物;本口的 `unparseable` 只由**窄读器**判(blob 形不合)。
+     *  · **窄读器是同一只** `pendingActionToolCallId`(与 SQL 孪生共用,零第二份手抄):身份三元组的第一维
+     *    `sourceTaskId`、`boundInputHash`、以及「读不出 vs 确定不匹配」的三态,全部由它一家判。
+     */
+    findCheckpointCandidatesForAsk(scope: string, sessionId: string, toolCallId: string, sinceMs: number): Promise<CheckpointAskCandidate[]>;
     /**
      * [ref]:按 token 的 scope 读 —— 与 SQL 孪生**同一条契约**(`undefined` 无行 / `null` 匿名 / 属主串),
      * 语义与存在理由的唯一属主 = SQL 侧 `peekScopeByToken` 顶注。

package/dist/plugins/local-checkpoint-store.js

@@ -4,7 +4,7 @@ import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync, mkdirSyn
 import { join } from "node:path";
 import { isApprovalGateKind } from "../tool-approval.js";
 import { FileCheckpointStore, atomicWriteFile, executionVerdict, sanitizePathComponent, } from "@sema-agent/core";
-import { approvalDecisionOfWinner, approvalPayloadFingerprint, boundedRuleOffers, boundedToolInput, pendingRowPrecedes, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-sql.js";
+import { approvalDecisionOfWinner, approvalPayloadFingerprint, boundedRuleOffers, boundedToolInput, pendingActionToolCallId, pendingRowPrecedes, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-sql.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
 function terminalAtOf(cp) {
     return Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS);
@@ -236,6 +236,29 @@ export class LocalCheckpointStore {
         }
         return out;
     }
+    async findCheckpointCandidatesForAsk(scope, sessionId, toolCallId, sinceMs) {
+        const tokens = this.sessionTokens.get(sessionId);
+        if (!tokens)
+            return [];
+        const out = [];
+        for (const t of [...tokens]) {
+            const cp = await this.inner.get(t);
+            if (!cp)
+                continue;
+            if (cp.scope !== scope || cp.sessionId !== sessionId || cp.createdAt < sinceMs)
+                continue;
+            const base = { token: t, status: cp.status, createdAtMs: cp.createdAt };
+            const derived = pendingActionToolCallId(cp);
+            if (!derived.readable) {
+                out.push({ ...base, sourceTaskId: null, boundCallId: null, boundInputHash: null, unparseable: true });
+                continue;
+            }
+            if (derived.toolCallId !== toolCallId)
+                continue;
+            out.push({ ...base, sourceTaskId: derived.sourceTaskId, boundCallId: derived.toolCallId, boundInputHash: derived.boundInputHash });
+        }
+        return out.sort((a, b) => a.createdAtMs - b.createdAtMs || (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));
+    }
     async peekScopeByToken(token) {
         return (await this.inner.get(token))?.scope;
     }

package/dist/plugins/posix-shell-fs.d.ts

@@ -1,4 +1,4 @@
-import { FileError, type ExecutionError, type RemoteExecutionError, type FileInfo, type Result } from "@sema-agent/core";
+import { FileError, type ExecutionError, type RemoteExecutionError, type FileInfo, type Result, type SymlinkChain } from "@sema-agent/core";
 export interface ShellRunResult {
     stdout: string;
     stderr: string;
@@ -14,6 +14,7 @@ export interface PosixShellFsDeps {
 }
 export interface PosixShellFs {
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     statFileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;

package/dist/plugins/posix-shell-fs.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { FileError, } from "@sema-agent/core";
-import { shellQuote, kindFromMode } from "./remote-shell.js";
+import { runSymlinkChain, shellQuote, kindFromMode } from "./remote-shell.js";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 const ok = (value) => ({ ok: true, value });
 export function createPosixShellFs(deps) {
@@ -22,6 +22,9 @@ export function createPosixShellFs(deps) {
                 return { ok: false, error: classifyFsStderr(r.value.stderr, abs, "not_found") };
             return ok(r.value.stdout.trim());
         },
+        async canonicalChain(p, abortSignal) {
+            return runSymlinkChain(resolve(p), (cmd) => run(cmd, abortSignal));
+        },
         async canonicalPath(p, abortSignal) {
             const abs = resolve(p);
             const r = await run(`realpath -- ${shellQuote(abs)}`, abortSignal);

package/dist/plugins/remote-env-adb.d.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export interface AdbEnvConfig {
     /** Device serial or `host:port` (TCP). `host:port` triggers `adb connect` on connect()/reconnect(). */
@@ -139,6 +139,10 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-362 / core 7.21.0 [ref] —— **实现**(表态:本腿实现 `canonicalChain`)。一次往返里的一个 `readlink`
+     *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
+     *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
+    canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {