@sema-agent/server 7.125.1 → 7.127.0

package/dist/plugins/remote-env-local-docker.d.ts

@@ -73,11 +73,15 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
+        canonicalPathAuthoritative: boolean;
     };
     /** Working directory inside the container; relative paths resolve against it (ExecutionEnv contract). */
     cwd: string;
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
+    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在容器里(镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+     *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
+    readonly cdPath: "unknown";
     private readonly cfg;
     private readonly spawnFn;
     /** Stable container NAME (also our handle id). Created on connect; targeted by every docker exec/cp/rm. */

package/dist/plugins/remote-env-local-docker.js

@@ -18,9 +18,10 @@ const unsupported = (op) => ({
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a local-docker target (v1: a container is an isolation boundary but not a managed memory snapshot; capabilities.suspendable=false)`),
 });
 export class RemoteLocalDockerExecutionEnv {
-    capabilities = { isolation: true, suspendable: false };
+    capabilities = { isolation: true, suspendable: false, canonicalPathAuthoritative: true };
     cwd;
     homeDir;
+    cdPath = "unknown";
     cfg;
     spawnFn;
     containerName;

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

@@ -94,6 +94,9 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private inFlight?;
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
+    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在远端登录 shell 里(目标机的 profile / env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+     *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
+    readonly cdPath: "unknown";
     private readonly cfg;
     private readonly injectedConnectOnce?;
     constructor(config: SshEnvConfig, deps?: SshEnvDeps);

package/dist/plugins/remote-env-ssh.js

@@ -24,6 +24,7 @@ export class RemoteSshExecutionEnv {
     connEpoch = 0;
     inFlight;
     homeDir;
+    cdPath = "unknown";
     cfg;
     injectedConnectOnce;
     constructor(config, deps) {

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

@@ -50,6 +50,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
 import { type IndexSpec } from "./ensure-index.js";
+import type { EndedSpace } from "../workspace-space.js";
 /**
  * 三只**被托管**的 SQL 店(session / checkpoint / tool-result)共用的 `retention` 声明常量。
  *
@@ -419,7 +420,9 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * ——后者跨十余张表、随部署形态漂(附件表可能不在场),做不成稳定判据;而「幂等重跑 ⇒ 0」这条契约在
      * 两种口径下同真。`tombstones` = 本次**新落地**的墓碑数(重跑时既有墓碑不重复计)。
      */
-    deleteExpiredSessions(input: RetentionCallInput): Promise<RetentionReceipt>;
+    deleteExpiredSessions(input: RetentionCallInput): Promise<RetentionReceipt & {
+        readonly endedSpaces?: readonly EndedSpace[];
+    }>;
     /**
      * E21 顺序契约的**事务化搬入**:同一组 DELETE、同一个顺序,一次性发在一条事务连接上。
      * 顺序的两条承重理由(其余是可读性):

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

@@ -68,7 +68,7 @@ export const TIDB_RETENTION_STATEMENTS = [
      row_key       VARCHAR(518) NOT NULL,
      deleted_at_ms BIGINT       NOT NULL,
      -- 🔴 主键**带 domain**(codex 对抗复审 R3-[high],验真后改):行键是 sessionId / tool_result.ref,而
-     -- 会话 id 是**调用方可自选**的(server.ts 逐字:「a client MAY supply an ARBITRARY id … LENGTH-ONLY」)
+     -- 会话 id 是**调用方提供**的(7.125.x 及更早任意 ≤64 字符串,7.126.0 起 canonical uuid —— 调用方仍可挑任意 uuid)
      -- ⇒ 两个租户先后用同一个 id 完全合法。旧形 PK(kind,row_key) 全局唯一,后果有两条,都不轻:
      --   ① 租户 B 删同名会话时墓碑 INSERT IGNORE 空转 ⇒ 回执 deleted=1 而 tombstones=0(账对不上),
      --      且 B 的域从此**枚举不到**它的孤儿(F4 的病灶原样复发);
@@ -222,7 +222,7 @@ export class SqlRetentionStore {
     async previewRetention(input) {
         const [checkpoints, sessions, toolResults] = await Promise.all([
             this.expiryCandidates(this.db, input).then((tokens) => tokens.length),
-            this.sessionCandidates(this.db, input).then((ids) => ids.length),
+            this.sessionCandidates(this.db, input).then((rows) => rows.length),
             this.countOrphanToolResultCandidates(this.db, input),
         ]);
         return { checkpoints, sessions, toolResults };
@@ -299,10 +299,10 @@ export class SqlRetentionStore {
     async sessionCandidates(exec, input, forUpdate = false) {
         const w = this.domainWhere("sm.owner", input.domain, 1);
         const suffix = forUpdate ? " FOR UPDATE" : "";
-        const { rows } = await exec.query(this.q(`SELECT sm.session_id FROM session_meta sm WHERE ${w.sql} AND sm.updated_at < ? AND NOT ${this.liveReferenceExists()} ` +
-            `ORDER BY sm.updated_at ASC LIMIT ?${suffix}`, `SELECT sm.session_id FROM session_meta sm WHERE ${w.sql} AND sm.updated_at < $2 AND NOT ${this.liveReferenceExists()} ` +
+        const { rows } = await exec.query(this.q(`SELECT sm.session_id, sm.incarnation FROM session_meta sm WHERE ${w.sql} AND sm.updated_at < ? AND NOT ${this.liveReferenceExists()} ` +
+            `ORDER BY sm.updated_at ASC LIMIT ?${suffix}`, `SELECT sm.session_id, sm.incarnation FROM session_meta sm WHERE ${w.sql} AND sm.updated_at < $2 AND NOT ${this.liveReferenceExists()} ` +
             `ORDER BY sm.updated_at ASC LIMIT $3${suffix}`), [...w.params, new Date(input.cutoffMs), RETENTION_SESSION_BATCH]);
-        return rows.map((r) => String(r.session_id));
+        return rows.map((r) => ({ id: String(r.session_id), incarnation: typeof r.incarnation === "string" ? r.incarnation : "" }));
     }
     async countOrphanToolResultCandidates(exec, input) {
         return (await this.orphanToolResultCandidates(exec, input)).length;
@@ -331,12 +331,14 @@ export class SqlRetentionStore {
                 skippedOnAbort = doomed.length + skipped;
                 let deleted = 0;
                 let tombstones = 0;
-                if (doomed.length > 0) {
-                    deleted = await this.purgeSessionTrees(conn, input.domain, doomed);
-                    tombstones = await this.writeTombstones(conn, input.domain, "session", doomed);
+                const ids = doomed.map((d) => d.id);
+                if (ids.length > 0) {
+                    deleted = await this.purgeSessionTrees(conn, input.domain, ids);
+                    tombstones = await this.writeTombstones(conn, input.domain, "session", ids);
                 }
                 await this.writeAuditRow(conn, { domain: input.domain, action: "deleted_sessions", audit, deleted, skipped, tombstones });
-                return { domain: input.domain, deleted, skipped, tombstones };
+                const endedSpaces = doomed.filter((d) => d.incarnation !== "").map((d) => ({ sessionId: d.id, spaceKey: d.incarnation }));
+                return { domain: input.domain, deleted, skipped, tombstones, ...(endedSpaces.length > 0 ? { endedSpaces } : {}) };
             });
         }
         catch (err) {

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

@@ -2,9 +2,10 @@ import type { TaskStatus } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
-import { type CreateRunOutcome, type NewRunMeta, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import { type SqlDriver } 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, SessionSummary, RunEvent, LatestRunRef } from "./store-contracts.js";
 export declare class SqlRunStore {
     protected readonly db: SqlDriver;
@@ -30,7 +31,8 @@ export declare class SqlRunStore {
      *
      * Submission idempotency rides the SAME mechanism on the row itself: `task_run` carries two unique keys a
      * submission can name — `task_id` (a caller-minted `body.taskId`) and `idem_key` (the scoped
-     * `Idempotency-Key`; NULL = none, which neither dialect's UNIQUE constrains). Claim + row are ONE
+     * `Idempotency-Key`; NULL = none, which neither dialect's UNIQUE constrains) — and, beside `idem_key`, the fingerprint
+     * of the request that bound it (`idem_body_fingerprint`; compared by the submit surface, never here). Claim + row are ONE
      * transaction, so a concurrent same-key submit on another replica either commits first (we collide on the
      * unique index — after its commit, PG/InnoDB/TiDB-pessimistic block on the uncommitted entry; TiDB-optimistic
      * reports it at COMMIT, which is why the commit sits inside the same classification) or loses to us.
@@ -84,6 +86,35 @@ export declare class SqlRunStore {
      *  blocked/timeout terminals — a first write of those could still be overwritten. The claim DELETE stays
      *  unconditional (idempotent; the first writer already released it). */
     setTerminal(taskId: string, status: TaskStatus, result: PersistedTaskResult | null, error: string | null): Promise<void>;
+    /** The space's row, or `undefined`. */
+    readSpaceCommit(spaceKey: string): Promise<SpaceCommitReading | undefined>;
+    /** Make the space's row this run's (its own transaction; the terminal write runs the same step inside its own). */
+    claimSpaceCommit(spaceKey: string, taskId: string, state: SpaceCommitState, claim: SpaceCommitClaim): Promise<boolean>;
+    /** Delete this run's row (never another run's). */
+    endSpaceCommit(spaceKey: string, taskId: string): Promise<void>;
+    /** Abandon run `taskId`'s commit (the reader's write, `workspace-space-commit.ts`): one transaction — lock the row, the
+     *  clock read under that lock, the shared rule, then a DELETE of that run's row. A writer's renewal in flight holds the
+     *  same lock, so the abandon judges the row it committed. */
+    abandonSpaceCommit(spaceKey: string, taskId: string): Promise<boolean>;
+    /** Dual-use read helper: pool-level plain read, or (`forUpdate`) the locking read inside a transaction. The row's
+     *  deadline, THEN the database clock on the same executor (`sqlDbNowMs`): the MySQL protocol's `NOW()` is its statement's
+     *  start, which a lock wait leaves behind — a deadline judged inside the locking statement would call a row that died
+     *  while this claim waited for its lock alive, and the claim would revive it. */
+    private readSpaceCommitIn;
+    /**
+     * One claim inside a transaction: the row made to exist when this claim may create it, a locking read, the shared
+     * decision, one conditional write (the deadline = db now + THIS run's `claim.boundMs`).
+     * Lock shape — never a locking read of a key that may be ABSENT followed by an insert: on InnoDB (REPEATABLE READ) a
+     * `FOR UPDATE` that finds no row takes a GAP lock, and this table holds only in-flight commits (mostly empty ⇒ every
+     * space key falls into one gap), so two terminal transactions of DIFFERENT spaces would each hold that gap and wait on
+     * the other's insert ⇒ `ER_LOCK_DEADLOCK` rolls back a terminal write. So a claim that may create the row
+     * (`!requireOwn`: {@link decideSpaceCommitClaim}'s `insert` on an absent row) creates it FIRST — form A of the lock-shape
+     * gate: the insert, or an exclusive lock on the row already there (MySQL `ON DUPLICATE KEY UPDATE pk = pk`, PG
+     * `ON CONFLICT … DO UPDATE` — never a gap lock, never a shared lock to upgrade) — and only then reads it under that lock.
+     * A claim that may not create it (`requireOwn`) only reads: its own short transaction, and a gap lock it may take is
+     * never followed by an insert.
+     */
+    private claimSpaceCommitIn;
     /**
      * Durable F4 ([ref]): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
      * KEEPS the `task_active` claim — the session stays locked (no new run) until an operator resumes it to a
@@ -143,11 +174,18 @@ export declare class SqlRunStore {
     /** The run a submission's `Idempotency-Key` names (`idem_key` = the scoped key, `idemKeyOf(raw, caller, "run")`), if any.
      *  `uq_task_run_idem` makes it at most one row. */
     getRunByIdem(idemKey: string): Promise<RunRecord | undefined>;
-    /** Undo THIS submission's key binding (`idem_key` → NULL) — called only where the submit surface refuses the submission
-     *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, a device-placement reject):
-     *  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 key is freed. */
+    /** Undo THIS submission's binding (`idem_key` + `idem_body_fingerprint` → NULL) — called only where the submit surface refuses
+     *  the submission before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, a device-placement
+     *  reject): 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>;
+    /** The body fingerprint this row's binding of `idem.key` holds — binding `idem.bodyFingerprint` first when it holds none (a key
+     *  bound before the column existed): first arrival binds, everyone after reads. The fingerprint belongs to the KEY that bound
+     *  the row, so a row this key is not bound to (hit by its `task_id` under another key, or made without a key) is never written
+     *  and answers `null` — as does a missing row. One conditional UPDATE (atomic on the row on both dialects: a concurrent binder
+     *  re-evaluates `IS NULL` after the winner commits and matches nothing), then a read of what the binding holds. The comparison
+     *  is the submit surface's (`http/submit-replay.ts`). */
+    bindIdemBodyFingerprint(taskId: string, idem: RunIdemBinding): Promise<string | null>;
     /** Task Trace list (S1): runs newest-first, keyset-paginated on (created_at, task_id). Optional status +
      *  jobId filters (jobId = the work-view group, served by idx_job). Caller passes `limit+1` to detect a next
      *  page. Cursor fields are bound as params (no SQL injection).

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

@@ -8,8 +8,9 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonObjectColumn, readNonNullJsonValueColumn } from "./sql-json-column.js";
 import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, readLegacyHolderDeathCode } from "./store-contracts.js";
 import { notifyRunTerminal, runTerminalLogLevel } from "../observability/run-terminal.js";
-import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
+import { mysqlDriver, pgDriver, dialectJsonEncoder, SQL_DB_NOW_MS, sqlDbNowMs } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
+import { decideSpaceCommitAbandon, decideSpaceCommitClaim, fenceSpaceCommitAtTerminal, spaceCommitStateOf } from "../workspace-space-commit.js";
 function runRowCols(dialect) {
     return (`task_id, session_id, owner, status, ${jsonColumnText(dialect, "result")}, error, error_code, job_id, source, ` +
         "instance_id, cancel_requested, objective_preview, created_at, updated_at");
@@ -74,7 +75,7 @@ export class SqlRunStore {
         }
     }
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
-        const idemKey = meta.idemKey ?? null;
+        const idemKey = meta.idem?.key ?? null;
         const conn = await this.db.connect();
         let stage = "claim";
         try {
@@ -83,9 +84,9 @@ export class SqlRunStore {
             try {
                 await conn.query(this.q("INSERT INTO task_active (session_id, task_id, since) VALUES (?,?,?)", "INSERT INTO task_active (session_id, task_id, since) VALUES ($1,$2,$3)"), [sessionId, taskId, now]);
                 stage = "row";
-                await conn.query(this.q("INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, objective_preview, idem_key, created_at, updated_at) " +
-                    "VALUES (?,?,?,'running',?,?,?,?,?,?,?)", "INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, objective_preview, idem_key, created_at, updated_at) " +
-                    "VALUES ($1,$2,$3,'running',$4,$5,$6,$7,$8,$9,$10)"), [
+                await conn.query(this.q("INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, objective_preview, idem_key, idem_body_fingerprint, created_at, updated_at) " +
+                    "VALUES (?,?,?,'running',?,?,?,?,?,?,?,?)", "INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, objective_preview, idem_key, idem_body_fingerprint, created_at, updated_at) " +
+                    "VALUES ($1,$2,$3,'running',$4,$5,$6,$7,$8,$9,$10,$11)"), [
                     taskId,
                     sessionId,
                     owner,
@@ -98,6 +99,7 @@ export class SqlRunStore {
                             ? null
                             : pgSanitizeText(meta.objectivePreview),
                     idemKey,
+                    meta.idem?.bodyFingerprint ?? null,
                     now,
                     now,
                 ]);
@@ -163,27 +165,33 @@ export class SqlRunStore {
         const errorCode = result === null ? null : (outwardPlane(result.terminal).errorCode ?? null);
         let won = false;
         let observed;
-        await this.tx(async (conn) => {
-            const w = await conn.query(this.q("UPDATE task_run SET status = ?, result = ?, error = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended','needs_review')", "UPDATE task_run SET status = $1, result = $2::jsonb, error = $3, error_code = $4, updated_at = $5 WHERE task_id = $6 AND status IN ('running','suspended','needs_review')"), [
-                status,
-                result == null ? null : this.json(result),
-                this.db.dialect === "tidb" ? error : error == null ? null : pgSanitizeText(error),
-                this.db.dialect === "tidb" ? errorCode : errorCode == null ? null : pgSanitizeText(errorCode),
-                new Date(),
-                taskId,
-            ]);
-            won = w.affected > 0;
-            if (won && runTerminalLogLevel(status, errorCode ?? undefined) !== undefined) {
-                const { rows } = await conn.query(this.q("SELECT owner, session_id, created_at FROM task_run WHERE task_id = ?", "SELECT owner, session_id, created_at FROM task_run WHERE task_id = $1"), [taskId]);
-                const row = rows[0];
-                const createdAt = row ? Date.parse(iso(row.created_at)) : NaN;
-                observed = {
-                    owner: row?.owner ?? null,
-                    sessionId: String(row?.session_id ?? result?.sessionId ?? ""),
-                    createdAt: Number.isFinite(createdAt) ? createdAt : undefined,
-                };
-            }
-            await conn.query(this.q("DELETE FROM task_active WHERE task_id = ?", "DELETE FROM task_active WHERE task_id = $1"), [taskId]);
+        await fenceSpaceCommitAtTerminal(taskId, async (spaceCommit) => {
+            let fenced = false;
+            await this.tx(async (conn) => {
+                const w = await conn.query(this.q("UPDATE task_run SET status = ?, result = ?, error = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended','needs_review')", "UPDATE task_run SET status = $1, result = $2::jsonb, error = $3, error_code = $4, updated_at = $5 WHERE task_id = $6 AND status IN ('running','suspended','needs_review')"), [
+                    status,
+                    result == null ? null : this.json(result),
+                    this.db.dialect === "tidb" ? error : error == null ? null : pgSanitizeText(error),
+                    this.db.dialect === "tidb" ? errorCode : errorCode == null ? null : pgSanitizeText(errorCode),
+                    new Date(),
+                    taskId,
+                ]);
+                won = w.affected > 0;
+                if (won && runTerminalLogLevel(status, errorCode ?? undefined) !== undefined) {
+                    const { rows } = await conn.query(this.q("SELECT owner, session_id, created_at FROM task_run WHERE task_id = ?", "SELECT owner, session_id, created_at FROM task_run WHERE task_id = $1"), [taskId]);
+                    const row = rows[0];
+                    const createdAt = row ? Date.parse(iso(row.created_at)) : NaN;
+                    observed = {
+                        owner: row?.owner ?? null,
+                        sessionId: String(row?.session_id ?? result?.sessionId ?? ""),
+                        createdAt: Number.isFinite(createdAt) ? createdAt : undefined,
+                    };
+                }
+                if (spaceCommit !== undefined)
+                    fenced = await this.claimSpaceCommitIn(conn, spaceCommit.spaceKey, taskId, "pending", spaceCommit.claim);
+                await conn.query(this.q("DELETE FROM task_active WHERE task_id = ?", "DELETE FROM task_active WHERE task_id = $1"), [taskId]);
+            });
+            return fenced;
         });
         if (won) {
             notifyRunTerminal({
@@ -198,6 +206,57 @@ export class SqlRunStore {
             });
         }
     }
+    async readSpaceCommit(spaceKey) {
+        return this.readSpaceCommitIn(this.db, spaceKey, false);
+    }
+    async claimSpaceCommit(spaceKey, taskId, state, claim) {
+        let claimed = false;
+        await this.tx(async (conn) => {
+            claimed = await this.claimSpaceCommitIn(conn, spaceKey, taskId, state, claim);
+        });
+        return claimed;
+    }
+    async endSpaceCommit(spaceKey, taskId) {
+        await this.db.query(this.q("DELETE FROM workspace_space_commit WHERE space_key = ? AND task_id = ?", "DELETE FROM workspace_space_commit WHERE space_key = $1 AND task_id = $2"), [spaceKey, taskId]);
+    }
+    async abandonSpaceCommit(spaceKey, taskId) {
+        let gone = false;
+        await this.tx(async (conn) => {
+            if (!decideSpaceCommitAbandon(await this.readSpaceCommitIn(conn, spaceKey, true), taskId))
+                return;
+            const w = await conn.query(this.q("DELETE FROM workspace_space_commit WHERE space_key = ? AND task_id = ?", "DELETE FROM workspace_space_commit WHERE space_key = $1 AND task_id = $2"), [spaceKey, taskId]);
+            gone = w.affected > 0;
+        });
+        return gone;
+    }
+    async readSpaceCommitIn(exec, spaceKey, forUpdate) {
+        const suffix = forUpdate ? " FOR UPDATE" : "";
+        const { rows } = await exec.query(this.q(`SELECT task_id, state, expires_at_ms FROM workspace_space_commit WHERE space_key = ?${suffix}`, `SELECT task_id, state, expires_at_ms FROM workspace_space_commit WHERE space_key = $1${suffix}`), [spaceKey]);
+        const row = rows[0];
+        if (row === undefined)
+            return undefined;
+        const expiresAt = Number(row["expires_at_ms"]);
+        if (typeof row["task_id"] !== "string" || !Number.isFinite(expiresAt))
+            throw new Error(`workspace_space_commit row for a space is unreadable (task_id ${String(row["task_id"])}, deadline ${String(row["expires_at_ms"])})`);
+        const now = await sqlDbNowMs({ dialect: this.db.dialect, query: (sql, params) => exec.query(sql, params) }, "workspace_space_commit");
+        return { taskId: row["task_id"], state: spaceCommitStateOf(row["state"]), remainingMs: expiresAt - now };
+    }
+    async claimSpaceCommitIn(conn, spaceKey, taskId, state, claim) {
+        if (!claim.requireOwn) {
+            await conn.query(this.q(`INSERT INTO workspace_space_commit (space_key, task_id, state, expires_at_ms) VALUES (?,?,?,${SQL_DB_NOW_MS.tidb} + ?) ON DUPLICATE KEY UPDATE space_key = space_key`, `INSERT INTO workspace_space_commit (space_key, task_id, state, expires_at_ms) VALUES ($1,$2,$3,${SQL_DB_NOW_MS.pg} + $4::bigint) ON CONFLICT (space_key) DO UPDATE SET space_key = EXCLUDED.space_key`), [spaceKey, taskId, state, claim.boundMs]);
+        }
+        const row = await this.readSpaceCommitIn(conn, spaceKey, true);
+        switch (decideSpaceCommitClaim(row, taskId, claim)) {
+            case "refuse":
+                return false;
+            case "insert":
+                throw new Error("workspace_space_commit: a space's row vanished under this transaction's own lock");
+            case "update": {
+                const w = await conn.query(this.q(`UPDATE workspace_space_commit SET task_id = ?, state = ?, expires_at_ms = ${SQL_DB_NOW_MS.tidb} + ? WHERE space_key = ? AND task_id = ?`, `UPDATE workspace_space_commit SET task_id = $1, state = $2, expires_at_ms = ${SQL_DB_NOW_MS.pg} + $3::bigint WHERE space_key = $4 AND task_id = $5`), [taskId, state, claim.boundMs, spaceKey, row.taskId]);
+                return w.affected > 0;
+            }
+        }
+    }
     async setSuspended(taskId, result) {
         const sealed = sealRunRowResult(result);
         await this.db.query(this.q("UPDATE task_run SET status = 'suspended', result = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended')", "UPDATE task_run SET status = 'suspended', result = $1::jsonb, updated_at = $2 WHERE task_id = $3 AND status IN ('running','suspended')"), [sealed == null ? null : this.json(sealed), new Date(), taskId]);
@@ -250,7 +309,13 @@ export class SqlRunStore {
         return rows[0] ? this.rowToRun(rows[0]) : undefined;
     }
     async releaseIdemKey(taskId) {
-        await this.db.query(this.q("UPDATE task_run SET idem_key = NULL WHERE task_id = ?", "UPDATE task_run SET idem_key = NULL WHERE task_id = $1"), [taskId]);
+        await this.db.query(this.q("UPDATE task_run SET idem_key = NULL, idem_body_fingerprint = NULL WHERE task_id = ?", "UPDATE task_run SET idem_key = NULL, idem_body_fingerprint = NULL WHERE task_id = $1"), [taskId]);
+    }
+    async bindIdemBodyFingerprint(taskId, idem) {
+        await this.db.query(this.q("UPDATE task_run SET idem_body_fingerprint = ? WHERE task_id = ? AND idem_key = ? AND idem_body_fingerprint IS NULL", "UPDATE task_run SET idem_body_fingerprint = $1 WHERE task_id = $2 AND idem_key = $3 AND idem_body_fingerprint IS NULL"), [idem.bodyFingerprint, taskId, idem.key]);
+        const { rows } = await this.db.query(this.q("SELECT idem_body_fingerprint FROM task_run WHERE task_id = ? AND idem_key = ?", "SELECT idem_body_fingerprint FROM task_run WHERE task_id = $1 AND idem_key = $2"), [taskId, idem.key]);
+        const held = rows[0]?.idem_body_fingerprint;
+        return typeof held === "string" ? held : null;
     }
     async listRuns(opts) {
         if (opts.cursor && Number.isNaN(Date.parse(opts.cursor.createdAt)))

package/dist/plugins/session-capture-record-store-sql.d.ts

@@ -25,9 +25,8 @@
  *     一条作者要求扣留的内容)。
  *
  * ── 键形法:**编码规范形**(codex R2-[high] 验真后改形;grant 店的「形状拒」在这里是错的)────────
- * 提交面把 sessionId 定为**任意不透明串**(server.ts submit 门:「LENGTH-ONLY — NOT a uuidv7 shape
- * check」,≤64 字符,run-local `--session` / 匿名分享 id 等都合法)——带空白/控制字符的 id 是**在契约内**
- * 的真会话,店若按字节形状拒它,后果=该会话在 SQL 部署上「opt-out 永远落不住(unpersisted)+ 采集态
+ * 7.125.x 及更早的提交面把 sessionId 定为**任意不透明串**(≤64 字符,run-local `--session` / 匿名分享 id 等都合法;7.126.0 起
+ * 只收 canonical uuid)——存量里带空白/控制字符的 id 是**在契约内建出来**的真会话,店若按字节形状拒它,后果=该会话在 SQL 部署上「opt-out 永远落不住(unpersisted)+ 采集态
  * 永远 indeterminate(commits 全抑制)」,是部署契约不兼容,不是输入加固。所以键列**不存生字节**,存
  * `encodeURIComponent(sessionId)` 规范形 —— 与 **core 文件三腿给文件名做的编码逐字同源**(layout.js
  * `captureOptOutPath` 亲读),两载体一个键法:

package/dist/plugins/session-store.d.ts

@@ -7,10 +7,11 @@ import type { StoreBackend } from "./store-backend.js";
  * - `memory` (default): core's in-memory `TtlSessionStore` (lost on restart, 7-day idle TTL).
  * - `tidb`: the durable "Session event-log center" (L1) — append-only events + wake/resume +
  *   cross-instance CAS (F2), on whichever SQL engine `DB_BACKEND` selects (TiDB or PG, via the store backend).
- *   Optionally wrapped in a warm cache (reuse a hot session across turns; requires session affinity) —
- *   set `SESSION_CACHE_TTL_SEC=0` to disable.
+ *   Optionally wrapped in a warm cache (reuse a hot session across turns; a hit is served only while the store's
+ *   head still names the cached leaf, so it is correct under any routing across replicas) — set
+ *   `SESSION_CACHE_TTL_SEC=0` to disable.
  */
-export declare function createSessionStore(config: ServiceConfig, backend?: StoreBackend, metrics?: {
+export declare function createSessionStore(config: Pick<ServiceConfig, "sessionBackend" | "sessionCacheTtlSec">, backend?: Pick<StoreBackend, "session">, metrics?: {
     inc(name: string, labels?: Record<string, string>, n?: number): void;
 }): SessionStore;
 /**

package/dist/plugins/session-store.js

@@ -6,7 +6,7 @@ export function createSessionStore(config, backend, metrics) {
             throw new Error("a DB session backend requires a store backend (DB_BACKEND=mysql|pg + a reachable DB).");
         const store = backend.session();
         return config.sessionCacheTtlSec > 0
-            ? new CachingSessionStore(store, { ttlSec: config.sessionCacheTtlSec, onConflictEvict: metrics ? () => metrics.inc("stale_cache_conflict_total") : undefined })
+            ? new CachingSessionStore(store, { ttlSec: config.sessionCacheTtlSec, onStaleHit: metrics ? () => metrics.inc("session_cache_stale_hit_total") : undefined })
             : store;
     }
     return new TtlSessionStore({ defaultTtlDays: 7 });

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

@@ -183,8 +183,9 @@ export declare const SQL_DB_NOW_MS: {
  *
  * `subject` 只进错误文案(出问题时运维要知道是哪一张表的判决卡住了)。读不出数 ⇒ **响亮抛**:
  * 一次「钟读不出来」在授权面上是运维事件,不是一个可以猜的默认值,更不是掉回 `Date.now()` 的理由。
+ * `db` 只要方言与一个执行口:池,或事务里的那条连接(锁读之后要「拿到锁那一刻」的钟时,在同一条连接上问)。
  */
-export declare function sqlDbNowMs(db: SqlDriver, subject: string): Promise<number>;
+export declare function sqlDbNowMs(db: Pick<SqlDriver, "dialect" | "query">, subject: string): Promise<number>;
 export interface SqlDriver extends SqlExec {
     readonly dialect: SqlDialect;
     /**

package/dist/plugins/store-backend.d.ts

@@ -5,6 +5,7 @@ import { type OutcomeSink } from "./file-outcome-sink.js";
 import { type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
 import { type OneTimeMigrationReport } from "./one-time-migrations.js";
+import type { SessionHeadReader } from "./caching-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { type ApprovalExemptionStore } from "./approval-exemption-store.js";
@@ -144,7 +145,11 @@ export interface StoreBackend {
     /** Protocol-truth kind (clay 2026-07-06 wording): "mysql" = any MySQL-protocol server (MySQL / TiDB /
      *  MariaDB) behind the one mysql2 pool — the startup summary prints durable(mysql) for all of them. */
     readonly kind: "mysql" | "pg" | "local";
-    /** Connect + create schema (also the reachability probe). */
+    /** Connect + create schema (also the reachability probe). On the SQL backends it first checks the database for the
+     *  schema that the one-time migrations of server 7.74.0–7.125.x retired and **refuses** with `RetiredSchemaPresentError`
+     *  (code `config.schema_mismatch`, exported from the package root) before it issues the first CREATE; only then does it create.
+     *  The check lives in this method itself, so the public sequence `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
+     *  needs no step of its own. The LOCAL backend has no SQL pool and nothing to probe. */
     ensureSchema(): Promise<void>;
     close(): Promise<void>;
     run(): RunStore;
@@ -337,8 +342,9 @@ export interface StoreBackend {
     breaker?(onWriteFail?: (streak: number) => void): BreakerStateStore;
     costQuota?(limitMicroUsd: number, windowMs: number, onDegraded?: CounterDegradeHook): CostQuotaStore;
     rateLimiter?(limit: number, onDegraded?: CounterDegradeHook): RateLimiterStore;
-    /** Session store (caller wraps caching). DB-backed on tidb/pg; the in-memory/file `LocalSessionStore` on local. */
-    session(): SessionStore;
+    /** Session store (caller wraps caching). DB-backed on tidb/pg; the in-memory/file `LocalSessionStore` on local. Carries the
+     *  head read the warm cache checks every hit against. */
+    session(): SessionStore & SessionHeadReader;
     /** The raw mysql2 pool — ONLY on the TiDB backend (undefined on PG). For the few TiDB-specific raw-SQL
      *  consumers outside the store abstraction (session audit, degenerate-output instrument); those features are
      *  no-ops on PG until ported. */
@@ -381,8 +387,9 @@ export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "l
  * 而兄弟行都写 `shared(${kind})`。)
  */
 export declare function counterStoreLabel(store: unknown, kind: string | undefined): string;
-/** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
- *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured.
+/** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily); the next
+ *  step is `ensureSchema()` (retired-schema check, then the CREATEs; it is also the reachability probe), then
+ *  `runOneTimeMigrations()`. Returns undefined when no DB is configured.
  *
  *  `onWarn` (additive, optional) is the boot-time warning sink the LOCAL backend needs for core's
  *  permission-rule DISCLOSURE face ([ref] §1): an unreadable / checksum-mismatched / symlinked rule file

package/dist/plugins/store-backend.js

@@ -12,7 +12,7 @@ import { FileRunStore } from "./file-run-store.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
-import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
+import { NO_SQL_MIGRATIONS, assertRetiredSchemaAbsentOnPool, runSqlOneTimeMigrations } from "./one-time-migrations.js";
 import { LocalSessionStore, createLocalSessionRepo } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
@@ -265,7 +265,7 @@ class LocalBackend {
     }
     async ensureSchema() { }
     async runOneTimeMigrations() {
-        return { ...NO_SQL_MIGRATIONS, askOriginRowsMigrated: await this.runStore.migrateRetiredAskOriginRows(), holderDeathCodeRowsBackfilled: this.runStore.migrateLegacyHolderDeathCodes() };
+        return { ...NO_SQL_MIGRATIONS, holderDeathCodeRowsBackfilled: this.runStore.migrateLegacyHolderDeathCodes() };
     }
     async close() {
         await this.sessionStore.dispose();
@@ -337,11 +337,20 @@ export function createStoreBackend(config, onWarn, onError) {
         if (!config.pg)
             return undefined;
         const pool = createPgPool(pgPoolOptions(config.pg, config.dbQueryTimeoutMs), onWarn);
-        return new PgBackend(pool, config);
+        return withRetiredSchemaProbe(new PgBackend(pool, config), { dialect: "pg", pool });
     }
     if (!config.tidb)
         return undefined;
-    return new TiDBBackend(createTidbPool(config), config);
+    const pool = createTidbPool(config);
+    return withRetiredSchemaProbe(new TiDBBackend(pool, config), { dialect: "tidb", pool });
+}
+function withRetiredSchemaProbe(inner, target) {
+    const guarded = Object.create(inner);
+    guarded.ensureSchema = async () => {
+        await assertRetiredSchemaAbsentOnPool(target);
+        await inner.ensureSchema();
+    };
+    return guarded;
 }
 export async function openStoreBackendWithFallback(config, logger) {
     const sqlEngine = config.dbBackend === "mysql" || config.dbBackend === "pg" ? config.dbBackend : undefined;

package/dist/plugins/store-contracts.d.ts

@@ -36,6 +36,9 @@ import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core"
  * 收法:**一个基类,一条重抛**。新 File 店的拒启只要 `extends StoreBootRefusalError` 就自动落在正确的
  * 一侧;忘了继承是**可见**的(它是一个必须显式选择的父类),而忘了往 if 链里加一行是不可见的。
  * (core 的 `AdoptionError` 不在本仓,改不了它的继承链 ⇒ 降级臂保留它那一条 `instanceof`,共两条。)
+ *
+ * 族的含义是「**确定的拒启表态**」,不限 File 店:SQL `ensureSchema()` 里库带着已退役 schema 的拒启(`RetiredSchemaPresentError`)也属此族。三处读它,读法一致 ——
+ * 降级臂不吞(穿过 `mayFallback`)、SQL 开库的等待窗不重试它(`store-open-wait.ts`:再等也等不来另一个答案)、「库打不开」的拒句不改写它(它自己的拒句才是真话)。
  */
 export declare class StoreBootRefusalError extends Error {
 }
@@ -221,17 +224,31 @@ export interface RunRecord {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * 一次提交在 run 账本上的**绑定** —— 幂等键 + 绑定它的那次请求的体指纹。两样同铸(提交面读到 `Idempotency-Key` 的同一处)、
+ * 同落一行(`task_run.idem_key` / `idem_body_fingerprint`)、同清(`releaseIdemKey`),在飞合流也按这一对分区。
+ *
+ *  · `key` —— `idemKeyOf(raw, caller, "run")`(`http/idempotency.ts`;sha256 hex 定宽 64)。
+ *  · `bodyFingerprint` —— 绑定它的那次请求的体指纹(sha256 hex 定宽 64):HTTP 三条提交腿 = `submissionFingerprintOf`
+ *    (同一只规范化函数);A2A `message/send` = 这条消息的内容指纹(它同时是 A2A 键的原始键 ⇒ 同键必同体)。
+ *
+ * 幂等 = 同一调用方、同一键、**同一请求**:命中账本而指纹不同 ⇒ 提交面的唯一回执函数答 409(`http/submit-replay.ts`)。
+ */
+export interface RunIdemBinding {
+    readonly key: string;
+    readonly bodyFingerprint: string;
+}
 /**
  * `RunStore.createRun` 的行元数据(写进 `task_run` 的附加列)。
  *
- * `idemKey` = 这次提交的幂等键(唯一铸法 `idemKeyOf(raw, caller, "run")`,`http/idempotency.ts`;sha256 hex 定宽 64)。
- * 缺席 / `null` = 调用方没带 `Idempotency-Key` ⇒ 列 NULL,不参与去重(UNIQUE 不约束 NULL,两方言同形)。
+ * `idem` = 这次提交的账本绑定({@link RunIdemBinding})。缺席 / `null` = 调用方没带 `Idempotency-Key` ⇒ 两列 NULL,不参与去重
+ * (UNIQUE 不约束 NULL,两方言同形)。
  */
 export interface NewRunMeta {
     jobId?: string | null;
     source?: string | null;
     objectivePreview?: string | null;
-    idemKey?: string | null;
+    idem?: RunIdemBinding | null;
 }
 /**
  * `RunStore.createRun` 的结局 —— 三形,一形一句话:

package/dist/plugins/store-open-wait.js

@@ -1,4 +1,5 @@
 import { STORE_LOCK_POLL_MS } from "./store-lock-wait.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 const REAL_CLOCK = {
     now: () => performance.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -46,6 +47,8 @@ export async function openWithinWait(open, waitMs, onWait, clock = REAL_CLOCK) {
                     throw lastFailure.error;
                 throw new StoreOpenWindowExpired(waitMs);
             case "failed": {
+                if (outcome.error instanceof StoreBootRefusalError)
+                    throw outcome.error;
                 if (lastFailure === undefined)
                     onWait({ waitMs, error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) });
                 lastFailure = { error: outcome.error };

package/dist/plugins/tidb-pool.js

@@ -170,6 +170,11 @@ export const SCHEMA_STATEMENTS = [
      -- runs: uq_task_run_idem makes createRun an atomic win-or-observe across replicas and restarts. NULL = the caller
      -- sent no key (UNIQUE does not constrain NULL; same on both dialects).
      idem_key    VARCHAR(64)  NULL,
+     -- idem_body_fingerprint: the fingerprint of the request that bound idem_key (sha256 hex, fixed width 64; HTTP legs =
+     -- http/idempotency.ts submissionFingerprintOf, A2A = its message fingerprint). Idempotency = same caller, same key, SAME
+     -- request: a hit whose fingerprint differs is answered 409 conflict.idempotency_payload_mismatch. NULL = no key, or a key
+     -- bound before this column existed (the first request to hit it binds its fingerprint).
+     idem_body_fingerprint VARCHAR(64) NULL,
      created_at  DATETIME(3)  NOT NULL,
      updated_at  DATETIME(3)  NOT NULL,
      PRIMARY KEY (task_id),
@@ -234,6 +239,13 @@ export const SCHEMA_STATEMENTS = [
      since      DATETIME(3) NOT NULL,
      PRIMARY KEY (session_id),
      KEY idx_task_active_task (task_id)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS workspace_space_commit (
+     space_key     VARCHAR(64) NOT NULL,
+     task_id       VARCHAR(64) NOT NULL,
+     state         VARCHAR(16) NOT NULL,
+     expires_at_ms BIGINT      NOT NULL,
+     PRIMARY KEY (space_key)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS checkpoint (
      token        VARCHAR(120) NOT NULL,
@@ -278,9 +290,9 @@ export const SCHEMA_STATEMENTS = [
      bound_input_hash VARCHAR(190) NULL,
      -- 🔴 队列化之前的**单座**列 pending_steer 已**退役删列**:那个席位在引擎侧没了(core 7.17.0 #717 d
      -- 对带席的行 PRE-CAS 拒 seat_retired),留着一列没人读、没人写的字节只会让下一个人以为还有两种读法。
-     -- 存量库由启动期的一次性迁移处置(plugins/one-time-migrations.ts 的 M2,窗口见该文件登记表):列上还送得出去的格 ⇒
-     -- **响亮拒启**并给出两条出路(先在 server 7.73.x 上把那些 run 决掉或取消,让座位送达 / 运维手工清列),
-     -- 清空之后 DROP COLUMN。刻意**不**自动把裸单座折进队列:那等于本仓替引擎铸一条它从没写过的队列条目。
+     -- 存量库里仍带着这一列的(没经过带迁移的版本的跳版升级库)起服**响亮拒**(plugins/one-time-migrations.ts 的退役 schema 拒启臂,
+     -- config.schema_mismatch):出路是先在 server 7.125.x 上起服一次,让当年的一次性迁移把它处置掉,再升。刻意**不**自动
+     -- 把裸单座折进队列:那等于本仓替引擎铸一条它从没写过的队列条目。
      -- pending_steer_queue:core 5.14.0(#147)的**有界有序队列**(PendingSteerEntry[] 的 JSON),现在是本表上
      -- durable steering 的唯一载体。Never touches status/resolve (design/80 inv #4)。
      -- 容量:core 的 PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES = 48000 字节是整信封的硬上界(越界 fail-loud