@sema-agent/server 7.112.0 → 7.113.0

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