@sema-agent/server 7.150.0 → 7.151.0

package/dist/plugins/remote-shell.js

@@ -1,5 +1,9 @@
 import { ExecutionError, FileError, SYMLINK_CHAIN_MAX_HOPS } from "@sema-agent/core";
+import { posix } from "node:path";
+import { anchorUnder } from "./exec-path-law.js";
+import { isCanonicalBase64 } from "../device-ws-protocol.js";
 import { NAME_MAX_BYTES, classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
+import { echoCallerText } from "../caller-text-echo.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { createLogger } from "../observability/logger.js";
 import { seatText } from "../trace/exit-seat.js";
@@ -156,6 +160,220 @@ export async function runSymlinkChain(absPath, run) {
         return { ok: false, error: classifyFsStderr(r.value.stderr, absPath, "unknown") };
     return { ok: true, value: { hops: symlinkChainHopsFromStdout(r.value.stdout, absPath) } };
 }
+export const BOUND_READ_EXITS = { link: 90, moved: 91, kind: 92, over: 93, platform: 94, name: 95 };
+const BOUND_READ_TIMEOUT_EXITS = [124, 137, 143];
+export const BOUND_READ_SCRIPT = [
+    "f=$1; op=$2; want=$3; wk=$4; max=$5; enc=$6; LC_ALL=C; export LC_ALL; nl=$(printf '\\n.'); nl=${nl%.}",
+    `[ -d /proc/self/fd ] || exit ${BOUND_READ_EXITS.platform}`,
+    `for t in readlink stat head; do command -v "$t" >/dev/null 2>&1 || exit ${BOUND_READ_EXITS.platform}; done`,
+    `if [ "$enc" = base64 ]; then command -v base64 >/dev/null 2>&1 || exit ${BOUND_READ_EXITS.platform}; fi`,
+    `if [ -L "$f" ]; then exit ${BOUND_READ_EXITS.link}; fi`,
+    `if [ -e "$f" ]; then if [ -f "$f" ] || [ -d "$f" ]; then :; else exit ${BOUND_READ_EXITS.kind}; fi; fi`,
+    "{",
+    `  p=$(readlink /proc/self/fd/0 && printf .) || exit ${BOUND_READ_EXITS.platform}`,
+    '  p=${p%.}; p=${p%"$nl"}',
+    `  s=$(stat -L -c '%d:%i %s %F' /proc/self/fd/0) || exit ${BOUND_READ_EXITS.platform}`,
+    `  [ "$p" = "$f" ] || exit ${BOUND_READ_EXITS.moved}`,
+    '  id=${s%% *}; r=${s#* }; sz=${r%% *}; t=${r#* }',
+    `  case $t in "regular file"|"regular empty file") k=file ;; directory) k=directory ;; *) exit ${BOUND_READ_EXITS.kind} ;; esac`,
+    `  if [ "$op" = open ]; then :; elif [ "$id" = "$want" ] && [ "$k" = "$wk" ]; then :; else exit ${BOUND_READ_EXITS.moved}; fi`,
+    "  case $op in",
+    `    open) printf '%s %s\\n' "$id" "$k" ;;`,
+    `    size) printf '%s\\n' "$sz" ;;`,
+    `    readBytes) if [ "$sz" -le "$max" ]; then :; else printf '%s\\n' "$sz"; exit ${BOUND_READ_EXITS.over}; fi`,
+    '      n=$sz; [ "$sz" -gt 0 ] || n=$((max + 1))',
+    `      printf '%s\\n' "$sz"`,
+    '      if [ "$enc" = base64 ]; then { rc=$( { { head -c "$n"; echo "$?" >&4; } | base64 >&3; } 4>&1 ); } 3>&1; [ "$rc" = 0 ] || exit 1; else head -c "$n"; fi ;;',
+    "    list) cd -P /proc/self/fd/0 || exit 1",
+    "      set --",
+    `      for n in * .[!.]* ..?*; do case $n in *"$nl"*) exit ${BOUND_READ_EXITS.name} ;; esac; if [ -e "$n" ] || [ -L "$n" ]; then set -- "$@" "$n"; fi; done`,
+    `      if [ "$#" -gt 0 ]; then stat -c '%f %s %Y %n' -- "$@"; fi ;;`,
+    "    *) exit 1 ;;",
+    "  esac",
+    "  exit",
+    '} < "$f"',
+    "exit 1",
+].join("\n");
+export function buildBoundReadCommand(abs, op, args, payload, boundSec) {
+    const argv = [abs, op, args.bound?.identity ?? "-", args.bound?.kind ?? "-", String(args.max ?? 0), payload].map(shellQuote).join(" ");
+    return `{ command -v timeout >/dev/null 2>&1 || exit ${BOUND_READ_EXITS.platform}; exec timeout ${Math.max(1, Math.floor(boundSec))} sh -c ${shellQuote(BOUND_READ_SCRIPT)} sema-bound-read ${argv}; }`;
+}
+const BOUND_SMALL_ANSWER_BYTES = 4096;
+const BOUND_LIST_ANSWER_BYTES = 16 * 1024 * 1024;
+const BOUND_IDENTITY_RE = /^\d+:\d+$/;
+const BOUND_DECIMAL_RE = /^\d+$/;
+function overCapError(abs, max, bytes) {
+    return new FileError("invalid", `The held file is over the ${max}-byte read cap (${bytes} bytes or more); it was not read`, abs);
+}
+function malformedAnswer(abs, what) {
+    return new FileError("unknown", `the target's bound-read answer was malformed (${what}); nothing was read`, abs);
+}
+function boundReadRefusal(word, abs, max, stdout) {
+    switch (word) {
+        case "link":
+            return new FileError("precondition_failed", "The path is now a link, not the object that was checked", abs);
+        case "moved":
+            return new FileError("precondition_failed", "The path named another object than the one opened", abs);
+        case "kind":
+            return new FileError("invalid", "Neither a regular file nor a directory", abs);
+        case "over":
+            return overCapError(abs, max, BOUND_DECIMAL_RE.test(stdout.trim()) ? stdout.trim() : "more than the cap");
+        case "platform":
+            return new FileError("not_supported", "This target cannot bind a read: it gives no /proc/self/fd observation of an opened file (not Linux, or /proc is not mounted), or it lacks timeout / readlink / stat / head / base64", abs);
+        case "name":
+            return new FileError("invalid", "A name in this directory contains a newline, which this listing cannot carry unambiguously; the directory was not listed", abs);
+    }
+}
+function boundReadExitOf(code) {
+    for (const word of Object.keys(BOUND_READ_EXITS))
+        if (BOUND_READ_EXITS[word] === code)
+            return word;
+    return undefined;
+}
+function answerCap(op, max, payload) {
+    switch (op) {
+        case "open":
+        case "size":
+            return BOUND_SMALL_ANSWER_BYTES;
+        case "list":
+            return BOUND_LIST_ANSWER_BYTES;
+        case "readBytes": {
+            const body = payload === "base64" ? Math.ceil((max + 1) / 3) * 4 : max + 1;
+            return BOUND_SMALL_ANSWER_BYTES + body + Math.ceil(body / 76) + 1;
+        }
+    }
+}
+async function runBoundOp(abs, op, args, lane, abortSignal) {
+    const max = args.max ?? 0;
+    const cap = answerCap(op, max, lane.payload);
+    const r = await lane.run(buildBoundReadCommand(abs, op, args, lane.payload, lane.boundSec), cap, abortSignal);
+    if (!r.ok)
+        return { ok: false, error: r.error.code === "timeout" ? new FileError("timeout", `the bound read ran past the lane's bound: ${r.error.message}`, abs, r.error) : fileErrorFromExec(r.error, abs) };
+    const { exitCode, stderr } = r.value;
+    const stdout = Buffer.from(r.value.stdout);
+    if (exitCode !== 0) {
+        const word = boundReadExitOf(exitCode);
+        if (word !== undefined)
+            return { ok: false, error: boundReadRefusal(word, abs, max, stdout.subarray(0, 64).toString("latin1")) };
+        if (BOUND_READ_TIMEOUT_EXITS.includes(exitCode))
+            return { ok: false, error: new FileError("timeout", `the bound read on the target ran past its ${lane.boundSec}s bound and was killed; nothing was read`, abs) };
+        return { ok: false, error: classifyFsStderr(stderr, abs, "unknown") };
+    }
+    if (stdout.length > cap)
+        return { ok: false, error: malformedAnswer(abs, `over the ${cap}-byte bound of a ${op} answer`) };
+    return { ok: true, value: stdout };
+}
+function bytesOfReadAnswer(abs, out, payload) {
+    const nl = out.indexOf(0x0a);
+    const head = nl < 0 ? "" : out.subarray(0, nl).toString("latin1");
+    if (!BOUND_DECIMAL_RE.test(head))
+        return { ok: false, error: malformedAnswer(abs, "no size line") };
+    const size = Number(head);
+    const rest = out.subarray(nl + 1);
+    let bytes;
+    if (payload === "base64") {
+        const text = rest.toString("latin1").replace(/\s+/g, "");
+        if (!isCanonicalBase64(text))
+            return { ok: false, error: malformedAnswer(abs, "the payload is not canonical base64") };
+        bytes = Buffer.from(text, "base64");
+    }
+    else {
+        bytes = rest;
+    }
+    if (size > 0 && bytes.length !== size) {
+        return { ok: false, error: new FileError("unknown", `the file was ${size} bytes when the read started but ${bytes.length} arrived (it changed while it was read, or the transfer was cut); nothing was read`, abs) };
+    }
+    return { ok: true, value: new Uint8Array(bytes) };
+}
+function entriesOfListAnswer(abs, out) {
+    const entries = [];
+    for (const line of out.toString("utf8").split("\n")) {
+        if (line === "")
+            continue;
+        const m = /^([0-9a-fA-F]+) (\d+) (\d+) (.+)$/.exec(line);
+        if (m === null)
+            return { ok: false, error: malformedAnswer(abs, "a listing line is not `<mode> <size> <mtime> <name>`") };
+        const type = parseInt(m[1], 16) & 0o170000;
+        const kind = type === 0o100000 ? "file" : type === 0o040000 ? "directory" : type === 0o120000 ? "symlink" : undefined;
+        if (kind === undefined)
+            continue;
+        entries.push({ name: m[4], kind, size: Number(m[2]), mtimeMs: Number(m[3]) * 1000 });
+    }
+    return { ok: true, value: entries };
+}
+export function createShellRebindingAnswers(abs, lane) {
+    return {
+        async open(abortSignal) {
+            const r = await runBoundOp(abs, "open", {}, lane, abortSignal);
+            if (!r.ok)
+                return r;
+            const [identity, kind, ...more] = r.value.toString("latin1").trim().split(" ");
+            if (identity === undefined || !BOUND_IDENTITY_RE.test(identity) || (kind !== "file" && kind !== "directory") || more.length > 0)
+                return { ok: false, error: malformedAnswer(abs, "the open answer is not `<dev>:<inode> <file|directory>`") };
+            return { ok: true, value: { identity, kind } };
+        },
+        async size(bound) {
+            const r = await runBoundOp(abs, "size", { bound }, lane);
+            if (!r.ok)
+                return r;
+            const text = r.value.toString("latin1").trim();
+            if (!BOUND_DECIMAL_RE.test(text))
+                return { ok: false, error: malformedAnswer(abs, "the size answer is not a decimal") };
+            return { ok: true, value: Number(text) };
+        },
+        async readBytes(bound, max, abortSignal) {
+            const r = await runBoundOp(abs, "readBytes", { bound, max }, lane, abortSignal);
+            return r.ok ? bytesOfReadAnswer(abs, r.value, lane.payload) : r;
+        },
+        async list(bound, abortSignal) {
+            const r = await runBoundOp(abs, "list", { bound }, lane, abortSignal);
+            return r.ok ? entriesOfListAnswer(abs, r.value) : r;
+        },
+    };
+}
+export function createRebindingBoundFile(abs, bound, answers) {
+    return {
+        identity: bound.identity,
+        kind: bound.kind,
+        size: () => answers.size(bound),
+        async readBytes(max, abortSignal) {
+            if (bound.kind !== "file")
+                return { ok: false, error: new FileError("is_directory", "The held object is a directory", abs) };
+            if (!Number.isSafeInteger(max) || max < 0)
+                return { ok: false, error: new FileError("invalid", `the read cap must be a non-negative integer (got ${String(max)})`, abs) };
+            const r = await answers.readBytes(bound, max, abortSignal);
+            if (!r.ok)
+                return r;
+            if (r.value.length > max)
+                return { ok: false, error: overCapError(abs, max, r.value.length) };
+            return r;
+        },
+        async list(abortSignal) {
+            if (bound.kind !== "directory")
+                return { ok: false, error: new FileError("not_directory", "The held object is a file", abs) };
+            const r = await answers.list(bound, abortSignal);
+            if (!r.ok)
+                return r;
+            const out = [];
+            for (const e of r.value) {
+                if (e.name === "" || e.name === "." || e.name === ".." || e.name.includes("/"))
+                    return { ok: false, error: malformedAnswer(abs, `a listed name is not one path segment: ${JSON.stringify(echoCallerText(e.name, { maxChars: 80 }))}`) };
+                out.push({ ...e, path: anchorUnder(posix, abs, e.name) });
+            }
+            return { ok: true, value: out };
+        },
+        close: async () => undefined,
+    };
+}
+export async function openRebinding(abs, answers, abortSignal) {
+    const opened = await answers.open(abortSignal);
+    if (!opened.ok)
+        return opened;
+    return { ok: true, value: createRebindingBoundFile(abs, opened.value, answers) };
+}
+export function openBoundOverShell(abs, lane, abortSignal) {
+    return openRebinding(abs, createShellRebindingAnswers(abs, lane), abortSignal);
+}
 const STAGED_FILE = "data";
 const STAGE_DIR_REFUSED_EXIT = 3;
 const STAGE_DIR_UNSEALED_EXIT = 4;

package/dist/plugins/resume-anchor-store-sql.d.ts

@@ -17,14 +17,23 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type SqlDriver } from "./sql-driver.js";
+import { type SqlDialect, type SqlDriver, type SqlExec } from "./sql-driver.js";
+/**
+ * 一条锚的写(幂等 upsert,主键 `(session_id, event_id)`)—— **语句源**,跑在调用方给的执行口上:落定段(`landed-attendants.ts`:段首锁根行判过住客,
+ * 同一事务)是生产里唯一的调用方;店的 {@link SqlResumeAnchorStore.put} 是夹具 / 契约面的同一句。
+ */
+export declare function putAnchorOn(exec: Pick<SqlExec, "query">, dialect: SqlDialect, sessionId: string, eventId: string, entryId: string, owner: string | null): Promise<void>;
+/** 一只会话的锚全删(按 `session_id` 定址)—— 语句源(落定段的擦除腿与 E21 删除同一句)。返回删掉的行数。 */
+export declare function deleteAnchorsOn(exec: Pick<SqlExec, "query">, dialect: SqlDialect, sessionId: string): Promise<number>;
 /** Dual-dialect durable resume-at anchor map. See the file header for the dialect-delta ledger. */
 export declare class SqlResumeAnchorStore {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
-    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert on the (session_id,event_id) PK). */
+    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert on the (session_id,event_id) PK). **Not a production writer**:
+     *  the deployment's read face (`StoreBackend.resumeAnchor()`'s `ResumeAnchorStore`) carries no `put` — every production anchor write goes through the landed section
+     *  (`landed-attendants.ts`), which runs {@link putAnchorOn} after locking the session row and judging the occupant. Fixtures seed through this verb. */
     put(sessionId: string, eventId: string, entryId: string, owner: string | null): Promise<void>;
     /** Resolve a shell-supplied eventId → the persisted SessionTreeEntry.id; undefined = unknown anchor. */
     resolve(sessionId: string, eventId: string, owner: string | null): Promise<string | undefined>;

