@sema-agent/server 7.139.0 → 7.141.0

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

@@ -8,6 +8,8 @@ import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
+import { capabilitiesFor } from "../execution-lane-caps.js";
+import { ADAPTER_START, BOOTSTRAP_START, createSandboxReadFloor, dockerIdentityFlags, engineStart, floorArgv, } from "./sandbox-read-floor.js";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 const PROVIDER = "local-docker";
@@ -20,7 +22,8 @@ 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, canonicalPathAuthoritative: true, sharesProcessTable: false, hostLocalPaths: false, externalContentTarget: false, io: true, keepsReadFloor: false };
+    capabilities;
+    floor;
     cwd;
     get homeDir() {
         return this.homeSeat.home;
@@ -49,8 +52,10 @@ export class RemoteLocalDockerExecutionEnv {
             controlTimeoutMs: config.controlTimeoutMs ?? DEFAULT_CONTROL_TIMEOUT_MS,
         };
         this.cwd = this.cfg.mountPath;
-        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
+        this.homeSeat = new LaneHomeSeat(PROVIDER, config);
         this.spawnFn = deps.spawn ?? spawn;
+        this.floor = deps.readFloor ?? createSandboxReadFloor({ lane: PROVIDER, knob: config.sandboxReadFloor });
+        this.capabilities = capabilitiesFor({ remoteExec: { provider: PROVIDER }, sandboxReadFloor: config.sandboxReadFloor });
         const id = config.id ?? randomBytes(6).toString("hex");
         const suffix = randomBytes(4).toString("hex");
         this.containerName = `sema-docker-${sanitizeId(id)}-${suffix}`;
@@ -129,6 +134,7 @@ export class RemoteLocalDockerExecutionEnv {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: home };
         }
