@sema-agent/server 7.128.0 → 7.129.1

package/dist/plugins/one-time-migrations.js

@@ -1,12 +1,39 @@
+import { SESSION_RULES_GRAMMAR, compileSessionRuleBucket, readSessionRulesShape } from "@sema-agent/core";
 import { SCHEMA_STATEMENTS, acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
 import { PG_SCHEMA_STATEMENTS, acquirePgEnsureSchemaLock, releasePgEnsureSchemaLock } from "./pg-pool.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 import { ensureIndexes } from "./ensure-index.js";
-import { decodeJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, readNonNullJsonValueColumn } from "./sql-json-column.js";
+import { decodeJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, readNonNullJsonValueColumn, readOpaqueJsonValueColumn } from "./sql-json-column.js";
 import { SESSION_META_INCARNATION_COLUMN, mintSessionIncarnation } from "../session-incarnation.js";
 import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError } from "./store-contracts.js";
 import { PERMISSION_RULE_TABLE, purgeUndurableScopeRows } from "./permission-rule-store-sql.js";
 import { SCHEMA_MISMATCH_ERROR_CODE } from "./schema-consistency.js";
+import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
+import { readJsonObjectColumn } from "./sql-json-column.js";
+import { retireStoredCardWords } from "../retired-card-words.js";
+import { redactSecrets } from "../trace/redact.js";
+const RETIRED_SESSION_RULE_BUCKETS = ["commandAllow", "commandDeny"];
+export function buildSessionRuleReceipts() {
+    return { rows: [], renamed: false };
+}
+export class OneTimeMigrationInterruptedError extends Error {
+    receipts;
+    constructor(cause, receipts) {
+        super(`${cause instanceof Error ? cause.message : String(cause)} — one-time migration M17 had already committed changes whose receipts the next boot cannot re-derive ` +
+            "(the rows below are rewritten, so a retry finds nothing left to remove from them) — record them before retrying: " +
+            receipts.sessionRuleRowsWithOldGrammarEntries.map((r) => `${r.policyKey} (session ${r.sessionId}): toolAllowDropped=${JSON.stringify(r.toolAllowDropped)}`).join("; "), { cause });
+        this.name = "OneTimeMigrationInterruptedError";
+        this.receipts = receipts;
+    }
+}
+function interruptedWith(cause, receipts) {
+    if (receipts.rows.length === 0)
+        return cause;
+    return new OneTimeMigrationInterruptedError(cause, {
+        ...(receipts.renamed ? { sessionRuleColumn: "renamed" } : {}),
+        sessionRuleRowsWithOldGrammarEntries: [...receipts.rows],
+    });
+}
 export const ONE_TIME_MIGRATIONS = [
     {
         id: "M4",
@@ -178,6 +205,42 @@ export const ONE_TIME_MIGRATIONS = [
             "models 域降级、rosters 整份读不出 —— 拒句点名迁移 id;出路是运维手跑契约命令行(契约删族之后只剩手改)",
         reportKeys: [],
     },
+    {
+        id: "M17",
+        introducedIn: "7.129.0",
+        releasedOn: "2026-10-15",
+        removableAfter: "2026-11-14",
+        removal: "删 migrateOn 的 M17 步(`migrateSessionRuleGrammar`:`session_policy` 在场探针、旧名 → 进行中的名 → 判读 → 终名三段、退役命令桶扫描与点名)与 " +
+            "`retiredSessionRuleBucketsOf` / `RetiredSessionRuleBucket` / `RETIRED_SESSION_RULE_BUCKETS` / `RETIRED_SESSION_RULES_COLUMN` / `OLD_GRAMMAR_SESSION_RULES_COLUMN` / `SESSION_RULES_SCAN_PAGE` / `SessionRuleRowRetiredBuckets` / " +
+            "`oldGrammarEntriesOf` / `OldGrammarEntries` / `judgeOldGrammarRows` / `renameSessionRulesColumnSql` / `scanSessionRuleRows` / `SessionRuleScanRow` / " +
+            "`RETIRED_BUCKET_PATTERNS` / `SessionRuleRowOldGrammarEntries` / 收据账 `SessionRuleReceipts` / `buildSessionRuleReceipts` / `OneTimeMigrationReceipts` / " +
+            "`OneTimeMigrationInterruptedError` / `interruptedWith`(`migrateOn` 外层的那一道 try / catch)/ `logOneTimeMigrationsInterrupted` / `runAndLogOneTimeMigrations` 里的失败日志臂 / `logSessionRuleOldGrammarRows`;" +
+            "报告、日志行(含逐行的 `session_rule_row_retired_bucket` 与 `session_rule_row_old_grammar_entries`)与 `NO_SQL_MIGRATIONS` 的 `sessionRuleColumn` / " +
+            "`sessionRuleRowsWithRetiredBuckets` / `sessionRuleRowsWithOldGrammarEntries`;" +
+            "**列名本身留在中央 DDL 里**(`session-rules-column.ts`,它不是迁移的一部分)",
+        afterRemoval: "① 列还叫 `rules`、或停在进行中的名 `rule_entries_old_grammar` 的存量库(跳过了带本条的版本直接升 / 判读没走完就跳版):起服列册探针 `schema-consistency.ts`(S-547)拒启 " +
+            "`config.schema_mismatch`(缺 `rule_entries`、多那一列)—— " +
+            "出路是先在一只带本条的版本上起服一次;② 行里仍带退役命令桶:SQL 店读回照旧答 `corrupt`(引擎的形读法点名那只桶,与本条在场时同一个结局),只是起服日志不再逐行点名 —— " +
+            "运维在库里把那一行改写成引擎文法或删掉它(删会话即删规则);③ 跳过本条直接升的库同样没有改名那一拍的条目判读 —— 由 ① 的拒启接住(出路同 ①)",
+        reportKeys: ["sessionRuleColumn", "sessionRuleRowsWithRetiredBuckets", "sessionRuleRowsWithOldGrammarEntries"],
+    },
+    {
+        id: "M18",
+        introducedIn: "7.129.0",
+        releasedOn: "2026-10-15",
+        removableAfter: "2026-11-14",
+        removal: "删 migrateOn 的 M18 步(`migrateRetiredCardWords` 的存卡扫描、`migrateRetiredCardWordsInCardJson`、" +
+            "`RETIRED_CARD_WORD_PATTERNS` / `RETIRED_CARD_WORD_BATCH`);报告、日志行与 `NO_SQL_MIGRATIONS` 的 `retiredCardWordAskRowsRewritten` / " +
+            "`retiredCardWordRowsUnreadable`;**连同读侧半场一起删**:`src/retired-card-words.ts` 整只文件、" +
+            "`approval-card.ts` 里 `readStoredCardEnvelope` 的改写那一步与 `currentParkArm`(两读者 `parkRowFacts` / `tool-approval.ts` `parkRowStandingAnswerFacts` " +
+            "回到直读传入的那一只)与 `noteRetiredCardWordRead`、fail-open tag `server.approval-card.retired-card-word-read`(`observability/fail-open.ts` 与 " +
+            "`docs/FAIL-OPEN-CENSUS.md` 那一行)、`test/retired-card-words-m18.test.ts`(唯一入口那一格改钉到 `approval-card.test.ts`)",
+        afterRemoval: "既有坏行臂接住(响亮,不再改写):仍带退役词的存卡(跳过了带本条的版本直接升的库、窗关之后还在写的 7.128.x 副本)整卡读不出 —— 断连重放跳过 + 一次 warn、" +
+            "幂等重入走 park、回决口按要人;仍带它们的待决停驻行(把 `APPROVAL_TERMINAL_BACKSTOP_MS` 调长的部署、local 车道引擎 File 店里窗关仍未决的 —— 停驻行从来不由本服务改写," +
+            "窗内靠读侧改写读,窗关后读侧改写删)由本服务的读面按坏行处置:运维队列行缺那一位 + `server.approval-card.closed-word-out-of-set` 计数、耐久 `/decide` 的 remember 按强制(只放行这一次)。" +
+            "引擎续跑不受影响:续跑入口读行摘要、不按今日闭集重判停驻行上的这两座,行字节引擎怎么写的还是怎么在",
+        reportKeys: ["retiredCardWordAskRowsRewritten", "retiredCardWordRowsUnreadable"],
+    },
 ];
 export function migrationWindowOpen(window, today) {
     return window.removableAfter === null || today <= window.removableAfter;
@@ -193,6 +256,11 @@ export const NO_SQL_MIGRATIONS = {
     undurableScopeRuleRows: [],
     undurableScopeRuleBucketsDeferred: 0,
     undurableScopeRuleBucketsUnreadable: [],
+    sessionRuleColumn: "file-store",
+    sessionRuleRowsWithRetiredBuckets: [],
+    sessionRuleRowsWithOldGrammarEntries: [],
+    retiredCardWordAskRowsRewritten: 0,
+    retiredCardWordRowsUnreadable: 0,
 };
 const AUDIT_TABLE = "device_audit";
 const AUDIT_DETAIL_COLUMN = "detail";
@@ -318,6 +386,15 @@ async function withPgLock(pool, run) {
     }
 }
 async function migrateOn(db, dialect) {
+    const receipts = buildSessionRuleReceipts();
+    try {
+        return await migrateStepsOn(db, dialect, receipts);
+    }
+    catch (e) {
+        throw interruptedWith(e, receipts);
+    }
+}
+async function migrateStepsOn(db, dialect, receipts) {
     const auditTablePresent = await tableExists(db, dialect, AUDIT_TABLE);
     const auditDetailJsonNullRows = !auditTablePresent
         ? 0
@@ -331,7 +408,9 @@ async function migrateOn(db, dialect) {
             ? "UPDATE task_run SET error_code = ? WHERE status = 'failed' AND error_code IS NULL AND (error = ? OR error LIKE ?)"
             : "UPDATE task_run SET error_code = $1 WHERE status = 'failed' AND error_code IS NULL AND (error = $2 OR error LIKE $3)", [RUN_HOLDER_DEATH_CODES.orphaned, RUN_ORPHANED_ERROR, `${RUN_ORPHANED_ERROR} (%`]));
     const { migrated: allowRuleShadowRowsMigrated, unreadable: allowRuleShadowRowsUnreadable } = await migrateShadowedRuleKey(db, dialect);
+    const { askRows: retiredCardWordAskRowsRewritten, unreadable: retiredCardWordRowsUnreadable } = await migrateRetiredCardWords(db, dialect);
     const { key: workflowParkIndexKey, carried: workflowParkIndexRowsCarried } = await reshapeWorkflowParkIndex(db, dialect);
+    const { sessionRuleColumn, sessionRuleRowsWithRetiredBuckets, sessionRuleRowsWithOldGrammarEntries } = await migrateSessionRuleGrammar(db, dialect, receipts);
     let undurableScopeRuleRows = [];
     let undurableScopeRuleBucketsDeferred = 0;
     let undurableScopeRuleBucketsUnreadable = [];
@@ -342,8 +421,113 @@ async function migrateOn(db, dialect) {
         auditDetailJsonNullRows,
         sessionIncarnationColumn, sessionIncarnationsBackfilled, holderDeathCodeRowsBackfilled, allowRuleShadowRowsMigrated, allowRuleShadowRowsUnreadable,
         workflowParkIndexKey, workflowParkIndexRowsCarried, undurableScopeRuleRows, undurableScopeRuleBucketsDeferred, undurableScopeRuleBucketsUnreadable,
+        sessionRuleColumn, sessionRuleRowsWithRetiredBuckets, sessionRuleRowsWithOldGrammarEntries,
+        retiredCardWordAskRowsRewritten, retiredCardWordRowsUnreadable,
     };
 }
