@sema-agent/server 7.112.0 → 7.114.0

package/dist/unattended-permission-mode.d.ts

@@ -6,7 +6,9 @@
  * 修复腿(集成沙箱修复 `mkRepair`、模块门修复 `leader.ts` `runModuleGate`、单代理修复环 `repair-wire.ts` `attachRepairLoopDeps`)、run-local
  * (`src/run-local.ts`,一次性 CLI)与这些腿的 durable 续跑重挂(`CheckpointCtx.unattendedLeg`)—— 经 {@link withUnattendedLeg} 这**一只**
  * 合并口铸两键:`permissionMode: "default"`(显式:续跑时盖过 checkpoint 记下的旧模式)与 `onAsk` = {@link createUnattendedOnAsk}。
- * 那只 onAsk 读 `AskRequest.classes` **整体**:集非空且每一类都在 {@link UNATTENDED_ANSWERED_CLASSES}(= `{ordinary}`,常量,不是旋钮)⇒ 答 yes;
+ * 那只 onAsk 读 `AskRequest.classes` **整体**:集非空且每一类都在 {@link UNATTENDED_ANSWERED_CLASSES}(= `{ordinary}`,常量,不是旋钮)⇒ 答 yes
+ * —— **以策略的名义**(S-953 / core 7.39.0 #1265:`{allow:true, settledBy:"policy", approver:"unattended_class_answer"}` ⇒ core 结算 `policy_allowed` /
+ * `who.party:"policy"`;修前是裸 `true`,core 把机器的放行记成**人**批 `human_allowed` / `person`);
  * 否则不答 —— 本腿**有席**(run-local 的 `createLocalApprover`:有 TTY 问人、无 TTY 当场拒;续跑腿的协调器席)⇒ 交给席;**无席** ⇒ 答
  * `"unavailable"` = 交回 core 的缺席路(本腿武装了 durable park ⇒ park,等人经 `/decide` 答;否则 headless 拒 —— fail-closed)。
  *
@@ -47,12 +49,17 @@ import type { AskClass, AskRequest, OnAsk, TaskSpec } from "@sema-agent/core";
  * 不变量(测试钉):答集 ⊆ core `RELEASABLE_ASK_CLASSES`,且与带 `requiresRealApproval` 的类(core `RRA_EXPLAINERS` ∪ `policy_rra`)不交;`mode` 不在其中。
  */
 export declare const UNATTENDED_ANSWERED_CLASSES: ReadonlySet<AskClass>;
+/**
+ * S-953(core 7.39.0 #1265):按类作答层这只席的**名字** —— 本仓自己的闭词(core 只把它转录到结算记录的 `who.approver`,不认证、不回读;
+ * `AskOutcome.approver` 契约逐字「a closed word the host owns, never a person」)。审计读者按它认出「这一次放行是无人值守腿按类答的」。
+ */
+export declare const UNATTENDED_POLICY_APPROVER = "unattended_class_answer";
 /** onAsk 的函数臂(`"allow"` / `"deny"` 两个字面臂是姿态设置,不是席)—— 本腿的活审批席与本层自己都是这一形。 */
 export type UnattendedSeat = Extract<OnAsk, (req: AskRequest, signal?: AbortSignal) => unknown>;
 /** 这一问是不是机器答得了的:读 `classes` **整体** —— 在场、非空、且每一类都在答集;缺席 / 空 / 任一类在答集外 ⇒ 否。 */
 export declare function unattendedAnswers(req: Pick<AskRequest, "classes">): boolean;
 /**
- * 按类作答的 onAsk(活对象 ⇒ `create*`)。答得了 ⇒ `true`(这一次调用的答);答不了 ⇒ 有席交席(席的答原样返回,席自己的
+ * 按类作答的 onAsk(活对象 ⇒ `create*`)。答得了 ⇒ 策略的 yes(这一次调用的答,记在策略名下 —— S-953);答不了 ⇒ 有席交席(席的答原样返回,席自己的
  * fail-closed 语义不动),无席 ⇒ `"unavailable"`(core G1:这一问此刻没有人够得着 ⇒ 改道 durable park;本腿没武装 park ⇒ headless 拒)。
  * 不答的臂**从不**自己拒成 `false`:那会把「交给 park 的人」折成「机器拒了」,durable 审批块的 leader worker 就再也 park 不下来。
  */

package/dist/unattended-permission-mode.js

@@ -1,10 +1,14 @@
 export const UNATTENDED_ANSWERED_CLASSES = new Set(["ordinary"]);