package/dist/plugins/resume-anchor-store-sql.js

@@ -1,4 +1,13 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { sealStoreClass } from "./store-boundary.js";
+export async function putAnchorOn(exec, dialect, sessionId, eventId, entryId, owner) {
+    await exec.query(dialect === "mysql"
+        ? "INSERT INTO resume_anchor (session_id, event_id, entry_id, owner, created_at) VALUES (?,?,?,?,?) ON DUPLICATE KEY UPDATE entry_id = VALUES(entry_id), owner = VALUES(owner)"
+        : "INSERT INTO resume_anchor (session_id, event_id, entry_id, owner, created_at) VALUES ($1,$2,$3,$4,$5) ON CONFLICT (session_id, event_id) DO UPDATE SET entry_id = EXCLUDED.entry_id, owner = EXCLUDED.owner", [sessionId, eventId, entryId, owner, new Date()]);
+}
+export async function deleteAnchorsOn(exec, dialect, sessionId) {
+    return (await exec.query(dialect === "mysql" ? "DELETE FROM resume_anchor WHERE session_id = ?" : "DELETE FROM resume_anchor WHERE session_id = $1", [sessionId])).affected;
+}
 export class SqlResumeAnchorStore {
     db;
     constructor(db) {
@@ -8,9 +17,7 @@ export class SqlResumeAnchorStore {
         return this.db.dialect === "mysql" ? mysql : pg;
     }
     async put(sessionId, eventId, entryId, owner) {
-        await this.db.query(this.q("INSERT INTO resume_anchor (session_id, event_id, entry_id, owner, created_at) VALUES (?,?,?,?,?) " +
-            "ON DUPLICATE KEY UPDATE entry_id = VALUES(entry_id), owner = VALUES(owner)", "INSERT INTO resume_anchor (session_id, event_id, entry_id, owner, created_at) VALUES ($1,$2,$3,$4,$5) " +
-            "ON CONFLICT (session_id, event_id) DO UPDATE SET entry_id = EXCLUDED.entry_id, owner = EXCLUDED.owner"), [sessionId, eventId, entryId, owner, new Date()]);
+        await putAnchorOn(this.db, this.db.dialect, sessionId, eventId, entryId, owner);
     }
     async resolve(sessionId, eventId, owner) {
         const { rows } = await this.db.query(this.q("SELECT entry_id FROM resume_anchor WHERE session_id = ? AND event_id = ? AND owner <=> ?", "SELECT entry_id FROM resume_anchor WHERE session_id = $1 AND event_id = $2 AND owner IS NOT DISTINCT FROM $3"), [sessionId, eventId, owner]);
@@ -21,10 +28,10 @@ export class SqlResumeAnchorStore {
         return rows.map((r) => ({ eventId: String(r.event_id), entryId: String(r.entry_id), owner: r.owner == null ? null : String(r.owner) }));
     }
     async deleteBySession(sessionId) {
-        const res = await this.db.query(this.q("DELETE FROM resume_anchor WHERE session_id = ?", "DELETE FROM resume_anchor WHERE session_id = $1"), [sessionId]);
-        return res.affected;
+        return deleteAnchorsOn(this.db, this.db.dialect, sessionId);
     }
 }
+sealStoreClass(SqlResumeAnchorStore, "sql-resume-anchor-store", { put: "exit", resolve: "exit", listBySession: "exit", deleteBySession: "exit" });
 export class TiDBResumeAnchorStore extends SqlResumeAnchorStore {
     constructor(pool) {
         super(mysqlDriver(pool));

package/dist/plugins/retention-lane-store-sql.js

@@ -1,4 +1,5 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { sealStoreClass } from "./store-boundary.js";
 export const RETENTION_AUDIT_TABLE = "retention_audit";
 export const RETENTION_HOLD_TABLE = "retention_hold";
 export const RETENTION_LEASE_TABLE = "retention_lease";
@@ -217,6 +218,9 @@ export class SqlRetentionLaneStore {
         }));
     }
 }
