@sema-agent/server 7.148.0 → 7.150.0

package/dist/plugins/approval-exemption-skill-cutoff.js

@@ -0,0 +1,122 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { SKILL_TOOL_NAME } from "@sema-agent/core";
+import { APPROVAL_EXEMPTION_DIR, EXEMPTION_LOG_SUFFIX, readExemptionLog } from "./approval-exemption-store.js";
+import { MIGRATION_MARKER_TABLE, SKILL_EXEMPTION_CUTOFF_ID } from "./one-time-migration-marker.js";
+import { atomicWriteFileSync } from "./owner-only-file-mode.js";
+import { readLiveColumns } from "./schema-live-columns.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
+export const SKILL_EXEMPTION_TOOL_NAME = SKILL_TOOL_NAME;
+export const SKILL_EXEMPTION_CUTOFF_SINCE = "7.148.0";
+export const LOCAL_SKILL_EXEMPTION_CUTOFF_FILE = "one-time-migration-M46.marker";
+export const PRE_CUTOFF_SKILL_EXEMPTION_CONSEQUENCE = `Such a row was written when approving a \`${SKILL_TOOL_NAME}\` call meant activating a skill (and pre-approving the tools that skill lists); ` +
+    `this build would read it as a standing answer for any later call of a tool named \`${SKILL_TOOL_NAME}\` in that session — a wider grant than the one given.`;
+function cutoffMsOf(raw) {
+    const n = typeof raw === "number" ? raw : typeof raw === "bigint" ? Number(raw) : typeof raw === "string" && /^-?\d+$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN;
+    return Number.isSafeInteger(n) && !Number.isNaN(new Date(n).getTime()) ? n : undefined;
+}
+export async function readSqlSkillExemptionCutoff(query, dialect) {
+    const [row] = await query(`SELECT marked_at_ms FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = ${dialect === "mysql" ? "?" : "$1"}`, [SKILL_EXEMPTION_CUTOFF_ID]);
+    if (row === undefined)
+        return undefined;
+    const ms = cutoffMsOf(row["marked_at_ms"]);
+    if (ms !== undefined)
+        return ms;
+    throw new StoreBootRefusalError(`${SCHEMA_MISMATCH_ERROR_CODE}: the Skill exemption cutoff row (${MIGRATION_MARKER_TABLE}, migration_id '${SKILL_EXEMPTION_CUTOFF_ID}') holds ${JSON.stringify(String(row["marked_at_ms"]))}, ` +
+        "which is not a time this build can read — refusing to start rather than guess which stored Skill session approval exemption rows predate it. " +
+        `Way out: DELETE FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = '${SKILL_EXEMPTION_CUTOFF_ID}'; then restart — the start records a new cutoff once the stored \`${SKILL_TOOL_NAME}\` rows are dealt with ` +
+        "(a release that still carries the one-time migration deletes them; a later release refuses until they are gone). This check only reads that row and changes nothing.");
+}
+export class LegacySkillExemptionsPresentError extends StoreBootRefusalError {
+    rows;
+    cutoff;
+    code = SCHEMA_MISMATCH_ERROR_CODE;
+    constructor(rows, cutoff) {
+        super(`${SCHEMA_MISMATCH_ERROR_CODE}: this database holds ${rows} \`${SKILL_TOOL_NAME}\` session approval exemption row(s) first granted before its Skill exemption cutoff ` +
+            `(${cutoff ?? "none recorded: no release that records it has started against this database"}) — refusing to start. ` +
+            `${PRE_CUTOFF_SKILL_EXEMPTION_CONSEQUENCE} ` +
+            `This build no longer carries the one-time migration (introduced in ${SKILL_EXEMPTION_CUTOFF_SINCE}) that deletes such rows. ` +
+            `Ways out: (1) start a server release at or above ${SKILL_EXEMPTION_CUTOFF_SINCE} that still carries that migration against this database once — it records the cutoff and deletes those rows — then start this build; ` +
+            `(2) or delete them yourself: DELETE FROM approval_exemption WHERE tool_name = '${SKILL_TOOL_NAME}'; — each session that held one is asked once more on its next \`${SKILL_TOOL_NAME}\` call. ` +
+            "The check behind this refusal is read-only and runs before this build creates any table: it changed nothing in the database.");
+        this.rows = rows;
+        this.cutoff = cutoff;
+        this.name = "LegacySkillExemptionsPresentError";
+    }
+}
+export async function judgeSqlSkillExemptionCutoff(query, dialect, carried) {
+    const live = await readLiveColumns((sql) => query(sql), dialect);
+    const cutoffMs = live.has(MIGRATION_MARKER_TABLE) ? await readSqlSkillExemptionCutoff(query, dialect) : undefined;
+    if (carried || !live.has("approval_exemption"))
+        return;
+    const ph = (i) => (dialect === "mysql" ? "?" : `$${i}`);
+    const [counted] = cutoffMs === undefined
+        ? await query(`SELECT COUNT(*) AS n FROM approval_exemption WHERE tool_name = ${ph(1)}`, [SKILL_EXEMPTION_TOOL_NAME])
+        : await query(`SELECT COUNT(*) AS n FROM approval_exemption WHERE tool_name = ${ph(1)} AND created_at < ${ph(2)}`, [SKILL_EXEMPTION_TOOL_NAME, new Date(cutoffMs)]);
+    const rows = Number(counted?.["n"] ?? 0);
+    if (rows > 0)
+        throw new LegacySkillExemptionsPresentError(rows, cutoffMs === undefined ? null : new Date(cutoffMs).toISOString());
+}
+export async function assertSkillExemptionCutoffHeldOnPool(target, carried) {
+    if (target.dialect === "mysql") {
+        const conn = await target.pool.getConnection();
+        try {
+            await judgeSqlSkillExemptionCutoff(async (sql, params) => (await conn.query(sql, params === undefined ? [] : [...params]))[0], "mysql", carried);
+        }
+        finally {
+            conn.release();
+        }
+        return;
+    }
+    const client = await target.pool.connect();
+    try {
+        await judgeSqlSkillExemptionCutoff(async (sql, params) => (await client.query(sql, params === undefined ? [] : [...params])).rows, "pg", carried);
+    }
+    finally {
+        client.release();
+    }
+}
+export function skillExemptionCutoffOfText(text) {
+    const t = Date.parse(text.trim());
+    return Number.isFinite(t) ? t : undefined;
+}
+export function writeLocalSkillExemptionCutoff(path, cutoffMs) {
+    atomicWriteFileSync(path, `${new Date(cutoffMs).toISOString()}\n`, { durability: "required" });
+}
+function exemptionLogNames(root) {
+    try {
+        return readdirSync(join(root, APPROVAL_EXEMPTION_DIR)).filter((name) => name.endsWith(EXEMPTION_LOG_SUFFIX)).sort();
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return [];
+        throw e;
+    }
+}
+export function localSkillExemptionSessionsBefore(root, cutoffMs, warn) {
+    let sessions = 0;
+    for (const name of exemptionLogNames(root)) {
+        const { rows, gate } = readExemptionLog(join(root, APPROVAL_EXEMPTION_DIR, name), warn);
+        if (gate.tripped)
+            continue;
+        const row = rows.get(SKILL_EXEMPTION_TOOL_NAME);
+        if (row !== undefined && (cutoffMs === undefined || row.createdAt < cutoffMs))
+            sessions += 1;
+    }
+    return sessions;
+}
+export function exemptionLogFingerprints(root) {
+    return exemptionLogNames(root).map((name) => {
+        const st = statSync(join(root, APPROVAL_EXEMPTION_DIR, name));
+        return `${name}\u0000${st.size}\u0000${st.mtimeMs}`;
+    });
+}
+export function settleLocalSkillExemptionCutoff(physicalRoot, action, now = Date.now) {
+    switch (action) {
+        case "none":
+            return;
+        case "lay":
+            return writeLocalSkillExemptionCutoff(join(physicalRoot, LOCAL_SKILL_EXEMPTION_CUTOFF_FILE), now());
+    }
+}
+//# sourceMappingURL=approval-exemption-skill-cutoff.js.map

