@sema-agent/server 7.114.0 → 7.116.0

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

@@ -13,15 +13,18 @@
  * 「本服务以回执向调用方承诺已交给引擎、而消费只发生在进程内存里的用户输入」,**且承载它的那只 `TaskStream` 活在本服务的一条 run 腿里**(S-966)——
  * 后半句是收敛判词成立的前提:证据面是那条 run 行(下文「收敛判据」)。行的 `taskId` = 回执上的 run、`sessionId` = 那条 run 的会话(人看的那一只),
  * run 里是哪一只流(run 自己的 / 同步子代的)**不是**账本的事实:告知按 run 并帧(`steer` = 条数),读面行同形。今天只有 steer 一族(`kind:"steer"` =
- * core 的车道词:引擎把这些输入记在 steer 车道),三个入口同一个引擎动词 `TaskStream.steer`:
+ * 受理它的引擎动词 `TaskStream.steer`,三档 `now` / `next` / `later` 同一个动词同一族),三个入口同一个引擎动词:
  *  · `POST /v1/runs/:id/steer` 的 live 腿(200 applied);
  *  · `POST /v1/runs/:id/interrupt` 的带 text 形(202 queued-immediate,档位 now;设计稿把它划在病面外,车 SW 亲核它进的是同一只进程内队列 ⇒ 同类同修);
  *  · `POST /v1/runs/:id/subagents/:target/steer`(200 applied,S-966)—— 投进**同步子代**自己的流(core `createSteerHandle` → `stream.steer`)。子代由父腿
  *    await,父腿收场时 core 撤掉在飞的复活(`subagentRetain.disposeAll`),所以它活在父 run 的腿里;腿 = 子代句柄,`handle.settled` 兑现 ⇒ 结清。
  * 规则的反面(不是例外表):workflow agent steer(`POST /v1/workflows/:id/agents/:label/steer`,200 applied)不在本账 —— workflow 是会话锚定的后台件
  * (core `WorkflowTaskHandle.sessionScoped`),活得比发起它的 run 腿长,没有一条 run 行约束它,而 workflow run 行上没有持有者列 ⇒ 判不出写者死没死(另票);
- * 子代 resume(`…/subagents/:target/resume`)不往在飞的队列里投,起的是一条新的子代腿;follow-up 在本仓**没有**进程内受理口(`src/http/routes` 零
- * follow-up 入口;steer 路由不下传 `priority`,core 缺省 `next` = steer 车道)⇒ 闭集一词,不预留第二词。
+ * 子代 resume(`…/subagents/:target/resume`)不往在飞的队列里投,起的是一条新的子代腿;follow-up 在本仓**没有**独立的受理口(`src/http/routes` 零
+ * follow-up 入口)。steer 的 `later` 档在引擎里走 follow-up 车道(引擎在腿收场时按车道分账:没投出去的 `later` 记进 `task.user_followup_undrained`),
+ * 但它仍是一次 `TaskStream.steer` 受理、消费帧同为 `human_input{delivery:"applied"}`(两车道同一只消费口)⇒ 同进本账,消费即结清;崩溃告知走 core 唯一的
+ * 服务层臂 `task.user_steer_undrained{cause:"crashed"}`(core 对该臂的定义按动词:服务层受理过的 steer)。follow-up 一族在 core 里没有 `cause` 键、没有
+ * 服务层臂 ⇒ 本账无处按车道归档,要按车道归档须 core 先给那一臂(上游待答)⇒ 闭集一词,不预留第二词。
  *
  * ## 五形行(append-only;行序 = 语义序;File 孪生的盘上形 = 下面的 {@link UserInputLedgerRecord},SQL 孪生 = 一行一受理 + CAS 列 + 删行,同义)
  *  · `accepted`  —— 受理点(`routes/runs.ts` 的 live 腿,**调 `TaskStream.steer` 之前**、回 200 之前)写;写不进 ⇒ 503