+export const UNATTENDED_POLICY_APPROVER = "unattended_class_answer";
+function unattendedPolicyYes() {
+    return { allow: true, settledBy: "policy", approver: UNATTENDED_POLICY_APPROVER };
+}
 export function unattendedAnswers(req) {
     const classes = req.classes;
     return classes !== undefined && classes.length > 0 && classes.every((c) => UNATTENDED_ANSWERED_CLASSES.has(c));
 }
 export function createUnattendedOnAsk(seat) {
-    return (req, signal) => (unattendedAnswers(req) ? true : seat !== undefined ? seat(req, signal) : "unavailable");
+    return (req, signal) => (unattendedAnswers(req) ? unattendedPolicyYes() : seat !== undefined ? seat(req, signal) : "unavailable");
 }
 export function withUnattendedLeg(spec, seat) {
     return { ...spec, permissionMode: "default", onAsk: createUnattendedOnAsk(seat) };

package/dist/user-input-ledger.d.ts

@@ -27,10 +27,14 @@
  *  · `accepted`  —— 受理点(`routes/runs.ts` 的 live 腿,**调 `TaskStream.steer` 之前**、回 200 之前)写;写不进 ⇒ 503
  *                   `steering.ledger_unavailable`,引擎一个字节都没收到(fail-closed:没账的 200 是空头承诺)。身份 = `acceptId`
  *                   (每次受理一枚;同 Idempotency-Key 的重放共享 `messageId`,但各是一次受理)。`writer` = 受理进程的 `instanceId`。
- *  · `settled`   —— 本进程对这次受理的守护**正常结束**:`leg_end`(承载它的腿在本进程收场 —— done / suspended / needs_review / failed
+ *  · `settled`   —— 本进程对这次受理的守护**正常结束**:`consumed`(S-968 / core 7.39.0 #1273:引擎在承载它的腿上铸了
+ *                   `human_input{delivery:"applied"}`、`inputId` = 本受理的 `messageId` —— 引擎确认把它消费进了转录;腿的事件环把每一帧交
+ *                   {@link UserInputLedger.observeLegEvent},认哪一帧只在本文件判;且引擎收下了**这次受理的调用** —— 路由报 {@link UserInputLedger.confirm},
+ *                   [ref] 7.113.0 opus 腿 L4:同 key 异正文的那次受理会被引擎拒,不能凭同名消费证据先结清)、`leg_end`(承载它的腿在本进程收场 —— done / suspended / needs_review / failed
  *                   一律,未消费的那一半 core 已用 `leg_end` 自己告知,本仓不重算「消费了没有」)或 `not_applied`(`TaskStream.steer`
- *                   抛了,这次受理没有变成 200;路由随即落这一行)。⚠️ 子代腿的 `leg_end` 由 core 铸在**子代自己的**会话上(`taskId` / `sessionId` /
- *                   `runId` 全是子代的),本服务没有那只会话的口 ⇒ 今天到不了人(S-966 core 请托;🚧 钉在 `test/engine-notice-wire.test.ts`)。
+ *                   抛了,这次受理没有变成 200;路由随即落这一行)。子代腿的 `leg_end`:core 铸在子代自己的会话上,core 7.39.0 #1279(S-980)起同一次收场
+ *                   **再铸一条到父腿**(`detail.sessionId` = 父会话、`taskId` = 父 run、带 `childSessionId`)⇒ 经分流器到人;本账对子代受理落的
+ *                   `settled{leg_end}`(行记父 run,S-966)与那条父口帧说的是同一件事(钉在 `test/engine-notice-wire.test.ts` S-980 两格)。
  *  · `converged` —— 收敛器判「受理它的进程已经不在、而它从没 settle」⇒ `cause:"crashed"`(core 闭集里服务层那一臂)。
  *  · `announced` —— 通告**落进新 run 的事件账之后**写(`taskId` = 告知它的那条**新** run;`EngineNoticeRouter.routeConfirmed` 等口的落账结果,
  *                   codex r1-F2):落账失败 ⇒ 不写,下一条 run 再说;重启再重启不重复。唯一的重复形 = 帧已落账而这一行没写成(写失败 / 进程死在两步之间)
@@ -78,7 +82,7 @@
  * 不开旋钮(没有「关掉告知」的正当需求)· 不改 steer 的 200 体(回执仍是「已交付」,账本是它的影子)· 不重放丢失的输入(core 明写
  * NOT redelivered;本账只告知,不替人决定重发)· 不存输入正文(行里只有身份与时刻)。
  */
-import { type EngineNoticeCode, type UserSteerUndrainedCause } from "@sema-agent/core";
+import { type EngineNoticeCode, type TaskEvent, type UserSteerUndrainedCause } from "@sema-agent/core";
 import { type RunRecord } from "./plugins/store-contracts.js";
 import { type EngineNoticeRouter } from "./trace/engine-notice-wire.js";
 /** local 数据根下的子目录(File 孪生;与 `approval-ask-audit/` 同层同形)。 */
@@ -90,10 +94,12 @@ export declare const USER_INPUT_KIND_WORDS: {
     readonly steer: true;
 };
 /** `settled` 的两种收场(闭集,见顶注)。 */
-export type SettleHow = "leg_end" | "not_applied";
+export type SettleHow = "leg_end" | "not_applied" | "consumed";
+/** 读盘词表(File 孪生的折叠守卫 / SQL 孪生的 `settle_how` 列读腿同读这一张;`consumed` 自 7.113.0 起,≤7.112.x 的读腿不认它 —— 回滚须知在 MIGRATION)。 */
 export declare const SETTLE_HOW_WORDS: {
     readonly leg_end: true;
     readonly not_applied: true;
+    readonly consumed: true;
 };
 /** 本服务铸的那一臂(core 删掉这个词 ⇒ `Extract` 得 `never` ⇒ 下面的常量编译红)。 */
 export type CrashedCause = Extract<UserSteerUndrainedCause, "crashed">;
@@ -293,8 +299,21 @@ export interface UserInputLedger {
     }): Promise<UserInputAcceptReceipt>;
     /** 引擎没收下(`TaskStream.steer` 抛)⇒ 落 `settled{not_applied}`。不抛(失败留痕,受理仍挂在腿上,腿收场时照常 settle)。 */
     withdraw(receipt: UserInputAcceptReceipt): Promise<void>;
