@sema-agent/server 7.147.0 → 7.149.0

package/dist/store-posture.js

@@ -1,4 +1,7 @@
+import { readdirSync } from "node:fs";
 import { projectSqlEngineCapability } from "./sql-engine-posture.js";
+import { parseMountinfo, readProcessMountinfo, visibleMountOf } from "./mountinfo.js";
+import { recordFailOpen } from "./observability/fail-open.js";
 export const STORE_DEGRADED_REASONS = ["local_unwritable"];
 export function storeDegradedReasonFor(declared) {
     switch (declared) {
@@ -16,19 +19,218 @@ export function storeDegradedReasonFor(declared) {
     }
 }
 export function sessionStoreLabelOf(sessionBackend, backendKind) {
-    return sessionBackend === "tidb" && backendKind !== undefined ? `durable(${backendKind})` : sessionBackend;
+    return sessionBackend === "tidb" && backendKind !== undefined ? backendKind : sessionBackend;
+}
+export const STORE_DURABILITIES = ["durable", "ephemeral", "unknown"];
+export const STORE_ROOTS = ["data", "sealed_key", "memory"];
+export const STORE_DURABILITY_RULES = [
+    "backend_memory",
+    "backend_sql",
+    "fs_volatile",
+    "k8s_empty_dir",
+    "k8s_persistent_volume",
+    "network_fs",
+    "block_device",
+    "unrecognized_mount",
+    "mount_unresolved",
+    "mountinfo_unreadable",
+    "mountinfo_malformed",
+    "path_unresolvable",
+    "not_linux",
+];
+export function durabilityOfRule(rule) {
+    switch (rule) {
+        case "backend_sql":
+        case "k8s_persistent_volume":
+        case "network_fs":
+        case "block_device":
+            return "durable";
+        case "backend_memory":
+        case "fs_volatile":
+        case "k8s_empty_dir":
+            return "ephemeral";
+        case "unrecognized_mount":
+        case "mount_unresolved":
+        case "mountinfo_unreadable":
+        case "mountinfo_malformed":
+        case "path_unresolvable":
+        case "not_linux":
+            return "unknown";
+        default: {
+            const unhandled = rule;
+            throw new Error(`store posture: no ruling for durability rule ${String(unhandled)}`);
+        }
+    }
+}
+const VOLATILE_FS_TYPES = new Set(["overlay", "tmpfs", "ramfs"]);
+const NETWORK_FS_TYPES = new Set(["cifs", "smb3", "ceph", "glusterfs", "fuse.glusterfs", "9p"]);
+export const STORE_MOUNT_RULES = [
+    { rule: "fs_volatile", holds: (m) => VOLATILE_FS_TYPES.has(m.fsType) },
+    { rule: "k8s_empty_dir", holds: (m) => m.root.includes("kubernetes.io~empty-dir") },
+    { rule: "k8s_persistent_volume", holds: (m) => m.root.includes("kubernetes.io~csi") || m.root.includes("kubernetes.io~local-volume") },
+    { rule: "network_fs", holds: (m) => (m.fsType.startsWith("nfs") || NETWORK_FS_TYPES.has(m.fsType)) && !(m.fsType === "9p" && m.mountPoint === "/") },
+    { rule: "block_device", holds: (m) => m.source.startsWith("/dev/") && m.root === "/" },
+];
+export function classifyStoreMount(m) {
+    return STORE_MOUNT_RULES.find((r) => r.holds(m))?.rule ?? "unrecognized_mount";
+}
+const readingWithoutMount = (path, rule) => ({ path, mountPoint: null, mountSource: null, fsType: null, rule, verdict: durabilityOfRule(rule) });
+export function judgeStoreRootPath(physicalPath, reading) {
+    switch (reading.kind) {
+        case "not_linux":
+            return readingWithoutMount(physicalPath, "not_linux");
+        case "unreadable":
+            return readingWithoutMount(physicalPath, "mountinfo_unreadable");
+        case "read": {
+            if (reading.table.malformed > 0)
+                return readingWithoutMount(physicalPath, "mountinfo_malformed");
+            const visible = visibleMountOf(reading.table.rows, physicalPath);
+            if (typeof visible !== "object")
+                return readingWithoutMount(physicalPath, "mount_unresolved");
+            const rule = classifyStoreMount(visible);
+            return { path: physicalPath, mountPoint: visible.mountPoint, mountSource: visible.source, fsType: visible.fsType, rule, verdict: durabilityOfRule(rule) };
+        }
+        default: {
+            const unhandled = reading;
+            throw new Error(`store posture: unknown mount table reading ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+const DURABILITY_RANK = { ephemeral: 0, unknown: 1, durable: 2 };
+export function weakestDurability(verdicts) {
+    return verdicts.reduce((w, v) => (w === undefined || DURABILITY_RANK[v] < DURABILITY_RANK[w] ? v : w), undefined) ?? "unknown";
+}
+export function localDataRootHoldsData(root) {
+    try {
+        return readdirSync(root).length > 0;
+    }
+    catch (e) {
+        const code = e.code;
+        return code !== "ENOENT" && code !== "ENOTDIR";
+    }
+}
+const EVIDENCE_TAG = "server.store-durability.evidence-unreadable";
+const errnoOf = (e) => (e instanceof Error && "code" in e && typeof e.code === "string" ? e.code : e instanceof Error ? e.name : "unknown");
+export async function captureStoreEvidence(paths, host) {
+    let reading;
+    try {
+        const text = await (host.mountinfo ?? readProcessMountinfo)();
+        reading = text === null ? { kind: "not_linux" } : { kind: "read", table: parseMountinfo(text) };
+    }
+    catch (err) {
+        recordFailOpen(EVIDENCE_TAG, `why=mountinfo_unreadable err=${errnoOf(err)}`);
+        reading = { kind: "unreadable" };
+    }
+    if (reading.kind === "read" && reading.table.malformed > 0)
+        recordFailOpen(EVIDENCE_TAG, `why=mountinfo_malformed lines=${reading.table.malformed}`);
+    const judge = (p) => {
+        let physical;
+        try {
+            physical = host.canonical(p);
+        }
+        catch (err) {
+            recordFailOpen(EVIDENCE_TAG, `why=path_unresolvable err=${errnoOf(err)} path=${p}`);
+            return readingWithoutMount(p, "path_unresolvable");
+        }
+        const judged = judgeStoreRootPath(physical, reading);
+        if (judged.rule === "mount_unresolved")
+            recordFailOpen(EVIDENCE_TAG, `why=mount_unresolved path=${physical}`);
+        return judged;
+    };
+    return {
+        dataRootHeldData: (host.holdsData ?? localDataRootHoldsData)(paths.dataRoot),
+        dataRoot: judge(paths.dataRoot),
+        sealedKey: judge(paths.sealedKeyDir),
+        ...(paths.memoryRoot !== undefined ? { memory: judge(paths.memoryRoot) } : {}),
+    };
+}
+function dataRootReadingOf(backend, evidence) {
+    switch (backend) {
+        case "memory":
+            return readingWithoutMount(null, "backend_memory");
+        case "mysql":
+        case "pg":
+            return readingWithoutMount(null, "backend_sql");
+        case "local":
+            if (evidence === undefined)
+                throw new Error("store posture: a local backend was assembled without boot evidence of its data root's mount — wiring defect (stage 2 captures it before the key directory is written)");
+            return evidence.dataRoot;
+        default: {
+            const unhandled = backend;
+            throw new Error(`store posture: unknown backend kind ${String(unhandled)}`);
+        }
+    }
 }
 export function buildStorePosture(a) {
-    return { declared: a.declared, backend: a.assembled ?? "memory", ...(a.degradedReason !== undefined ? { degradedReason: a.degradedReason } : {}) };
+    const backend = a.assembled ?? "memory";
+    const ev = a.evidence;
+    const memory = a.memoryRootWired ? ev?.memory : undefined;
+    const roots = [
+        { root: "data", ...dataRootReadingOf(backend, ev) },
+        ...(ev !== undefined ? [{ root: "sealed_key", ...ev.sealedKey }] : []),
+        ...(memory !== undefined ? [{ root: "memory", ...memory }] : []),
+    ];
+    return {
+        declared: a.declared,
+        backend,
+        ...(a.degradedReason !== undefined ? { degradedReason: a.degradedReason } : {}),
+        durability: weakestDurability(roots.map((r) => r.verdict)),
+        roots,
+        ...localDeclarationOf(backend, a.localDeclaration),
+    };
+}
+function localDeclarationOf(backend, declaration) {
+    switch (backend) {
+        case "local":
+            if (declaration === undefined)
+                throw new Error("store posture: a local backend was assembled without the declaration it handed its stores — wiring defect (read it back from the backend)");
+            return { localDeclaration: declaration };
+        case "memory":
+        case "mysql":
+        case "pg":
+            return {};
+        default: {
+            const unhandled = backend;
+            throw new Error(`store posture: unknown backend kind ${String(unhandled)}`);
+        }
+    }
+}
+export function unwiredStorePosture(declared) {
+    return buildStorePosture({ declared, assembled: undefined, degradedReason: undefined, evidence: undefined, memoryRootWired: false, localDeclaration: undefined });
+}
+export function buildStoreFreshStartLine(posture, evidence) {
+    if (posture.backend !== "local" || evidence.dataRootHeldData)
+        return undefined;
+    return {
+        dataRoot: evidence.dataRoot.path,
+        durability: posture.durability,
+        roots: posture.roots.map((r) => ({ root: r.root, verdict: r.verdict, rule: r.rule })),
+        note: "this boot initialized an empty local store (the data root held nothing before startup wrote to it); a first start, a lost volume and a wrong mount all look like this — if this deployment had data before, check the volume mounted at the data root",
+    };
 }
 export function projectStoreCapability(posture, sqlFacts) {
     const sql = posture.backend === "mysql" || posture.backend === "pg" ? projectSqlEngineCapability(sqlFacts) : null;
     return {
         declared: posture.declared,
         backend: posture.backend,
-        durable: posture.backend !== "memory",
+        durability: posture.durability,
         ...(posture.degradedReason !== undefined ? { degradedReason: posture.degradedReason } : {}),
         ...(sql !== null ? { sql } : {}),
     };
 }
+export function projectHealthStoreSection(posture) {
+    return { durability: posture.durability };
+}
+export function projectStoreDurabilityWiring(posture) {
+    return { durability: posture.durability, roots: posture.roots };
+}
+export function describeStoreRoot(r) {
+    const where = r.path ?? (r.rule === "backend_sql" ? "(rows held by the database)" : "(no store backend)");
+    const mount = r.fsType !== null ? ` (${r.fsType} ${r.mountSource ?? "?"} at ${r.mountPoint ?? "?"})` : "";
+    return `${r.root} ${where}${mount} ⇒ ${r.verdict} [${r.rule}]`;
+}
+export const STORE_NOT_DURABLE_CODE = "config.store_not_durable";
+export class StoreNotDurableError extends Error {
+    code = STORE_NOT_DURABLE_CODE;
+}
 //# sourceMappingURL=store-posture.js.map

package/dist/stored-request-hooks-m20.js

@@ -1,5 +1,5 @@
 import { HOOK_ENTRY_FIELDS, HOOK_ENTRY_TYPES } from "@sema-agent/settings-schema/hooks";
-import { hooksCoordinate, parseHooksConfig } from "./hooks/hook-runner.js";
+import { hooksFieldCoordinate, parseHooksConfig } from "./hooks/hook-runner.js";
 import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./plugins/one-time-migrations.js";
 const MATCHER_FIELD_NAMES = { matcher: true, hooks: true };
 function isRecord(v) {
@@ -113,7 +113,7 @@ export function rereadStoredHooksM20(raw, read = parseHooksConfig) {
         for (const target of targets) {
             if (!removeKeyAt(doc, target))
                 continue;
-            stripped.push(hooksCoordinate(["hooks", ...target]));
+            stripped.push(hooksFieldCoordinate(["hooks", ...target]));
             removedAny = true;
         }
         if (!removedAny)

package/dist/stores-sql/background-agent-store-sql.d.ts

@@ -43,13 +43,21 @@ type ListOpts = {
     status?: BackgroundAgentRecord["status"];
     limit?: number;
 };
+declare const CORRUPT_TAG: "server.sql-json.background-agent.unreadable-row-skipped";
+/**
+ * 本店容忍臂(上面规则里的「跳过 + 计 tag」)的 **F 类披露口** —— `recordFailOpen` 形,由组合座注入(生产装配 = `boot/stores.ts` 交
+ * `observability/fail-open.ts` 的 `recordFailOpen`):店不直引服务的披露座(本目录对 server 其余部分零依赖,要能原样搬进 core 包)。
+ * 两只店的构造参里**必填**:缺席是编译错,不存在一只静默跳行的实例。
+ */
+export type BackgroundAgentRowDisclosure = (tag: typeof CORRUPT_TAG, detail: string) => void;
 export declare function ensureTiDBBackgroundAgentSchema(pool: Pool): Promise<void>;
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgBackgroundAgentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const BACKGROUND_AGENT_INDEXES: readonly IndexSpec[];
 export declare function ensurePgBackgroundAgentSchema(q: PgQueryFn): Promise<void>;
 export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
     private readonly pool;
-    constructor(pool: Pool);
+    private readonly disclose;
+    constructor(pool: Pool, disclose: BackgroundAgentRowDisclosure);
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
@@ -89,7 +97,8 @@ export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
 }
 export declare class PgBackgroundAgentStore implements BackgroundAgentStore {
     private readonly q;
-    constructor(q: PgQueryFn);
+    private readonly disclose;
+    constructor(q: PgQueryFn, disclose: BackgroundAgentRowDisclosure);
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {

package/dist/stores-sql/background-agent-store-sql.js

@@ -2,8 +2,8 @@ import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, } from "@sem
 import { pgSafeJsonStringify, pgSanitizeText } from "../plugins/pg-safe-json.js";
 import { isMysqlDupKeyError } from "../plugins/sql-errors.js";
 import { ensureIndexes } from "../plugins/ensure-index.js";
-import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText } from "../plugins/sql-json-column.js";
-import { backgroundAgentNameOf } from "../background-agent-name.js";
+import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText, SqlJsonColumnError, StoreCorruptError } from "../plugins/sql-json-column.js";
+import { backgroundAgentNameOf, readBackgroundAgentName } from "../background-agent-name.js";
 export const BACKGROUND_AGENT_TABLE = "background_agent";
 function summaryCols(dialect) {
     return ("handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, " +
@@ -19,7 +19,15 @@ function readRecordColumn(v, handle) {
     catch (e) {
         throw foldJsonColumn(e, (m) => `BackgroundAgentStore: ${m} — refusing rather than serve a hollow agent record`);
     }
-    return { ...record, name: backgroundAgentNameOf(record) };
+    return { ...record, name: agentNameOrRefuse(record, `${BACKGROUND_AGENT_TABLE}.record_json for handle ${handle}`) };
+}
+const TERMINAL_STATUSES = new Set(["completed", "failed", "killed"]);
+const CORRUPT_TAG = "server.sql-json.background-agent.unreadable-row-skipped";
+function agentNameOrRefuse(row, where) {
+    const read = readBackgroundAgentName(row);
+    if (read.ok)
+        return read.name;
+    throw new StoreCorruptError(new SqlJsonColumnError("malformed", where, read.problem), `BackgroundAgentStore: ${where}: ${read.problem} — refusing rather than serve an agent row without a name`);
 }
 function readUsageColumn(v, handle) {
     try {
@@ -71,7 +79,7 @@ function rowToSummary(r) {
         ...(r.session_id !== null && r.session_id !== undefined ? { sessionId: String(r.session_id) } : {}),
         ...(r.parent_session_id !== null && r.parent_session_id !== undefined ? { parentSessionId: String(r.parent_session_id) } : {}),
         ...(r.root_session_id !== null && r.root_session_id !== undefined ? { rootSessionId: String(r.root_session_id) } : {}),
-        name: backgroundAgentNameOf({ handle: String(r.handle), ...(r.name !== null && r.name !== undefined ? { name: String(r.name) } : {}) }),
+        name: agentNameOrRefuse({ handle: String(r.handle), ...(r.name !== null && r.name !== undefined ? { name: String(r.name) } : {}) }, `${BACKGROUND_AGENT_TABLE}.name for handle ${String(r.handle)}`),
         ...(r.agent_type !== null && r.agent_type !== undefined ? { agentType: String(r.agent_type) } : {}),
         status: String(r.status),
         spawnedAt: Number(r.spawned_at_ms),
@@ -80,6 +88,41 @@ function rowToSummary(r) {
         ...((u) => (u === undefined ? {} : { usage: u }))(readUsageColumn(r.usage_json, String(r.handle))),
     };
 }
+async function listReadable(fetchRows, limit, op, disclose) {
+    const want = limit === undefined || limit === Infinity ? undefined : Number.isFinite(Math.floor(limit)) ? Math.max(0, Math.floor(limit)) : 0;
+    for (let extra = 0;;) {
+        const rows = await fetchRows(want === undefined ? limit : want + extra);
+        const out = [];
+        const skipped = [];
+        for (const r of rows) {
+            try {
+                out.push(rowToSummary(r));
+            }
+            catch (e) {
+                if (!(e instanceof StoreCorruptError) || !TERMINAL_STATUSES.has(String(r.status)))
+                    throw e;
+                skipped.push(`table=${BACKGROUND_AGENT_TABLE} op=${op} handle=${String(r.handle)} status=${String(r.status)} ${e.message}`);
+            }
+        }
+        if (want === undefined || out.length >= want || rows.length < want + extra || skipped.length === 0) {
+            for (const detail of skipped)
+                disclose(CORRUPT_TAG, detail);
+            return want === undefined ? out : out.slice(0, want);
+        }
+        extra = skipped.length;
+    }
+}
+function staleRowOrSkip(row, disclose) {
+    try {
+        return readRecordColumn(row.record_json, String(row.handle));
+    }
+    catch (e) {
+        if (!(e instanceof StoreCorruptError))
+            throw e;
+        disclose(CORRUPT_TAG, `table=${BACKGROUND_AGENT_TABLE} op=reap handle=${String(row.handle)} status=running ${e.message}`);
+        return undefined;
+    }
+}
 function flippedForm(live, now) {
     return {
         ...live,
@@ -198,8 +241,10 @@ export async function ensurePgBackgroundAgentSchema(q) {
 }
 export class TiDBBackgroundAgentStore {
     pool;
-    constructor(pool) {
+    disclose;
+    constructor(pool, disclose) {
         this.pool = pool;
+        this.disclose = disclose;
     }
     async put(record) {
         assertScope(record);
@@ -234,14 +279,18 @@ export class TiDBBackgroundAgentStore {
         return res.affectedRows === 1;
     }
     async listBySession(scope, sessionId, opts) {
-        const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND (session_anchor = ? OR root_session_id = ?)${opts?.status !== undefined ? " AND status = ?" : ""}
-       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]));
-        return rows.map(rowToSummary);
+        return listReadable(async (limit) => {
+            const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND (session_anchor = ? OR root_session_id = ?)${opts?.status !== undefined ? " AND status = ?" : ""}
+         ORDER BY spawned_at_ms DESC, handle DESC${limitClause(limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]));
+            return rows;
+        }, opts?.limit, "listBySession", this.disclose);
     }
     async listByScope(scope, opts) {
-        const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ?${opts?.status !== undefined ? " AND status = ?" : ""}
-       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]));
-        return rows.map(rowToSummary);
+        return listReadable(async (limit) => {
+            const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ?${opts?.status !== undefined ? " AND status = ?" : ""}
+         ORDER BY spawned_at_ms DESC, handle DESC${limitClause(limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]));
+            return rows;
+        }, opts?.limit, "listByScope", this.disclose);
     }
     async delete(handle, scope, expect) {
         const [res] = (await this.pool.query(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND handle = ?${expect !== undefined ? " AND rev = ?" : ""}`, expect !== undefined ? [scope, handle, expect.rev] : [scope, handle]));
@@ -254,7 +303,9 @@ export class TiDBBackgroundAgentStore {
         if (opts.staleRunningMaxAgeMs !== undefined) {
             const [stale] = (await this.pool.query(`SELECT handle, ${jsonColumnText("mysql", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status = 'running' AND updated_at_ms < ?`, [scope, now - opts.staleRunningMaxAgeMs]));
             for (const row of stale) {
-                const live = readRecordColumn(row.record_json, String(row.handle));
+                const live = staleRowOrSkip(row, this.disclose);
+                if (live === undefined)
+                    continue;
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))
                     flipped.add(String(row.handle));
             }
@@ -281,8 +332,10 @@ export class TiDBBackgroundAgentStore {
 }
 export class PgBackgroundAgentStore {
     q;
-    constructor(q) {
+    disclose;
+    constructor(q, disclose) {
         this.q = q;
+        this.disclose = disclose;
     }
     async put(record) {
         assertScope(record);
@@ -316,14 +369,12 @@ export class PgBackgroundAgentStore {
         return rows.length === 1;
     }
     async listBySession(scope, sessionId, opts) {
-        const { rows } = await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND (session_anchor = $2 OR root_session_id = $3)${opts?.status !== undefined ? " AND status = $4" : ""}
-       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]);
-        return rows.map(rowToSummary);
+        return listReadable(async (limit) => (await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND (session_anchor = $2 OR root_session_id = $3)${opts?.status !== undefined ? " AND status = $4" : ""}
+       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId])).rows, opts?.limit, "listBySession", this.disclose);
     }
     async listByScope(scope, opts) {
-        const { rows } = await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1${opts?.status !== undefined ? " AND status = $2" : ""}
-       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]);
-        return rows.map(rowToSummary);
+        return listReadable(async (limit) => (await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1${opts?.status !== undefined ? " AND status = $2" : ""}
+       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope])).rows, opts?.limit, "listByScope", this.disclose);
     }
     async delete(handle, scope, expect) {
         const { rows } = await this.q(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND handle = $2${expect !== undefined ? " AND rev = $3" : ""} RETURNING handle`, expect !== undefined ? [scope, handle, expect.rev] : [scope, handle]);
@@ -336,7 +387,9 @@ export class PgBackgroundAgentStore {
         if (opts.staleRunningMaxAgeMs !== undefined) {
             const { rows: stale } = await this.q(`SELECT handle, ${jsonColumnText("pg", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND status = 'running' AND updated_at_ms < $2`, [scope, now - opts.staleRunningMaxAgeMs]);
             for (const row of stale) {
-                const live = readRecordColumn(row.record_json, String(row.handle));
+                const live = staleRowOrSkip(row, this.disclose);
+                if (live === undefined)
+                    continue;
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))
                     affected.add(String(row.handle));
             }

package/dist/stores-sql/checkpoint-store-sql.d.ts

@@ -2,10 +2,9 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type ExecutionOutcomeRecordWord, type GateOutcome, type Checkpoint, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
 import { type SqlDialect, type SqlDriver } from "../plugins/sql-driver.js";
-import type { SqlRunStore } from "../plugins/run-store-sql.js";
-import type { FencedRun } from "../plugins/store-contracts.js";
+import type { CtxWriteClaim } from "../plugins/store-contracts.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type CheckpointAskCandidate, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "../plugins/checkpoint-store-face.js";
+import { type CheckpointAskCandidate, type CtxClaimPut, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type ExpiredApprovalGate, type ExpiredGatePosition, type PendingCheckpoint, type PendingRowBinding } from "../plugins/checkpoint-store-face.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
 /**
  * The capability token IS the resume credential (token-as-auth) — anyone who reads it can impersonate a
@@ -41,7 +40,7 @@ export declare const CHECKPOINT_ADDED_COLUMNS: ReadonlyArray<{
  *
  * 判据 = **能力探测**(恒空的 `WHERE 1=0` 读)+ **方言的缺列错误码**({@link isMissingColumnError},
  * 判据属主 `sql-errors.ts`);其余错误**原样 rethrow**,一个字都不加工 —— 把一次瞬时故障诊断成「缺列」的拒因
- * 比它要挡的缺陷更贵([ref] 两轮收窄的结论逐字继承)。拒因的出路是**闭集三条**(与整库对账同一份,{@link describeProbedTableDrift}),
+ * 比它要挡的缺陷更贵([ref] 两轮收窄的结论逐字继承)。拒因的出路是**闭集三条**(与整库对账同一份,{@link probedMissingColumnRefusal}),
  * 没有销毁性的一条:这张表里是在飞的停驻,出路是原表上加列。
  *
  * 位置:与三条先例同款,不在 `ensureSchema` 里(那条通道的契约是「只发 CREATE」),放在 boot 的
@@ -73,10 +72,9 @@ interface SteerColumnRead {
  * 列有内容却读不出 ⇒ `lossy`(两个调用点对它的处置见 {@link SteerColumnRead})。
  */
 export declare function readPendingSteerQueueColumn(queueRaw: unknown): SteerColumnRead;
-/** SQL checkpoint 店的装配选项:托管留存声明 + ctx 改写的认领栅栏(同一只池上的 run 店)。 */
+/** SQL checkpoint 店的装配选项:托管留存声明。(ctx 栅栏写口的认领由调用方每次交进来 —— [ref]:栅栏的来源是认领本身,店不另绑 run 店。) */
 export interface SqlCheckpointStoreOptions {
     readonly retention?: RetentionDeclaration;
-    readonly claims?: SqlRunStore;
 }
 /** Dual-dialect durable CheckpointStore. See the file header for the dialect-delta ledger. */
 export declare class SqlCheckpointStore implements CheckpointStore {
@@ -132,9 +130,6 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     readonly execution: {
         readonly outcome: true;
     };
-    /** ctx 改写的认领栅栏({@link SqlCheckpointStore.rewriteCtxWhileClaimed}):后端装配绑**同一只池**上的 run 店(`plugins/store-backend.ts` 的 `checkpoint()`)。
-     *  缺席 ⇒ 那一口响亮抛(装配缺陷),其余口不读它。 */
-    private readonly claims;
     /** 停驻行投影记忆([ref] ④;运维队列与调度视图共用,见 {@link StoredRowProjectionMemo})。进程内、按店实例。 */
     private readonly storedRowMemo;
     constructor(db: SqlDriver, logger?: {
@@ -290,19 +285,16 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * in SQL, before the LIMIT: `limit` bounds the per-tick deny-resume work (each is a model run), never hides a row behind
      * rows the sweep does not own.
      *
-     * Order ({@link CHECKPOINT_SWEEP_ORDER_SQL}): rows whose `approval_card` column carries a word come first, then rows whose card
-     * is NULL, each by deadline. A NULL card on an approval gate is either a gate the engine gave no card (a real SLA row) or a
-     * row a replica that does not know the column wrote during a mixed-version window — possibly a question, which the engine
-     * refuses to deny (`sla_timeout`) and which the next boot's M29 backfill settles. The column cannot tell the two apart, so the
-     * order does: rows whose facet is certain take the window first and a straggler cannot crowd them out.
+     * Order and paging ({@link CHECKPOINT_SWEEP_ORDER_SQL} / {@link checkpointSweepAfterSql}): deadline, then token. Each row carries
+     * its position on that order; `after` (the last position the sweep read) returns only the rows strictly after it, so the sweep
+     * walks the expired set round-robin — a row it could not settle (refused before claim, skipped, parked child) never holds the
+     * window for the rows behind it ([ref]). The two position columns are the cursor only: in-process, never on the wire.
      */
-    listExpiredApprovalGates(cutoff: number, limit?: number): Promise<Array<{
-        sessionId: string;
-        scope: string;
-    }>>;
-    /** Pending checkpoints for the operator queue — NON-secret fields only (never the token). `taskId` is
-     *  joined from task_active (the JOIN KEY to the run/trace — a suspended run KEEPS its
-     *  session claim, so the join is live for every pending row; null only in pathological windows). */
+    listExpiredApprovalGates(cutoff: number, limit?: number, after?: ExpiredGatePosition): Promise<ExpiredApprovalGate[]>;
+    /** Pending checkpoints for the operator queue — NON-secret fields only (never the token). `taskId` = the task the
+     *  parked leg runs as ([ref], written by `parkedLegTaskId`): the registry row the engine recorded on the row
+     *  (`$.state.rowTaskId`, a background child's `a…` handle), else the task_active join (a suspended run KEEPS its
+     *  session claim); null when neither (a synchronous / workflow child, a terminal-only park). */
     /**
      * [ref] 显式记账 —— **本口与 {@link SqlCheckpointStore.listByScope} 都不投执行判词,这是结构性的不是遗漏**:
      * 两口的谓词都硬 `status='pending'`,而执行记录的 CAS 谓词是 `status='resolved' AND execution_outcome IS NULL`
@@ -463,9 +455,15 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      */
     peekScopeByToken(token: CheckpointToken): Promise<string | null | undefined>;
     peekPendingScope(sessionId: string, binding?: PendingRowBinding): Promise<string | null | undefined>;
-    /** Upsert the resume rebuild inputs for a session — written at SUBMIT (durable mode on) and, since [ref] F2,
-     *  once per resume leg at its CAS win point (`DriveResumeArgs.resumeCtx`). Unconditional per `session_id`:
-     *  the ordering fence lives at the CALLER's CAS win, not in a version column here.
+    /**
+     * 一张卡**归在哪只会话上**(归属列;不判状态、不读 blob)—— 手里拿着卡(凭据)、要找它那条 run 的读者读它:决断腿的 run 行 / 续跑输入 / 认领,结算作废的核对。
+     * `undefined` = 没有这一行;`null` = 行在、归属列空(滚动升级窗里旧副本写下、还没被 M49 补上的行:说不出归属,读者按「找不到它的 run」处置)。
+     */
+    hostSessionOfCard(token: CheckpointToken): Promise<string | null | undefined>;
+    /** Upsert the resume rebuild inputs for a session —— 续跑输入的**唯一**写口([ref]):写者持有一只认领 ⇒ 交 `claim`,写落在那只认领的栅栏里
+     *  ({@link writeCtxWhileClaimed}:「这条 run 此刻仍持有会话认领、在跑、腿判据答是」与写同一笔,同一条事务连接;不持有 ⇒ 零写,答 `claim_released`);
+     *  没有认领的写者(leader 子工作者 / 无 run 店的部署)不交 ⇒ 无条件写(没有栅栏可依)。持认领的腿:提交腿 `createRun` 之后、续跑腿 CAS 赢点。
+     *  于是「认领 → 写在路上 → 认领被收割 / 终局放掉 → 同会话新 run 写下它的体 → 迟到的这一笔」**结构上落不下**。结局闭集 {@link CtxClaimPut}。
      *
      *  🔴 `ctx: object`, not `unknown` ([ref]): the read leg judges this column as a JSON **object**
      *  ({@link decodeCtxColumn}), so a writer that took `unknown` would be the "writes fine, reads back
@@ -479,7 +477,9 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      *  SUCCEED and replace a readable durable row with an unreadable one (caller sees 2xx, the next resume
      *  409s forever). So the serialized value is judged by {@link assertJsonColumnWritable} — the SAME shape
      *  reader the read leg uses — BEFORE the statement runs: refuse loudly, leave the row on disk untouched. */
-    putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
+    putCtx(sessionId: string, ctx: SealedCheckpointCtx, claim?: CtxWriteClaim): Promise<CtxClaimPut>;
+    /** ctx 行的 upsert 语句(唯一一份;无栅栏写跑在池上,栅栏写跑在栅栏的事务连接上)。 */
+    private upsertCtx;
     getCtx<T extends object = object>(sessionId: string): Promise<T | null>;
     /**
      * **认领栅栏下改写既有 ctx 行** —— 在飞 run 的切档口(`http/routes/run-permission-mode.ts`)把准入的模式词写回存储体的唯一写口。
@@ -487,17 +487,22 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * 规则:只有**接下这笔改写的那条腿**此刻仍持有这条 run 时才写 —— `taskId` 持有 `sessionId` 的会话认领、这条 run 在跑、且调用方的腿判据 `legHolds`
      * 对锁住那一行的 {@link FencedRun} 答是(认领与 `running` 只认 taskId:续跑腿让同一个 taskId 停驻之后回到 `running`、认领仍在,旧腿迟到的改写不许盖掉续跑的新腿
      * 写下的体 —— 那是 ABA,只有腿判据分得开;今天的腿身份 = 副本 `instanceId`(续跑的 CAS 赢点改写它)∧ 调用方进程里这条 run 的活流仍是接下改写的那一只)。
-     * 写在所绑 run 店的认领栅栏事务里
+     * 写在调用方交来的那只认领(`claim.fence`,持认领的 run 店)的栅栏事务里
      * (`SqlRunStore.whileHoldingClaim`:先锁 run 行、再锁认领行 —— 与终局 / 收割同序 —— 刷新活性,本口的锁读 + UPDATE 在同一个事务连接上)。
      * 于是「这条 run 终局放掉认领 → 同会话新 run 写下它自己的 ctx → 本口迟到的改写」这一序**结构上不可能**盖掉新 run 的行:终局要等本事务提交才拿得到
-     * run 行的锁,拿到之后本口再来就判出不持有、一个字节都不写。`putCtx` 的无条件 upsert 只给持有认领的那几条腿自己的写点(提交 / 续跑 CAS 赢点)用;
-     * 不在腿里的写者走这一口。
+     * run 行的锁,拿到之后本口再来就判出不持有、一个字节都不写。持认领的腿自己的写(提交 / 续跑 CAS 赢点)经 {@link putCtx} 交认领、走同一只栅栏例程([ref])。
      * 只改**既有**行(锁读零行 ⇒ `context_absent`,不建行):切档改的是这条 run 提交时写下的那一行,没有那一行就没有要改的存储体。
      * 结局闭集 {@link CtxClaimRewrite}:`written` / `claim_released`(接下改写的那条腿已不持有这条 run —— 认领放了 / 不在跑 / 腿判据答否:零写)/ `context_absent`(持有、无行:零写)。
      * 腿判据在栅栏里同步问一次(锁已持有、写之前);它只读、不许 await。
      * 编码与形闸同 {@link SqlCheckpointStore.putCtx}(写之前判,坏形响亮拒、盘上不动);一行装不下 ⇒ `StoreRowTooLargeError`。
      */
-    rewriteCtxWhileClaimed(sessionId: string, taskId: string, ctx: SealedCheckpointCtx, legHolds: (run: FencedRun) => boolean): Promise<CtxClaimRewrite>;
+    rewriteCtxWhileClaimed(sessionId: string, ctx: SealedCheckpointCtx, claim: CtxWriteClaim): Promise<CtxClaimRewrite>;
+    /**
+     * 两只 ctx 栅栏写(`putCtx` 交认领的那一形 / `rewriteCtxWhileClaimed`)共用的栅栏例程(一处判形、一处判持有、一处折码):调用方交来的认领栅栏必须是 SQL run 店且与本店同方言
+     * (两店出自同一后端 —— 同一只池;错形 ⇒ 响亮抛,不降级成无栅栏写);在它的事务里(先锁 run 行、再锁认领行,与终局 / 收割同序)问一次腿判据,
+     * 答是才在**同一条事务连接**上跑 `write`。形闸在栅栏之前(坏形不开事务);一行装不下 ⇒ `StoreRowTooLargeError`。
+     */
+    private writeCtxWhileClaimed;
     /**
      * 🔴 **一次性迁移的 ctx 行改写店腿**({@link CheckpointCtxRowsRewriter};用它的迁移与各自的行改写见那里,窗与删法见 `plugins/one-time-migrations.ts` 登记表;
      * 本店不知道改写是什么,只负责扫与回写):按 `session_id` 键集分页扫 `checkpoint_ctx`