@@ -50,8 +53,8 @@
  * ## 收敛判据(一条:**受理它的进程已经不在,而承载它的腿没有正常收场**)—— 两车道同一只判词({@link judgeOpen},S-969 L8 合一)
  * 证据面只有一个:承载它的 **run 行**(run 店;行上的 `instanceId` = 当前持有者,createRun 铸、markResuming 接管)。
  *  · 行在、持有者是写者、仍 `running` ⇒ 腿没收场;写者在不在由车道答(下一段)—— 不在 ⇒ `crashed`,可能在 ⇒ `live`(不动,等 reaper)。
- *  · 行在、持有者是写者、`failed` 且落款是 run 店的**死亡判决**({@link isHolderDeathVerdict}:`reapStale` 的 `RUN_STALLED_ERROR` /
- *    File 车道孤儿回收与 claim 接管的 `RUN_ORPHANED_ERROR`)⇒ 写者死在腿收场之前 ⇒ `crashed`。判决落盘之后才收(codex r1-F1 / r3-F1:
+ *  · 行在、持有者是写者、`failed` 且行上是 run 店的**死亡判决码**({@link isHolderDeathVerdict}:`reapStale` 的 `run.stalled` /
+ *    File 车道孤儿回收与 claim 接管的 `run.orphaned`;7.116.0 起按码判,句子只给人读)⇒ 写者死在腿收场之前 ⇒ `crashed`。判决落盘之后才收(codex r1-F1 / r3-F1:
  *    读到的旧心跳不算 —— 读后写者可能恢复;收敛与 reap 的先后因此不承重)。维护 tick 里收敛排在 reapStale **之后**(同一条腿串行)。
  *  · 其余 —— 行正常翻面(完成 / 失败 / 取消)、已 park(suspended / needs_review:引擎把未消费的 steer 迁进检查点,续跑重投)、易手(续跑被别的
  *    进程接走)⇒ 腿正常收场了,只是没人替它落 settle ⇒ 补落 `settled{leg_end}`(判词 `leg_over`,见 {@link OpenVerdict}),不告知。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.114.0",
+  "version": "7.116.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,7 +28,9 @@
     "!dist/run-local-linux-x64",
     "!dist/run-local-darwin-arm64",
     "skills",
-    "scripts/retired-mode-seed-drain-local.mjs",
+    "scripts/drain-check-local.mjs",
+    "scripts/drain-check.mysql.sql",
+    "scripts/drain-check.pg.sql",
     "deploy/sema-up",
     "docs/DEVICE-EXECUTOR-PROTOCOL.md",
     "USAGE.md",
@@ -62,8 +64,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.39.2",
-    "@sema-agent/settings-schema": "7.0.1",
+    "@sema-agent/core": "7.41.2",
+    "@sema-agent/settings-schema": "8.0.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
     "mysql2": "^3.22.4",

package/scripts/drain-check-local.mjs

@@ -0,0 +1,528 @@
+#!/usr/bin/env node
+/**
+ * 换钉前的**排空检查 —— `DB_BACKEND=local`(File 店)车道**,只读。随 npm 包出(`scripts/drain-check-local.mjs`)。
+ * 一次跑**四条判据**(判据表 {@link DRAIN_CRITERIA},每条一行末行、各自的命中行;SQL 车道的同一判据是同目录随包的 `drain-check.mysql.sql` / `drain-check.pg.sql`,
+ * 每条判据一段、段首标记 `-- drain-check:<判据名>:<后端>`,判据名与本表的 `name` 同一个词):
+ *  · `skill-grants-rollback`(**回滚**到 7.115.x 前,即引擎从 7.41 退回 7.40):四样任一 ——
+ *    ① pending 行带 `state.skillGrants`(本次 run 冻结在行上的技能授予行:模型激活 / 子代捕获写下的放行与禁止);
+ *    ② 行带 `pendingAction.boundGrantDigest`(停驻的 `Skill` 卡的同意绑定);
+ *    ③ 行所在会话的续跑上下文(`checkpoint-ctx/*.json` 的 `ctx.body.userInvokedSkills`)是非空数组 —— 人用名字点过的技能写下的行**不冻结**进 ①
+ *      (引擎靠续跑重递请求键重写它们),而 7.115.x 的续跑翻译点不认这个键、不重递。
+ *  ④ 行所在会话的续跑上下文体里,某只技能(顶层 `skills[]` 或某只子代的 `agents[].skills[]`)声明了**非空** `disallowedTools` —— 那只技能停驻时还没被激活(没有授予行可冻在行上),
+ *    回滚后模型再激活它,上一版不读这个键、什么也不拒;前三样都数不到这一形。
+ *    7.40 的引擎续跑这种行时都不读:这一 run 的技能禁止行丢失、卡的绑定不核。①② 只看键**在不在**(在却读不出的节 7.40 同样不读,一并数);
+ *    这是行形 / 上下文形上的事实,本服务运行期没有同一判据的函数(它不拒这种行),所以判据就写在这一张表里(与 `retired-mode-seed` 同),
+ *    SQL 车道的孪生是随包 `drain-check.*.sql` 里同名的两段只读 SQL(`-- drain-check:skill-grants-rollback:<后端>`);读不懂的 ctx 档计入 `corrupt`(rc 2:一份读不懂的上下文可能正是带这个键的那一份);
+ *  · `retired-skill-manifest`(升级到 7.116.0 前,core 7.41.0 退役技能上的 `manifest` 键):pending 行所在会话的续跑上下文(`checkpoint-ctx/*.json`)里,提交体顶层 `skills[]` 或某只子代定义的
+ *    `agents[].skills[]` 仍带 `manifest`(任何值)—— 升级后续跑顶层那种会被引擎按名拒(行仍 pending,只能取消重提),子代那种不被拒、而是那只子代定义被整只丢掉并留一条警告日志(任务照跑、少一只子代)。命中行点名是哪一层(`member=skills` / `member=agents.skills`)。
+ *    「带 `manifest`」的判据是服务里**一只**函数(`src/http/retired-skill-manifest.ts`,提交口的顶层技能门读同一只),经包里脚本隔壁的编译产物 `dist/http/retired-skill-manifest.js` 取 —— 本脚本不写第二份;
+ *  · `retired-mode-seed`(换钉 7.113.0 前,core 7.39.0 删掉退役 mode-seed 的一次性迁移):pending 行的 `state.inheritedGate` 仍带退役成员;
+ *  · `permissions-allow-list`(换钉 7.115.0 前,本服务把 `settings.permissions.allow` 从名单改成 allow 规则):pending 行所在会话的续跑上下文
+ *    (`checkpoint-ctx/*.json` 的信封 `{ sessionId, updatedAt, ctx }`)里,`ctx.body.settings.permissions.allow` 是非空数组,且 `ctx.permissionsAllowReading` 不是 `"statement"`
+ *    —— 这样的行在 7.115.0 上续跑会被拒(行字节不动;出路按停驻种类分,见随包 `MIGRATION.md` 7.115.0 节)。判据**就是**服务续跑腿拒臂的那一只函数(`src/http/checkpoint-ctx.ts` 的 `allowListReadingUnstated`),
+ *    经包里脚本隔壁的编译产物 `dist/http/checkpoint-ctx.js` 取(与缺省数据根经 `dist/local-data-root.js` 取同一姿势;该模块只有类型 import,编出来零运行期依赖)—— 本脚本不写第二份。
+ * 扫描骨架(快照 + 账本折成当前行、一致性重读、数据根判定)各条判据共用;判据只回答「这一条 pending 行算不算命中」。
+ *
+ * ## 为什么是一只脚本,不是一行 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/drain-check-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 没对上服务,都会读到一个什么都没有的目录。
+ *
+ * ## 读数(机读末行 + 退出码)
+ *  · 每条命中一行:`SKILL-GRANTS-ROW token=<token> sessionId=<id> createdAt=<ms> member=<skillGrants|boundGrantDigest|userInvokedSkills|disallowedTools>` / `SKILL-MANIFEST-ROW token=<token> sessionId=<id> createdAt=<ms> member=<skills|agents.skills>` /
+ *    `ALLOW-LIST-ROW token=<token> sessionId=<id> createdAt=<ms>` / `RETIRED-ROW token=<token> sessionId=<id> createdAt=<ms> member=<成员>`;
+ *  · 每条判据一行末行(表序;`RETIRED-MODE-SEED` 那一行恒在最后,7.113.0 起读「最后一行」的下游不受影响;`PERMISSIONS-ALLOW-LIST` 仍是倒数第二行):
+ *    `SKILL-GRANTS rows=<命中数> pending=<pending 行数> total=<行数> unknownEvents=<n> corrupt=<n> root=<实际读的数据根>`,
+ *    `RETIRED-SKILL-MANIFEST rows=<命中数> pending=<pending 行数> total=<行数> unknownEvents=<n> corrupt=<n> root=<实际读的数据根>`,
+ *    `PERMISSIONS-ALLOW-LIST rows=<命中数> pending=<pending 行数> total=<行数> unknownEvents=<n> corrupt=<n> root=<实际读的数据根>`,
+ *    `RETIRED-MODE-SEED rows=<命中数> pending=<pending 行数> total=<行数> unknownEvents=<n> corrupt=<n> root=<实际读的数据根>`;
+ *    `corrupt` = 共用扫描的坏记录 + 这条判据自己读不懂的旁路输入(`permissions-allow-list`:读不懂的 ctx 档,文件名进 stderr —— 一份读不懂的 ctx 可能正是某条 pending 行带 `allow` 的那一份);
+ *    没读成 / 不能下结论(rc 2 的几种缺席与不稳形)时前五个计数是 `-`、多一个 `reason=<词>`,**不会出现 `rows=0`**(下游读 `rows=0` 即「干净」);
+ *  · rc 0 = 每条判据都零命中(可换钉 / 可回滚)· rc 1 = 有命中(逐行列出;答完或取消再跑)· rc 2 = 读不懂 / 没读成 / 不能下结论(账本里有本脚本不认的事件词 / 不合形的记录 / 读不懂的 ctx 档 /
+ *    数据根缺席 / 缺省根解析不可用 / 判据模块不可用(脚本隔壁没有 `dist/`:源码树没 build)/ 读期间文件一直在变 / 读文件出错 / 用法错)—— 不给结论(缺席 ≠ 干净:一条读不懂的记录可能正是让某行回到 pending 的那一条)。
+ *    rc 2 与 rc 1 同时成立时(有命中、也有读不懂的记录)报 rc 2,命中行照列。
+ */
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** 从脚本隔壁的编译产物取来的服务判据(脚本不持第二份实现)。
+ * @typedef {{ allowListReadingUnstated: (ctx: Record<string, unknown>) => boolean, retiredSkillManifestLayerOf: (body: unknown) => "skills" | "agents.skills" | undefined }} ServiceCriteria */
+
+/** 读期间文件在变时的有界重读次数(含第一次)。 */
+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;
+}
+
+/** @param {unknown} v */
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * 提交体里有没有技能声明了**非空** `disallowedTools`(数组、至少一员):顶层 `skills[]`,或某只子代定义的 `agents[].skills[]`。体不是对象 / 层不是数组 / 项不是对象 ⇒ 该处不算。
+ * @param {unknown} body */
+const declaresDisallowedTools = (body) => {
+  if (!isObject(body)) return false;
+  const { skills, agents } = /** @type {{ skills?: unknown, agents?: unknown }} */ (body);
+  /** @param {unknown} list */
+  const anyDeclares = (list) => Array.isArray(list) && list.some((sk) => isObject(sk) && Array.isArray(/** @type {Record<string, unknown>} */ (sk).disallowedTools) && /** @type {unknown[]} */ (/** @type {Record<string, unknown>} */ (sk).disallowedTools).length > 0);
+  if (anyDeclares(skills)) return true;
+  return Array.isArray(agents) && agents.some((a) => isObject(a) && anyDeclares(/** @type {Record<string, unknown>} */ (a).skills));
+};
+
+/**
+ * `<数据根>/checkpoint-ctx/*.json` —— 本服务 local 店的续跑上下文,一档一会话,信封 `{ sessionId, updatedAt, ctx }`(`ctx` 是对象;形判据同本服务 `LocalCheckpointStore` 的
+ * `CtxRecordSchema` + 对象读者)。目录不存在 = 没有 ctx(没写过);读不懂的档计入 `corrupt`(不猜它属于哪个会话)、文件名回给调用方;读期间被收割删掉的档跳过。
+ * @param {string} root
+ * @returns {{ bySession: Map<string, Record<string, unknown>>, corrupt: number, unreadable: string[] }} */
+function readCtxIndex(root) {
+  const dir = join(root, "checkpoint-ctx");
+  /** @type {Map<string, Record<string, unknown>>} */
+  const bySession = new Map();
+  /** @type {string[]} */
+  const unreadable = [];
+  /** @type {string[]} */
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === "ENOENT") return { bySession, corrupt: 0, unreadable };
+    throw e;
+  }
+  for (const name of names.sort()) {
+    if (!name.endsWith(".json")) continue;
+    let text;
+    try {
+      text = readFileSync(join(dir, name), "utf8");
+    } catch (e) {
+      if (/** @type {NodeJS.ErrnoException} */ (e).code === "ENOENT") continue; // 读期间被收割删掉
+      throw e;
+    }
+    const rec = parse(text);
+    if (rec === undefined || typeof rec.sessionId !== "string" || typeof rec.updatedAt !== "number" || !isObject(rec.ctx)) {
+      unreadable.push(name);
+      continue;
+    }
+    bySession.set(rec.sessionId, /** @type {Record<string, unknown>} */ (rec.ctx));
+  }
+  return { bySession, corrupt: unreadable.length, unreadable };
+}
+
+/**
+ * 判据表 —— 「哪些 pending 行算命中」。扫描骨架(快照 + 账本折成当前行、一致性重读、数据根判定)各条共用,判据只管这一问:
+ *  · `tail` / `hit`:末行前缀 / 命中行前缀;
+ *  · `load(root, service)`:这条判据要的旁路输入(读不懂的记录计入 `corrupt`,`unreadable` 回显进 stderr);`service` = 从编译产物取来的服务判据({@link drainReport} 取一次);
+ *  · `judge(row, input)`:命中 ⇒ 命中行的尾巴(可为空串),不命中 ⇒ `undefined`。
+ * 表序 = 输出序;`retired-mode-seed` 排最后 ⇒ 最后一行仍是 `RETIRED-MODE-SEED …`(7.113.0 起读最后一行的下游)。
+ * @type {ReadonlyArray<{ name: string, tail: string, hit: string, load: (root: string, service: ServiceCriteria) => { input: unknown, corrupt: number, unreadable: string[] }, judge: (row: Record<string, unknown>, input: unknown) => string | undefined }>}
+ */
+export const DRAIN_CRITERIA = [
+  {
+    // 回滚到 7.115.x(引擎 7.40)之前:7.41 停驻的行上 7.40 不读的四样(头注第一条)。先看授予节,再看卡的绑定,再看会话上下文里的人点名技能,最后看上下文里还没被激活的技能声明的禁止清单;
+    // 命中行点名是哪一样。
+    name: "skill-grants-rollback",
+    tail: "SKILL-GRANTS",
+    hit: "SKILL-GRANTS-ROW",
+    load: (root) => {
+      const idx = readCtxIndex(root);
+      return { input: idx.bySession, corrupt: idx.corrupt, unreadable: idx.unreadable };
+    },
+    judge: (row, input) => {
+      if (isObject(row.state) && Object.hasOwn(/** @type {Record<string, unknown>} */ (row.state), "skillGrants")) return " member=skillGrants";
+      if (isObject(row.pendingAction) && Object.hasOwn(/** @type {Record<string, unknown>} */ (row.pendingAction), "boundGrantDigest")) return " member=boundGrantDigest";
+      const bySession = /** @type {Map<string, Record<string, unknown>>} */ (input);
+      const ctx = typeof row.sessionId === "string" ? bySession.get(row.sessionId) : undefined;
+      const body = ctx !== undefined && isObject(ctx.body) ? /** @type {Record<string, unknown>} */ (ctx.body) : undefined;
+      const invoked = body?.userInvokedSkills;
+      if (Array.isArray(invoked) && invoked.length > 0) return " member=userInvokedSkills";
+      return declaresDisallowedTools(body) ? " member=disallowedTools" : undefined;
+    },
+  },
+  {
+    // 升级到 7.116.0 之前:停驻、持久化体里技能还带退役 `manifest` 的行(头注第二条判据)。判据函数是服务里那一只(`retiredSkillManifestLayerOf`,经编译产物取);
+    // 命中行点名是顶层 `skills[]` 还是子代 `agents[].skills[]`。表序紧跟回滚前那一条 —— `PERMISSIONS-ALLOW-LIST` 仍倒数第二、`RETIRED-MODE-SEED` 仍最后。
+    name: "retired-skill-manifest",
+    tail: "RETIRED-SKILL-MANIFEST",
+    hit: "SKILL-MANIFEST-ROW",
+    load: (root, service) => {
+      const idx = readCtxIndex(root);
+      return { input: { bySession: idx.bySession, layerOf: service.retiredSkillManifestLayerOf }, corrupt: idx.corrupt, unreadable: idx.unreadable };
+    },
+    judge: (row, input) => {
+      const { bySession, layerOf } = /** @type {{ bySession: Map<string, Record<string, unknown>>, layerOf: ServiceCriteria["retiredSkillManifestLayerOf"] }} */ (input);
+      const ctx = typeof row.sessionId === "string" ? bySession.get(row.sessionId) : undefined;
+      const layer = ctx === undefined ? undefined : layerOf(ctx.body);
+      return layer === undefined ? undefined : ` member=${layer}`;
+    },
+  },
+  {
+    name: "permissions-allow-list",
+    tail: "PERMISSIONS-ALLOW-LIST",
+    hit: "ALLOW-LIST-ROW",
+    load: (root, service) => {
+      const idx = readCtxIndex(root);
+      return { input: { bySession: idx.bySession, unstated: service.allowListReadingUnstated }, corrupt: idx.corrupt, unreadable: idx.unreadable };
+    },
+    judge: (row, input) => {
+      const { bySession, unstated } = /** @type {{ bySession: Map<string, Record<string, unknown>>, unstated: (ctx: Record<string, unknown>) => boolean }} */ (input);
+      const ctx = typeof row.sessionId === "string" ? bySession.get(row.sessionId) : undefined;
+      return ctx !== undefined && unstated(ctx) ? "" : undefined;
+    },
+  },
+  {
+    name: "retired-mode-seed",
+    tail: "RETIRED-MODE-SEED",
+    hit: "RETIRED-ROW",
+    load: () => ({ input: undefined, corrupt: 0, unreadable: [] }),
+    judge: (row) => {
+      const state = isObject(row.state) ? /** @type {Record<string, unknown>} */ (row.state) : {};
+      const member = retiredMember(state.inheritedGate);
+      return member === undefined ? undefined : ` member=${member}`;
+    },
+  },
+];
+
+/** 没读成 / 不能下结论的报告:一句人话进 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: DRAIN_CRITERIA.map((c) => `${c.tail} rows=- pending=- total=- unknownEvents=- corrupt=- reason=${reason} root=${rootEcho}`), stderr: [sentence] };
+}
+
+/**
+ * 取服务判据(每个判据模块一次 import + 导出自检)。任一模块加载失败 / 导出缺席 ⇒ 同一条 `criterion-unavailable` 不给结论(报告),不退回手写判据。
+ * @param {string} rootEcho
+ * @returns {Promise<ServiceCriteria | ReturnType<typeof unreadableReport>>} */
+async function loadServiceCriteria(rootEcho) {
+  /** @type {Array<[string, () => Promise<Record<string, unknown>>, string]>} 〔产物相对路径(报告用), 取模块, 导出名〕 */
+  const wanted = [
+    ["dist/http/checkpoint-ctx.js", () => import("../dist/http/checkpoint-ctx.js"), "allowListReadingUnstated"],
+    ["dist/http/retired-skill-manifest.js", () => import("../dist/http/retired-skill-manifest.js"), "retiredSkillManifestLayerOf"],
+  ];
+  /** @type {Record<string, unknown>} */
+  const fns = {};
+  for (const [rel, load, name] of wanted) {
+    /** @type {Record<string, unknown>} */
+    let mod;
+    try {
+      mod = await load();
+    } catch (e) {
+      return unreadableReport(
+        "criterion-unavailable",
+        `cannot load the service's own criterion (${rel} next to scripts/ is not loadable: ${e instanceof Error ? e.message : String(e)}) — no verdict: run the copy inside an installed @sema-agent/server package (or after \`npm run build\`)`,
+        rootEcho,
+      );
+    }
+    if (typeof mod?.[name] !== "function") {
+      return unreadableReport(
+        "criterion-unavailable",
+        `cannot use the service's own criterion (${rel} next to scripts/ loaded but does not provide it — the compiled output is incomplete or damaged) — no verdict: reinstall @sema-agent/server and run the copy inside the installed package`,
+        rootEcho,
+      );
+    }
+    fns[name] = mod[name];
+  }
+  return /** @type {ServiceCriteria} */ (fns);
+}
+
+/**
+ * 一次排空检查的完整报告(导出: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,
+    );
+  }
+  // 判据的唯一实现在服务里;随包形里编译产物在脚本隔壁。取不到(源码树没 build)⇒ 不给结论 —— 绝不退回一份手写的判据。
+  // 模块能加载不等于判据在:产物被截断 / 损坏时 import 照样成功、导出缺席。判据给不出来 ⇒ 同一条「不给结论」,
+  // 不许在没有行可判时读成 rows=0,也不许等到调用处抛出(未捕获异常的退出码是 1 = 「有命中」)。
+  const service = await loadServiceCriteria(root);
+  if ("rc" in service) return service;
+  let scan;
+  /** @type {Array<{ input: unknown, corrupt: number, unreadable: string[] }>} */
+  let inputs;
+  try {
+    scan = await scanCheckpointDir(dir, opts);
+    inputs = DRAIN_CRITERIA.map((c) => c.load(root, service));
+  } catch (e) {
+    // 读文件出错(权限 / 路径是目录 / …)⇒ 不给结论。未捕获异常的退出码是 1 = 「有命中」,会被下游读成有停放行。
+    return unreadableReport("read-error", `cannot read the checkpoint files under ${root}: ${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;
+  /** @type {string[]} */
+  const stdout = [];
+  /** @type {string[]} */
+  const stderr = [];
+  /** @type {string[]} */
+  const tails = [];
+  let anyHit = false;
+  let anyUnreadable = unknownEvents > 0 || corrupt > 0;
+  DRAIN_CRITERIA.forEach((criterion, i) => {
+    const { input, corrupt: ownCorrupt, unreadable } = inputs[i];
+    let hits = 0;
+    let pending = 0;
+    for (const [token, row] of rows) {
+      if (row.status !== "pending") continue;
+      pending++;
+      const tailOfHit = criterion.judge(row, input);
+      if (tailOfHit === undefined) continue;
+      hits++;
+      stdout.push(`${criterion.hit} token=${token} sessionId=${String(row.sessionId)} createdAt=${String(row.createdAt)}${tailOfHit}`);
+    }
+    if (unreadable.length > 0) stderr.push(`${criterion.name}: unreadable input files (no verdict — one of them may be what makes a pending row count): ${unreadable.join(", ")}`);
+    if (ownCorrupt > 0) anyUnreadable = true;
+    if (hits > 0) anyHit = true;
+    tails.push(`${criterion.tail} rows=${hits} pending=${pending} total=${rows.size} unknownEvents=${unknownEvents} corrupt=${corrupt + ownCorrupt} root=${root}`);
+  });
+  return { rc: anyUnreadable ? 2 : anyHit ? 1 : 0, stdout: [...stdout, ...tails], stderr };
+}
+
+/** CLI 入口:解析实参与缺省根,打印报告,按报告的 rc 退出。 */
+async function main() {
+  const usage = "usage: drain-check-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();