@sema-agent/server 7.114.0 → 7.116.0

package/scripts/drain-check.mysql.sql

@@ -0,0 +1,67 @@
+-- 换钉 / 回滚前的排空检查 —— MySQL 协议后端(TiDB / InnoDB),只读:本文件里只有 SELECT。随 npm 包出。
+--
+-- 怎么跑(整只文件一次跑完,每条判据出一行读数):
+--   mysql -h <主机> -P <端口> -u <用户> -p <库名> < node_modules/@sema-agent/server/scripts/drain-check.mysql.sql
+-- 读数:每条判据一行 `criterion | hit_rows | sessions` ——
+--   criterion  判据名(与随包脚本 drain-check-local.mjs 判据表里的名字同一个词,与下面各段的标记 `-- drain-check:<判据名>:mysql` 同一个词);
+--   hit_rows   命中的停驻行数(pending 行里算命中的那些);**全部为 0 才算排空**,非 0 ⇒ 逐条答完或取消(各判据对应的升级 / 回滚说明见随包 MIGRATION.md);
+--   sessions   命中行所在的会话 id,逗号连接,新的在前。以 hit_rows 为准:这一列被会话变量 group_concat_max_len(缺省 1024 字节)截断时,列出的会话数会少于 hit_rows ——
+--              先处理列出的再跑一次,或先在同一个会话里 SET SESSION group_concat_max_len = 1048576; 再跑本文件(本文件自己只含 SELECT)。
+-- 每段只数 pending 行(已决 / 已过期的行不数);判据只看**键在不在 / 值形**,不读行的其余内容。
+-- DB_BACKEND=local(File 店)没有 SQL:用同目录的 drain-check-local.mjs,四条判据同名。
+--
+-- 四条判据(顺序同 drain-check-local.mjs 的判据表):
+--   skill-grants-rollback   回滚到 7.115.x(引擎 7.40)之前:7.116.0 停驻的行带 7.40 不读的技能授予节 / 卡绑定 / 会话上下文里的人点名技能 / 还没被激活的技能声明的禁止清单。
+--   retired-skill-manifest  升级到 7.116.0 之前:停驻、持久化提交体里技能(顶层 skills[] 或子代 agents[].skills[])还带已退役的 manifest 键。
+--   permissions-allow-list  换钉 7.115.0 之前:停驻、提交体 settings.permissions.allow 是非空数组且没有「按表态读」的记号。
+--   retired-mode-seed       换钉 7.113.0 之前:检查点的 inheritedGate 里仍带退役 mode-seed 成员。
+
+-- drain-check:skill-grants-rollback:mysql —— 期望 hit_rows = 0;每一行 = 一条回滚到 7.115.x 后续跑会丢技能禁止行 / 不核卡绑定的停驻行。
+-- 判据四样任一:前两个键(skillGrants 节 / pendingAction.boundGrantDigest)在不在(在却读不出的授予节 7.40 同样不读、一并数);所在会话续跑上下文里提交体的 userInvokedSkills 是非空数组;
+-- 提交体顶层 skills[] 或某只子代 agents[].skills[] 里某一项声明了非空 disallowedTools(那只技能停驻时还没被激活,没有授予行可冻在行上;回滚后上一版不读这个键)。
+SELECT 'skill-grants-rollback' AS criterion, COUNT(*) AS hit_rows,
+       COALESCE(GROUP_CONCAT(k.session_id ORDER BY k.created_at_ms DESC SEPARATOR ','), '') AS sessions
+FROM checkpoint k
+LEFT JOIN checkpoint_ctx c ON c.session_id = k.session_id
+WHERE k.status = 'pending'
+  AND (JSON_CONTAINS_PATH(k.checkpoint, 'one', '$.state.skillGrants', '$.pendingAction.boundGrantDigest')
+       OR (JSON_TYPE(JSON_EXTRACT(c.ctx, '$.body.userInvokedSkills')) = 'ARRAY'
+           AND JSON_LENGTH(JSON_EXTRACT(c.ctx, '$.body.userInvokedSkills')) > 0)
+       OR (JSON_TYPE(JSON_EXTRACT(c.ctx, '$.body.skills')) = 'ARRAY'
+           AND JSON_CONTAINS_PATH(c.ctx, 'one', '$.body.skills[*].disallowedTools[0]'))
+       OR (JSON_TYPE(JSON_EXTRACT(c.ctx, '$.body.agents')) = 'ARRAY'
+           AND JSON_CONTAINS_PATH(c.ctx, 'one', '$.body.agents[*].skills[*].disallowedTools[0]')));
+
+-- drain-check:retired-skill-manifest:mysql —— 期望 hit_rows = 0;每一行 = 一条升级到 7.116.0 后续跑会被引擎拒(顶层 skills[]:行仍 pending、只能取消重提)
+-- 或丢掉子代定义(agents[].skills[]:那只子代定义被整只丢掉并留一条警告日志、任务照跑、少一只子代)的停驻行。
+-- 判据 = 所在会话续跑上下文里提交体的顶层 skills[] 或 agents[].skills[] 某一项带 manifest 键(任何值,含 JSON null)。
+SELECT 'retired-skill-manifest' AS criterion, COUNT(*) AS hit_rows,
+       COALESCE(GROUP_CONCAT(k.session_id ORDER BY k.created_at_ms DESC SEPARATOR ','), '') AS sessions
+FROM checkpoint k
+JOIN checkpoint_ctx c ON c.session_id = k.session_id
+WHERE k.status = 'pending'
+  AND ((JSON_TYPE(JSON_EXTRACT(c.ctx, '$.body.skills')) = 'ARRAY'
+        AND JSON_CONTAINS_PATH(c.ctx, 'one', '$.body.skills[*].manifest'))
+       OR (JSON_TYPE(JSON_EXTRACT(c.ctx, '$.body.agents')) = 'ARRAY'
+           AND JSON_CONTAINS_PATH(c.ctx, 'one', '$.body.agents[*].skills[*].manifest')));
+
+-- drain-check:permissions-allow-list:mysql —— 期望 hit_rows = 0;每一行 = 一条升级后续跑会被拒的停驻行。
+-- 判据 = 服务续跑腿拒臂的同一句话:提交体 settings.permissions.allow 是非空数组,且上下文没有读法记号 permissionsAllowReading = "statement"。
+SELECT 'permissions-allow-list' AS criterion, COUNT(*) AS hit_rows,
+       COALESCE(GROUP_CONCAT(k.session_id ORDER BY k.created_at_ms DESC SEPARATOR ','), '') AS sessions
+FROM checkpoint k
+JOIN checkpoint_ctx c ON c.session_id = k.session_id
+WHERE k.status = 'pending'
+  AND JSON_TYPE(JSON_EXTRACT(c.ctx, '$.body.settings.permissions.allow')) = 'ARRAY'
+  AND JSON_LENGTH(JSON_EXTRACT(c.ctx, '$.body.settings.permissions.allow')) > 0
+  AND COALESCE(JSON_UNQUOTE(JSON_EXTRACT(c.ctx, '$.permissionsAllowReading')), '') <> 'statement';
+
+-- drain-check:retired-mode-seed:mysql —— 期望 hit_rows = 0;每一行 = 一条升级后会被拒的停放行。
+-- 判据逐字照引擎 refuseRetiredModeSeed:inheritedGate 带 autoModeRequested / approverPosture(任何值,含 JSON null),或 shellGate 不是 "always"(含 JSON null)。
+SELECT 'retired-mode-seed' AS criterion, COUNT(*) AS hit_rows,
+       COALESCE(GROUP_CONCAT(k.session_id ORDER BY k.created_at_ms DESC SEPARATOR ','), '') AS sessions
+FROM checkpoint k
+WHERE k.status = 'pending'
+  AND (JSON_CONTAINS_PATH(k.checkpoint, 'one', '$.state.inheritedGate.autoModeRequested', '$.state.inheritedGate.approverPosture')
+       OR (JSON_CONTAINS_PATH(k.checkpoint, 'one', '$.state.inheritedGate.shellGate')
+           AND JSON_UNQUOTE(JSON_EXTRACT(k.checkpoint, '$.state.inheritedGate.shellGate')) <> 'always'));

