@sema-agent/server 7.148.0 → 7.149.0

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

@@ -19,6 +19,7 @@ import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { SANDBOX_IPV6_DEFAULT, sandboxEgressGaps, sandboxPodSysctls } from "../sandbox-egress-policy.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { ADAPTER_START, BOOTSTRAP_START, buildFloorPodSeat, createSandboxReadFloor, FLOOR_K8S_CONFIGMAP_KEY, engineStart, floorArgv, } from "./sandbox-read-floor.js";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -283,12 +284,13 @@ export class RemoteK8sExecutionEnv {
         this.floor = this.deps.readFloor ?? createSandboxReadFloor({ lane: PROVIDER, knob: config.sandboxReadFloor, ...(config.logger !== undefined ? { logger: config.logger } : {}) });
         this.capabilities = capabilitiesFor({ remoteExec: { provider: PROVIDER, s3Snapshot: this.cfg.s3Snapshot }, sandboxReadFloor: config.sandboxReadFloor });
         const bgMax = Math.max(1, Math.min(K8S_BG_MAX_TIMEOUT_SEC, Math.floor(this.cfg.timeoutMs / 1000)));
+        const backgroundShellOn = DEPLOYMENT_SHAPE_PREDICATES.backgroundShell.holds({ remoteExec: { provider: PROVIDER } });
         this.backgroundCapabilities = {
-            supported: true,
+            supported: backgroundShellOn,
             maxConcurrent: K8S_BG_MAX_CONCURRENT,
             defaultBgTimeoutSec: Math.min(K8S_BG_DEFAULT_TIMEOUT_SEC, bgMax),
             maxBgTimeoutSec: bgMax,
-            supportsDetach: true,
+            supportsDetach: backgroundShellOn,
         };
     }
     get sandboxLeaseRef() {

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

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { type LaneLogger } from "./remote-shell.js";
+import { type CustodyMember } from "./workspace-custody.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
@@ -105,7 +106,7 @@ export interface LocalDockerEnvDeps {
     /** 这只环境手里的读地板模块(缺席 ⇒ `createSandboxReadFloor` 按旋钮选;钉注入守地板的模块)。能力块的 `keepsReadFloor` 读它的状态。 */
     readFloor?: SandboxReadFloor;
 }
-export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv {
+export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<LocalDockerLeftover>, RemoteExecutionEnv {
     /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。读地板旋钮是它的输入,{@link floor} 由同一只判据、同一个旋钮值选出。 */
     readonly capabilities: ExecutionEnvCapabilities;
     /** 读拒表字节地板模块:容器里每一次 `docker exec` 起动都先经它的 `wrap`({@link startArgv},唯一接缝)。 */
@@ -155,8 +156,10 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     get leftover(): LocalDockerLeftover | undefined;
     /** 收场的进度:活着 ⇒ 缺席;{@link destroy} 开始 ⇒ 那一次收场(容器删除证实或放弃之后落定)。工厂读它:活着就交回、收场中就等它落定。 */
     get releasing(): Promise<void> | undefined;
-    /** 收场已落定(工厂从同身份表里清掉它)。 */
+    /** 收场已落定。 */
     get released(): boolean;
+    /** 收场落定、不欠删除 ⇒ 出托管表(欠着的由同一身份的下一只拿走)。容器名由身份派生,一只身份同一时刻只有一只没收场的环境 ⇒ 它收场即删,不存在第二个持有者。 */
+    get settled(): boolean;
     private resolve;
     /** 收据句柄。还没连上(懒环境:续跑腿的引擎在恢复相**之前**先取它比车道)⇒ 未连接形 `{ sandboxId: "(unconnected)", provider, mountPath }`(与 k8s / e2b 车道同形),
      *  不抛 —— 抛了,续跑腿在恢复相就失败。 */
@@ -393,7 +396,7 @@ export declare function localDockerIdentityOfName(workerLabel: string, name: str
  * owns the lifetime and calls `destroy()` (= `docker rm -f`) on task end.
  *
  * 身份 = `ctx.taskId ?? ctx.sessionId`(与引擎交给工具的宿主任务号同一读法:顶层 run = run 号,委派子代 = 它自己的会话号 —— 子代从不带 `taskId`)。
- * 一只身份一只工作区:本工厂对同一身份交回**那一只**还没销毁的环境(停驻腿的环境引擎还拿着;续跑腿拿到的就是它 —— 引擎 park-only 契约要的「重连到同一工作区」,
+ * 一只身份一只工作区(工作区托管表 `workspace-custody.ts`,与 host 车道同一只):本工厂对同一身份交回**那一只**还没销毁的环境(停驻腿的环境引擎还拿着;续跑腿拿到的就是它 —— 引擎 park-only 契约要的「重连到同一工作区」,
  * 在同一进程里就是同一只环境,读地板的中继也只有一只);上一只正在收场 ⇒ 等它的删除落定再铸;没有 ⇒ 铸一只(它连接时在跑的同名容器就附着 —— 上一只进程起的)。
  * 收场落定的从表里清掉。
  * 无主容器:停驻中取消 / 停驻过期(本服务在店层结清,不经引擎的仲裁器,停驻腿的环境没有销毁者)与重起之后才结清的停驻,容器一直在跑 ——

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

@@ -4,6 +4,7 @@ import { hostSubprocessEnv } from "../server-secret-env.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { createHash, randomBytes } from "node:crypto";
 import { shellQuote, armPipeDestroyGrace, appendFileStaged, readyUpload, writeFileStaged } from "./remote-shell.js";
+import { createWorkspaceCustody } from "./workspace-custody.js";
 import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { buildCapturedOutput, createCutError } from "../exec-cut.js";
@@ -84,6 +85,9 @@ export class RemoteLocalDockerExecutionEnv {
     get released() {
         return this.teardownSettled;
     }
+    get settled() {
+        return this.teardownSettled && this.leftover === undefined;
+    }
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
     }
@@ -974,30 +978,11 @@ function errMsg(e) {
 }
 export function localDockerExecutionEnvFactory(config, deps = {}) {
     const { workspaceFillOf, ...base } = config;
-    const live = new Map();
-    const envOf = async (identity, ctx) => {
-        sweep();
-        let leftover;
-        for (let held = live.get(identity); held !== undefined; held = live.get(identity)) {
-            const releasing = held.releasing;
-            if (releasing === undefined)
-                return held;
-            await releasing;
-            if (live.get(identity) === held) {
-                leftover = held.leftover;
-                live.delete(identity);
-            }
-        }
+    const custody = createWorkspaceCustody();
+    const envOf = (identity, ctx) => custody.envOf(identity, (leftover) => {
         const workspaceFill = ctx !== undefined ? workspaceFillOf?.(ctx) : undefined;
-        const env = new RemoteLocalDockerExecutionEnv({ ...base, id: identity, ...(workspaceFill !== undefined ? { workspaceFill } : {}), ...(leftover !== undefined ? { leftover } : {}) }, deps);
-        live.set(identity, env);
-        return env;
-    };
-    const sweep = () => {
-        for (const [identity, env] of live)
-            if (env.released && env.leftover === undefined)
-                live.delete(identity);
-    };
+        return new RemoteLocalDockerExecutionEnv({ ...base, id: identity, ...(workspaceFill !== undefined ? { workspaceFill } : {}), ...(leftover !== undefined ? { leftover } : {}) }, deps);
+    });
     let lister;
     const reapPort = {
         label: base.workerLabel,

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

@@ -170,8 +170,16 @@ export declare class SqlRunStore {
      * 同一只入口、同列同序列化),不是引擎交出的原件:`paused.token` / `failed.nestedPause.token` 两座在落列前摘掉,
      * 所以 poll 这一行的调用方(`GET /v1/runs/:id → result`)拿到的是「停在哪扇门上」而拿不到 resume 能力。
      * `result = null` = 这条腿没观察到 park 结果(断连竞态 / 重开 re-park),列写空 —— 与修前行形同。
+     *
+     * 🔴 **停驻写的 CAS = 「行仍归 `legId` 这条腿 ∧ 仍在跑(或已停在本词上)∧ 没挂取消请求」**(内存 / 文件孪生同一句):
+     *  · 持有腿(`leg_id`,认领铸、交回认领者):一笔丢了回执的停驻写之后卡被决、下一条腿认领了这条行 ⇒ 前一条腿的再提交落不到接手腿的行上;
+     *  · `running`:失联收割已把行落成 `failed` 并删掉 `task_active` 认领时,这一写若把它翻回停驻,会话就没了锁、卡还待决 ⇒ 收割的判决立住;
+     *  · 取消旗:取消动词对在跑行只置旗(`requestCancel`,CAS `status = 'running'`);停驻写认这面旗 ⇒ 同一行上两只写各 CAS 对方的事实,恰一个赢
+     *    (旗先 ⇒ 停驻不落,提交点以取消收场;停驻先 ⇒ 置旗落空,取消路由按停驻结算)。
+     * 交回 CAS 的答:命中行数 > 0 ⇔ 这一写之后行停在这个词上(MySQL 协议缺省带 FOUND_ROWS ⇒ 计的是匹配行,同值重写照算;PG 的 rowCount 同义);
+     * 0 ⇔ 上面三件有一件不成立(或行不在)—— 是哪一件由提交点读行答(`park-row-commit.ts`)。
      */
-    setSuspended(taskId: string, result: PersistedTaskResult | null): Promise<void>;
+    setSuspended(taskId: string, result: PersistedTaskResult | null, legId: string): Promise<boolean>;
     /**
      * [ref] D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
      * pre-action `plan_review`; core assemble-result slot 8.6). Like {@link setSuspended} this is a NON-terminal park
@@ -179,8 +187,8 @@ export declare class SqlRunStore {
      * resume path (`getActiveTaskId` → `markResuming`) can find + claim the row. core treats a review pause "like a
      * suspend, an INTENTIONAL durable pause" ([ref] §2.5) — the service MUST park it the same way, else the run is
      * terminalized + its lock released and the plan_review/dry_run_review resume can never run (it gets
-     * taskId=undefined and drives the model unprotected on an unlocked session). CAS on `running`/`needs_review`
-     * (reaper-revert guard, mirrors setSuspended). The park→resume→claim invariant is pinned on BOTH REAL engines by
+     * taskId=undefined and drives the model unprotected on an unlocked session). CAS = {@link setSuspended}'s three conditions
+     * (holding leg · `running`/`needs_review` · no cancel request). The park→resume→claim invariant is pinned on BOTH REAL engines by
      * `test/run-store-reaper-integration.test.ts` (`inv#1` row ownership across park→resume→handover, `inv#2` two
      * replicas racing one session ⇒ exactly one claim wins, `inv#3`/`inv#3'` stale-claim takeover vs fresh/parked
      * claims), closing the former required-before-GA gap. Keep it that way: the P2 lease-SQL bug and this
@@ -189,14 +197,15 @@ export declare class SqlRunStore {
      * mocked run-store unit tests stayed green. A mock cannot observe a unique-key claim race, a rolled-back loser,
      * or a multi-table reaper DELETE.
      */
-    setNeedsReview(taskId: string, result: PersistedTaskResult | null): Promise<void>;
+    setNeedsReview(taskId: string, result: PersistedTaskResult | null, legId: string): Promise<boolean>;
     /**
      * Durable F4 resume: a suspended run is being actively resumed. Flip it back to `running` (CAS — only if
      * still suspended) and refresh liveness, so the in-flight resume is protected by the running-run heartbeat
      * and is NOT killed by `reapSuspended` (which targets `status='suspended'` past the approval TTL). Without
      * this the row sits at `suspended`/updated_at=suspend-time for the WHOLE resume execution, so a resume that
-     * crosses the TTL is marked `failed` mid-run and its session lock (`task_active`) is released. Returns true
-     * if it claimed the flip (false ⇒ the reaper already expired it, or it isn't suspended).
+     * crosses the TTL is marked `failed` mid-run and its session lock (`task_active`) is released. Returns the
+     * HOLDING LEG this claim minted ({@link RunRecord.legId}; the resumed leg's park writes carry it) when it claimed
+     * the flip, `undefined` otherwise (the reaper already expired it, or it isn't suspended).
      *
      * [ref](codex R1 [medium],红先双库证):认领 = **接管 `instance_id`**。此前该列只在 createRun 铸、此处不动,
      * 于是 A 创建、C 认领 resume 的行永远记 A —— 而 steer/interrupt 的「他副本」臂与 sendHandleMiss 都拿这列当
@@ -204,7 +213,7 @@ export declare class SqlRunStore {
      * 语义自此成文:`instance_id` = **当前持有副本**(createRun 铸、markResuming 认领接管);CAS 输不改列
      * (一个输掉的认领不许覆盖赢家的持有记录——同一条条件 UPDATE 天然保证)。
      */
-    markResuming(taskId: string, instanceId: string): Promise<boolean>;
+    markResuming(taskId: string, instanceId: string): Promise<string | undefined>;
     /**
      * 认领当写栅栏用(进程内两孪生的契约 = `store-contracts.ts` 的 `InProcessClaimFence`;本孪生是它的事务形):一个事务 ——
      *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
@@ -238,6 +247,16 @@ export declare class SqlRunStore {
      *  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>;
+    /** 放一条行上提交幂等键绑定的那一句(`releaseIdemKey` 与 `withdrawMintedRun` 的非在跑臂同读)。 */
+    private releaseIdemKeySql;
+    /**
+     * 撤回本请求铸的这一条 run(认领没放行,行从没交给引擎)—— 回到认领之前「没有这一行」的样子。唯一调用口 = 撤回表 `withdrawClaim` 的 `run` 臂
+     * (经 `http/claimed-run.ts` 的 `withdrawClaimedRun`)。本请求的行 = `task_id` 与建行交回的持有腿 `leg_id` 这一对(与停驻写的 CAS 同一只身份读法):
+     * 行上的持有腿不是 `legId`(没有这一行 / 别的腿持着 / 列之前的行)⇒ 一个字节不动。一个事务、取锁序 `task_run` → `task_active`(与终局 / 收割 / 栅栏同序):行仍在跑(`status = 'running'`:
+     * 没被收割、没终局)⇒ 删它的事件、它的认领、行本身(幂等键与指纹在行上,随行去);已终局 ⇒ 行零删 —— 死亡判决或别的终局写先到,那一份就是这条行的结局 ——
+     * 只放本请求在这一行上绑的提交幂等键;停驻 ⇒ 一个字节不动(撤回只对本请求铸的行,而它从没停驻过;口径与另两孪生同)(撤回之后本请求答的是「原样再发」,同键再发要真跑,不重放那一份结局)。交回删没删。
+     */
+    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 (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

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

@@ -5,7 +5,7 @@ import { pgSanitizeText } from "./pg-safe-json.js";
 import { toIso as iso } from "./sql-row-helpers.js";
 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, RUN_STALL_DEFAULT_WIRING, RUN_STALL_VERDICT_UNLANDED_TAG, isParkedRunStatus, runLivenessOf, settledLegObservationOf } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, RUN_STALL_DEFAULT_WIRING, RUN_STALL_VERDICT_UNLANDED_TAG, isParkedRunStatus, isTerminalRunStatus, mintRunLegId, runLivenessOf, settledLegObservationOf } from "./store-contracts.js";
 import { notifyRunTerminal, runTerminalLogLevel } from "../observability/run-terminal.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder, SQL_DB_NOW_MS, sqlDbNowMs } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
@@ -14,7 +14,7 @@ import { readRunIdentityCells, runIdentityCells } from "../identity-source.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, ` +
-        "identity_source, identity_scope, identity_principal_inc, instance_id, cancel_requested, objective_preview, created_at, updated_at");
+        "identity_source, identity_scope, identity_principal_inc, instance_id, leg_id, cancel_requested, objective_preview, created_at, updated_at");
 }
 const readPersistedTaskResultBody = createObjectColumnReader();
 function decodeResultColumn(v, taskId) {
@@ -101,18 +101,19 @@ export class SqlRunStore {
         }
     }
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
+        const legId = mintRunLegId();
         const conn = await this.db.connect();
         try {
-            const first = await this.createRunOn(conn, taskId, sessionId, owner, instanceId, meta);
+            const first = await this.createRunOn(conn, taskId, sessionId, owner, instanceId, legId, meta);
             if (first.activeTaskId === undefined || !(await this.settleDueHolderOn(conn, first.activeTaskId)))
                 return first;
-            return await this.createRunOn(conn, taskId, sessionId, owner, instanceId, meta);
+            return await this.createRunOn(conn, taskId, sessionId, owner, instanceId, legId, meta);
         }
         finally {
             conn.release();
         }
     }
-    async createRunOn(conn, taskId, sessionId, owner, instanceId, meta) {
+    async createRunOn(conn, taskId, sessionId, owner, instanceId, legId, meta) {
         const idemKey = meta.idem?.key ?? null;
         let stage = "claim";
         try {
@@ -127,13 +128,14 @@ export class SqlRunStore {
                 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";
                 const cells = runIdentityCells(meta.identity ?? null);
-                await conn.query(this.q("INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, identity_source, identity_scope, identity_principal_inc, 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, identity_source, identity_scope, identity_principal_inc, objective_preview, idem_key, idem_body_fingerprint, created_at, updated_at) " +
-                    "VALUES ($1,$2,$3,'running',$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14)"), [
+                await conn.query(this.q("INSERT INTO task_run (task_id, session_id, owner, status, instance_id, leg_id, job_id, source, identity_source, identity_scope, identity_principal_inc, 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, leg_id, job_id, source, identity_source, identity_scope, identity_principal_inc, objective_preview, idem_key, idem_body_fingerprint, created_at, updated_at) " +
+                    "VALUES ($1,$2,$3,'running',$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15)"), [
                     taskId,
                     sessionId,
                     owner,
                     instanceId,
+                    legId,
                     meta.jobId ?? null,
                     meta.source ?? null,
                     cells.identitySource,
@@ -150,7 +152,7 @@ export class SqlRunStore {
                     now,
                 ]);
                 await conn.commit();
-                return { ok: true };
+                return { ok: true, legId };
             }
             catch (err) {
                 if (!this.isDupKey(err))
@@ -363,17 +365,20 @@ export class SqlRunStore {
             }
         }
     }
-    async setSuspended(taskId, result) {
+    async setSuspended(taskId, result, legId) {
         const sealed = sealRunRowResult(result);
-        await this.db.query(this.q("UPDATE task_run SET status = 'suspended', result = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended')", "UPDATE task_run SET status = 'suspended', result = $1::jsonb, error_code = $2, updated_at = $3 WHERE task_id = $4 AND status IN ('running','suspended')"), [sealed == null ? null : this.json(sealed), runRowErrorCodeOf(sealed), new Date(), taskId]);
+        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'suspended', result = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND leg_id = ? AND status IN ('running','suspended') AND cancel_requested = 0", "UPDATE task_run SET status = 'suspended', result = $1::jsonb, error_code = $2, updated_at = $3 WHERE task_id = $4 AND leg_id = $5 AND status IN ('running','suspended') AND cancel_requested = 0"), [sealed == null ? null : this.json(sealed), runRowErrorCodeOf(sealed), new Date(), taskId, legId]);
+        return affected > 0;
     }
-    async setNeedsReview(taskId, result) {
+    async setNeedsReview(taskId, result, legId) {
         const sealed = sealRunRowResult(result);
-        await this.db.query(this.q("UPDATE task_run SET status = 'needs_review', result = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','needs_review')", "UPDATE task_run SET status = 'needs_review', result = $1::jsonb, error_code = $2, updated_at = $3 WHERE task_id = $4 AND status IN ('running','needs_review')"), [sealed == null ? null : this.json(sealed), runRowErrorCodeOf(sealed), new Date(), taskId]);
+        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'needs_review', result = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND leg_id = ? AND status IN ('running','needs_review') AND cancel_requested = 0", "UPDATE task_run SET status = 'needs_review', result = $1::jsonb, error_code = $2, updated_at = $3 WHERE task_id = $4 AND leg_id = $5 AND status IN ('running','needs_review') AND cancel_requested = 0"), [sealed == null ? null : this.json(sealed), runRowErrorCodeOf(sealed), new Date(), taskId, legId]);
+        return affected > 0;
     }
     async markResuming(taskId, instanceId) {
-        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, error_code = NULL, instance_id = ?, updated_at = ? WHERE task_id = ? AND status IN ('suspended','needs_review')", "UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, error_code = NULL, instance_id = $1, updated_at = $2 WHERE task_id = $3 AND status IN ('suspended','needs_review')"), [instanceId, new Date(), taskId]);
-        return affected === 1;
+        const legId = mintRunLegId();
+        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, error_code = NULL, instance_id = ?, leg_id = ?, updated_at = ? WHERE task_id = ? AND status IN ('suspended','needs_review')", "UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, error_code = NULL, instance_id = $1, leg_id = $2, updated_at = $3 WHERE task_id = $4 AND status IN ('suspended','needs_review')"), [instanceId, legId, new Date(), taskId]);
+        return affected === 1 ? legId : undefined;
     }
     async whileHoldingClaim(sessionId, taskId, write) {
         let fenced = { held: false };
@@ -409,6 +414,7 @@ export class SqlRunStore {
             source: r.source ?? null,
             identity: readRunIdentityCells(r.identity_source, r.identity_scope, r.identity_principal_inc),
             instanceId: r.instance_id ?? null,
+            legId: r.leg_id ?? null,
             cancelRequested: Boolean(r.cancel_requested),
             objectivePreview: r.objective_preview ?? null,
             createdAt: iso(r.created_at),
@@ -433,7 +439,29 @@ 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, idem_body_fingerprint = NULL WHERE task_id = ?", "UPDATE task_run SET idem_key = NULL, idem_body_fingerprint = NULL WHERE task_id = $1"), [taskId]);
+        await this.db.query(this.releaseIdemKeySql(), [taskId]);
+    }
+    releaseIdemKeySql() {
+        return 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");
+    }
+    async withdrawMintedRun(taskId, legId) {
+        let withdrawn = false;
+        await this.tx(async (conn) => {
+            const { rows } = await conn.query(this.q("SELECT status FROM task_run WHERE task_id = ? AND leg_id = ? FOR UPDATE", "SELECT status FROM task_run WHERE task_id = $1 AND leg_id = $2 FOR UPDATE"), [taskId, legId]);
+            if (rows.length === 0)
+                return;
+            const status = rows[0].status;
+            if (status !== "running") {
+                if (isTerminalRunStatus(status))
+                    await conn.query(this.releaseIdemKeySql(), [taskId]);
+                return;
+            }
+            await conn.query(this.q("DELETE FROM task_event WHERE task_id = ?", "DELETE FROM task_event WHERE task_id = $1"), [taskId]);
+            await conn.query(this.q("DELETE FROM task_active WHERE task_id = ?", "DELETE FROM task_active WHERE task_id = $1"), [taskId]);
+            await conn.query(this.q("DELETE FROM task_run WHERE task_id = ?", "DELETE FROM task_run WHERE task_id = $1"), [taskId]);
+            withdrawn = true;
+        });
+        return withdrawn;
     }
     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]);

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

@@ -37,7 +37,9 @@ export declare class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalEr
     readonly hits: readonly ScenarioPrefixHit[];
     readonly live?: ScenarioPrefixLiveRuns | undefined;
     readonly code = "config.scenario_prefix_switch_refused";
-    constructor(reason: ScenarioPrefixRefusalReason, hits: readonly ScenarioPrefixHit[], live?: ScenarioPrefixLiveRuns | undefined);
+    constructor(reason: ScenarioPrefixRefusalReason, hits: readonly ScenarioPrefixHit[], live?: ScenarioPrefixLiveRuns | undefined, 
+    /** 库此刻还差的列(SQL 腿经 `describeUpgradeDriftTail` 读到的;列齐 / local 腿 ⇒ 空串):一次起服读全。 */
+    tail?: string);
     private static sentence;
 }
 /** local 腿的一处来源:店名 + 它的计数口(以保留前缀开头的属主行数)。 */

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

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { SCENARIO_SUBJECT_PREFIX } from "../owner-brands.js";
 import { atomicWriteFileSync } from "./owner-only-file-mode.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
+import { stopThenStartAction } from "./stop-then-start-sentence.js";
 export const SCENARIO_PREFIX_SWITCH_REFUSED_CODE = "config.scenario_prefix_switch_refused";
 export const SCENARIO_PREFIX_MARKER_ID = "M42";
 export const LOCAL_MARKER_FILE = "one-time-migration-M42.json";
@@ -12,8 +13,8 @@ export class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
     hits;
     live;
     code = SCENARIO_PREFIX_SWITCH_REFUSED_CODE;
-    constructor(reason, hits, live) {
-        super(ScenarioPrefixSwitchRefusedError.sentence(reason, hits, live));
+    constructor(reason, hits, live, tail = "") {
+        super(ScenarioPrefixSwitchRefusedError.sentence(reason, hits, live) + tail);
         this.reason = reason;
         this.hits = hits;
         this.live = live;
@@ -30,7 +31,7 @@ export class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
             case "live_runs":
                 return (`${SCENARIO_PREFIX_SWITCH_REFUSED_CODE}: no stored identity starts with the reserved prefix "${SCENARIO_SUBJECT_PREFIX}", but ${live?.liveRuns ?? 0} run(s) heartbeated on this database ` +
                     `within the last ${live?.windowSec ?? 0}s — 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. Stop every replica of the earlier version, then start this version after ${live?.after ?? "the heartbeat window"} (this check is stop-then-start, not rolling).`);
+                    `Nothing was 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

@@ -36,6 +36,12 @@
  *   · `key`   —— 主键成员:给存量行加主键列等于改它们的身份,**不出语句**,只一句话(出路走「部署匹配的构建」)。
  * 反方向(构建可空、库里非空)不判:现网库里可能有,判了会让数量不明的库起不来。
  *
+ * ── 位置:建表之后、一次性迁移之前;比的是「待跑迁移跑完之后」的形 ─────────────────────────────────────
+ * 起服的每一只拒启判都先于第一笔一次性迁移写(拒启的那一次起服对存量一笔没改写;迁移读数只出现在起得来的那一次)。本探针因此在迁移段**之前**跑,
+ * 而库上可能还有本构建带着的迁移待跑(它们删 / 改名 / 补 / 重建的列):登记表每一行用 `shapeChanges` 声明它对表形做的事,{@link projectPendingShape}
+ * 是唯一一只投影 —— 先把库形投影成迁移之后的样子再对账。迁移要动的列不算不符;别的缺列 / 多列 / 可空列照拒。发车门 1.10 第三档读同一只投影。
+ * 迁移段之后起服再调一次、待跑集为空(收口):声明多报了迁移没做的改动 ⇒ 这一次拒(构建缺陷;不收口则投影在窗内每次起服都把那一处抹平)。
+ *
  * ── 失败方向:读不到就拒,不跳过 ─────────────────────────────────────────────────────────────
  * information_schema 查询抛错、或整库一行都读不出来 ⇒ **拒启**。探针的语义是「我证明了库等于代码」,
  * 证不出来时放行等于把一条保护性断言静默降级成祝福([ref]:保护型缺席必须 fail-closed)。
@@ -54,6 +60,8 @@
  * (探针先于它的第一条 CREATE)—— 一次会拒的起服不许先在库里建出几十张本版新表(`task_run` 还带着新列),否则拒句里「没动过库」就是假话,
  * 按拒句指路去 7.125.x 起服的人会撞上「库比 7.125.x 新」的第二道拒。嵌入方走公开序列 `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
  * 即得到这一问,零动作。
+ * 同一处(建表之前、只读)还有本族的另一只跳版臂:`Skill` 豁免截点(`approval-exemption-skill-cutoff.ts`)—— 证据不是 schema 而是行(截点之前的 `Skill` 豁免行),
+ * 截点、判与拒(`LegacySkillExemptionsPresentError`,同码)住在那一只模块;调用点同在 `withRetiredSchemaProbe`。
  * 残余(如实):运维在第一次起带迁移的版本之前就把两件退役 schema 都手工删掉的库,残留的旧拼法由门记录的读腿接住 —— 7.129.0 起(core 7.51.0 [ref])
  * 那只读腿按 core 的档案读法读,`unresolvable` 是 core 退役词注册表里的词 ⇒ 记录原词原样读回、不改写(`trace/project.ts` `screenedGate`);local 文件车道
  * 没有表与列,没有这一问 —— 引擎 File 店里已决 checkpoint 的记录按契约物理不可变,本仓没有合法缝改写它们,同由那条读腿接住。
@@ -113,6 +121,54 @@ export interface TableMismatch {
 }
 /** 对账(纯函数:期望 × 实况 → 不符表清单)。实况 = {@link readLiveColumns} 的读数(列在不在 + 可不可空,一次读)。 */
 export declare function diffSchema(expected: Map<string, ParsedTable>, live: LiveColumns): TableMismatch[];
+/**
+ * 一条一次性迁移起服时对**存量表形**做的事(登记表 `plugins/one-time-migrations.ts` 一行的 `shapeChanges` 里的一项;纯数据,列名取自迁移语句读的那一份常量)。闭集四种,
+ * 条件都只读**迁移之前**的库形(与迁移步自己的判据同一个事实:列在不在):
+ *  · `drop`    —— 列在 ⇒ 删;
+ *  · `rename`  —— `to` 不在 ∧ `from` 里**恰有一列**在 ⇒ 那一列改名成 `to`(改名之后的可空性按方言:MySQL 协议的改名句是 `CHANGE COLUMN <旧名> <本构建的列定义>`,
+ *               列按本构建的声明重定义;PG 的 `RENAME COLUMN` 不动列定义,可空性随旧列走);别的形(两列都在 / 新名已在)迁移自己会撞库,不投影 ⇒ 对账照拒;
+ *  · `add`     —— 列不在 ⇒ 按本构建的声明加上;`whilePresent` 在场 ⇒ 只在那张表上还有其中任一列时才加(迁移步的判据就是那几列在不在);
+ *  · `rebuild` —— `whilePresent` 列在 ∧ 本构建声明的列里除 `supplies`(迁移自己给值的那几列)以外每一列都在(迁移的搬运句从旧表读的就是这几列)⇒ 整张表按本构建的建表语句重建
+ *               (列集与可空性 = 本构建的声明;旧表上别的列随重建丢掉 —— 迁移真落下的形就是这样);缺搬运要读的列 ⇒ 不投影(迁移会在搬运那一步失败)⇒ 对账照拒,拒在迁移写之前。
+ */
+export type PendingShapeChange = {
+    readonly kind: "drop";
+    readonly table: string;
+    readonly columns: readonly string[];
+} | {
+    readonly kind: "rename";
+    readonly table: string;
+    readonly from: readonly string[];
+    readonly to: string;
+} | {
+    readonly kind: "add";
+    readonly table: string;
+    readonly column: string;
+    readonly whilePresent?: {
+        readonly table: string;
+        readonly anyOf: readonly string[];
+    };
+} | {
+    readonly kind: "rebuild";
+    readonly table: string;
+    readonly whilePresent: string;
+    readonly supplies: readonly string[];
+};
+/** 一条迁移的表形声明(登记表的行结构上满足它:`id` + 可选的 `shapeChanges`)。 */
+export interface PendingShapeSource {
+    readonly id: string;
+    readonly shapeChanges?: readonly PendingShapeChange[];
+}
+/** 投影的结果:迁移跑完之后的库形 + 真改了表形的那几条迁移(按登记序)。 */
+export interface PendingShapeProjection {
+    readonly projected: LiveColumns;
+    readonly appliedBy: readonly string[];
+}
+/**
+ * 待跑的一次性迁移把库形改成什么(纯函数;**唯一**一只投影 —— 起服列册对账与发车门 1.10 第三档都读它)。条件读 `live`(迁移之前的形),改动落在一份拷贝上 ⇒ 与声明的先后无关。
+ * 一个(表 × 列)只许一条声明认领(`rebuild` 认领整张表):两条声明碰同一处 ⇒ 响亮抛(一件事一个属主,不挑一个)。
+ */
+export declare function projectPendingShape(expected: Map<string, ParsedTable>, live: LiveColumns, sources: readonly PendingShapeSource[], dialect: SqlDialect): PendingShapeProjection;
 /** 缺一列时的配方(按 {@link columnFill} 三类);拒启句里这一列的那几行就是它的返回值,真库钉据此取期望而不手抄句子。 */
 export declare function missingColumnLines(dialect: SqlDialect, table: string, c: ParsedColumn): string[];
 /**
@@ -126,14 +182,42 @@ export declare function missingColumnLines(dialect: SqlDialect, table: string, c
  * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据 —— 这里不写,拒启句的钉也守着(`test/schema-consistency.test.ts` ⑤)。
  */
 export declare function describeMismatchedTables(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string[];
-/** 拒启文案(表头 + 逐表段与闭集三条出路 {@link describeMismatchedTables})。 */
-export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string;
 /**
- * 启动期对账:**建表之后**跑,不符即抛(= 拒启)。两方言 + InnoDB 同腿(MySQL 协议共用 `mysql` 臂)。
+ * **升级清单**(多行;`[]` = 没有语句要部署者执行,清单不出):一次起服的拒句里「这只库此刻对本构建还差什么、先后顺序」一段。
+ * 缺列拒、判活拒、一次性迁移的拒本来各报各的一段 —— 运维补一句再起、才撞上下一族(列册对账在迁移段之后时,第四次起服才拒出其余全部 ALTER)。
+ * 清单把本构建对存量库的全部动作写成一张:① 逐表的 ALTER(其下 {@link describeMismatchedTables} 的逐表段,全库一次列全)② 本构建带的停-迁-起迁移(登记表 `stopThenStart` 一格,
+ * 行在 ⇒ 码在;一次性迁移文件静态依赖本文件,所以惰性载入)③ 起服。第 ② 步对「已经走过这些迁移」的库是空操作(迁移在自己的守卫处判),清单不替守卫判「这一只库欠不欠」。
+ */
+export declare function describeUpgradeChecklist(mismatches: readonly TableMismatch[]): Promise<string[]>;
+/** 拒启文案(表头 + {@link describeUpgradeChecklist}〔有语句要执行时〕+ 逐表段与闭集三条出路 {@link describeMismatchedTables})。`checklist` 由调用方 `await describeUpgradeChecklist(…)` 交来(本函数保持同步纯函数)。 */
+export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches: readonly TableMismatch[], checklist?: readonly string[]): string;
+/**
+ * 迁移段**之前 / 之中**读列册的拒句(单表探针的拒因、判活守卫的句尾)要的那一份:库经本构建**全部待跑迁移**之后({@link projectPendingShape},登记表各行的 `shapeChanges`,
+ * 与起服对账同一只投影)对本构建的不符里,只留**要部署者执行语句**的方向(缺列、声明非空而库里允许 NULL):
+ *  · 待跑迁移要删 / 改名走的旧列、自己要建的列,投影已经按迁移自己的条件换成迁移之后的形 —— 不读成「库比构建新」,也不列成部署者的 `ALTER`
+ *    (部署者照句子先加了,迁移的改名 / 加列反而撞上已存在的目标列、起服卡死);条件不成立的(如改名的源列不在)照列,迁移不会替它建;
+ *  · 投影之后还剩的幽灵列〔库里有、代码没有〕去掉 —— 没有语句可给,名字又来自库里、不受信,不进「给运维的指令」。
+ * 迁移段之中读:已跑过的迁移的条件读到的是迁移之后的形、不再投影,所以读数与迁移段之前同一份。登记表惰性载入(一次性迁移文件静态依赖本文件)。
+ */
+export declare function statementBearing(expected: Map<string, ParsedTable>, live: LiveColumns, dialect: SqlDialect): Promise<TableMismatch[]>;
+/** 清单 + 逐表段 + 闭集三条出路(多行):单表探针的拒因与判活守卫的句尾共用的正文(列册对账的拒句是 {@link describeSchemaMismatch},同一份清单与逐表段)。 */
+export declare function describeUpgradeBody(dialect: SqlDialect, mismatches: readonly TableMismatch[]): Promise<string[]>;
+/** 句尾读列册的期限(ms):这一段是拒句上的附加,不许把已经成立的拒拖住 —— 读不回来就如实说没读到,拒照出。 */
+export declare const DRIFT_TAIL_DEADLINE_MS = 10000;
+/**
+ * 别的拒启(一次性迁移的判活守卫)句尾上的「这只库此刻还差的列」一段:读整库列册对账同一份读数({@link statementBearing} 之后),没有语句要执行 ⇒ `""`;否则一个空行 + 一行引子 +
+ * {@link describeUpgradeBody}。读不出列册 / 超过 {@link DRIFT_TAIL_DEADLINE_MS} ⇒ 响亮地说没读到及原因(不静默吞:吞了运维以为列是齐的;也不无限等:拒已经成立,
+ * 这一段只是附加 —— 读卡住的那条语句留在连接上,和迁移段里任何一条卡住的语句同一个去处)。`deadlineMs` 是测试缝。
+ */
+export declare function describeUpgradeDriftTail(read: SchemaProbeRead, dialect: SqlDialect, deadlineMs?: number): Promise<string>;
+/**
+ * 启动期对账:**建表之后、一次性迁移之前**跑,不符即抛(= 拒启;拒的时候迁移一笔没写)。两方言 + InnoDB 同腿(MySQL 协议共用 `mysql` 臂)。
+ * 比的是库**经待跑的一次性迁移之后**的形({@link projectPendingShape};`pending` = 本构建带着的迁移的表形声明,起服读登记表交来):迁移要删 / 改名 / 补的列不算不符,
+ * 别的缺列 / 多列 / 可空列照拒 —— 漏了升级前 DDL 的库在迁移改写任何一行之前就被拒。
  *
- * 失败方向见文件头注:读抛 / 整库零行 ⇒ 拒。
+ * 失败方向见文件头注:读抛 / 整库零行 ⇒ 拒。三条拒(读不出 / 整库零行 / 列集不符)与单表探针的拒启同一只出口 {@link SchemaMismatchRefusedError}(`code` = `config.schema_mismatch`)。
  */
-export declare function assertSchemaMatchesCode(read: SchemaProbeRead, dialect: SqlDialect): Promise<void>;
+export declare function assertSchemaMatchesCode(read: SchemaProbeRead, dialect: SqlDialect, pending: readonly PendingShapeSource[]): Promise<void>;
 /**
  * 跳版升级的库的拒启:退役 schema(快照索引表 / 单座列)任一仍在。**具名类型**:锚类型不锚文案(日志消费端与测试按 `code` / 类型分派);
  * 码取列册对账同一个 `config.schema_mismatch`,运维面一个拒启码一个读法。拒句点名在场的坐标、说明第三条(旧拼法改写)同样没跑过、给出路。