+        await this.floor.attach(this.floorTransport(), { origin: "created", workspaceRoot: this.cfg.mountPath });
         if (this.destroyed) {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
@@ -142,7 +148,8 @@ export class RemoteLocalDockerExecutionEnv {
     async homeVerdict(signal) {
         if (!this.homeSeat.asks)
             return undefined;
-        const probe = await this.docker(this.execRaw(LANE_HOME_PROBE_COMMAND), { signal, timeoutMs: this.cfg.controlTimeoutMs });
+        const argv = this.startArgv(ADAPTER_START, LANE_HOME_PROBE_COMMAND);
+        const probe = argv.ok ? await this.docker(argv.value, { signal, timeoutMs: this.cfg.controlTimeoutMs }) : argv;
         if (!probe.ok && probe.error.code === "aborted")
             return new RemoteExecutionError("aborted", "connect aborted while reading the environment's home");
         const verdict = this.homeSeat.settle(probe.ok && probe.value.exitCode === 0 ? { ok: true, stdout: probe.value.stdout } : { ok: false, reason: probe.ok ? `exit ${probe.value.exitCode}` : probe.error.message });
@@ -198,6 +205,7 @@ export class RemoteLocalDockerExecutionEnv {
         this.connecting = undefined;
         this.containerId = undefined;
         await inflight?.catch(() => { });
+        this.floor.dispose();
         await this.forceRemove().catch(() => { });
     }
     async cleanup() {
@@ -212,8 +220,10 @@ export class RemoteLocalDockerExecutionEnv {
         const ready = await this.ensureConnectedExec();
         if (!ready.ok)
             return ready;
-        const execArgs = this.execArgv(command, options?.cwd, options?.env);
-        const r = await this.docker(execArgs, {
+        const execArgs = this.startArgv(engineStart(options?.readFloor), command, { cwd: options?.cwd, env: options?.env });
+        if (!execArgs.ok)
+            return execArgs;
+        const r = await this.docker(execArgs.value, {
             signal: options?.abortSignal,
             timeoutMs: options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs,
             onStdout: options?.onStdout,
@@ -227,8 +237,10 @@ export class RemoteLocalDockerExecutionEnv {
         const ready = await this.ensureConnectedExec();
         if (!ready.ok)
             throw new RemoteExecutionError("connect_failed", ready.error.message, ready.error);
-        const execArgs = this.execArgv(command, options?.cwd, options?.env);
-        const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(execArgs), { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
+        const execArgs = this.startArgv(engineStart(undefined), command, { cwd: options?.cwd, env: options?.env });
+        if (!execArgs.ok)
+            throw new RemoteExecutionError("unsupported", execArgs.error.message, execArgs.error);
+        const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(execArgs.value), { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
         const queue = [];
         let finished = false;
         let failure;
@@ -360,7 +372,8 @@ export class RemoteLocalDockerExecutionEnv {
         if (!ready.ok)
             return ready;
         const abs = this.resolve(p);
-        const r = await this.docker(this.execRaw(`cat ${shellQuote(abs)}`), { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, binary: true });
+        const argv = this.startArgv(ADAPTER_START, `cat ${shellQuote(abs)}`);
+        const r = argv.ok ? await this.docker(argv.value, { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, binary: true }) : argv;
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
         if (r.value.exitCode !== 0)
@@ -420,9 +433,12 @@ export class RemoteLocalDockerExecutionEnv {
         if (!this.containerId) {
             const c = await this.connect();
             if (!c.ok)
-                return { ok: false, error: new ExecutionError("shell_unavailable", `local-docker connect failed: ${c.error.message}`) };
+                return { ok: false, error: new ExecutionError("shell_unavailable", `local-docker connect failed: ${c.error.message}`, c.error) };
         }
-        return this.docker(this.execArgv(cmd, undefined, undefined, input !== undefined), { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, ...(input !== undefined ? { input } : {}) });
+        const argv = this.startArgv(ADAPTER_START, cmd, { stdin: input !== undefined });
+        if (!argv.ok)
+            return argv;
+        return this.docker(argv.value, { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, ...(input !== undefined ? { input } : {}) });
     }
     async fileInfo(p, abortSignal) {
         return this.posixFs.statFileInfo(p, abortSignal);
@@ -460,18 +476,68 @@ export class RemoteLocalDockerExecutionEnv {
     withHostFlag(args) {
         return this.cfg.dockerHost ? ["-H", this.cfg.dockerHost, ...args] : args;
     }
-    execArgv(command, cwd, env, stdin = false) {
-        const args = stdin ? ["exec", "-i"] : ["exec"];
-        const dir = cwd != null ? this.resolve(cwd) : this.cwd;
-        args.push("-w", dir);
-        const mergedEnv = { ...(this.cfg.env ?? {}), ...(env ?? {}) };
-        for (const [k, v] of Object.entries(mergedEnv))
-            args.push("-e", `${k}=${v}`);
-        args.push(this.containerName, this.containerShell, "-c", command);
-        return args;
-    }
-    execRaw(command) {
-        return this.execArgv(command);
+    startArgv(start, command, o = {}) {
+        const launch = this.floor.wrap(start);
+        if (!launch.ok)
+            return launch;
+        const args = o.stdin ? ["exec", "-i"] : ["exec"];
+        args.push(...dockerIdentityFlags(launch.value));
+        if (o.containerDefaults !== true) {
+            args.push("-w", o.cwd != null ? this.resolve(o.cwd) : this.cwd);
+            const mergedEnv = { ...(this.cfg.env ?? {}), ...(o.env ?? {}) };
+            for (const [k, v] of Object.entries(mergedEnv))
+                args.push("-e", `${k}=${v}`);
+        }
+        args.push(this.containerName, ...floorArgv(launch.value, [o.shell ?? this.containerShell, "-c", command]));
+        return ok(args);
+    }
+    floorTransport() {
+        const control = { timeoutMs: this.cfg.controlTimeoutMs };
+        return {
+            bootstrap: async (command) => {
+                const argv = this.startArgv(BOOTSTRAP_START, command, { shell: "/bin/sh" });
+                if (!argv.ok)
+                    return { ok: false, error: argv.error.message };
+                const r = await this.docker(argv.value, control);
+                return r.ok ? { ok: true, exitCode: r.value.exitCode, stdout: r.value.stdout, stderr: r.value.stderr } : { ok: false, error: r.error.message };
+            },
+            place: async (dest, bytes) => {
+                const dir = path.posix.dirname(dest);
+                const tmp = `${dest}.${randomBytes(6).toString("hex")}`;
+                const cmd = `umask 022 && mkdir -p ${shellQuote(dir)} && cat > ${shellQuote(tmp)} && chmod 0755 ${shellQuote(tmp)} && mv -f ${shellQuote(tmp)} ${shellQuote(dest)}`;
+                const argv = this.startArgv(BOOTSTRAP_START, cmd, { shell: "/bin/sh", stdin: true });
+                if (!argv.ok)
+                    return { ok: false, error: argv.error.message };
+                const r = await this.docker(argv.value, { ...control, input: bytes });
+                if (!r.ok)
+                    return { ok: false, error: r.error.message };
+                return r.value.exitCode === 0 ? { ok: true } : { ok: false, error: r.value.stderr.trim() || `exit ${r.value.exitCode}` };
+            },
+            openRelay: (identity, command, events) => {
+                const args = ["exec", "-i", ...dockerIdentityFlags({ mode: "control", identity }), this.containerName, "/bin/sh", "-c", command];
+                const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: ["pipe", "pipe", "pipe"], env: this.cliEnv() });
+                let closed = false;
+                const close = (why) => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    events.closed(why);
+                };
+                child.stdout?.setEncoding("utf8");
+                child.stdout?.on("data", (d) => events.data(d));
+                child.stderr?.on("data", () => { });
+                child.stdin?.on("error", () => { });
+                child.on("error", (e) => close(`docker exec failed: ${e.message}`));
+                child.on("close", (code, signal) => close(`relay exited (${code ?? signal ?? "unknown"})`));
+                return {
+                    send: (line) => void child.stdin?.write(line),
+                    close: () => {
+                        child.stdin?.end();
+                        child.kill("SIGKILL");
+                    },
+                };
+            },
+        };
     }
     docker(args, opts) {
         return new Promise((resolve) => {
@@ -570,7 +636,8 @@ export class RemoteLocalDockerExecutionEnv {
     }
     async detectContainerShell() {
         try {
-            const r = await this.docker(["exec", this.containerName, "/bin/sh", "-c", "command -v bash"], { timeoutMs: this.cfg.controlTimeoutMs });
+            const argv = this.startArgv(ADAPTER_START, "command -v bash", { shell: "/bin/sh", containerDefaults: true });
+            const r = argv.ok ? await this.docker(argv.value, { timeoutMs: this.cfg.controlTimeoutMs }) : argv;
             if (r.ok && r.value.exitCode === 0 && r.value.stdout.trim().length > 0)
                 this.containerShell = "bash";
         }
@@ -597,7 +664,7 @@ export class RemoteLocalDockerExecutionEnv {
             return ok(undefined);
         const c = await this.connect();
         if (!c.ok)
-            return { ok: false, error: new FileError("unknown", `local-docker connect failed: ${c.error.message}`, this.resolve(p), c.error) };
+            return { ok: false, error: fileErrorFromExec(c.error, this.resolve(p)) };
         return ok(undefined);
     }
     dockerToRemoteError(e, fallback) {

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

@@ -53,28 +53,8 @@ export interface SshEnvDeps {
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
 }
 export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
-    /**
-     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
-     * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,在真机上解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
-     * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
-     * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
-     * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
-     * 布尔字面量零影响(四键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
-     * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
-     * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
-     */
-    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在 SSH 目标机上;目标恰是本机(或本进程所在容器的宿主)时命令与本进程同表,这一形今天没有配置面可声明 `true`。 */
-    /** 能力块(引擎 [ref],八键必填、各键只经引擎读器读):`hostLocalPaths` = 这条车道答出的路径是不是本进程所在机器上的文件;`externalContentTarget` = 产出是否来自部署信任边界之外;`io` = 文件与 shell 两面真到达目标;`keepsReadFloor` = 是否守住读拒表的字节地板(本车道不守 ⇒ 读拒表非空的 run 被告知,部署要求地板时准备期拒)。 */
-    readonly capabilities: {
-        isolation: false;
-        suspendable: false;
-        canonicalPathAuthoritative: true;
-        sharesProcessTable: false;
-        hostLocalPaths: false;
-        externalContentTarget: false;
-        io: true;
-        keepsReadFloor: false;
-    };
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
+    readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
     /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at mountPath. */
     cwd: string;
     private conn?;
@@ -91,9 +71,9 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
      *  =重连风暴);②共享尝试**不携带任何 caller 信号**(首创者的 pre-abort 不得毒化 joiner;单 caller
      *  取消只退它自己的等待,底层握手余命 ≤ readyTimeout 有界,彻底取消归 destroy 代际闸)。 */
     private inFlight?;
-    /** core `ExecutionEnv.homeDir`([ref]):目标机上登录用户的 home —— 声明胜,否则连上之后实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    /** core `ExecutionEnv.homeDir`([ref]):目标机上登录用户的 home —— 声明在场 ⇒ 声明(开环境那一拍与 `$HOME` 对证过),否则连上之后实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
     get homeDir(): string | undefined;
-    /** 家目录的座(声明胜 · 否则连上之后实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则连上之后实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
     /** 家目录声明 × 实测的判定,按连接记(同一条连接只问一次;重连换了连接再问 —— 登录用户不变时答案相同,代价一次往返;没声明且已量到绝对路径之后不再问)。 */
     private homeChecked?;

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

@@ -7,6 +7,7 @@ import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
+import { capabilitiesFor } from "../execution-lane-caps.js";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 const PROVIDER = "ssh";
@@ -19,7 +20,7 @@ function exitCodeForSignalKill(signal) {
     return 128 + (signalNumber(`SIG${signal}`) ?? 9);
 }
 export class RemoteSshExecutionEnv {
-    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false, hostLocalPaths: false, externalContentTarget: false, io: true, keepsReadFloor: false };
+    capabilities = capabilitiesFor({ remoteExec: { provider: "ssh" } });
     cwd;
     conn;
     sftpPromise;
@@ -52,7 +53,7 @@ export class RemoteSshExecutionEnv {
             hostKey: config.hostKey,
         };
         this.cwd = this.cfg.mountPath;
-        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
+        this.homeSeat = new LaneHomeSeat(PROVIDER, config);
     }
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
@@ -579,7 +580,7 @@ export class RemoteSshExecutionEnv {
     async sftp(abortSignal) {
         const ready = await this.ensureConnected(abortSignal);
         if (!ready.ok)
-            return Promise.reject(ready.error.code === "aborted" ? fileErrorFromExec(ready.error) : new Error(ready.error.message));
+            return Promise.reject(ready.error.code === "aborted" ? fileErrorFromExec(ready.error) : new FileError("target_unavailable", ready.error.message, undefined, ready.error));
         if (!this.conn)
             return Promise.reject(new Error("SSH not connected"));
         if (!this.sftpPromise) {

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

@@ -4,8 +4,8 @@ export class SqlResumeAnchorStore {
     constructor(db) {
         this.db = db;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     async put(sessionId, eventId, entryId, owner) {
         await this.db.query(this.q("INSERT INTO resume_anchor (session_id, event_id, entry_id, owner, created_at) VALUES (?,?,?,?,?) " +

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

@@ -118,7 +118,7 @@ export declare class SqlRetentionLaneStore implements RetentionLaneStore {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
     /** 方言取文(两条语句都写在调用点;A12 判据)。 */
-    protected q(tidb: string, pg: string): string;
+    protected q(mysql: string, pg: string): string;
     /**
      * 抢/续租一次(单行 CAS)。抢到 ⇒ `{held:true, fencingToken}`;别人正持着 ⇒ `{held:false}`,调用方
      * **本 tick 零写静默跳过**。

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

@@ -7,8 +7,8 @@ export class SqlRetentionLaneStore {
     constructor(db) {
         this.db = db;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     async acquire(holder, ttlMs, nowMs) {
         const conn = await this.db.connect();

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

@@ -183,7 +183,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
     readonly retention: RetentionDeclaration;
     constructor(db: SqlDriver, opts: SqlRetentionStoreOptions);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE (A12 判据)。 */
-    protected q(tidb: string, pg: string): string;
+    protected q(mysql: string, pg: string): string;
     /**
      * 域谓词。**四种写法逐条写出来**(方言 × 有主/无主):
      *  · 有主:`col = ?` / `col = $n`;

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

@@ -155,8 +155,8 @@ export class SqlRetentionStore {
         this.db = db;
         this.opts = opts;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     domainWhere(col, domain, pgIndex) {
         return domain === ""
@@ -164,7 +164,7 @@ export class SqlRetentionStore {
             : { sql: this.q(`${col} = ?`, `${col} = $${pgIndex}`), params: [domain] };
     }
     idSet(col, ids, pgIndex) {
-        return this.db.dialect === "tidb"
+        return this.db.dialect === "mysql"
             ? { sql: `${col} IN (${ids.map(() => "?").join(",")})`, params: [...ids] }
             : { sql: `${col} = ANY($${pgIndex}::text[])`, params: [ids] };
     }
@@ -210,7 +210,7 @@ export class SqlRetentionStore {
         if (keys.length === 0)
             return 0;
         const now = Date.now();
-        if (this.db.dialect === "tidb") {
+        if (this.db.dialect === "mysql") {
             const params = [];
             for (const k of keys)
                 params.push(domain, kind, k, now);
@@ -267,7 +267,7 @@ export class SqlRetentionStore {
         }
     }
     horizonArms(pgFirst) {
-        return this.db.dialect === "tidb"
+        return this.db.dialect === "mysql"
             ? `((c.deadline IS NOT NULL AND c.deadline <= ?) OR (c.deadline IS NULL AND c.created_at_ms <= ?))`
             : `((c.deadline IS NOT NULL AND c.deadline <= $${pgFirst}) OR (c.deadline IS NULL AND c.created_at_ms <= $${pgFirst + 1}))`;
     }
@@ -287,7 +287,7 @@ export class SqlRetentionStore {
         return Number(rows[0]?.n ?? 0);
     }
     liveReferenceExists() {
-        const workflow = this.db.dialect === "tidb"
+        const workflow = this.db.dialect === "mysql"
             ? `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND JSON_UNQUOTE(JSON_EXTRACT(wr.run, '$.originatingSessionId')) = sm.session_id)`
             : `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND wr.run::json->>'originatingSessionId' = sm.session_id)`;
         return (`(sm.placement_kind IS NOT NULL` +

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

@@ -2,7 +2,7 @@ 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 ClaimFenced, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { type ClaimFenced, type CreateRunOutcome, type FencedRun, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
@@ -171,7 +171,7 @@ export declare class SqlRunStore {
     /**
      * 认领当写栅栏用(进程内两孪生的契约 = `store-contracts.ts` 的 `InProcessClaimFence`;本孪生是它的事务形):一个事务 ——
      *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
-     *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑;提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
+     *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑(另收锁住那一行的 {@link FencedRun});提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
      * 🔴 **取锁序 = task_run → task_active**,与 `setTerminal` / `reapStale` / `reapSuspended` 同序(它们先改 run 行、再删认领行):两行用两条语句按序锁,
      *    不用连表锁读(那一形的先后由计划器定,与终局 / 收割相反时两只事务各攥一行成环)。`createRun` 先锁根会话行再插认领行(本序从不碰 `session_meta`)、
      *    `deleteBySession` 先锁根会话行、见认领行在就中止,都不与本序成环。锁住之后:收割的改行 / 终局与收割的删认领 / 别人的建行都排在本事务之后,收割器提交后重判 `updated_at` 看到的是刚刷的。
@@ -180,7 +180,7 @@ export declare class SqlRunStore {
      * 🔴 **`write` 不许写 `session_meta`**:本事务持着 `task_active`,而 `createRun` 与改根行的写者都先锁根会话行再碰 `task_*`(全局锁序见 {@link createRun})——
      *    回调去锁根行就是反序,与等着本会话认领的 `createRun` 各攥一行成环。门:`test/submission-root-contract.test.ts` 扫每个调用点的回调体。
      */
-    whileHoldingClaim<T>(sessionId: string, taskId: string, write: (tx: SqlTxConn) => Promise<T>): Promise<ClaimFenced<T>>;
+    whileHoldingClaim<T>(sessionId: string, taskId: string, write: (tx: SqlTxConn, run: FencedRun) => Promise<T>): Promise<ClaimFenced<T>>;
     /** The active run's taskId for a session (the `task_active` claim) — lets resume find the suspended run row. */
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     /** Shared row→record mapper — byte-identical between dialects (both drivers hand back the same column

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

@@ -47,8 +47,8 @@ export class SqlRunStore {
     constructor(db) {
         this.db = db;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     isDupKey(err) {
         return isDupKeyError(this.db.dialect, err);
@@ -103,7 +103,7 @@ export class SqlRunStore {
                     cells.identitySource,
                     cells.identityScope,
                     cells.identityPrincipalInc,
-                    this.db.dialect === "tidb"
+                    this.db.dialect === "mysql"
                         ? meta.objectivePreview ?? null
                         : meta.objectivePreview == null
                             ? null
@@ -181,8 +181,8 @@ export class SqlRunStore {
                 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),
+                    this.db.dialect === "mysql" ? error : error == null ? null : pgSanitizeText(error),
+                    this.db.dialect === "mysql" ? errorCode : errorCode == null ? null : pgSanitizeText(errorCode),
                     new Date(),
                     taskId,
                 ]);
@@ -253,7 +253,7 @@ export class SqlRunStore {
     }
     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]);
+            await conn.query(this.q(`INSERT INTO workspace_space_commit (space_key, task_id, state, expires_at_ms) VALUES (?,?,?,${SQL_DB_NOW_MS.mysql} + ?) 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)) {
@@ -262,7 +262,7 @@ export class SqlRunStore {
             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]);
+                const w = await conn.query(this.q(`UPDATE workspace_space_commit SET task_id = ?, state = ?, expires_at_ms = ${SQL_DB_NOW_MS.mysql} + ? 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;
             }
         }
@@ -282,15 +282,16 @@ export class SqlRunStore {
     async whileHoldingClaim(sessionId, taskId, write) {
         let fenced = { held: false };
         await this.tx(async (conn) => {
-            const run = await conn.query(this.q("SELECT task_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
-            if (run.rows.length === 0)
+            const run = await conn.query(this.q("SELECT task_id, instance_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id, instance_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
+            const row = run.rows[0];
+            if (row === undefined)
                 return;
             const claim = await conn.query(this.q("SELECT task_id FROM task_active WHERE session_id = ? FOR UPDATE", "SELECT task_id FROM task_active WHERE session_id = $1 FOR UPDATE"), [sessionId]);
             const holder = claim.rows[0];
             if (holder === undefined || String(holder.task_id) !== taskId)
                 return;
             await conn.query(this.q("UPDATE task_run SET updated_at = ? WHERE task_id = ?", "UPDATE task_run SET updated_at = $1 WHERE task_id = $2"), [new Date(), taskId]);
-            fenced = { held: true, value: await write(conn) };
+            fenced = { held: true, value: await write(conn, { instanceId: row.instance_id ?? null }) };
         });
         return fenced;
     }
@@ -318,20 +319,20 @@ export class SqlRunStore {
         };
     }
     async getRun(taskId) {
-        const { rows } = await this.db.query(this.q(`SELECT ${runRowCols("tidb")} FROM task_run WHERE task_id = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE task_id = $1`), [taskId]);
+        const { rows } = await this.db.query(this.q(`SELECT ${runRowCols("mysql")} FROM task_run WHERE task_id = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE task_id = $1`), [taskId]);
         return rows[0] ? this.rowToRun(rows[0]) : undefined;
     }
     async observeSubmittedRow(conn, taskId, idemKey) {
         if (idemKey !== null) {
-            const { rows } = await conn.query(this.q(`SELECT ${runRowCols("tidb")} FROM task_run WHERE idem_key = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE idem_key = $1`), [idemKey]);
+            const { rows } = await conn.query(this.q(`SELECT ${runRowCols("mysql")} FROM task_run WHERE idem_key = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE idem_key = $1`), [idemKey]);
             if (rows[0])
                 return this.rowToRun(rows[0]);
         }
-        const { rows } = await conn.query(this.q(`SELECT ${runRowCols("tidb")} FROM task_run WHERE task_id = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE task_id = $1`), [taskId]);
+        const { rows } = await conn.query(this.q(`SELECT ${runRowCols("mysql")} FROM task_run WHERE task_id = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE task_id = $1`), [taskId]);
         return rows[0] ? this.rowToRun(rows[0]) : undefined;
     }
     async getRunByIdem(idemKey) {
-        const { rows } = await this.db.query(this.q(`SELECT ${runRowCols("tidb")} FROM task_run WHERE idem_key = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE idem_key = $1`), [idemKey]);
+        const { rows } = await this.db.query(this.q(`SELECT ${runRowCols("mysql")} FROM task_run WHERE idem_key = ?`, `SELECT ${runRowCols("pg")} FROM task_run WHERE idem_key = $1`), [idemKey]);
         return rows[0] ? this.rowToRun(rows[0]) : undefined;
     }
     async releaseIdemKey(taskId) {
@@ -346,7 +347,7 @@ export class SqlRunStore {
     async listRuns(opts) {
         if (opts.cursor && Number.isNaN(Date.parse(opts.cursor.createdAt)))
             return [];
-        if (this.db.dialect === "tidb") {
+        if (this.db.dialect === "mysql") {
             const where = [];
             const params = [];
             if (opts.status) {
@@ -372,7 +373,7 @@ export class SqlRunStore {
                 where.push("(created_at < ? OR (created_at = ? AND task_id < ?))");
                 params.push(new Date(opts.cursor.createdAt), new Date(opts.cursor.createdAt), opts.cursor.taskId);
             }
-            const sql = `SELECT ${runRowCols("tidb")} FROM task_run` +
+            const sql = `SELECT ${runRowCols("mysql")} FROM task_run` +
                 (where.length ? " WHERE " + where.join(" AND ") : "") +
                 " ORDER BY created_at DESC, task_id DESC LIMIT ?";
             params.push(opts.limit);
@@ -413,7 +414,7 @@ export class SqlRunStore {
         return r === undefined ? undefined : { taskId: String(r.task_id), owner: r.owner ?? null, createdAt: iso(r.created_at) };
     }
     async listSessions(opts) {
-        if (this.db.dialect === "tidb") {
+        if (this.db.dialect === "mysql") {
             const params = [];
             let innerWhere = "";
             if (opts.owner !== undefined) {
@@ -533,7 +534,7 @@ export class SqlRunStore {
         return m == null ? 0 : Number(m);
     }
     async getEvents(taskId, afterSeq) {
-        const { rows } = await this.db.query(this.q(`SELECT seq, type, ${jsonColumnText("tidb", "data")}, ts FROM task_event WHERE task_id = ? AND seq > ? ORDER BY seq ASC`, `SELECT seq, type, ${jsonColumnText("pg", "data")}, ts FROM task_event WHERE task_id = $1 AND seq > $2 ORDER BY seq ASC`), [taskId, afterSeq]);
+        const { rows } = await this.db.query(this.q(`SELECT seq, type, ${jsonColumnText("mysql", "data")}, ts FROM task_event WHERE task_id = ? AND seq > ? ORDER BY seq ASC`, `SELECT seq, type, ${jsonColumnText("pg", "data")}, ts FROM task_event WHERE task_id = $1 AND seq > $2 ORDER BY seq ASC`), [taskId, afterSeq]);
         return rows.map((r) => ({
             seq: Number(r.seq),
             type: String(r.type),