package/dist/plugins/approval-exemption-skill-m46.d.ts

@@ -1,10 +1,4 @@
 import type { FileApprovalExemptionStore } from "./approval-exemption-store.js";
-/** 本条在标记表(`one-time-migration-marker.ts`)里的那一行的键。 */
-export declare const LEGACY_SKILL_EXEMPTION_MARKER_ID = "M46";
-/** local 车道的标记文件(数据根下,文件名即本条;正文 = T0 的 ISO 时刻一行,人可直接读)。 */
-export declare const LOCAL_LEGACY_SKILL_EXEMPTION_MARKER_FILE = "one-time-migration-M46.marker";
-/** 被删行的 wire 工具名 —— 引擎 `Skill` 工具的名字,core 导出(core 改名 ⇒ 谓词跟着走,不会静默指向空气)。 */
-export declare const LEGACY_SKILL_EXEMPTION_TOOL_NAME: string;
 /** SQL 腿一页的会话数(键集分批:`session_id` 升序,一页一次读、一句删)。 */
 export declare const LEGACY_SKILL_EXEMPTION_PAGE = 500;
 /**

package/dist/plugins/approval-exemption-skill-m46.js

@@ -1,25 +1,21 @@
 import { existsSync, readFileSync } from "node:fs";
-import { SKILL_TOOL_NAME } from "@sema-agent/core";
-import { atomicWriteFileSync } from "./owner-only-file-mode.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
-export const LEGACY_SKILL_EXEMPTION_MARKER_ID = "M46";
-export const LOCAL_LEGACY_SKILL_EXEMPTION_MARKER_FILE = "one-time-migration-M46.marker";
-export const LEGACY_SKILL_EXEMPTION_TOOL_NAME = SKILL_TOOL_NAME;
+import { SKILL_EXEMPTION_TOOL_NAME, skillExemptionCutoffOfText, writeLocalSkillExemptionCutoff } from "./approval-exemption-skill-cutoff.js";
 export const LEGACY_SKILL_EXEMPTION_PAGE = 500;
 export function legacySkillExemptionCutoffLocal(markerPath, now = Date.now) {
     if (existsSync(markerPath)) {
-        const marked = Date.parse(readFileSync(markerPath, "utf8").trim());
-        if (!Number.isFinite(marked)) {
-            throw new StoreBootRefusalError(`one-time migration ${LEGACY_SKILL_EXEMPTION_MARKER_ID}: ${markerPath} exists but does not hold a readable cutoff time (expected one ISO time, e.g. 2026-11-06T09:00:00.000Z); ` +
+        const marked = skillExemptionCutoffOfText(readFileSync(markerPath, "utf8"));
+        if (marked === undefined) {
+            throw new StoreBootRefusalError(`one-time migration M46: ${markerPath} exists but does not hold a readable cutoff time (expected one ISO time, e.g. 2026-11-06T09:00:00.000Z); ` +
                 `refusing to start rather than guess which stored Skill exemption rows predate the upgrade. Delete the file and restart: the step then records a new cutoff (now) and deletes the stored Skill exemption rows older than it.`);
         }
         return marked;
     }
     const t0 = now();
-    atomicWriteFileSync(markerPath, `${new Date(t0).toISOString()}\n`, { durability: "required" });
+    writeLocalSkillExemptionCutoff(markerPath, t0);
     return t0;
 }
 export function dropLocalLegacySkillExemptionsM46(markerPath, store) {
-    return store.dropToolRowsCreatedBeforeM46(LEGACY_SKILL_EXEMPTION_TOOL_NAME, legacySkillExemptionCutoffLocal(markerPath));
+    return store.dropToolRowsCreatedBeforeM46(SKILL_EXEMPTION_TOOL_NAME, legacySkillExemptionCutoffLocal(markerPath));
 }
 //# sourceMappingURL=approval-exemption-skill-m46.js.map

package/dist/plugins/approval-exemption-store.d.ts

@@ -1,5 +1,6 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+import { type JsonlStoreGate } from "../observability/corrupt-read-seat.js";
 import type { Logger } from "../observability/logger.js";
 /** The server's own audit event for a question a row answered without asking anyone — one name for both reading positions
  *  (the list gate: field `seat: "deployment_list"`; the approval seat: `seat: "approval_seat"`). Not a settlement record: nobody
@@ -48,6 +49,30 @@ export declare class MemoryApprovalExemptionStore implements ApprovalExemptionSt
     revoke(sessionId: string, toolName: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;
 }
+/** The File twin's directory under the data root (one JSONL log per session) and the log suffix — the store and the `Skill` cutoff's skip-version arm read the same layout. */
+export declare const APPROVAL_EXEMPTION_DIR = "approval-exemptions";
+export declare const EXEMPTION_LOG_SUFFIX = ".jsonl";
+/**
+ * A record whose first-grant time cannot be read (no `ts`, or a `ts` that is not a time — only a damaged or hand-edited log; the writer always stamps it)
+ * reads as the EARLIEST time, never as "now": every reader that asks "granted before cutoff X?" (the `Skill` exemption cutoff arm, one-time migration M46)
+ * then answers yes — the fail-closed direction. ("Now" changed with every restart and, read after a cutoff was recorded, silently kept such a row.)
+ */
+export declare const UNDATED_FIRST_GRANT_MS = 0;
+/** One session log's replayed rows: per wire tool name, the row in force (`createdAt` = its FIRST grant since the last revoke; unreadable ⇒ {@link UNDATED_FIRST_GRANT_MS}). */
+export type ExemptionLogRows = ReadonlyMap<string, {
+    readonly grantedBy: string | null;
+    readonly createdAt: number;
+}>;
+/**
+ * Replay ONE session log (the only reader of a log's bytes: the store's hydrate and the `Skill` cutoff's skip-version arm both call it —
+ * `approval-exemption-skill-cutoff.ts`). Torn-tail-safe, last-wins with revoke tombstones; a record in the middle that cannot be read closes
+ * that file's gate (`gate.tripped`) — the store then refuses every read of that session (ask anyway), so its rows answer nothing.
+ * A record without a parseable `ts` reads as granted now (the replay's own moment).
+ */
+export declare function readExemptionLog(path: string, warn?: Logger["warn"]): {
+    readonly rows: ExemptionLogRows;
+    readonly gate: JsonlStoreGate;
+};
 /**
  * 🔴 [ref] —— **fail-closed per session file.** A record in the MIDDLE of a session's log that cannot be read (bit rot,
  * a hand edit, a line `42`, an object missing `toolName`) used to be skipped silently. When that line was a REVOKE
@@ -73,7 +98,7 @@ export declare class FileApprovalExemptionStore implements ApprovalExemptionStor
     /** [ref]: first line of every judging / appending method (see the class note). */
     private assertUsable;
     private pathFor;