package/scripts/drain-check.pg.sql

@@ -0,0 +1,71 @@
+-- 换钉 / 回滚前的排空检查 —— PostgreSQL 后端,只读:本文件里只有 SELECT。随 npm 包出。
+--
+-- 怎么跑(整只文件一次跑完,每条判据出一行读数):
+--   psql "<连接串>" -f node_modules/@sema-agent/server/scripts/drain-check.pg.sql
+-- 读数:每条判据一行 `criterion | hit_rows | sessions` ——
+--   criterion  判据名(与随包脚本 drain-check-local.mjs 判据表里的名字同一个词,与下面各段的标记 `-- drain-check:<判据名>:pg` 同一个词);
+--   hit_rows   命中的停驻行数(pending 行里算命中的那些);**全部为 0 才算排空**,非 0 ⇒ 逐条答完或取消(各判据对应的升级 / 回滚说明见随包 MIGRATION.md);
+--   sessions   命中行所在的会话 id,逗号连接,新的在前。
+-- 每段只数 pending 行(已决 / 已过期的行不数);判据只看**键在不在 / 值形**,不读行的其余内容。
+-- DB_BACKEND=local(File 店)没有 SQL:用同目录的 drain-check-local.mjs,四条判据同名。
+--
+-- 四条判据(顺序同 drain-check-local.mjs 的判据表):
+--   skill-grants-rollback   回滚到 7.115.x(引擎 7.40)之前:7.116.0 停驻的行带 7.40 不读的技能授予节 / 卡绑定 / 会话上下文里的人点名技能 / 还没被激活的技能声明的禁止清单。
+--   retired-skill-manifest  升级到 7.116.0 之前:停驻、持久化提交体里技能(顶层 skills[] 或子代 agents[].skills[])还带已退役的 manifest 键。
+--   permissions-allow-list  换钉 7.115.0 之前:停驻、提交体 settings.permissions.allow 是非空数组且没有「按表态读」的记号。
+--   retired-mode-seed       换钉 7.113.0 之前:检查点的 inheritedGate 里仍带退役 mode-seed 成员。
+
+-- drain-check:skill-grants-rollback:pg —— 期望 hit_rows = 0;每一行 = 一条回滚到 7.115.x 后续跑会丢技能禁止行 / 不核卡绑定的停驻行。
+-- 判据四样任一:前两个键(skillGrants 节 / pendingAction.boundGrantDigest)在不在(在却读不出的授予节 7.40 同样不读、一并数);所在会话续跑上下文里提交体的 userInvokedSkills 是非空数组;
+-- 提交体顶层 skills[] 或某只子代 agents[].skills[] 里某一项声明了非空 disallowedTools(那只技能停驻时还没被激活,没有授予行可冻在行上;回滚后上一版不读这个键)。
+SELECT 'skill-grants-rollback' AS criterion, count(*) AS hit_rows,
+       coalesce(string_agg(k.session_id, ',' ORDER BY k.created_at_ms DESC), '') AS sessions
+FROM checkpoint k
+LEFT JOIN checkpoint_ctx c ON c.session_id = k.session_id
+WHERE k.status = 'pending'
+  AND ((k.checkpoint -> 'state') ? 'skillGrants' OR (k.checkpoint -> 'pendingAction') ? 'boundGrantDigest'
+       OR (jsonb_typeof(c.ctx #> '{body,userInvokedSkills}') = 'array' AND (c.ctx #> '{body,userInvokedSkills}') <> '[]'::jsonb)
+       OR EXISTS (SELECT 1
+                  FROM jsonb_array_elements(CASE WHEN jsonb_typeof(c.ctx #> '{body,skills}') = 'array' THEN c.ctx #> '{body,skills}' ELSE '[]'::jsonb END) AS s
+                  WHERE jsonb_typeof(s) = 'object' AND jsonb_typeof(s -> 'disallowedTools') = 'array' AND jsonb_array_length(s -> 'disallowedTools') > 0)
+       OR EXISTS (SELECT 1
+                  FROM jsonb_array_elements(CASE WHEN jsonb_typeof(c.ctx #> '{body,agents}') = 'array' THEN c.ctx #> '{body,agents}' ELSE '[]'::jsonb END) AS a,
+                       jsonb_array_elements(CASE WHEN jsonb_typeof(a -> 'skills') = 'array' THEN a -> 'skills' ELSE '[]'::jsonb END) AS s
+                  WHERE jsonb_typeof(s) = 'object' AND jsonb_typeof(s -> 'disallowedTools') = 'array' AND jsonb_array_length(s -> 'disallowedTools') > 0));
+
+-- drain-check:retired-skill-manifest:pg —— 期望 hit_rows = 0;每一行 = 一条升级到 7.116.0 后续跑会被引擎拒(顶层 skills[]:行仍 pending、只能取消重提)
+-- 或丢掉子代定义(agents[].skills[]:那只子代定义被整只丢掉并留一条警告日志、任务照跑、少一只子代)的停驻行。
+-- 判据 = 所在会话续跑上下文里提交体的顶层 skills[] 或 agents[].skills[] 某一项(对象)带 manifest 键(任何值,含 JSON null)。
+SELECT 'retired-skill-manifest' AS criterion, count(*) AS hit_rows,
+       coalesce(string_agg(k.session_id, ',' ORDER BY k.created_at_ms DESC), '') AS sessions
+FROM checkpoint k
+JOIN checkpoint_ctx c ON c.session_id = k.session_id
+WHERE k.status = 'pending'
+  AND (EXISTS (SELECT 1
+               FROM jsonb_array_elements(CASE WHEN jsonb_typeof(c.ctx #> '{body,skills}') = 'array' THEN c.ctx #> '{body,skills}' ELSE '[]'::jsonb END) AS s
+               WHERE jsonb_typeof(s) = 'object' AND s ? 'manifest')
+       OR EXISTS (SELECT 1
+                  FROM jsonb_array_elements(CASE WHEN jsonb_typeof(c.ctx #> '{body,agents}') = 'array' THEN c.ctx #> '{body,agents}' ELSE '[]'::jsonb END) AS a,
+                       jsonb_array_elements(CASE WHEN jsonb_typeof(a -> 'skills') = 'array' THEN a -> 'skills' ELSE '[]'::jsonb END) AS s
+                  WHERE jsonb_typeof(s) = 'object' AND s ? 'manifest'));
+
+-- drain-check:permissions-allow-list:pg —— 期望 hit_rows = 0;每一行 = 一条升级后续跑会被拒的停驻行。
+-- 判据 = 服务续跑腿拒臂的同一句话:提交体 settings.permissions.allow 是非空数组,且上下文没有读法记号 permissionsAllowReading = "statement"。
+SELECT 'permissions-allow-list' AS criterion, count(*) AS hit_rows,
+       coalesce(string_agg(k.session_id, ',' ORDER BY k.created_at_ms DESC), '') AS sessions
+FROM checkpoint k
+JOIN checkpoint_ctx c ON c.session_id = k.session_id
+WHERE k.status = 'pending'
+  AND jsonb_typeof(c.ctx #> '{body,settings,permissions,allow}') = 'array'
+  AND (c.ctx #> '{body,settings,permissions,allow}') <> '[]'::jsonb
+  AND (c.ctx -> 'permissionsAllowReading') IS DISTINCT FROM '"statement"'::jsonb;
+
+-- drain-check:retired-mode-seed:pg —— 期望 hit_rows = 0;每一行 = 一条升级后会被拒的停放行。
+-- 判据逐字照引擎 refuseRetiredModeSeed:inheritedGate 带 autoModeRequested / approverPosture(任何值,含 JSON null),或 shellGate 不是 "always"(含 JSON null)。
+SELECT 'retired-mode-seed' AS criterion, count(*) AS hit_rows,
+       coalesce(string_agg(k.session_id, ',' ORDER BY k.created_at_ms DESC), '') AS sessions
+FROM checkpoint k
+WHERE k.status = 'pending'
+  AND ((k.checkpoint #> '{state,inheritedGate}') ?| array['autoModeRequested', 'approverPosture']
+       OR (jsonb_typeof(k.checkpoint #> '{state,inheritedGate,shellGate}') IS NOT NULL
+           AND (k.checkpoint #> '{state,inheritedGate,shellGate}') <> '"always"'::jsonb));

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

@@ -1,317 +0,0 @@
-#!/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();