+sealStoreClass(SqlRetentionLaneStore, "sql-retention-lane-store", {
+    acquire: "exit", renew: "exit", release: "exit", setHold: "exit", setHoldAudited: "exit", holdInForce: "exit", appendAudit: "exit", listAudit: "exit",
+});
 export class TiDBRetentionLaneStore extends SqlRetentionLaneStore {
     constructor(pool) {
         super(mysqlDriver(pool));

package/dist/plugins/retention-sql.d.ts

@@ -1,6 +1,7 @@
 /**
- * 托管留存的两只 SQL 谓词 —— 执行器(`stores-sql/retention-store-sql.ts`,引擎座表那一半)与部署的事务内钩(`plugins/retention-deployment.ts`,
- * 部署表那一半)对**同一条域律**发谓词,只从这里取:一条律一个读法,两半不各写一份(分家的方向是多删或漏删)。
+ * 托管留存的三只 SQL 谓词 —— 执行器(`stores-sql/retention-store-sql.ts`,引擎座表那一半)与部署的事务内钩(`plugins/retention-deployment.ts`,
+ * 部署表那一半)对**同一条域律**发谓词,只从这里取:一条律一个读法,两半不各写一份(分家的方向是多删或漏删)。第三只 —— 会话树的活引用
+ * ({@link sessionLiveReferenceSql})—— 另有会话老化的两个读者(`plugins/session-store-sql.ts` 的老化候选面与老化围栏):自动老化不许比托管留存松。
  *
  * 域 = 租户键:`COALESCE(session_meta.owner, '')` / `checkpoint.scope` 原样;**空串 `''` = 无主(anonymous/dev)桶**,谓词写成
  * `(owner IS NULL OR owner = '')` —— 合并只发生在无主侧,永远伸不进一个真租户;拆成两个桶才会漏(NULL 那半永不被枚举)。
@@ -26,4 +27,21 @@ export declare function retentionIdSet(dialect: SqlDialect, col: string, ids: re
     sql: string;
     params: unknown[];
 };
+/**
+ * **会话树的活引用 —— SQL 谓词的唯一写法**(`sm` = `session_meta` 的别名;两方言一只函数)。
+ *
+ * 读者三只,同调这一只:托管留存的「可删候选」(否定)与「被保护计数」(肯定)(`stores-sql/retention-store-sql.ts` 的 `liveReferenceExists`)、会话老化的候选面与
+ * 老化围栏的锁内重判(`plugins/session-store-sql.ts`;会话种类的律在 `src/session-kind.ts`)。两份手抄必然在某次改动后分家,而分家的方向是**多删**(候选放宽、
+ * 计数收紧,两边都不会有人红)。local 店的同义判是 `plugins/local-session-live-reference.ts`。
+ *
+ * 腿的词表:活跑 claim / 挂起 park(pending 检查点)/ 活着的后台子代(running|parked,三根会话锚)/ 在跑的 workflow(`originatingSessionId` 住在 run blob 里 ⇒
+ * JSON 提取是真方言分叉)。fork 子代**结构上没有边**(理由见 `SqlRetentionStore.deleteExpiredSessions` 的头注)。
+ *
+ * 🔴 [ref] C18 追加的**第五条腿**(placed 分区,core 5.48 [ref] 义务 4 的 server 侧兑现):一只 `placement_kind` 在场的会话是某条委派的**转录**,它的删除权
+ * **独家**属于联合 reap(`reapDurableAgents`:先按 rev 条件删 agent 行、赢了才 `release` 终结转录;以及行已不在时的分区收割腿)。让视界腿也去删它会造出两个删除
+ * 权威,而它们的交叠恰好是这条义务要关死的那个状态:行还在、指着一份已经不存在的转录(core 的 `delegation.transcript_integrity` 通告说的就是它)。⇒ 把「placed」当成
+ * 一条**活引用**:候选谓词排除它,被保护计数同时把它记成 skipped(两侧共用本函数 ⇒ 不可能分家)。它不会因此永生:分区收割腿按 `backgroundAgentRetentionMs` 的
+ * 年龄 + 「行确实不在」联合判定后真删。
+ */
+export declare function sessionLiveReferenceSql(dialect: SqlDialect): string;
 //# sourceMappingURL=retention-sql.d.ts.map

package/dist/plugins/retention-sql.js

@@ -5,4 +5,15 @@ export function retentionDomainWhere(dialect, col, domain, pgIndex) {
 export function retentionIdSet(dialect, col, ids, pgIndex) {
     return dialect === "mysql" ? { sql: `${col} IN (${ids.map(() => "?").join(",")})`, params: [...ids] } : { sql: `${col} = ANY($${pgIndex}::text[])`, params: [ids] };
 }
+export function sessionLiveReferenceSql(dialect) {
+    const workflow = dialect === "mysql"
+        ? `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND JSON_UNQUOTE(JSON_EXTRACT(wr.run, '$.originatingSessionId')) = sm.session_id)`
+        : `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND wr.run::json->>'originatingSessionId' = sm.session_id)`;
+    return (`(sm.placement_kind IS NOT NULL` +
+        ` OR EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = sm.session_id)` +
+        ` OR EXISTS (SELECT 1 FROM checkpoint c2 WHERE c2.session_id = sm.session_id AND c2.status = 'pending')` +
+        ` OR EXISTS (SELECT 1 FROM background_agent ba WHERE ba.status IN ('running','parked')` +
+        `   AND (ba.session_id = sm.session_id OR ba.parent_session_id = sm.session_id OR ba.root_session_id = sm.session_id))` +
+        ` OR ${workflow})`);
+}
 //# sourceMappingURL=retention-sql.js.map

package/dist/plugins/run-store-sql.d.ts

@@ -3,7 +3,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
 import { type RunStallWiring, type ClaimFenced, type CreateRunOutcome, type FencedRun, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } from "./store-contracts.js";
-import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
+import { type SqlDialect, type SqlDriver, type SqlTxConn } from "./sql-driver.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
 export type { RunRecord, RunEvent, LatestRunRef } from "./store-contracts.js";
@@ -12,6 +12,25 @@ export type { RunRecord, RunEvent, LatestRunRef } from "./store-contracts.js";
  * ({@link decodeResultColumn},投影须经 `jsonColumnText`);读不出 ⇒ `"unreadable"`(迁移跳过那一行、码列不动 —— 店的读腿对它照旧响亮拒)。
  */
 export declare function decodeRunResultCellM44(v: unknown, taskId: string): PersistedTaskResult | null | "unreadable";
+/** 「`running` × 心跳 × 判活窗」谓词的哪一侧:`live` = 窗内心跳过(停-迁-起证据读法选的那一批),`stale` = 窗外(死亡判决落的那一批)。 */
+export type RunHeartbeatSide = "live" | "stale";
+/**
+ * 🔴 **「`running` × 心跳 × 判活窗」谓词的唯一构造**(SQL 两方言):死亡判决的那一句({@link SqlRunStore} 的 `landStallVerdicts`:收割器与两处单行落判决)
+ * 与停-迁-起证据读法(`stop-then-start.ts` 的 `readOlderReplicaEvidence`)同调它 —— 同一个窗界、同一处 `>=` / `<` 边界,`task_run` 心跳比较在本仓只有这一处文本
+ * (源码门 `test/run-liveness-single-source-gate.test.ts`)。交回 WHERE 片段与它唯一的绑定参数(窗界)。
+ *
+ * **钟**:心跳由写者在绑定参数里送它自己的进程钟(本店每一句 `updated_at = ?` 都送 `new Date()`),池把它编成库里的值(MySQL 协议:池选项 `timezone: "Z"`
+ * ⇒ `DATETIME(3)` 里存 UTC 墙钟,`tidb-pool.ts` 的 `tidbPoolOptions`;PG:`TIMESTAMPTZ` 存绝对时刻)。窗界取同一种钟、经同一只池编码 —— `nowMs − windowMs` 作绑定参数,
+ * 不用库侧的 `NOW(3)`:它按会话时区答墙钟,会话时区不是 UTC 的库上与写者存下的 UTC 墙钟差出整个时区偏移(证据读法因此读空 = 守卫静默放行)。
+ * `placeholder` = 这一片段在整句里的 PG 占位符序号(MySQL 协议恒 `?`)。
+ */
+export declare function runningHeartbeatPredicate(dialect: SqlDialect, side: RunHeartbeatSide, at: {
+    readonly nowMs: number;
+    readonly windowMs: number;
+}, placeholder: number): {
+    readonly sql: string;
+    readonly param: Date;
+};
 export declare class SqlRunStore {
     readonly db: SqlDriver;
     private readonly stall;
@@ -70,7 +89,7 @@ export declare class SqlRunStore {
      */
     private settleDueHolderOn;
     /**
-     * 🔴 **死亡判决的那一句**(收割器与两处单行落判决共用一只语句构造):`running ∧ updated_at < cutoff` ⇒ `failed` / `result = NULL` / {@link RUN_STALLED_ERROR} /
+     * 🔴 **死亡判决的那一句**(收割器与两处单行落判决共用一只语句构造;条件 = {@link runningHeartbeatPredicate} 的 `stale` 一侧,与停-迁-起证据读法同一只):`running ∧ updated_at < 窗界` ⇒ `failed` / `result = NULL` / {@link RUN_STALLED_ERROR} /
      * `error_code = run.stalled`,同一事务放认领。两种作用域:
      *  · **全表**(`taskId` 缺席,收割器):放掉每条非活非停驻行的认领 + 孤儿认领(语义同修前);
      *  · **单行**(`AND task_id = ?`,观察口 / 认领冲突):只有命中 1 行才 `DELETE FROM task_active WHERE task_id = ?` —— 心跳或停驻抢先赢了 CAS ⇒ 0 行 ⇒ 认领不动。

package/dist/plugins/run-store-sql.js

@@ -12,6 +12,7 @@ import { isDupKeyError } from "./sql-errors.js";
 import { readDeletingTokenOn } from "./session-ext-table.js";
 import { readRunIdentityCells, runIdentityCells } from "../identity-source.js";
 import { decideSpaceCommitAbandon, decideSpaceCommitClaim, fenceSpaceCommitAtTerminal, spaceCommitStateOf } from "../workspace-space-commit.js";
+import { sealStoreClass } from "./store-boundary.js";
 function runRowCols(dialect) {
     return (`task_id, session_id, owner, status, ${jsonColumnText(dialect, "result")}, error, error_code, job_id, source, ` +
         "identity_source, identity_scope, identity_principal_inc, instance_id, leg_id, cancel_requested, objective_preview, created_at, updated_at");
@@ -60,6 +61,20 @@ function m44ErrorCodeReadSide(status, result, column) {
         return column;
     return persistedPlaneOf(result).errorCode ?? null;
 }
+export function runningHeartbeatPredicate(dialect, side, at, placeholder) {
+    const p = dialect === "mysql" ? "?" : `$${placeholder}`;
+    const param = new Date(at.nowMs - at.windowMs);
+    switch (side) {
+        case "live":
+            return { sql: `status = 'running' AND updated_at >= ${p}`, param };
+        case "stale":
+            return { sql: `status = 'running' AND updated_at < ${p}`, param };
+        default: {
+            const unhandled = side;
+            throw new Error(`runningHeartbeatPredicate: unknown side ${String(unhandled)}`);
+        }
+    }
+}
 export class SqlRunStore {
     db;
     stall;
@@ -188,7 +203,7 @@ export class SqlRunStore {
         let landed = 0;
         try {
             await this.txOn(conn, async (c) => {
-                landed = await this.landStallVerdicts(c, new Date(nowMs - windowMs), holderTaskId);
+                landed = await this.landStallVerdicts(c, { nowMs, windowMs }, holderTaskId);
             });
         }
         catch (err) {
@@ -199,11 +214,12 @@ export class SqlRunStore {
             this.stall.onVerdicts(landed);
         return landed > 0;
     }
-    async landStallVerdicts(conn, cutoff, taskId) {
+    async landStallVerdicts(conn, at, taskId) {
         const one = taskId !== undefined;
+        const stale = { mysql: runningHeartbeatPredicate("mysql", "stale", at, 2), pg: runningHeartbeatPredicate("pg", "stale", at, 2) };
         const { affected } = await conn.query(this.q(`UPDATE task_run SET status = 'failed', result = NULL, error = '${RUN_STALLED_ERROR}', error_code = '${RUN_HOLDER_DEATH_CODES.stalled}', updated_at = ? ` +
-            `WHERE status = 'running' AND updated_at < ?${one ? " AND task_id = ?" : ""}`, `UPDATE task_run SET status = 'failed', result = NULL, error = '${RUN_STALLED_ERROR}', error_code = '${RUN_HOLDER_DEATH_CODES.stalled}', updated_at = $1 ` +
-            `WHERE status = 'running' AND updated_at < $2${one ? " AND task_id = $3" : ""}`), one ? [new Date(), cutoff, taskId] : [new Date(), cutoff]);
+            `WHERE ${stale.mysql.sql}${one ? " AND task_id = ?" : ""}`, `UPDATE task_run SET status = 'failed', result = NULL, error = '${RUN_STALLED_ERROR}', error_code = '${RUN_HOLDER_DEATH_CODES.stalled}', updated_at = $1 ` +
+            `WHERE ${stale.pg.sql}${one ? " AND task_id = $3" : ""}`), one ? [new Date(), stale[this.db.dialect].param, taskId] : [new Date(), stale[this.db.dialect].param]);
         if (one) {
             if (affected === 1)
                 await conn.query(this.q("DELETE FROM task_active WHERE task_id = ?", "DELETE FROM task_active WHERE task_id = $1"), [taskId]);
@@ -221,7 +237,7 @@ export class SqlRunStore {
         let landed = 0;
         try {
             await this.tx(async (conn) => {
-                landed = await this.landStallVerdicts(conn, new Date(nowMs - windowMs), row.taskId);
+                landed = await this.landStallVerdicts(conn, { nowMs, windowMs }, row.taskId);
             });
         }
         catch (err) {
@@ -596,10 +612,10 @@ export class SqlRunStore {
         }));
     }
     async reapStale() {
-        const cutoff = new Date(Date.now() - this.stall.windowMs());
+        const at = { nowMs: Date.now(), windowMs: this.stall.windowMs() };
         let reaped = 0;
         await this.tx(async (conn) => {
-            reaped = await this.landStallVerdicts(conn, cutoff);
+            reaped = await this.landStallVerdicts(conn, at);
         });
         if (reaped > 0)
             this.stall.onVerdicts(reaped);
@@ -635,6 +651,14 @@ export class SqlRunStore {
         return reaped;
     }
 }
+sealStoreClass(SqlRunStore, "sql-run-store", {
+    createRun: "exit", observeRun: "exit", fillObjectivePreview: "exit", requestCancel: "exit", isCancelRequested: "exit", requestPreempt: "exit",
+    isPreemptRequested: "exit", heartbeat: "exit", appendEvent: "exit", maxSeq: "exit", setTerminal: "exit", readSpaceCommit: "exit", claimSpaceCommit: "exit",
+    endSpaceCommit: "exit", abandonSpaceCommit: "exit", setSuspended: "exit", setNeedsReview: "exit", markResuming: "exit", whileHoldingClaim: "exit",
+    getActiveTaskId: "exit", getRun: "exit", getRunByIdem: "exit", releaseIdemKey: "exit", withdrawMintedRun: "exit", bindIdemBodyFingerprint: "exit",
+    listRuns: "exit", latestRunForSession: "exit", latestMemoryObservationForSession: "exit", deleteBySession: "exit", sourceSummary: "exit", usageScan: "exit",
+    retainedFrom: "exit", getEvents: "exit", reapStale: "exit", reapSuspended: "exit", failSuspendedWithExpiredCheckpoint: "exit",
+});
 export class TiDBRunStore extends SqlRunStore {
     constructor(pool, stall) {
         super(mysqlDriver(pool), stall);

package/dist/plugins/scenario-prefix-switch-m42.d.ts

@@ -24,7 +24,7 @@ export type ScenarioPrefixRefusalReason = "stored_prefix" | "older_replica";
 /**
  * M42 的起服拒。具名类型 + 机读码 + 拒因;继承 {@link StoreBootRefusalError}(SQL 开库的等待窗不重试它;隐式 local 的降级臂不吞)。一个字节没改(扫描只读,标记没写)。
  *  · `stored_prefix` —— 存量里有以保留前缀开头的身份(`hits` 逐来源点名);
- *  · `older_replica` —— 零命中,但有停-迁-起证据:更早版本的副本可能还在服务,扫描之后它还会收下这类身份 ⇒ 全停之后再起(`live` = 证据,带时刻)。
+ *  · `older_replica` —— 标记不在,而有停-迁-起证据(守卫段在扫描之前判):更早版本的副本可能还在服务,扫描之后它还会收下这类身份 ⇒ 全停之后再起(`live` = 证据,带时刻)。
  */
 export declare class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
     readonly reason: ScenarioPrefixRefusalReason;

package/dist/plugins/scenario-prefix-switch-m42.js

@@ -31,9 +31,9 @@ export class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
             case "older_replica":
                 if (live === undefined)
                     throw new Error("scenario-prefix-switch: an older_replica refusal carries its evidence");
-                return (`${SCENARIO_PREFIX_SWITCH_REFUSED_CODE}: no stored identity starts with the reserved prefix "${SCENARIO_SUBJECT_PREFIX}", but ${olderReplicaEvidenceSentence(live)} ` +
+                return (`${SCENARIO_PREFIX_SWITCH_REFUSED_CODE}: this version reserves the prefix "${SCENARIO_SUBJECT_PREFIX}" and checks stored identities for it once before recording a marker, but ${olderReplicaEvidenceSentence(live)} ` +
                     `— a replica of an earlier version may still be serving, and it accepts principals with that prefix, so a clean check now would not stay clean. ` +
-                    `Nothing was changed and no marker was written. ${stopThenStartAction(live.after)}`);
+                    `Nothing was scanned or changed and no marker was written. ${stopThenStartAction(live.after)}`);
             default: {
                 const unhandled = reason;
                 throw new Error(`scenario-prefix-switch: unknown refusal reason ${String(unhandled)}`);

package/dist/plugins/schema-consistency.d.ts

@@ -185,8 +185,10 @@ export declare function describeMismatchedTables(dialect: SqlDialect, mismatches
 /**
  * **升级清单**(多行;`[]` = 没有语句要部署者执行,清单不出):一次起服的拒句里「这只库此刻对本构建还差什么、先后顺序」一段。
  * 缺列拒、判活拒、一次性迁移的拒本来各报各的一段 —— 运维补一句再起、才撞上下一族(列册对账在迁移段之后时,第四次起服才拒出其余全部 ALTER)。
- * 清单把本构建对这一只库的全部动作写成一张:① 逐表的 ALTER(其下 {@link describeMismatchedTables} 的逐表段,全库一次列全)② 这只库**还欠**的停-迁-起迁移
- * ③ 起服。第 ② 步逐行问登记行的 `stopThenStart.owedOn`(一次性迁移文件静态依赖本文件,所以惰性载入)—— 那条迁移的守卫自己问的同一只判据,清单不另判:
+ * 清单把本构建对这一只库的全部动作写成一张:⓪ 这只库要求、本构建没有的能力(起服要求表 `serving_requirement` 里本构建能力名单之外的行;有才出,排在一切语句之前 ——
+ * 照清单补完语句也不会让本构建能在这里服务:库形对账与「谁可以服务」是两个事实,补列是在把那条迁移改掉的形补回去)① 逐表的 ALTER(其下 {@link describeMismatchedTables} 的逐表段,
+ * 全库一次列全)② 这只库**还欠**的停-迁-起迁移 ③ 起服。第 ⓪ 步与准入同一只读法(`serving-requirement.ts` 的 `unmetServingRequirements`);要求表不在 ⇒ 不出(那是准入的 `table_absent`,
+ * 清单不判);读抛 ⇒ 照出并如实说没读到。第 ② 步逐行问登记行的 `stopThenStart.owedOn`(一次性迁移文件静态依赖本文件,所以惰性载入)—— 那条迁移的守卫段自己问的同一只判据,清单不另判:
  * 已经走过它们的库(标记落了 / 部署格已搬 / 零行旧词)一条不欠 ⇒ 第 ② 步与它的「不可滚动」动作段都不出,起服是第 ② 步。某一条读不出欠不欠(探针读抛)⇒ 照列并如实说
  * 没读到(多停一次,不漏停)。`read` = 列册对账读列册的同一只无参读口。
  */

package/dist/plugins/schema-consistency.js

@@ -2,7 +2,9 @@ import { recordEnsureStatements } from "./schema-ensure-legs.js";
 import { readLiveColumns } from "./schema-live-columns.js";
 import { SCHEMA_MISMATCH_WAYS_OUT } from "./schema-drift-sentence.js";
 import { SCHEMA_MISMATCH_ERROR_CODE, SchemaMismatchRefusedError, StoreBootRefusalError } from "./store-contracts.js";
-import { stopThenStartAction } from "./stop-then-start-sentence.js";
+import { stopThenStartAction, unmetRequirementChecklistStep } from "./stop-then-start-sentence.js";
+import { SERVING_REQUIREMENT_TABLE, unmetServingRequirements } from "./serving-requirement.js";
+import { REPLICA_CAPABILITIES } from "./replica-registration.js";
 const QUOTES = new Set(["'", '"', "`"]);
 function stripComments(sql) {
     let out = "";
@@ -469,7 +471,11 @@ export async function describeUpgradeChecklist(read, dialect, mismatches) {
         if (owes)
             owed.push(`  - ${m.id}: ${m.reason}`);
     }
-    const steps = [["Run every statement printed below, each recipe in the order it is printed (a printed comment line marks a value only you can choose) — all tables at once, before anything else (this build never alters a database for you)."]];
+    const steps = [];
+    const requirements = await unmetRequirementsForChecklist(read, dialect);
+    if (requirements !== undefined)
+        steps.push(requirements);
+    steps.push(["Run every statement printed below, each recipe in the order it is printed (a printed comment line marks a value only you can choose) — all tables at once, before anything else (this build never alters a database for you)."]);
     if (owed.length > 0) {
         steps.push([
             "Stop-then-start one-time migrations this database still owes: this build runs them itself on its first boot (no statement from you), and each refuses to start — writing nothing — while a run on this database has",
@@ -484,6 +490,17 @@ export async function describeUpgradeChecklist(read, dialect, mismatches) {
         ...steps.flatMap((lines, i) => lines.map((l, k) => (k === 0 ? `  ${i + 1}. ${l}` : `     ${l}`))),
     ];
 }
+async function unmetRequirementsForChecklist(read, dialect) {
+    try {
+        if (!(await readLiveColumns(read, dialect)).has(SERVING_REQUIREMENT_TABLE))
+            return undefined;
+        const unmet = await unmetServingRequirements(read, { capabilities: REPLICA_CAPABILITIES });
+        return unmet.length === 0 ? undefined : unmetRequirementChecklistStep(unmet);
+    }
+    catch (err) {
+        return unmetRequirementChecklistStep([], err instanceof Error ? err.message : String(err));
+    }
+}
 export function describeSchemaMismatch(dialect, mismatches, checklist = []) {
     const lines = [
         `${SCHEMA_MISMATCH_ERROR_CODE}: the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database does not match this build's schema — refusing to start.`,

package/dist/plugins/send-file-ledger.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { AppendLog, ensureDir, uuidv7 } from "@sema-agent/core";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
+import { sealStoreClass } from "./store-boundary.js";
 export const SENDFILE_SINGLE_USER_SCOPE = "_";
 export class TiDBSendFileLedger {
     pool;
@@ -17,6 +18,7 @@ export class TiDBSendFileLedger {
         return rows.map((r) => rowToEntry(r));
     }
 }
+sealStoreClass(TiDBSendFileLedger, "tidb-send-file-ledger", { record: "exit", listByScope: "exit" });
 export class PgSendFileLedger {
     pool;
     constructor(pool) {
@@ -32,6 +34,7 @@ export class PgSendFileLedger {
         return res.rows.map(rowToEntry);
     }
 }
+sealStoreClass(PgSendFileLedger, "pg-send-file-ledger", { record: "exit", listByScope: "exit" });
 function rowToEntry(r) {
     return {
         id: String(r.id),