-    /** Replay every session log (torn-tail-safe; last-wins with revoke tombstones). Index keyed by the SANITIZED id. */
+    /** Replay every session log (torn-tail-safe; last-wins with revoke tombstones). Index keyed by the SANITIZED id. One reader per file: {@link readExemptionLog}. */
     private hydrate;
     private logFor;
     grant(sessionId: string, toolName: string, grantedBy: string | null): Promise<void>;

package/dist/plugins/approval-exemption-store.js

@@ -115,6 +115,27 @@ const EXEMPTION_RECORD_SHAPE = {
         return { toolName, grantedBy: grantedBy ?? null, ts: ts ?? "", ...(revoked !== undefined ? { revoked } : {}) };
     },
 };
+export const APPROVAL_EXEMPTION_DIR = "approval-exemptions";
+export const EXEMPTION_LOG_SUFFIX = ".jsonl";
+export const UNDATED_FIRST_GRANT_MS = 0;
+const firstGrantMsOf = (ts) => {
+    const t = Date.parse(ts);
+    return Number.isNaN(t) ? UNDATED_FIRST_GRANT_MS : t;
+};
+export function readExemptionLog(path, warn) {
+    const { records, gate } = replayJsonlGuarded(path, "approval-exemption", EXEMPTION_RECORD_SHAPE, warn);
+    const rows = new Map();
+    for (const r of records) {
+        if (r.revoked) {
+            rows.delete(r.toolName);
+        }
+        else {
+            const prior = rows.get(r.toolName);
+            rows.set(r.toolName, { grantedBy: r.grantedBy ?? null, createdAt: prior?.createdAt ?? firstGrantMsOf(r.ts) });
+        }
+    }
+    return { rows, gate };
+}
 export class FileApprovalExemptionStore {
     dir;
     bySession = new Map();
@@ -122,7 +143,7 @@ export class FileApprovalExemptionStore {
     corruptGates = new Map();
     warn;
     constructor(root, opts) {
-        this.dir = join(root, "approval-exemptions");
+        this.dir = join(root, APPROVAL_EXEMPTION_DIR);
         this.warn = opts?.warn;
         ensureDir(this.dir);
         this.hydrate();
@@ -131,7 +152,7 @@ export class FileApprovalExemptionStore {
         this.corruptGates.get(key)?.assertUsable();
     }
     pathFor(sessionId) {
-        return join(this.dir, `${sanitizePathComponent(sessionId)}.jsonl`);
+        return join(this.dir, `${sanitizePathComponent(sessionId)}${EXEMPTION_LOG_SUFFIX}`);
     }
     hydrate() {
         let names;
@@ -142,26 +163,14 @@ export class FileApprovalExemptionStore {
             return;
         }
         for (const name of names) {
-            if (!name.endsWith(".jsonl"))
+            if (!name.endsWith(EXEMPTION_LOG_SUFFIX))
                 continue;
-            const key = name.slice(0, -".jsonl".length);
-            const { records, gate } = replayJsonlGuarded(join(this.dir, name), "approval-exemption", EXEMPTION_RECORD_SHAPE, this.warn);
+            const key = name.slice(0, -EXEMPTION_LOG_SUFFIX.length);
+            const { rows, gate } = readExemptionLog(join(this.dir, name), this.warn);
             if (gate.tripped)
                 this.corruptGates.set(key, gate);
-            if (!records.length)
-                continue;
-            const m = this.bySession.get(key) ?? new Map();
-            for (const r of records) {
-                if (r.revoked) {
-                    m.delete(r.toolName);
-                }
-                else {
-                    const prior = m.get(r.toolName);
-                    m.set(r.toolName, { grantedBy: r.grantedBy ?? null, createdAt: prior?.createdAt ?? (Date.parse(r.ts) || Date.now()) });
-                }
-            }
-            if (m.size)
-                this.bySession.set(key, m);
+            if (rows.size)
+                this.bySession.set(key, new Map(rows));
             else
                 this.bySession.delete(key);
         }

package/dist/plugins/ensure-schema-lock-policy.d.ts

@@ -1,14 +1,47 @@
 export declare const LOCK_PROBE_INITIAL_JITTER_MS = 400;
 export declare const LOCK_PROBE_WARN_EVERY = 40;
 export declare const MAX_CONSECUTIVE_LOCK_PROBE_ERRORS = 5;
-/** 抖动退避(~0.1s..0.4s + 至多 0.15s 抖动)—— 两方言同一条曲线。 */
+/** 抖动退避(~0.1s..0.4s + 至多 0.15s 抖动)—— 启动锁的曲线。 */
 export declare function lockProbeBackoffMs(attempt: number): number;
 /**
- * 轮到拿到为止。`tryOnce` = 方言自己的非阻塞探针:`true` 拿到、`false` 别人持着(继续轮)、抛 = 探针本身失败。
- * 初始抖动把 ~20 个在 t=0 同时开火的调用方(集成套扇出 / 同步的舰队启动)铺开。
+ * 一把库内具名锁的身份。两方言的「名字」不同形(引擎事实,不是口味):MySQL 协议一个字符串(服务器实例**全局**,上限 64 字符),
+ * PG 一个 bigint 键或一对 int4 键(**每库**;单键与双键是两个互不相交的键空间)。身份由属主模块各自铸(启动锁:`tidb-pool.ts` / `pg-pool.ts`;弧锁:`adoption-log-sql.ts`),
+ * 本模块只负责怎么取、怎么放。
+ */
+export type AdvisoryLockId = {
+    readonly dialect: "mysql";
+    readonly name: string;
+} | {
+    readonly dialect: "pg";
+    readonly keys: readonly [number] | readonly [number, number];
+};
+/**
+ * 取锁要的最小连接面:发一句带参 SQL、读回行。锁是**连接级**的 —— 调用方必须把取、放与锁罩住的全部语句跑在**同一条**连接上。
+ * `SqlTxConn`(`{ rows, affected }`)与 node-pg 的 `PoolClient`(`{ rows }`)天然满足;mysql2 的 `[rows, fields]` 由调用方一行适配。
+ */
+export interface LockConn {
+    query(sql: string, params: unknown[]): Promise<{
+        readonly rows: ReadonlyArray<Record<string, unknown>>;
+    }>;
+}
+/**
+ * 轮到拿到为止(启动锁的预算)。`tryOnce` = 方言自己的非阻塞探针:`true` 拿到、`false` 别人持着(继续轮)、抛 = 探针本身失败。
+ * 取锁调用方走 {@link acquireAdvisoryLock};本函数留给只想验循环律、不带连接的单测。
  */
 export declare function pollUntilLocked(tryOnce: () => Promise<boolean>, opts: {
     tag: string;
     label: string;
 }): Promise<void>;
+/**
+ * 在 `conn` 上取 `id`,**轮到拿到为止**(永不无锁跑;一条探针连续抛的连接上抛成起服失败)。
+ * 锁是连接级的:调用方必须把锁罩住的全部语句跑在这条 `conn` 上,并用 {@link releaseAdvisoryLock} 放。
+ */
+export declare function acquireAdvisoryLock(conn: LockConn, id: AdvisoryLockId, tag: string): Promise<void>;
+/**
+ * 在 `conn` 上取 `id`,**最多探 `attempts` 次、每次没拿到睡 `sleepMs`**(无开跑抖动:常路零额外延迟)。
+ * `true` = 拿到(调用方负责放);`false` = 用尽次数仍是「别人持着」(调用方按「在飞」应答)。其余同 {@link acquireAdvisoryLock}。
+ */
+export declare function acquireAdvisoryLockWithin(conn: LockConn, id: AdvisoryLockId, tag: string, attempts: number, sleepMs: number): Promise<boolean>;
+/** {@link acquireAdvisoryLock} / {@link acquireAdvisoryLockWithin} 的释放(尽力而为 —— 锁随连接关闭自动释放;失败留一行,不盖掉真正的结果)。 */
+export declare function releaseAdvisoryLock(conn: LockConn, id: AdvisoryLockId, tag: string): Promise<void>;
 //# sourceMappingURL=ensure-schema-lock-policy.d.ts.map

package/dist/plugins/ensure-schema-lock-policy.js

@@ -6,27 +6,93 @@ export function lockProbeBackoffMs(attempt) {
     return 100 + Math.min(attempt, 3) * 100 + Math.floor(Math.random() * 150);
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-export async function pollUntilLocked(tryOnce, opts) {
-    await sleep(Math.floor(Math.random() * LOCK_PROBE_INITIAL_JITTER_MS));
+const TIDB_PESSIMISTIC_RETRY_LIMIT = "pessimistic lock retry limit reached";
+function isTidbPessimisticRetryLimit(err) {
+    return err?.message === TIDB_PESSIMISTIC_RETRY_LIMIT;
+}
+function lockStatements(id) {
+    switch (id.dialect) {
+        case "mysql":
+            return {
+                probe: "SELECT GET_LOCK(?, 0) AS got",
+                release: "SELECT RELEASE_LOCK(?)",
+                params: [id.name],
+                label: `GET_LOCK('${id.name}')`,
+                held: (row) => Number(row?.got) === 1,
+                contended: isTidbPessimisticRetryLimit,
+            };
+        case "pg":
+            return id.keys.length === 1
+                ? { probe: "SELECT pg_try_advisory_lock($1) AS got", release: "SELECT pg_advisory_unlock($1)", params: [...id.keys], label: `pg advisory lock ${id.keys[0]}`, held: (row) => row?.got === true, contended: () => false }
+                : { probe: "SELECT pg_try_advisory_lock($1, $2) AS got", release: "SELECT pg_advisory_unlock($1, $2)", params: [...id.keys], label: `pg advisory lock ${id.keys[0]}/${id.keys[1]}`, held: (row) => row?.got === true, contended: () => false };
+        default: {
+            const unreachable = id;
+            throw new Error(`unreachable advisory-lock dialect: ${JSON.stringify(unreachable)}`);
+        }
+    }
+}
+const UNTIL_HELD = { initialJitterMs: LOCK_PROBE_INITIAL_JITTER_MS, maxAttempts: Number.POSITIVE_INFINITY, backoffMs: lockProbeBackoffMs };
+async function pollLock(tryOnce, budget, opts) {
+    if (budget.initialJitterMs > 0)
+        await sleep(Math.floor(Math.random() * budget.initialJitterMs));
     let consecutiveErrors = 0;
-    for (let attempt = 0;; attempt++) {
+    let lastMsg = "";
+    let lastErr;
+    for (let attempt = 0; attempt < budget.maxAttempts; attempt++) {
         try {
             if (await tryOnce())
-                return;
+                return true;
             consecutiveErrors = 0;
         }
         catch (err) {
             consecutiveErrors += 1;
-            const msg = err?.message ?? String(err);
-            writeLogText("stderr", `[${opts.tag}] ${opts.label} probe attempt ${attempt + 1} threw (${consecutiveErrors}/${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS}):`, msg);
+            lastErr = err;
+            lastMsg = err?.message ?? String(err);
+            writeLogText("stderr", `[${opts.tag}] ${opts.label} probe attempt ${attempt + 1} threw (${consecutiveErrors}/${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS}):`, lastMsg);
             if (consecutiveErrors >= MAX_CONSECUTIVE_LOCK_PROBE_ERRORS) {
-                throw new Error(`[${opts.tag}] ${opts.label}: lock probe threw ${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS} times in a row — the connection itself is unusable, refusing to poll forever (last: ${msg})`, { cause: err });
+                throw new Error(`[${opts.tag}] ${opts.label}: lock probe threw ${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS} times in a row — the connection itself is unusable, refusing to poll forever (last: ${lastMsg})`, { cause: err });
             }
         }
         if (attempt > 0 && attempt % LOCK_PROBE_WARN_EVERY === 0) {
-            writeLogText("stderr", `[${opts.tag}] still waiting for ${opts.label} (another replica is running the serialized DDL; attempt ${attempt})`);
+            writeLogText("stderr", `[${opts.tag}] still waiting for ${opts.label} (another session holds it; attempt ${attempt})`);
         }
-        await sleep(lockProbeBackoffMs(attempt));
+        if (attempt + 1 < budget.maxAttempts)
+            await sleep(budget.backoffMs(attempt));
+    }
+    if (consecutiveErrors > 0) {
+        throw new Error(`[${opts.tag}] ${opts.label}: the attempt budget (${budget.maxAttempts}) ran out while the lock probe was still throwing (${consecutiveErrors} in a row) — not reading that as "held by another" (last: ${lastMsg})`, { cause: lastErr });
+    }
+    return false;
+}
+export async function pollUntilLocked(tryOnce, opts) {
+    await pollLock(tryOnce, UNTIL_HELD, opts);
+}
+async function tryAdvisoryLock(conn, stmts) {
+    try {
+        const res = await conn.query(stmts.probe, stmts.params);
+        return stmts.held(res.rows[0]);
+    }
+    catch (err) {
+        if (stmts.contended(err))
+            return false;
+        throw err;
+    }
+}
+export async function acquireAdvisoryLock(conn, id, tag) {
+    const stmts = lockStatements(id);
+    await pollLock(() => tryAdvisoryLock(conn, stmts), UNTIL_HELD, { tag, label: stmts.label });
+}
+export async function acquireAdvisoryLockWithin(conn, id, tag, attempts, sleepMs) {
+    const stmts = lockStatements(id);
+    return pollLock(() => tryAdvisoryLock(conn, stmts), { initialJitterMs: 0, maxAttempts: attempts, backoffMs: () => sleepMs }, { tag, label: stmts.label });
+}
+export async function releaseAdvisoryLock(conn, id, tag) {
+    const stmts = lockStatements(id);
+    try {
+        await conn.query(stmts.release, stmts.params);
+    }
+    catch (err) {
+        writeLogText("stderr", `[${tag}] releasing ${stmts.label} failed (the lock auto-frees when the connection closes):`, err);
     }
 }
 //# sourceMappingURL=ensure-schema-lock-policy.js.map

package/dist/plugins/exec-path-law.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The execution seam's path law — ONE reading for every execution environment this server mints (the seven lanes: adb / device / e2b /
+ * host / k8s / local-docker / ssh) and for the sandbox write gate's stand-in environment (`boot/deferred-sandbox-path-env.ts`).
+ *
+ * The law (the engine's, `ExecutionEnv` contract; the engine's own `NodeExecutionEnv` reads every path this way): a path a method is
+ * handed is ABSOLUTE AS WRITTEN, or relative and ANCHORED at the environment's working directory with exactly one separator. Nothing here
+ * folds a `..` or a `.` and nothing resolves a link: the filesystem the path lands on resolves them, components first — so a `..` that
+ * follows a symbolic link goes where the link leads (`<base>/bridge/../next` with `bridge -> elsewhere/sub` names `<base>/elsewhere/next`).
+ * A lexical fold would name `<base>/next` instead: the write gate (which asks the real filesystem what the spelling names) and the tool
+ * (which opened the folded name) would then judge and touch two different files.
+ *
+ * Three faces, one anchor ({@link anchorUnder}): the path a method reads ({@link anchoredPath}), `joinPath` ({@link joinedPath}) and the
+ * paths a listing reports (each entry anchored under the path the listing was handed). The remote lanes' shell scripts (the link-chain walk
+ * and the staged write, `remote-shell.ts`) already anchor this way in shell; this module is the same law for the TypeScript faces.
+ *
+ * Pure leaf: string arithmetic only, no I/O.
+ */
+import type { PlatformPath } from "node:path";
+/**
+ * The two facts of a path family the law reads: its separator and its absolute-path judge. The remote lanes read POSIX whatever the
+ * worker runs on (`path.posix`; the device lane passes its one absolute-path judge, `isDeviceAbsolutePath`); the host lane reads the
+ * worker's own (`path`).
+ */
+export type SeamPathFamily = Pick<PlatformPath, "sep" | "isAbsolute">;
+/** `name` placed under `dir` with exactly one separator — never folded, never re-rooted. */
+export declare function anchorUnder(family: SeamPathFamily, dir: string, name: string): string;
+/** The path a method is handed, as the environment reads it: absolute ⇒ as written; relative ⇒ anchored at `cwd`. */
+export declare function anchoredPath(family: SeamPathFamily, cwd: string, p: string): string;
+/**
+ * `joinPath`: the first part as written; every later part is a segment, never a root (its leading separators are dropped); empty parts
+ * are dropped; the rest anchored in turn. No parts ⇒ `"."`.
+ */
+export declare function joinedPath(family: SeamPathFamily, parts: readonly string[]): string;
+//# sourceMappingURL=exec-path-law.d.ts.map

package/dist/plugins/exec-path-law.js

@@ -0,0 +1,13 @@
+export function anchorUnder(family, dir, name) {
+    const endsInSeparator = dir.endsWith(family.sep) || (family.sep === "\\" && dir.endsWith("/"));
+    return endsInSeparator ? `${dir}${name}` : `${dir}${family.sep}${name}`;
+}
+export function anchoredPath(family, cwd, p) {
+    return family.isAbsolute(p) ? p : anchorUnder(family, cwd, p);
+}
+export function joinedPath(family, parts) {
+    const leading = family.sep === "\\" ? /^[\\/]+/ : /^\/+/;
+    const named = parts.map((part, i) => (i === 0 ? part : part.replace(leading, ""))).filter((part) => part !== "");
+    return named.length === 0 ? "." : named.reduce((at, part) => anchorUnder(family, at, part));
+}
+//# sourceMappingURL=exec-path-law.js.map

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

@@ -204,15 +204,16 @@ export declare class FileRunStore implements InProcessClaimFence {
     /** The terminal write's one synchronous section (SQL twin: one transaction): the k8s space's pending commit record (when
      *  offered) → the terminal row → the active-run claim release. Returns whether the pending record is now this run's. */
     private writeTerminal;
-    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard).
-     *  [ref]:同时落 `result` —— 封口脱敏后的投影(`sealRunRowResult`,凭据不落;`null` = 没观察到 park 结果),SQL 孪生同注。 */
-    setSuspended(taskId: string, result: PersistedTaskResult | null): Promise<void>;
-    /** [ref] D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review.
-     *  [ref]:同 {@link setSuspended} 落封口脱敏后的 `result`。 */
-    setNeedsReview(taskId: string, result: PersistedTaskResult | null): Promise<void>;
-    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags.
-     *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
-    markResuming(taskId: string, instanceId: string): Promise<boolean>;
+    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS = 行仍归 `legId` ∧ running / suspended ∧ 没挂取消请求(三件的理由见 SQL 孪生)。
+     *  [ref]:同时落 `result` —— 封口脱敏后的投影(`sealRunRowResult`,凭据不落;`null` = 没观察到 park 结果),SQL 孪生同注。
+     *  交回 CAS 的答(内存 / SQL 孪生同义):`true` ⇔ 这一写之后行停在这个词上;`false` ⇔ 三件有一件不成立(或行不在)。判与落盘同一个同步段。 */
+    setSuspended(taskId: string, result: PersistedTaskResult | null, legId: string): Promise<boolean>;
+    /** [ref] D-B: park NON-terminal `needs_review`, KEEP the claim. CAS = {@link setSuspended} 的三件(词换成 needs_review)。
+     *  [ref]:同 {@link setSuspended} 落封口脱敏后的 `result`;CAS 的答同 {@link setSuspended}。 */
+    setNeedsReview(taskId: string, result: PersistedTaskResult | null, legId: string): Promise<boolean>;
+    /** Durable F4 resume: flip suspended/needs_review → running (CAS);认领 = 换持有腿(铸新的 `legId` 交回)+ 两面请求旗随旧腿清零(SQL 孪生同注)。
+     *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改、交回 `undefined`。 */
+    markResuming(taskId: string, instanceId: string): Promise<string | undefined>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     /** 认领当写栅栏用(契约 = `store-contracts.ts` 的 `InProcessClaimFence`):判、刷新活性(同步落盘)与 `write` 是同一个同步段。 */
     whileHoldingClaim(sessionId: string, taskId: string, write: (run: FencedRun) => FenceLanded): boolean;
@@ -222,6 +223,13 @@ export declare class FileRunStore implements InProcessClaimFence {
      *  the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
      *  is the refusal's record); only the binding is freed. */
     releaseIdemKey(taskId: string): Promise<void>;
+    /** 放一条行上的提交幂等键绑定(盘先、索引后;`releaseIdemKey` 与 `withdrawMintedRun` 的非在跑臂同读)。同步段。 */
+    private dropIdemBinding;
+    /**
+     * 撤回本请求铸的这一条 run(SQL 孪生同判同序,律见那里的头注):行上的持有腿不是 `legId` ⇒ 不是本腿的行,一个字节不动;是 ⇒ 行仍在跑 ⇒ 严格删行({@link dropRun}:盘先、索引后;删不掉 ⇒ 抛,认领与行都没动)、
+     * 再放本行持有的那一枚认领;已终局 ⇒ 行零删(收割 / 终局先到,那一份就是这条行的结局),只放它上面的提交幂等键;停驻 ⇒ 一个字节不动。同步段,不让出事件循环。交回删没删。
+     */
+    withdrawMintedRun(taskId: string, legId: string): Promise<boolean>;
     /** The body fingerprint this row's binding of `idem.key` holds — binding `idem.bodyFingerprint` first when it holds none (first
      *  arrival binds and is persisted, everyone after reads; the file twin of the SQL conditional UPDATE — one writer per data root,
      *  single-threaded between the check and the write). `null` = no such row, or the row is not bound to this key (never written). */
@@ -422,8 +430,13 @@ export declare class FileRunStore implements InProcessClaimFence {
     /**
      * 一次性迁移 **M48 的 local 腿**(run 行半场;窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):属主恰为 cli 哨兵(`shell-sentinel-owner-m48.ts`)的 run 行
      * 改写成无主。盘上与内存同改(副本写律)。起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);数据根独占 ⇒ 没有混跑窗。幂等:第二跑零命中零写盘。
+     * 命中的行由 {@link shellSentinelRunsM48} 说(与 {@link countShellSentinelOwnersM48} 同一只)。
      */
     clearShellSentinelOwnersM48(): number;
+    /** 一次性迁移 **M48 的 local 腿**(有身份边界的部署:只数不写):属主恰为 cli 哨兵的 run 行数 —— 命中判据与 {@link clearShellSentinelOwnersM48} 同一只({@link shellSentinelRunsM48})。读内存索引,零写。 */
+    countShellSentinelOwnersM48(): number;
+    /** M48(local 腿)命中的 run 行:属主恰为 cli 哨兵({@link isShellSentinelOwnerM48})—— 改写与留存计数共用的**唯一**判据。先取快照再改(改写会 `persist` 替换索引里的行)。随 M48 删。 */
+    private shellSentinelRunsM48;
     /**
      * 一次性迁移 **M32 的 local 腿**(执行放置回填;窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):有 run 行的会话 id(去重)。
      * 起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);读内存索引(构造时已从盘上 hydrate),零写。