+    /**
+     * 引擎收下了这次受理的那一次调用(`TaskStream.steer` / 子代句柄 `steer` resolve)—— {@link withdraw} 的对偶,路由对每次受理恰报其一(经 `routes/runs.ts`
+     * 的 `relayAcceptedInput`)。收下之后这次受理才可被消费证据结清([ref] 7.113.0 opus 腿 L4,见 {@link observeLegEvent});消费证据此刻已在这条腿上
+     * (消费帧先于本调用到达 / 同 Idempotency-Key 的重放在消费之后才来)⇒ 当场落 `settled{consumed}`。不抛(结清写失败留在腿上,收场照常 `leg_end`)。
+     */
+    confirm(receipt: UserInputAcceptReceipt): Promise<void>;
     /** 腿在本进程收场 ⇒ 这条腿上的每一次受理落 `settled{leg_end}`。不抛。 */
     settleLeg(leg: object): Promise<void>;
+    /**
+     * S-968(core 7.39.0 #1273):腿的事件环把**每一帧**引擎事件交进来(三条腿同一只口;不认的帧零成本返回)。唯一认的一形 =
+     * `human_input{delivery:"applied"}`:引擎确认把那条输入消费进了转录 ⇒ 这条腿上 `messageId` = 帧 `inputId`、**且引擎已收下其调用**({@link confirm})的受理
+     * (同 Idempotency-Key 的幂等重放一并)落 `settled{consumed}`,离开 open 集 —— 之后写者死也不再按崩溃告知。结清写失败 ⇒ 留在腿上(收场照常落 `leg_end`),不抛。
+     * 引擎还没判的受理不结清:messageId 只由 key 派生、账本看不见正文,同 key 异正文的那一次会被引擎拒(`steering.duplicate_input_id`)、走 {@link withdraw}。
+     */
+    observeLegEvent(leg: object, ev: TaskEvent): Promise<void>;
     /** 收敛扫描(boot 一次 + 每个维护 tick;判据见顶注)。不抛;返回本次收敛条数。 */
     converge(): Promise<number>;
     /** 新 run 首拍:把本会话已收敛、未告知的受理按旧 run 分组铸通告、投出后落 `announced`。不抛。 */

package/dist/user-input-ledger.js

@@ -4,7 +4,7 @@ import { isHolderDeathVerdict } from "./plugins/store-contracts.js";
 import { defaultEngineNoticeRouter } from "./trace/engine-notice-wire.js";
 export const USER_INPUT_LEDGER_DIR = "user-input-ledger";
 export const USER_INPUT_KIND_WORDS = { steer: true };
