@sema-agent/server 7.115.0 → 7.116.0

package/scripts/drain-check-local.mjs

@@ -1,13 +1,27 @@
 #!/usr/bin/env node
 /**
  * 换钉前的**排空检查 —— `DB_BACKEND=local`(File 店)车道**,只读。随 npm 包出(`scripts/drain-check-local.mjs`)。
- * 一次跑**两条判据**(判据表 {@link DRAIN_CRITERIA},每条一行末行、各自的命中行;SQL 车道的同一判据是 `docs/DEPLOY-PREREQS.md` 各节的只读 SQL):
+ * 一次跑**四条判据**(判据表 {@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 行算不算命中」。
+ * 扫描骨架(快照 + 账本折成当前行、一致性重读、数据根判定)各条判据共用;判据只回答「这一条 pending 行算不算命中」。
  *
  * ## 为什么是一只脚本,不是一行 grep
  *  ① 判据有三条成员(core `refuseRetiredModeSeed`):`autoModeRequested` / `approverPosture` **任何值**(含 JSON null)、
@@ -41,13 +55,16 @@
  *    根 `LOCK` 是 pidfile、干净退出即删,不能当标记)⇒ rc 2,不给结论 —— 路径打错、env 没对上服务,都会读到一个什么都没有的目录。
  *
  * ## 读数(机读末行 + 退出码)
- *  · 每条命中一行:`ALLOW-LIST-ROW token=<token> sessionId=<id> createdAt=<ms>` / `RETIRED-ROW token=<token> sessionId=<id> createdAt=<ms> member=<成员>`;
- *  · 每条判据一行末行(表序;`RETIRED-MODE-SEED` 那一行恒在最后,7.113.0 起读「最后一行」的下游不受影响):
+ *  · 每条命中一行:`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 档 /
+ *  · rc 0 = 每条判据都零命中(可换钉 / 可回滚)· rc 1 = 有命中(逐行列出;答完或取消再跑)· rc 2 = 读不懂 / 没读成 / 不能下结论(账本里有本脚本不认的事件词 / 不合形的记录 / 读不懂的 ctx 档 /
  *    数据根缺席 / 缺省根解析不可用 / 判据模块不可用(脚本隔壁没有 `dist/`:源码树没 build)/ 读期间文件一直在变 / 读文件出错 / 用法错)—— 不给结论(缺席 ≠ 干净:一条读不懂的记录可能正是让某行回到 pending 的那一条)。
  *    rc 2 与 rc 1 同时成立时(有命中、也有读不懂的记录)报 rc 2,命中行照列。
  */
@@ -56,6 +73,9 @@ 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`)。 */
@@ -215,6 +235,18 @@ function retiredMember(gate) {
 /** @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`(不猜它属于哪个会话)、文件名回给调用方;读期间被收割删掉的档跳过。
@@ -254,14 +286,52 @@ function readCtxIndex(root) {
 }
 
 /**
- * 判据表 —— 「哪些 pending 行算命中」。扫描骨架(快照 + 账本折成当前行、一致性重读、数据根判定)两条共用,判据只管这一问:
+ * 判据表 —— 「哪些 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: { allowListReadingUnstated: (ctx: Record<string, unknown>) => boolean }) => { input: unknown, corrupt: number, unreadable: string[] }, judge: (row: Record<string, unknown>, input: unknown) => string | undefined }>}
+ * @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",
@@ -297,6 +367,42 @@ 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 数据根
@@ -321,26 +427,10 @@ export async function drainReport(root, opts = {}) {
     );
   }
   // 判据的唯一实现在服务里;随包形里编译产物在脚本隔壁。取不到(源码树没 build)⇒ 不给结论 —— 绝不退回一份手写的判据。
-  /** @type {{ allowListReadingUnstated: (ctx: Record<string, unknown>) => boolean }} */
-  let service;
-  try {
-    service = await import("../dist/http/checkpoint-ctx.js");
-  } catch (e) {
-    return unreadableReport(
-      "criterion-unavailable",
-      `cannot load the service's own criterion (dist/http/checkpoint-ctx.js 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\`)`,
-      root,
-    );
-  }
   // 模块能加载不等于判据在:产物被截断 / 损坏时 import 照样成功、导出缺席。判据给不出来 ⇒ 同一条「不给结论」,
   // 不许在没有行可判时读成 rows=0,也不许等到调用处抛出(未捕获异常的退出码是 1 = 「有命中」)。
-  if (typeof service?.allowListReadingUnstated !== "function") {
-    return unreadableReport(
-      "criterion-unavailable",
-      "cannot use the service's own criterion (dist/http/checkpoint-ctx.js 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",
-      root,
-    );
-  }
+  const service = await loadServiceCriteria(root);
+  if ("rc" in service) return service;
   let scan;
   /** @type {Array<{ input: unknown, corrupt: number, unreadable: string[] }>} */
   let inputs;

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));