+const SESSION_POLICY_TABLE = "session_policy";
+const RETIRED_SESSION_RULES_COLUMN = "rules";
+const OLD_GRAMMAR_SESSION_RULES_COLUMN = "rule_entries_old_grammar";
+const SESSION_RULES_SCAN_PAGE = 500;
+export function retiredSessionRuleBucketsOf(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return [];
+    return RETIRED_SESSION_RULE_BUCKETS.filter((b) => Object.hasOwn(body, b));
+}
+export function oldGrammarEntriesOf(body, rev) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const retired = retiredSessionRuleBucketsOf(body);
+    const buckets = Object.fromEntries(Object.entries(body).filter(([k]) => !retired.includes(k)));
+    const shaped = readSessionRulesShape({ ...buckets, rev });
+    if ("fault" in shaped)
+        return undefined;
+    const compiled = compileSessionRuleBucket(shaped.rules, "toolAllow");
+    if (body.grammar === undefined && compiled.inert.some((i) => i.reason === "wildcard_all"))
+        return { toolAllowDropped: [], wildcardMasked: true };
+    const earlier = new Set(compiled.inert.filter((i) => i.reason === "earlier_grammar").map((i) => i.entry));
+    const toolAllow = shaped.rules.toolAllow?.filter((e) => !earlier.has(e));
+    const toolAllowDropped = (shaped.rules.toolAllow ?? []).filter((e) => earlier.has(e));
+    if (toolAllowDropped.length === 0 && body.grammar !== undefined)
+        return { toolAllowDropped };
+    return { toolAllowDropped, rewritten: { ...body, ...(toolAllow !== undefined ? { toolAllow } : {}), grammar: SESSION_RULES_GRAMMAR } };
+}
+const RETIRED_BUCKET_PATTERNS = ['%"commandDeny"%', '%"commandAllow"%'];
+async function scanSessionRuleRows(db, dialect, column, patterns, visit) {
+    const text = jsonColumnTextExpr(dialect, column);
+    const prefilter = patterns.length === 0 ? "" : ` AND (${patterns.map((_, i) => `${text} LIKE ${dialect === "tidb" ? "?" : `$${i + 2}`}`).join(" OR ")})`;
+    const scan = dialect === "tidb"
+        ? `SELECT policy_key, session_id, rev, ${jsonColumnText("tidb", column)} FROM ${SESSION_POLICY_TABLE} WHERE policy_key > ?${prefilter} ORDER BY policy_key LIMIT ${SESSION_RULES_SCAN_PAGE}`
+        : `SELECT policy_key, session_id, rev, ${jsonColumnText("pg", column)} FROM ${SESSION_POLICY_TABLE} WHERE policy_key > $1${prefilter} ORDER BY policy_key LIMIT ${SESSION_RULES_SCAN_PAGE}`;
+    let cursor = "";
+    for (;;) {
+        const page = await db.rows(scan, [cursor, ...patterns]);
+        for (const row of page) {
+            let body;
+            try {
+                body = decodeJsonColumn(row[column], readOpaqueJsonValueColumn, "session_policy.rule_entries for the M17 scans (read under its in-progress name while the old-grammar judge runs)");
+            }
+            catch (e) {
+                if (!isJsonColumnBodyProblem(e))
+                    throw e;
+                continue;
+            }
+            await visit({ policyKey: String(row.policy_key), sessionId: String(row.session_id), rev: Number(row.rev), text: String(row[column]), body });
+        }
+        if (page.length < SESSION_RULES_SCAN_PAGE)
+            return;
+        cursor = String(page[page.length - 1].policy_key);
+    }
+}
+async function judgeOldGrammarRows(db, dialect, receipts) {
+    const column = OLD_GRAMMAR_SESSION_RULES_COLUMN;
+    const text = jsonColumnTextExpr(dialect, column);
+    const cas = dialect === "tidb"
+        ? `UPDATE ${SESSION_POLICY_TABLE} SET ${column} = ? WHERE policy_key = ? AND CAST(${text} AS BINARY) = CAST(? AS BINARY)`
+        : `UPDATE ${SESSION_POLICY_TABLE} SET ${column} = $1::jsonb WHERE policy_key = $2 AND ${text} = $3`;
+    await scanSessionRuleRows(db, dialect, column, [], async (row) => {
+        const read = oldGrammarEntriesOf(row.body, row.rev);
+        if (read?.wildcardMasked) {
+            receipts.rows.push({ policyKey: row.policyKey, sessionId: row.sessionId, toolAllowDropped: [], wildcardMasked: true });
+            return;
+        }
+        if (read?.rewritten === undefined)
+            return;
+        if ((await db.exec(cas, [JSON.stringify(read.rewritten), row.policyKey, row.text])) !== 1) {
+            throw new Error(`one-time migration M17: session_policy row ${row.policyKey} changed while its rule entries were being rewritten under the in-progress column ${column} — no writer can reach the ` +
+                "table at that moment (builds up to 7.128.x lost the column, this build's replicas wait on the boot lock), so the step refuses rather than guess");
+        }
+        if (read.toolAllowDropped.length > 0)
+            receipts.rows.push({ policyKey: row.policyKey, sessionId: row.sessionId, toolAllowDropped: read.toolAllowDropped.map((e) => redactSecrets(e)) });
+    });
+}
+export async function migrateSessionRuleGrammar(db, dialect, receipts) {
+    if (!(await tableExists(db, dialect, SESSION_POLICY_TABLE)))
+        return { sessionRuleColumn: "no-table", sessionRuleRowsWithRetiredBuckets: [], sessionRuleRowsWithOldGrammarEntries: [] };
+    const col = SESSION_RULES_COLUMN;
+    const has = (column) => columnExists(db, dialect, SESSION_POLICY_TABLE, column);
+    if (await has(RETIRED_SESSION_RULES_COLUMN)) {
+        await execUntil(db, renameSessionRulesColumnSql(dialect, RETIRED_SESSION_RULES_COLUMN, OLD_GRAMMAR_SESSION_RULES_COLUMN), async () => !(await has(RETIRED_SESSION_RULES_COLUMN)));
+    }
+    let sessionRuleColumn = "current";
+    if (await has(OLD_GRAMMAR_SESSION_RULES_COLUMN)) {
+        await judgeOldGrammarRows(db, dialect, receipts);
+        await execUntil(db, renameSessionRulesColumnSql(dialect, OLD_GRAMMAR_SESSION_RULES_COLUMN, col.name), async () => !(await has(OLD_GRAMMAR_SESSION_RULES_COLUMN)) && (await has(col.name)));
+        receipts.renamed = true;
+        sessionRuleColumn = "renamed";
+    }
+    const named = [];
+    await scanSessionRuleRows(db, dialect, col.name, RETIRED_BUCKET_PATTERNS, async (row) => {
+        const buckets = retiredSessionRuleBucketsOf(row.body);
+        if (buckets.length > 0)
+            named.push({ policyKey: row.policyKey, sessionId: row.sessionId, buckets });
+    });
+    return { sessionRuleColumn, sessionRuleRowsWithRetiredBuckets: named, sessionRuleRowsWithOldGrammarEntries: receipts.rows };
+}
+function renameSessionRulesColumnSql(dialect, from, to) {
+    const definition = SESSION_RULES_COLUMN.tidb.slice(SESSION_RULES_COLUMN.name.length);
+    return dialect === "tidb" ? `ALTER TABLE ${SESSION_POLICY_TABLE} CHANGE COLUMN ${from} ${to}${definition}` : `ALTER TABLE ${SESSION_POLICY_TABLE} RENAME COLUMN ${from} TO ${to}`;
+}
 const WORKFLOW_PARK_INDEX_TABLE = "workflow_agent_session";
 async function primaryKeyWidth(db, dialect, table) {
     const sql = dialect === "tidb"
@@ -472,6 +656,57 @@ async function migrateShadowedRuleKey(db, dialect) {
             return { migrated, unreadable };
     }
 }