-export const SETTLE_HOW_WORDS = { leg_end: true, not_applied: true };
+export const SETTLE_HOW_WORDS = { leg_end: true, not_applied: true, consumed: true };
 const UNDRAINED_CAUSE_MINTER = { leg_end: "engine", crashed: "server" };
 export const CRASHED_CAUSE = "crashed";
 export function isServingLayerUndrainedCause(v) {
@@ -128,7 +128,7 @@ const USER_STEER_UNDRAINED = "task.user_steer_undrained";
 export function buildCrashedSteerNotice(input) {
     return {
         code: USER_STEER_UNDRAINED,
-        message: `Check the earlier run's transcript and results before re-sending any of these steers to a live run. The server accepted ${input.steer} user steer(s) for run ${input.taskId} (each answered 200 applied or 202 queued-immediate), but the process running that run ended before the run settled; whether the run consumed them is not known. They are NOT redelivered.`,
+        message: `Check the earlier run's transcript and results before re-sending any of these steers to a live run. The server accepted ${input.steer} user steer(s) for run ${input.taskId} (each answered 200 applied or 202 queued-immediate), but the process running that run ended before the engine confirmed consuming them. They are NOT redelivered.`,
         detail: { steer: input.steer, cause: CRASHED_CAUSE, taskId: input.taskId, sessionId: input.sessionId },
         sessionId: input.sessionId,
     };
@@ -157,13 +157,25 @@ export function createUserInputLedger(opts) {
     const { store, writer, evidence } = opts;
     const now = opts.now ?? Date.now;
     const legs = new WeakMap();
+    const consumedOnLeg = new WeakMap();
+    const settleConsumed = async (leg, acceptId) => {
+        try {
+            await store.settle(acceptId, "consumed", now());
+            legs.get(leg)?.delete(acceptId);
+            liveHere.delete(acceptId);
+        }
+        catch (e) {
+            recordFailOpen("server.user-input-ledger.append-failed", `op=consumed ${errText(e)}`);
+        }
+    };
     const liveHere = new Set();
-    const track = (leg, acceptId) => {
-        const set = legs.get(leg);
-        if (set)
-            set.add(acceptId);
+    const track = (leg, acceptId, messageId) => {
+        const entry = { messageId, taken: false };
+        const onLeg = legs.get(leg);
+        if (onLeg)
+            onLeg.set(acceptId, entry);
         else
-            legs.set(leg, new Set([acceptId]));
+            legs.set(leg, new Map([[acceptId, entry]]));
     };
     const pageSize = opts.scanBudget?.pageSize ?? USER_INPUT_OPEN_SCAN_MAX;
     const maxPages = opts.scanBudget?.maxPages ?? USER_INPUT_OPEN_SCAN_PAGES;
@@ -239,9 +251,17 @@ export function createUserInputLedger(opts) {
                 liveHere.delete(acceptId);
                 throw e;
             }
-            track(input.leg, acceptId);
+            track(input.leg, acceptId, input.messageId);
             return { acceptId, leg: input.leg };
         },
+        async confirm(receipt) {
+            const entry = legs.get(receipt.leg)?.get(receipt.acceptId);
+            if (entry === undefined)
+                return;
+            entry.taken = true;
+            if (consumedOnLeg.get(receipt.leg)?.has(entry.messageId) === true)
+                await settleConsumed(receipt.leg, receipt.acceptId);
+        },
         async withdraw(receipt) {
             legs.get(receipt.leg)?.delete(receipt.acceptId);
             try {
@@ -255,11 +275,11 @@ export function createUserInputLedger(opts) {
             }
         },
         async settleLeg(leg) {
-            const ids = legs.get(leg);
-            if (!ids)
+            const onLeg = legs.get(leg);
+            if (!onLeg)
                 return;
             legs.delete(leg);
-            for (const acceptId of ids) {
+            for (const acceptId of onLeg.keys()) {
                 try {
                     await store.settle(acceptId, "leg_end", now());
                 }
@@ -271,6 +291,21 @@ export function createUserInputLedger(opts) {
                 }
             }
         },
+        async observeLegEvent(leg, ev) {
+            if (ev.type !== "human_input" || ev.delivery !== "applied")
+                return;
+            const seen = consumedOnLeg.get(leg);
+            if (seen)
+                seen.add(ev.inputId);
+            else
+                consumedOnLeg.set(leg, new Set([ev.inputId]));
+            const onLeg = legs.get(leg);
+            if (!onLeg)
+                return;
+            const due = [...onLeg].flatMap(([acceptId, entry]) => (entry.messageId === ev.inputId && entry.taken ? [acceptId] : []));
+            for (const acceptId of due)
+                await settleConsumed(leg, acceptId);
+        },
         converge() {
             inFlight ??= convergePass().finally(() => {
                 inFlight = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.112.0",
+  "version": "7.114.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -28,6 +28,7 @@
     "!dist/run-local-linux-x64",
     "!dist/run-local-darwin-arm64",
     "skills",
+    "scripts/retired-mode-seed-drain-local.mjs",
     "deploy/sema-up",
     "docs/DEVICE-EXECUTOR-PROTOCOL.md",
     "USAGE.md",
@@ -61,8 +62,8 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.38.3",
-    "@sema-agent/settings-schema": "6.4.0",
+    "@sema-agent/core": "7.39.2",
+    "@sema-agent/settings-schema": "7.0.1",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
     "mysql2": "^3.22.4",

package/scripts/retired-mode-seed-drain-local.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * 换钉 7.113.0(core 7.39.0 删掉退役 mode-seed 的一次性迁移)前的**排空检查 —— `DB_BACKEND=local`(File 店)车道**,只读。
+ * 随 npm 包出(`scripts/retired-mode-seed-drain-local.mjs`;SQL 车道的同一判据是 `docs/DEPLOY-PREREQS.md` 同名节的两条只读 SQL)。
+ *
+ * ## 为什么是一只脚本,不是一行 grep
+ *  ① 判据有三条成员(core `refuseRetiredModeSeed`):`autoModeRequested` / `approverPosture` **任何值**(含 JSON null)、
+ *     `shellGate` **不是 `"always"`**(含 JSON null)。`"always"` 是 7.34.0 起的合法新形,grep 表达不了「值不是 always」;
+ *  ② core 的 File 店是**快照 + 账本**两只文件(`checkpoints/checkpoints.snapshot.jsonl` 每行一条行,`checkpoints/checkpoints.jsonl` 是快照之后的事件):
+ *     压实之后旧行**只在快照里**,只扫账本会把最该排的那批(≤7.105.0 停放的老行)整批漏掉;
+ *  ③ 账本是追加写:同一条行先 `put` 后 `resolve` / `expire` / `reopen`,只有折叠到**当前状态**才知道它还 pending 没有。
+ * ⇒ 本脚本照 core 的同一组事件把两只文件折成当前行,再按上面三条成员判 pending 行。
+ *
+ * ## 与 core 同判 —— 判据坐标(core 7.39.1 安装树 `node_modules/@sema-agent/core/dist/`;core 改了这些,本脚本要跟着改)
+ *  · 行形:`stores/file/checkpoint-store.js:61` `isCheckpointRow`(`token` / `scope` / `status` 三个串)。快照行(`:70` `judgeRow`)与账本 `put` 的 `cp`(`:71-78` `judgeEvent`)
+ *    **同一只判**。不合形的记录 core **跳过并披露、保留旧行**(`stores/file/fs-atomic.js:122` `readJsonlRecords`)—— 升级后那张旧卡照样在、照样被拒;所以本脚本对不合形的 `put`
+ *    **不覆盖**旧行、计入 `corrupt`(⇒ rc 2),旧卡仍被数到;不合形的快照行(含缺 `scope`)不当行数、计入 `corrupt`。
+ *  · 事件词:`stores/file/checkpoint-store.js:7-14` 注册表六词(put / resolve / reopen / execution / expire / steer_append);不认的词 core **拒绝重放**
+ *    (`:16-19` `applyCheckpointEvent` 抛 `ledger_event_unknown`)⇒ 本脚本计入 `unknownEvents`(⇒ rc 2),不替它猜。
+ *  · 重放序:`stores/file/shared-ledger.js:20-31` 先快照、后账本。压实 `stores/file/shared-ledger.js:63-72` `compact()` 先**原子换新快照**、再**清空账本**。
+ *  · 退役成员:`core/checkpoint-store.js:739-756` `RETIRED_MODE_SEED_MEMBERS` / `refuseRetiredModeSeed`。
+ *
+ * ## 只读、不取锁;服务运行中也可以跑,但脚本只对**一致的**快照 + 账本组合下结论
+ * 不打开 core 的店(那会取 `checkpoints/LOCK`、与在跑的服务争锁),只读两只 JSONL。服务在写时,两次读之间可能发生压实 ——
+ * 先读快照(旧)、压实(新快照含账本里的行,账本清空)、再读账本(空)⇒ 只在账本里的 pending 退役卡两边都读不到,读出一个假的「干净」。
+ * 所以读前读后各取两文件的身份(dev / ino / size / mtimeNs),任一变了(压实 = 原子替换 ⇒ ino 变;追加 ⇒ size 变)就**重读**,至多 3 次;
+ * 仍不稳 ⇒ rc 2 + 一句话(服务在写:停写或重跑),不给结论。
+ *
+ * ## 数据根
+ *  · 带参:`node scripts/retired-mode-seed-drain-local.mjs <数据根>` —— 读那个目录;
+ *  · 不带参:数据根 = **服务自己的那只解析**(`dist/local-data-root.js` 的 `resolveLocalDataRoot`,`loadConfig` 调的同一只函数,脚本不自抄那条链),
+ *    所以要在**与服务同一份 env**(同样的数据根相关 env、同一个 home)下跑,读到的才是服务用的那个目录;末行 `root=` 回显实际读了哪个目录。
+ *    随包形里 `dist/` 在脚本隔壁;源码树没 build 过又没给根 ⇒ rc 2 说明(见下)。
+ *  · **数据根缺席 ≠ 干净**:根目录不存在 / 不是目录 / 根下没有 `checkpoints/`(core File 店在后端构造时就建这个目录,所以它是「这里跑过 local 后端」的标记;
+ *    根 `LOCK` 是 pidfile、干净退出即删,不能当标记)⇒ rc 2,不给结论 —— 路径打错、env 没对上服务,都会读到一个什么都没有的目录。
+ *
+ * ## 读数(机读末行 + 退出码)
+ *  · 每条命中一行:`RETIRED-ROW token=<token> sessionId=<id> createdAt=<ms> member=<成员>`;
+ *  · 末行恒有:`RETIRED-MODE-SEED rows=<命中数> pending=<pending 行数> total=<行数> unknownEvents=<n> corrupt=<n> root=<实际读的数据根>`;
+ *    没读成 / 不能下结论(rc 2 的几种缺席与不稳形)时前五个计数是 `-`、多一个 `reason=<词>`,**不会出现 `rows=0`**(下游读 `rows=0` 即「干净」);
+ *  · rc 0 = 零命中(可换钉)· rc 1 = 有命中(逐行列出;答完或取消再跑)· rc 2 = 读不懂 / 没读成 / 不能下结论(账本里有本脚本不认的事件词 / 不合形的记录 /
+ *    数据根缺席 / 缺省根解析不可用 / 读期间文件一直在变 / 读文件出错 / 用法错)—— 不给结论(缺席 ≠ 干净:一条读不懂的记录可能正是让某行回到 pending 的那一条)。
+ *    rc 2 与 rc 1 同时成立时(有命中、也有读不懂的记录)报 rc 2,命中行照列。
+ */
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TAIL_PREFIX = "RETIRED-MODE-SEED";
+/** 读期间文件在变时的有界重读次数(含第一次)。 */
+const STABLE_READ_ATTEMPTS = 3;
+/** core 账本事件注册表(`stores/file/checkpoint-store.js:7-14`)。 */
+const KNOWN_LEDGER_EVENTS = new Set(["put", "resolve", "reopen", "execution", "expire", "steer_append"]);
+
+/** @param {string} path */
+const dirKind = (path) => {
+  try {
+    return statSync(path).isDirectory() ? "dir" : "file";
+  } catch {
+    return "absent";
+  }
+};
+
+/** 文件全文;不存在 = 空(与 core `readJsonlRecords` 的 ENOENT 臂同);其余错误抛出(由 {@link drainReport} 转 rc 2)。
+ * @param {string} path */
+const textOf = (path) => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === "ENOENT") return "";
+    throw e;
+  }
+};
+
+/** @param {string} path */
+const linesOf = (path) => textOf(path).split("\n").filter((l) => l.trim().length > 0);
+
+/** @param {string} line */
+const parse = (line) => {
+  try {
+    const v = JSON.parse(line);
+    return v !== null && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** core `isCheckpointRow`(`stores/file/checkpoint-store.js:61`)逐字:`token` / `scope` / `status` 三个串。快照行与账本 `put` 的 `cp` 同一只判。
+ * @param {unknown} x
+ * @returns {x is Record<string, unknown> & { token: string, scope: string, status: string }} */
+const isCheckpointRow = (x) =>
+  x !== null && typeof x === "object" && typeof (/** @type {Record<string, unknown>} */ (x).token) === "string" && typeof (/** @type {Record<string, unknown>} */ (x).scope) === "string" && typeof (/** @type {Record<string, unknown>} */ (x).status) === "string";
+
+/** 一只文件的身份;不存在 = `absent`(账本可以合法不存在);其余 stat 错误抛出。
+ * @param {string} path */
+const identityOf = (path) => {
+  try {
+    const st = statSync(path, { bigint: true });
+    return `${st.dev}:${st.ino}:${st.size}:${st.mtimeNs}`;
+  } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === "ENOENT") return "absent";
+    throw e;
+  }
+};
+
+/** 两只文件的身份(快照 | 账本)。
+ * @param {string} dir */
+const identitiesOf = (dir) => `${identityOf(join(dir, "checkpoints.snapshot.jsonl"))}|${identityOf(join(dir, "checkpoints.jsonl"))}`;
+
+/**
+ * 读一遍(不判一致性):快照 → 钩子 → 账本,折成当前行。
+ * @param {string} dir
+ * @param {() => void | Promise<void>} betweenReads
+ * @returns {Promise<{ rows: Map<string, Record<string, unknown>>, corrupt: number, unknownEvents: number }>}
+ */
+async function foldOnce(dir, betweenReads) {
+  /** @type {Map<string, Record<string, unknown>>} token → 行(当前状态) */
+  const rows = new Map();
+  let corrupt = 0;
+  let unknownEvents = 0;
+
+  // ① 快照:每行一条行;不合形(core `isCheckpointRow`)⇒ core 跳过 ⇒ 本脚本也不当行数,计 corrupt
+  for (const line of linesOf(join(dir, "checkpoints.snapshot.jsonl"))) {
+    const r = parse(line);
+    if (r === undefined || !isCheckpointRow(r)) {
+      corrupt++;
+      continue;
+    }
+    rows.set(r.token, r);
+  }
+
+  await betweenReads();
+
+  // ② 账本:快照之后的事件,照 core `applyCheckpointEvent` 的同一组词折叠(状态相关的三词改 status;其余两词与 pending 判定无关)
+  for (const line of linesOf(join(dir, "checkpoints.jsonl"))) {
+    const ev = parse(line);
+    if (ev === undefined || typeof ev.t !== "string") {
+      corrupt++;
+      continue;
+    }
+    if (!KNOWN_LEDGER_EVENTS.has(ev.t)) {
+      unknownEvents++; // 新版本写的事件词:本脚本不替它猜(core 对未知词拒绝重放)
+      continue;
+    }
+    if (typeof ev.token !== "string") {
+      corrupt++;
+      continue;
+    }
+    if (ev.t === "put") {
+      // core:`put` 的 cp 不合形 ⇒ 跳过该事件、保留旧行。本脚本同:不覆盖,计 corrupt(⇒ rc 2),旧行照数。
+      if (!isCheckpointRow(ev.cp)) {
+        corrupt++;
+        continue;
+      }
+      rows.set(ev.token, ev.cp);
+      continue;
+    }
+    const row = rows.get(ev.token);
+    switch (ev.t) {
+      case "resolve":
+        if (row) row.status = "resolved";
+        break;
+      case "reopen":
+        if (row) row.status = "pending";
+        break;
+      case "expire":
+        if (row) row.status = "expired";
+        break;
+      default:
+        break; // execution / steer_append:不改 status
+    }
+  }
+  return { rows, corrupt, unknownEvents };
+}
+
+/**
+ * 把 `<dir>` 下的快照 + 账本折成当前行,**只对一致的组合交结果**(导出:测试与 CLI 共用同一只;CLI 不传钩子)。
+ * 读前读后各取两文件身份,变了就重读,至多 {@link STABLE_READ_ATTEMPTS} 次;仍变 ⇒ `stable:false`(不交行)。
+ * @param {string} dir `<数据根>/checkpoints`
+ * @param {{ afterSnapshotRead?: (attempt: number) => void | Promise<void> }} [opts] 测试钩子:快照读完、账本还没读的那一刻(`attempt` 从 1 起)
+ * @returns {Promise<{ stable: true, attempts: number, rows: Map<string, Record<string, unknown>>, corrupt: number, unknownEvents: number } | { stable: false, attempts: number }>}
+ */
+export async function scanCheckpointDir(dir, opts = {}) {
+  for (let attempt = 1; attempt <= STABLE_READ_ATTEMPTS; attempt++) {
+    const before = identitiesOf(dir);
+    const folded = await foldOnce(dir, async () => {
+      await opts.afterSnapshotRead?.(attempt);
+    });
+    if (identitiesOf(dir) === before) return { stable: true, attempts: attempt, ...folded };
+  }
+  return { stable: false, attempts: STABLE_READ_ATTEMPTS };
+}
+
+/** core `refuseRetiredModeSeed` 的三条成员(`core/checkpoint-store.js:739-756` 逐字):前两条任何值都算(含 null),`shellGate` 不是 "always" 才算。
+ * @param {unknown} gate
+ * @returns {string | undefined} */
+function retiredMember(gate) {
+  if (gate === null || typeof gate !== "object") return undefined;
+  const g = /** @type {Record<string, unknown>} */ (gate);
+  if (g.autoModeRequested !== undefined) return "autoModeRequested";
+  if (g.approverPosture !== undefined) return "approverPosture";
+  if (g.shellGate !== undefined && g.shellGate !== "always") return "shellGate";
+  return undefined;
+}
+
+/** 没读成 / 不能下结论的报告:一句人话进 stderr、机读末行进 stdout(计数全 `-`,不出现 `rows=0`),rc 2。
+ * @param {string} reason 机读词
+ * @param {string} sentence
+ * @param {string} rootEcho */
+function unreadableReport(reason, sentence, rootEcho) {
+  return { rc: /** @type {const} */ (2), stdout: [`${TAIL_PREFIX} rows=- pending=- total=- unknownEvents=- corrupt=- reason=${reason} root=${rootEcho}`], stderr: [sentence] };
+}
+
+/**
+ * 一次排空检查的完整报告(导出:CLI 与测试共用)。
+ * @param {string} root 数据根
+ * @param {{ afterSnapshotRead?: (attempt: number) => void | Promise<void> }} [opts]
+ * @returns {Promise<{ rc: 0 | 1 | 2, stdout: string[], stderr: string[] }>}
+ */
+export async function drainReport(root, opts = {}) {
+  const dir = join(root, "checkpoints");
+  switch (dirKind(root)) {
+    case "absent":
+      return unreadableReport("root-absent", `data root ${root} does not exist — no verdict (absent is not clean): check that this process has the same data-root env as the service, or pass the data root as the argument`, root);
+    case "file":
+      return unreadableReport("root-not-a-directory", `data root ${root} is not a directory — no verdict: pass the service's data root`, root);
+    case "dir":
+      break;
+  }
+  if (dirKind(dir) !== "dir") {
+    return unreadableReport(
+      "no-checkpoints-dir",
+      `no checkpoints/ directory under ${root} — no verdict (absent is not clean): this is not the data root of a local-backend service that has booted (the service creates checkpoints/ when it starts); check that this process has the same data-root env as the service, or pass the data root as the argument`,
+      root,
+    );
+  }
+  let scan;
+  try {
+    scan = await scanCheckpointDir(dir, opts);
+  } catch (e) {
+    // 读文件出错(权限 / 路径是目录 / …)⇒ 不给结论。未捕获异常的退出码是 1 = 「有命中」,会被下游读成有停放行。
+    return unreadableReport("read-error", `cannot read the checkpoint files under ${dir}: ${e instanceof Error ? e.message : String(e)} — no verdict`, root);
+  }
+  if (!scan.stable) {
+    return unreadableReport(
+      "unstable-read",
+      `the checkpoint files under ${dir} changed while being read (${scan.attempts} reads in a row) — the service is writing to its checkpoint store, so no consistent snapshot + ledger could be read: no verdict; stop the service (or its checkpoint traffic) and rerun`,
+      root,
+    );
+  }
+  const { rows, corrupt, unknownEvents } = scan;
+  const stdout = [];
+  let hits = 0;
+  let pending = 0;
+  for (const [token, row] of rows) {
+    if (row.status !== "pending") continue;
+    pending++;
+    const state = row.state !== null && typeof row.state === "object" ? /** @type {Record<string, unknown>} */ (row.state) : {};
+    const member = retiredMember(state.inheritedGate);
+    if (member === undefined) continue;
+    hits++;
+    stdout.push(`RETIRED-ROW token=${token} sessionId=${String(row.sessionId)} createdAt=${String(row.createdAt)} member=${member}`);
+  }
+  stdout.push(`${TAIL_PREFIX} rows=${hits} pending=${pending} total=${rows.size} unknownEvents=${unknownEvents} corrupt=${corrupt} root=${root}`);
+  return { rc: unknownEvents > 0 || corrupt > 0 ? 2 : hits > 0 ? 1 : 0, stdout, stderr: [] };
+}
+
+/** CLI 入口:解析实参与缺省根,打印报告,按报告的 rc 退出。 */
+async function main() {
+  const usage = "usage: retired-mode-seed-drain-local.mjs [<data root>]";
+  const args = process.argv.slice(2);
+  /** @param {{ rc: number, stdout: string[], stderr: string[] }} r */
+  const finish = (r) => {
+    for (const l of r.stderr) process.stderr.write(`${l}\n`);
+    for (const l of r.stdout) process.stdout.write(`${l}\n`);
+    process.exit(r.rc);
+  };
+  if (args.length > 1 || (args[0] !== undefined && args[0].startsWith("-"))) finish(unreadableReport("usage", usage, "-"));
+  /** @type {string} */
+  let root;
+  if (args[0] !== undefined) {
+    root = args[0];
+  } else {
+    try {
+      const { resolveLocalDataRoot } = await import("../dist/local-data-root.js");
+      root = resolveLocalDataRoot(process.env, homedir());
+    } catch (e) {
+      finish(
+        unreadableReport(
+          "default-root-unavailable",
+          `cannot resolve the default data root (dist/local-data-root.js next to scripts/ is not loadable: ${e instanceof Error ? e.message : String(e)}) — run the copy inside an installed @sema-agent/server package (or after \`npm run build\`), or pass the data root as the argument`,
+          "-",
+        ),
+      );
+    }
+  }
+  finish(await drainReport(root));
+}
+
+// 作脚本跑才进 CLI;被 import(测试)时只导出函数。
+// 7.113.0 合并复审的修复验证两腿同根发现(主会话按「门轴新代码 fail-closed」收口):入口判定**自己不许失败成「什么都不跑、rc 0」**
+// (rc 0 = 「干净,可换钉」)。两边都取 realpath 再比(`--preserve-symlinks-main` 下 `import.meta.url` 留软链路径、argv[1] 解析成真路径 ⇒ 修前
+// 两边不等 ⇒ main 不跑 ⇒ 静默 rc 0);argv[1] 缺席 / 为 `-`(stdin 导入方)/ 解析不到 ⇒ 当 import,不抛(修前 realpathSync 对 `-` 抛 ENOENT);
+// Node ≥ 22.18 有 `import.meta.main`,在场就以它为准(平台自己的判定,比路径比对可靠)。
+function invokedAsMain() {
+  const metaMain = /** @type {{ main?: unknown }} */ (import.meta).main;
+  if (typeof metaMain === "boolean") return metaMain;
+  const arg = process.argv[1];
+  if (arg === undefined || arg === "-" || arg === "") return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(arg);
+  } catch {
+    return false;
+  }
+}
+if (invokedAsMain()) await main();