+const RETIRED_CARD_WORD_PATTERNS = ['%"shadowed"%', '%"governance_unavailable"%'];
+const RETIRED_CARD_WORD_BATCH = 500;
+function decodeForM18(text, where) {
+    try {
+        return { ok: true, value: decodeJsonColumn(text, readJsonObjectColumn, where) };
+    }
+    catch (error) {
+        if (isJsonColumnBodyProblem(error))
+            return { ok: false, error };
+        throw error;
+    }
+}
+export function migrateRetiredCardWordsInCardJson(text) {
+    const decoded = decodeForM18(text, "approval_ask.card_json (M18 rewrite)");
+    if (!decoded.ok)
+        return { kind: "unreadable", error: decoded.error };
+    const next = retireStoredCardWords(decoded.value);
+    return next.seats.length === 0 ? { kind: "untouched" } : { kind: "rewrite", text: JSON.stringify(next.value), value: next.value };
+}
+async function migrateRetiredCardWords(db, dialect) {
+    let askRows = 0;
+    let unreadable = 0;
+    if (!(await tableExists(db, dialect, "approval_ask")))
+        return { askRows, unreadable };
+    const cardText = jsonColumnTextExpr(dialect, "card_json");
+    let after = "";
+    for (;;) {
+        const rows = await db.rows(dialect === "tidb"
+            ? `SELECT ask_id, ${jsonColumnText(dialect, "card_json")} FROM approval_ask WHERE (${cardText} LIKE ? OR ${cardText} LIKE ?) AND ask_id > ? ORDER BY ask_id LIMIT ${RETIRED_CARD_WORD_BATCH}`
+            : `SELECT ask_id, ${jsonColumnText(dialect, "card_json")} FROM approval_ask WHERE (${cardText} LIKE $1 OR ${cardText} LIKE $2) AND ask_id > $3 ORDER BY ask_id LIMIT ${RETIRED_CARD_WORD_BATCH}`, [...RETIRED_CARD_WORD_PATTERNS, after]);
+        for (const r of rows) {
+            const askId = String(r.ask_id);
+            after = askId;
+            const text = r.card_json;
+            if (typeof text !== "string")
+                continue;
+            const next = migrateRetiredCardWordsInCardJson(text);
+            if (next.kind === "unreadable") {
+                unreadable += 1;
+                continue;
+            }
+            if (next.kind === "untouched")
+                continue;
+            askRows += await db.exec(dialect === "tidb"
+                ? `UPDATE approval_ask SET card_json = ? WHERE ask_id = ? AND CAST(${cardText} AS BINARY) = CAST(? AS BINARY)`
+                : `UPDATE approval_ask SET card_json = $1 WHERE ask_id = $2 AND ${cardText} = $3`, [next.text, askId, text]);
+        }
+        if (rows.length < RETIRED_CARD_WORD_BATCH)
+            return { askRows, unreadable };
+    }
+}
 const INCARNATION_BACKFILL_BATCH = 500;
 async function migrateSessionIncarnations(db, dialect) {
     if (!(await tableExists(db, dialect, "session_meta")))
@@ -530,7 +765,9 @@ export function logOneTimeMigrations(log, backend, report) {
     const changed = report.auditDetailJsonNullRows > 0 ||
         report.sessionIncarnationColumn === "added" || report.sessionIncarnationsBackfilled > 0 || report.holderDeathCodeRowsBackfilled > 0 || report.allowRuleShadowRowsMigrated > 0 || report.allowRuleShadowRowsUnreadable > 0 ||
         report.workflowParkIndexKey === "reshaped" || report.undurableScopeRuleRows.length > 0 || report.undurableScopeRuleBucketsDeferred > 0 ||
-        report.undurableScopeRuleBucketsUnreadable.length > 0;
+        report.undurableScopeRuleBucketsUnreadable.length > 0 ||
+        report.sessionRuleColumn === "renamed" || report.sessionRuleRowsWithRetiredBuckets.length > 0 || report.sessionRuleRowsWithOldGrammarEntries.length > 0 ||
+        report.retiredCardWordAskRowsRewritten > 0 || report.retiredCardWordRowsUnreadable > 0;
     (changed ? log.warn : log.info).call(log, "one_time_migrations_applied", {
         backend,
         auditDetailJsonNullRows: report.auditDetailJsonNullRows,
@@ -544,6 +781,11 @@ export function logOneTimeMigrations(log, backend, report) {
         undurableScopeRuleRowsRemoved: report.undurableScopeRuleRows.length,
         undurableScopeRuleBucketsDeferred: report.undurableScopeRuleBucketsDeferred,
         undurableScopeRuleBucketsUnreadable: report.undurableScopeRuleBucketsUnreadable.length,
+        sessionRuleColumn: report.sessionRuleColumn,
+        sessionRuleRowsWithRetiredBuckets: report.sessionRuleRowsWithRetiredBuckets.length,
+        sessionRuleRowsWithOldGrammarEntries: report.sessionRuleRowsWithOldGrammarEntries.length,
+        retiredCardWordAskRowsRewritten: report.retiredCardWordAskRowsRewritten,
+        retiredCardWordRowsUnreadable: report.retiredCardWordRowsUnreadable,
         removableAfter: Object.fromEntries(ONE_TIME_MIGRATIONS.map((w) => [w.id, w.removableAfter])),
         note: "one-time persisted-data migrations (M4: audit details written as the JSON " +
             "text `null` by an earlier version folded to a SQL NULL, so \"no detail\" has exactly one on-disk spelling; M5: the " +
@@ -556,7 +798,16 @@ export function logOneTimeMigrations(log, backend, report) {
             "on a session written by an earlier version (which recorded no owner) claims that session for the principal, one session_owner_claimed line per claim; " +
             "M11: persisted permission rules whose project scope root is not a complete absolute path — accepted by earlier versions, dropped on every read " +
             "by the current engine and not removable through DELETE /v1/rules — removed, one permission_rule_row_removed line per row; a bucket the read path " +
-            "refuses in whole is left untouched, one permission_rule_bucket_unreadable line per bucket). Each step " +
+            "refuses in whole is left untouched, one permission_rule_bucket_unreadable line per bucket; M17: the session-rules column renamed from `rules` to " +
+            "`rule_entries`, so a build that reads rules under the earlier name-only grammar finds no column to misread; at that rename every row's rule entries " +
+            "are read by the engine in the grammar the row carries (none = the grammar before the stamp) and rewritten as the same statement in the current grammar " +
+            "(the column carries the in-progress name rule_entries_old_grammar until every row is rewritten, so an interrupted boot resumes there) — toolAllow entries " +
+            "that the earlier grammar read as naming no tool are removed from the row, every row is stamped with the current grammar, one session_rule_row_old_grammar_entries " +
+            "line per row that lost entries; " +
+            "rows still holding a retired command bucket keep that bucket and are named, one session_rule_row_retired_bucket line per row on every boot; " +
+            "M18: stored approval cards written by an earlier engine with two words the current engine retired rewritten — ruleOffersAbsence shadowed removed, ask class " +
+            "governance_unavailable read as rule_unreadable; the engine's own parked-row documents are never rewritten (their row digest covers the ask class), they and " +
+            "the cards this step cannot reach are read the same way, counted under server.approval-card.retired-card-word-read). Each step " +
             "runs on every boot until its window closes (the release that introduced it + 30 days; the per-step date is in " +
             "removableAfter, null while that release is not published yet) and is deleted in the first minor after that — start a " +
             "version that still carries a step at least once before upgrading past its deletion.",
@@ -582,6 +833,67 @@ export function logOneTimeMigrations(log, backend, report) {
                 "keeps being refused, as before this release, until someone repairs or deletes that row by hand",
         });
     }
+    logSessionRuleOldGrammarRows(log, backend, report.sessionRuleRowsWithOldGrammarEntries);
+    for (const row of report.sessionRuleRowsWithRetiredBuckets) {
+        log.warn("session_rule_row_retired_bucket", {
+            backend,
+            policyKey: row.policyKey,
+            sessionId: row.sessionId,
+            buckets: row.buckets,
+            note: "a session's stored rules hold a retired command bucket (commandAllow / commandDeny), which the current rule grammar does not read: the bucket is left " +
+                "as written and every read of the row is refused as corrupt (the session's rules face answers 500 and its new tasks do not start). No rewrite is made for " +
+                "you: the retired bucket also refused every shell command line it could not read as one command name (a path such as /bin/rm, pipelines, &&), which no " +
+                "rule entry refuses. Rewrite the row in the database in the current grammar (toolDeny entries such as Bash(rm:*), or Bash to refuse the shell outright; " +
+                "keep rev and gen) or delete the session (deleting the session deletes its rules)",
+        });
+    }
+}
+function logSessionRuleOldGrammarRows(log, backend, rows) {
+    for (const row of rows) {
+        log.warn("session_rule_row_old_grammar_entries", {
+            backend,
+            policyKey: row.policyKey,
+            sessionId: row.sessionId,
+            toolAllowDropped: row.toolAllowDropped,
+            ...(row.wildcardMasked ? { wildcardMasked: true } : {}),
+            note: row.wildcardMasked
+                ? "a session's stored rules were written before the rule-grammar stamp and its toolAllow list holds `*`: the engine reads that list as void in every grammar (every call " +
+                    "refused), which hides what the other entries meant in the earlier grammar, so this row was NOT rewritten or stamped — it stays in its earlier grammar. To restore the other " +
+                    "entries, an operator rewrites the row without `*` (entries spelled as rules, `Bash(rm:*)`, then become allow rules — review them first)."
+                :
+                    "a session's stored rules were written before the rule-grammar stamp, when an entry was compared as a tool name as written; the engine reads such a row " +
+                        "in that earlier grammar, where these toolAllow entries named no tool and admitted nothing, while in the current grammar they would be allow rules. " +
+                        "The row was rewritten as the same statement in the current grammar: these entries were removed and the row stamped (an emptied list stays in place and allows " +
+                        "nothing); toolDeny entries read the same in every grammar and were left as written. Every entry named on this line is named exactly once, by the boot that " +
+                        "removed it — no later boot lists it again — so keep the line. Write the session's rules afresh through the session policy endpoint if an entry was meant as an allow rule",
+        });
+    }
+}
+function logOneTimeMigrationsInterrupted(log, backend, error) {
+    const { receipts } = error;
+    log.warn("one_time_migrations_interrupted", {
+        backend,
+        sessionRuleColumn: receipts.sessionRuleColumn ?? "in-progress",
+        sessionRuleRowsWithOldGrammarEntries: receipts.sessionRuleRowsWithOldGrammarEntries.length,
+        note: "the one-time migrations failed after committing changes whose receipts the next boot cannot re-derive: the session_rule_row_old_grammar_entries lines that follow name " +
+            "rows this boot already rewrote — a retried boot finds them rewritten and removes nothing from them. These lines are the only place the rewritten rows are ever " +
+            "reported — no later boot lists them — so save them. The failure itself follows as this boot's refusal. sessionRuleColumn \"renamed\": every row was rewritten and the final " +
+            "column name was published before the failure; \"in-progress\": the column still carries its in-progress name — the next boot rewrites the remaining rows (rows already " +
+            "rewritten are left alone) and publishes the final name",
+    });
+    logSessionRuleOldGrammarRows(log, backend, receipts.sessionRuleRowsWithOldGrammarEntries);
+}
+export async function runAndLogOneTimeMigrations(log, backend) {
+    let report;
+    try {
+        report = await backend.runOneTimeMigrations();
+    }
+    catch (e) {
+        if (e instanceof OneTimeMigrationInterruptedError)
+            logOneTimeMigrationsInterrupted(log, backend.kind, e);
+        throw e;
+    }
+    logOneTimeMigrations(log, backend.kind, report);
 }
 function removedRuleRowNote(kind) {
     switch (kind) {

package/dist/plugins/pg-pool.js

@@ -17,6 +17,7 @@ import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
 import { ensurePgLeaderRunSchema } from "./leader-run-store-sql.js";
 import { ensurePgRetentionSchema } from "./retention-store-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
@@ -176,7 +177,8 @@ export const PG_SCHEMA_STATEMENTS = [
      -- sha256, so the principal is not recoverable from it. Enumeration-only — it is NOT part of the key and
      -- NOT part of the CAS / tighten-only path. NULL = a session-wide (principal-less) policy row.
      principal  VARCHAR(190) COLLATE "C",
-     rules      JSONB          NOT NULL,
+     -- 会话规则(TiDB 孪生同注:列定义唯一属主 = session-rules-column.ts 的 SESSION_RULES_COLUMN;7.128.x 及以前叫 rules,存量库由 M17 改名)。
+     ${SESSION_RULES_COLUMN.pg},
      rev        BIGINT         NOT NULL,
      -- gen (core 7.25.0 StoredSessionRules.gen, S-529 二期):TiDB 孪生同注 —— 这一行的血统,DEFAULT 0 = 第 0 代。
      gen        BIGINT         NOT NULL DEFAULT 0,

package/dist/plugins/remote-env-e2b.d.ts

@@ -71,8 +71,9 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers {
      *  isRunning/files.*. A provider hang is surfaced as a typed retryable `RemoteExecutionError("timeout")` after
      *  this, instead of pinning the worker for the sandbox lifetime. Default {@link DEFAULT_RPC_TIMEOUT_MS}. */
     rpcTimeoutMs?: number;
-    /** 🔴 (hang class-fix) Idle/liveness bound (ms) for a command (exec/execStream): max time with NO output
-     *  and not yet complete = suspected hang. Also bounds the command-creation RPC. Default {@link DEFAULT_LIVENESS_MS}. */
+    /** 🔴 (hang class-fix) The lane's idle/liveness bound (ms; env `E2B_LIVENESS_MS`): max time with NO output and not yet
+     *  complete = suspected hang — cuts a running command ONLY when its caller stated neither a wall-clock (`timeout`) nor its own
+     *  idle bound (`readTimeoutMs`); the rule: `exec-bounds.ts` (creation included). Positive only (`laneLivenessOf`). Default `LIVENESS_MS_DEFAULT`. */
     livenessMs?: number;
     /** 🔴 Wall-clock for data-transfer/provisioning RPCs (large file io, snapshot suspend/resume,
      *  create/connect) — wider than {@link rpcTimeoutMs} so a legit multi-minute transfer is not killed. Default
@@ -105,6 +106,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     readonly cdPath: "unknown";
     private readonly cfg;
     private readonly sandboxApi;
+    /** This lane's own liveness bound — what {@link commandBoundsOf} falls back to when a command's caller stated no bound. */
+    private readonly laneLiveness;
     private sbx?;
     /** 🔴 BL-31 keep-alive — the E2B sandbox lifetime is hard-capped (≈1h, {@link E2B_SANDBOX_MAX_MS}), but a long
      *  leader/repair run legitimately exceeds it. This interval RE-extends the sandbox (`setTimeout(timeoutMs)` resets
@@ -287,23 +290,42 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      * the adapter NEVER blind-retries). A caller AbortSignal still aborts independently (op surfaces it / "aborted").
      */
     private rpc;
+    /**
+     * A command start that already returned to its caller (its creation deadline fired, or it failed): a handle the provider
+     * hands over LATER is killed — the caller was told the command was cut, so it must not run on. The rule for the in-flight
+     * count this start holds: it is released **once, and only when the command is confirmed not running** (council #4: never
+     * snapshot a running command). Confirmations: the provider answered `kill()` (`true` killed / `false` no such process);
+     * the handle's one `wait()` reports the process exited (a result, or `CommandExitError` for a non-zero exit). Not
+     * confirmations: a refused `kill()` (logged; the exit is still awaited), a `wait()` that ends without an exit (the
+     * connection deadline, a lost stream — the process may still run). With neither the count stays held and `suspendVM`
+     * keeps refusing `command_in_flight` — the same arm as a start that never settles. No start promise (the op never ran)
+     * ⇒ released now. A failed start is released at once too, as in 7.129.0 — and that one is NOT a confirmation: there is
+     * no handle to kill or wait on, and a start whose reply was lost (the SDK's own 60 s handshake) may have spawned the
+     * process. Closing it means classifying the start failure (provider refused ⇒ not started; lost reply ⇒ held) — open,
+     * not done here.
+     */
+    private settleAbandonedStart;
     /**
      * Per-command wall-clock for the E2B SDK (seconds→ms). 🔴 This is a PHYSICAL CAP, NOT the hang
      * detector. The old code returned `this.cfg.timeoutMs` (the sandbox lifetime) when no `timeout` was given AND
      * had no liveness check → a hung command waited the WHOLE lifetime (~30 min, the original hang bug). The fix is
      * NOT to shorten this cap (that would spuriously kill a long-but-progressing `npm ci`) — it's to add a LIVENESS
      * bound ({@link cfg.livenessMs}) in exec/execStream that catches a *zero-progress* command in ~livenessMs,
-     * independent of this cap. So: explicit caller `timeout` wins; else the lifetime is the cap (a command can't
-     * outlive its VM) but hang detection no longer depends on it.
+     * independent of this cap. So: explicit caller `timeout` wins — and is then the command's bound (the liveness bound
+     * stays out, `exec-bounds.ts`); else the lifetime is the cap (a command can't outlive its VM) and the liveness bound
+     * is the hang detector.
      */
     private commandTimeoutMs;
     /**
-     * 🔴 Liveness for the buffered exec WAIT phase. `handle.wait()` is a long-poll with no read timeout —
+     * 🔴 Bounds for the buffered exec WAIT phase. `handle.wait()` is a long-poll with no read timeout —
      * a command that hangs DURING execution (not creation) would otherwise wait the E2B command timeout (= the
-     * lifetime when none is set, the original hang bug). Races wait() against an idle check: if no stdout/stderr for
-     * `livenessMs`, the command is hung → kill + typed retryable "timeout". `lastProgress()` is bumped by the
-     * stdout/stderr callbacks, so a slow-but-PROGRESSING command (long `npm ci`) is never killed. (execStream has
-     * its own chunk-driven idle timer; this is the buffered-exec analogue.)
+     * lifetime when none is set, the original hang bug). With a `liveness` bound (the caller stated no `timeout` —
+     * `exec-bounds.ts`) it races wait() against an idle check: no stdout/stderr for `liveness.ms` ⇒ hung → kill + typed
+     * retryable "timeout" with the shared cut sentence. `lastProgress()` is bumped by the stdout/stderr callbacks, so a
+     * slow-but-PROGRESSING command (long `npm ci`) is never killed. Both cuts reject with an `ExecutionError` carrying
+     * its real code (exec returns it as-is) — a `RemoteExecutionError` here would reach {@link execError}'s text match
+     * and land as `unknown`. The rejection is armed BEFORE the kill: the kill rejects `wait()` too, and the race must
+     * see the bound, not the kill. (execStream has its own chunk-driven idle timer; this is the buffered-exec analogue.)
      */
     private waitWithLiveness;
     /** Lazily provision the VM on first use: a task that never touches the hand pays zero cost.