@sema-agent/server 7.141.0 → 7.143.0

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

@@ -8,7 +8,7 @@ import { appendFileStaged, buildCwdEnvCommand, createCwdGuardedCall, shellQuote,
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
 import { WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { SNAPSHOT_BUCKET_MISSING, isNoSuchBucketAnswer } from "./s3-answer.js";
-import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotKeyPrefixProblem, snapshotNameOwnedBy } from "../workspace-space.js";
+import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotIdHolds, snapshotKeyPrefixProblem, snapshotNameOwnedBy } from "../workspace-space.js";
 import { spaceCommitAlive } from "../workspace-space-commit.js";
 import { incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
 import { WORKSPACE_CACHE_SPACE_LABEL, workspaceCacheClaimOf, workspaceCacheEnv } from "../workspace-cache.js";
@@ -48,6 +48,9 @@ export { applyPodSpecPatch } from "./k8s-exec-protocol.js";
 import { sandboxRunEndHoldMs } from "./k8s-pod-reaper.js";
 import { BROKER_COMMAND, BROKER_CONTAINER_NAME, BROKER_LEASE_DIR, BROKER_LEASE_KEY, BROKER_PROBE_ARG, BROKER_VOLUME_NAME } from "../broker/constants.js";
 import { buildSandboxLeaseFile, placeholderLeaseEntries, sandboxGitRouteEnv } from "../sandbox-git-lease.js";
+function minted(c) {
+    return c.ok ? { ...c, origin: "minted" } : c;
+}
 const CACHE_VOLUME = ADAPTER_VOLUME_NAMES.cache;
 function occupantKeyOf(occupant) {
     if (occupant === undefined)
@@ -213,6 +216,7 @@ export class RemoteK8sExecutionEnv {
     inFlight = new Set();
     idleWaiters = [];
     connectInFlight;
+    resumeInFlight;
     connectRefusal;
     get homeDir() {
         return this.homeSeat.home;
@@ -231,6 +235,7 @@ export class RemoteK8sExecutionEnv {
     cacheUnavailableSaid = false;
     logger;
     onWorkspaceSnapshot;
+    workspaceFill;
     cacheMisses;
     constructor(config, deps) {
         this.cfg = {
@@ -270,6 +275,7 @@ export class RemoteK8sExecutionEnv {
         this.cacheLane = cacheLaneOf(config.cache, config.spaceOccupant);
         this.logger = config.logger;
         this.onWorkspaceSnapshot = config.onWorkspaceSnapshot;
+        this.workspaceFill = config.workspaceFill;
         this.cacheMisses = config.cacheMisses;
         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 });
@@ -374,10 +380,14 @@ export class RemoteK8sExecutionEnv {
         });
     }
     connect(config) {
-        this.connectInFlight ??= this.establish(config).finally(() => {
-            this.connectInFlight = undefined;
+        if (this.connectInFlight)
+            return this.connectInFlight;
+        const walk = this.establish(config).finally(() => {
+            if (this.connectInFlight === walk)
+                this.connectInFlight = undefined;
         });
-        return this.connectInFlight;
+        this.connectInFlight = walk;
+        return walk;
     }
     async establish(config) {
         if (this.connectRefusal)
@@ -386,10 +396,10 @@ export class RemoteK8sExecutionEnv {
         const lane = this.spaceLane;
         switch (lane.state) {
             case "off":
-                return this.provision(signal);
+                return this.settle(minted(await this.provision(signal)));
             case "unavailable":
                 this.sayUnavailable(lane.reason);
-                return this.provision(signal);
+                return this.settle(minted(await this.provision(signal)));
             case "unreadable":
                 return this.provision(signal);
             case "open": {
@@ -399,7 +409,7 @@ export class RemoteK8sExecutionEnv {
                 const latest = await this.readLatest(lane.space, signal);
                 if (!latest.ok)
                     return latest;
-                const c = latest.value === undefined ? await this.provision(signal) : await this.restoreSnapshot({ lane: "space", space: lane.space }, latest.value, signal);
+                const c = await this.settle(latest.value === undefined ? minted(await this.provision(signal)) : await this.restoreSnapshot({ lane: "space", space: lane.space }, latest.value, signal));
                 if (c.ok)
                     this.armSpace();
                 return c;
@@ -410,6 +420,43 @@ export class RemoteK8sExecutionEnv {
             }
         }
     }
+    async settle(c) {
+        if (!c.ok)
+            return c;
+        const fill = this.workspaceFill;
+        if (fill !== undefined) {
+            const filled = await fill.fill(this.fillChannel(), this.cwd, c.origin);
+            if (!filled.ok) {
+                await this.releasePod();
+                return filled.standing ? this.holdRefusal(filled.error) : { ok: false, error: filled.error };
+            }
+        }
+        if (this.destroyed) {
+            await this.releasePod();
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "env destroyed during connect") };
+        }
+        return { ok: true, value: c.value };
+    }
+    fillChannel() {
+        const exec = (command) => this.runExec(ADAPTER_START, command, { capMs: this.cfg.dataTimeoutMs });
+        return {
+            run: async (command) => {
+                const r = await exec(command);
+                return r.ok ? { ok: true, exitCode: r.value.exitCode, stdout: r.value.stdout, stderr: r.value.stderr } : { ok: false, error: r.error.message };
+            },
+            write: async (abs, bytes) => {
+                const w = await this.writeChunked(abs, bytes, true, undefined, exec);
+                return w.ok ? { ok: true } : { ok: false, error: w.error.message };
+            },
+        };
+    }
+    async releasePod() {
+        const name = this.podName;
+        this.podName = undefined;
+        this.podIP = undefined;
+        if (name)
+            await this.deletePod(name).catch(() => { });
+    }
     armSpace() {
         if (this.spaceLane.state === "open")
             this.spaceLane.space.fence.arm(this.cfg.dataTimeoutMs);
@@ -462,8 +509,10 @@ export class RemoteK8sExecutionEnv {
         return spaceReadFailed("occupant", ` (${code}) — refusing to start this run on a workspace that could be neither restored nor saved; retry the run once the session store answers, or set ${ways}`);
     }
     spaceLine(event, space, fields) {
-        const safe = Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, typeof v === "string" ? redactIncarnations(v) : v]));
-        this.logger?.warn(event, { space: incarnationLogPrefix(space.incarnation), ...safe });
+        this.snapshotLine(event, { space: incarnationLogPrefix(space.incarnation), ...fields });
+    }
+    snapshotLine(event, fields) {
+        this.logger?.warn(event, Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, typeof v === "string" ? redactIncarnations(v) : v])));
     }
     provision(signal) {
         const space = this.spaceLane;
@@ -1177,12 +1226,12 @@ export class RemoteK8sExecutionEnv {
     async uploadSnapshot(target, boundMs = this.cfg.dataTimeoutMs) {
         if (target.lane === "park" && this.inFlight.size > 0)
             return { ok: false, error: new RemoteExecutionError("command_in_flight", "cannot suspend while a command is in flight (would snapshot a torn workspace)") };
-        const snapshotId = mintSnapshotId(this.occupantIncarnation);
         if (!this.podName) {
             return target.lane === "space"
                 ? { ok: false, error: new RemoteExecutionError("connect_failed", "the sandbox pod was gone when the run-end snapshot reached the upload — nothing was saved (the workspace could not be read), and `latest` keeps naming the previous snapshot") }
-                : ok(snapshotId);
+                : ok(mintSnapshotId(this.occupantIncarnation, "nothing"));
         }
+        const snapshotId = mintSnapshotId(this.occupantIncarnation, "archive");
         const presigned = this.presignSnapshot({ ...target, method: "PUT", snapshotId });
         if (!presigned.ok)
             return presigned;
@@ -1202,16 +1251,50 @@ export class RemoteK8sExecutionEnv {
         await this.deletePod(name).catch(() => { });
         return ok(snapshotId);
     }
-    async resumeVM(snapshotId, options) {
+    resumeVM(snapshotId, options) {
         if (!this.cfg.s3Snapshot)
-            return unsupported("resumeVM");
-        const r = await this.restoreSnapshot({ lane: "park" }, snapshotId, options?.abortSignal);
+            return Promise.resolve(unsupported("resumeVM"));
+        const same = this.resumeInFlight;
+        if (same?.snapshotId === snapshotId)
+            return same.walk;
+        const prior = this.connectInFlight;
+        const walk = this.resumeWalk(prior, snapshotId, options).finally(() => {
+            if (this.connectInFlight === walk)
+                this.connectInFlight = undefined;
+            if (this.resumeInFlight?.walk === walk)
+                this.resumeInFlight = undefined;
+        });
+        this.connectInFlight = walk;
+        this.resumeInFlight = { snapshotId, walk };
+        return walk;
+    }
+    async resumeWalk(prior, snapshotId, options) {
+        if (prior)
+            await prior;
+        if (this.podName) {
+            this.logger?.warn("sandbox_pod_released_before_restore", { pod: this.podName, ...(this.cfg.sessionId ? { sessionId: this.cfg.sessionId } : {}), effect: "this env held a pod minted before the park snapshot's restore — it is deleted; the restore provisions the leg's one pod" });
+            await this.releasePod();
+        }
+        const r = await this.restorePointOf(snapshotId, options?.abortSignal);
         if (!r.ok)
             return r;
         this.handleSnapshotId = snapshotId;
         this.armSpace();
         return ok(this.workspaceHandle());
     }
+    async restorePointOf(snapshotId, abortSignal) {
+        const holds = snapshotIdHolds(snapshotId);
+        switch (holds) {
+            case "archive":
+                return this.settle(await this.restoreSnapshot({ lane: "park" }, snapshotId, abortSignal));
+            case "nothing":
+                return this.establish(abortSignal ? { abortSignal } : undefined);
+            default: {
+                const unreachable = holds;
+                throw new Error(`unhandled snapshot id family: ${String(unreachable)}`);
+            }
+        }
+    }
     async restoreSnapshot(target, snapshotId, abortSignal) {
         const presigned = this.presignSnapshot({ ...target, method: "GET", snapshotId });
         if (!presigned.ok)
@@ -1234,15 +1317,13 @@ export class RemoteK8sExecutionEnv {
                     ? { cls: restoreClassOfExit(r.value.exitCode), detail: `workspace snapshot restore exited ${r.value.exitCode}: ${this.redactUrl(r.value.stderr, url).slice(0, 300)}` }
                     : undefined;
             if (!failure) {
-                if (target.lane === "space" && r.ok && r.value.stdout.includes("EMPTY_SNAPSHOT"))
-                    await this.dropDanglingLatest(target.space, snapshotId);
-                return ok(this.workspaceHandle());
+                if (r.ok && r.value.stdout.includes("EMPTY_SNAPSHOT")) {
+                    await this.dropDangling(target, snapshotId);
+                    return { ok: true, value: this.workspaceHandle(), origin: "minted" };
+                }
+                return { ok: true, value: this.workspaceHandle(), origin: "restored" };
             }
-            const name = this.podName;
-            this.podName = undefined;
-            this.podIP = undefined;
-            if (name)
-                await this.deletePod(name).catch(() => { });
+            await this.releasePod();
             if (attempt < RESTORE_MAX_ATTEMPTS[target.lane] && restoreFailureIsTransient(failure.cls)) {
                 if (await this.restorePause(abortSignal))
                     continue;
@@ -1280,15 +1361,34 @@ export class RemoteK8sExecutionEnv {
             signal?.addEventListener("abort", onAbort, { once: true });
         });
     }
-    async dropDanglingLatest(space, snapshotId) {
-        const prefix = this.snapshotKeyPrefix();
-        const dropped = await this.writePointer(space, "latest", null);
-        this.spaceLine("workspace_latest_dangling", space, {
-            key: `${prefix}/${space.incarnation}/space/${snapshotId}.tar.gz`,
-            deleted: dropped.ok,
-            ...(dropped.ok ? {} : { error: dropped.error.message }),
-            effect: "the space's latest snapshot is gone (removed by a bucket lifecycle rule or by hand) — this run starts from an empty /workspace; its run-end snapshot becomes the new latest",
-        });
+    async dropDangling(target, snapshotId) {
+        const key = `${this.snapshotBase(target)}${snapshotId}.tar.gz`;
+        switch (target.lane) {
+            case "space": {
+                const dropped = await this.writePointer(target.space, "latest", null);
+                this.spaceLine("workspace_latest_dangling", target.space, {
+                    lane: "space",
+                    key,
+                    deleted: dropped.ok,
+                    ...(dropped.ok ? {} : { error: dropped.error.message }),
+                    effect: "the space's latest snapshot is gone (removed by a bucket lifecycle rule or by hand) — this run starts from an empty /workspace; its run-end snapshot becomes the new latest",
+                });
+                return;
+            }
+            case "park":
+                this.snapshotLine("workspace_latest_dangling", {
+                    lane: "park",
+                    key,
+                    ...(this.cfg.sessionId ? { sessionId: this.cfg.sessionId } : {}),
+                    effect: "the parked run's snapshot is gone (removed by a bucket lifecycle rule or by hand) — the resumed leg starts from an empty /workspace" +
+                        (this.spaceLane.state === "open" ? "; its run-end snapshot becomes the space's new latest" : ""),
+                });
+                return;
+            default: {
+                const unreachable = target;
+                throw new Error(`unhandled snapshot lane: ${String(unreachable.lane)}`);
+            }
+        }
     }
     async postResumeInit() {
         if (!this.cfg.s3Snapshot)
@@ -2081,12 +2181,12 @@ export class RemoteK8sExecutionEnv {
         const abs = this.resolve(p);
         return appendFileStaged(this.stagedLane(content), abs, abortSignal, (ctx) => ctx.inPlace((signal) => this.writeChunked(abs, content, false, signal)));
     }
-    async writeChunked(abs, content, truncateFirst, abortSignal) {
+    async writeChunked(abs, content, truncateFirst, abortSignal, exec = (command) => this.execData(command, abortSignal)) {
         const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
         for (let off = 0, first = true; off < bytes.length || first; off += WRITE_CHUNK_BYTES, first = false) {
             const b64 = bytes.subarray(off, off + WRITE_CHUNK_BYTES).toString("base64");
             const redirect = first && truncateFirst ? ">" : ">>";
-            const r = await this.execData(`printf '%s' ${shellQuote(b64)} | base64 -d ${redirect} ${shellQuote(abs)}`, abortSignal);
+            const r = await exec(`printf '%s' ${shellQuote(b64)} | base64 -d ${redirect} ${shellQuote(abs)}`);
             if (!r.ok)
                 return { ok: false, error: fileErrorFromExec(r.error, abs) };
             if (r.value.exitCode !== 0)

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

@@ -3,6 +3,7 @@ import { type LaneHomeConfig } from "../lane-home-probe.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";
+import type { WorkspaceFill, WorkspaceFillOf } from "./workspace-fill.js";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** Construction config for {@link RemoteLocalDockerExecutionEnv}. */
@@ -59,6 +60,8 @@ export interface LocalDockerEnvConfig extends LaneHomeConfig {
     id?: string;
     /** `SANDBOX_READ_FLOOR`(keep | off;缺席 ⇒ keep):本容器守不守读拒表的字节地板 = 读地板模块服务本车道 ∧ 本键不是 off(`sandbox-read-floor.ts`)。 */
     sandboxReadFloor?: SandboxReadFloorKnob;
+    /** 恢复点的填充座(`workspace-fill.ts`;工厂按 run 装配):容器新建之后、交给本环境之前,经本适配器自己的 `docker exec` 往工作区里放内容。缺席 ⇒ 不放。 */
+    workspaceFill?: WorkspaceFill;
 }
 /** Inject `spawn` for tests (a fake docker CLI). Defaults to node's child_process spawn. */
 export interface LocalDockerEnvDeps {
@@ -92,12 +95,15 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     private destroyed;
     /** In-flight connect, memoized so concurrent lazy first-use starts exactly one container (no double-run). */
     private connecting?;
-    /** 家目录:环境答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。 */
-    private homeRefusal?;
+    /** 这只环境的拒 —— 记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。两个写者:家目录(环境答了而与声明不一致)
+     *  与恢复点的填充(换一只容器也是同一个答的拒:种子不是项目包、摘要不符、镜像没有 `tar`、镜像预置撞名 —— `FillOutcome.standing`)。 */
+    private connectRefusal?;
     /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
     constructor(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps);
     private resolve;
+    /** 收据句柄。还没连上(懒环境:续跑腿的引擎在恢复相**之前**先取它比车道)⇒ 未连接形 `{ sandboxId: "(unconnected)", provider, mountPath }`(与 k8s / e2b 车道同形),
+     *  不抛 —— 抛了,续跑腿在恢复相就失败。 */
     workspaceHandle(): WorkspaceHandle;
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
@@ -107,6 +113,10 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         error: RemoteExecutionError;
     }>;
     private doConnect;
+    /** 恢复点的填充:有座 ⇒ 经 {@link fillChannel} 放(容器恒是新起的 ⇒ `minted`;本车道不可挂起);没有 ⇒ 什么都不放。 */
+    private fillWorkspace;
+    /** 恢复点手里的通道:`docker exec` 经唯一起动接缝(起动形 `adapter`,与引擎命令同一执行用户;连接进行中,不经懒连接的文件面);写 = 容器内 `cat >` 从 stdin 收整份字节。 */
+    private fillChannel;
     /**
      * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 实测)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、同一份 `-e` env),读数交座。
      * 声明在场:环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,
@@ -258,6 +268,8 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
  * owns the lifetime and calls `destroy()` (= `docker rm -f`) on task end. Folds the per-task `ctx.taskId`/
  * `ctx.sessionId` into the container name so two concurrent tasks never share a container.
  */
-export declare function localDockerExecutionEnvFactory(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps): ExecutionEnvFactory;
+export declare function localDockerExecutionEnvFactory(config: Omit<LocalDockerEnvConfig, "workspaceFill"> & {
+    readonly workspaceFillOf?: WorkspaceFillOf;
+}, deps?: LocalDockerEnvDeps): ExecutionEnvFactory;
 export {};
 //# sourceMappingURL=remote-env-local-docker.d.ts.map

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

@@ -37,7 +37,7 @@ export class RemoteLocalDockerExecutionEnv {
     handle;
     destroyed = false;
     connecting;
-    homeRefusal;
+    connectRefusal;
     homeSeat;
     constructor(config, deps = {}) {
         if (!config.image || !config.image.trim()) {
@@ -64,17 +64,15 @@ export class RemoteLocalDockerExecutionEnv {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
     }
     workspaceHandle() {
-        if (!this.handle)
-            throw new RemoteExecutionError("connect_failed", "workspaceHandle() called before connect()");
-        return this.handle;
+        return this.handle ?? { sandboxId: "(unconnected)", provider: PROVIDER, mountPath: this.cfg.mountPath };
     }
     async connect(config) {
         if (config?.snapshotId)
             return unsupported("connect(snapshotId)");
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (this.homeRefusal)
-            return { ok: false, error: this.homeRefusal };
+        if (this.connectRefusal)
+            return { ok: false, error: this.connectRefusal };
         if (config?.abortSignal?.aborted)
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
         if (this.containerId)
@@ -139,12 +137,38 @@ export class RemoteLocalDockerExecutionEnv {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         }
+        const filled = await this.fillWorkspace();
+        if (!filled.ok || this.destroyed) {
+            await this.forceRemove().catch(() => { });
+            if (!filled.ok && filled.standing)
+                this.connectRefusal = filled.error;
+            return { ok: false, error: filled.ok ? new RemoteExecutionError("connect_failed", "execution env destroyed during connect") : filled.error };
+        }
         this.containerId = run.value.stdout.trim() || this.containerName;
         this.handle = { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
         if (config?.secrets?.length) {
         }
         return ok(this.handle);
     }
+    fillWorkspace() {
+        return this.cfg.workspaceFill === undefined ? Promise.resolve({ ok: true }) : this.cfg.workspaceFill.fill(this.fillChannel(), this.cfg.mountPath, "minted");
+    }
+    fillChannel() {
+        const run = async (command, input) => {
+            const argv = this.startArgv(ADAPTER_START, command, { shell: "/bin/sh", ...(input !== undefined ? { stdin: true } : {}) });
+            if (!argv.ok)
+                return { ok: false, error: argv.error.message };
+            const r = await this.docker(argv.value, { timeoutMs: this.cfg.commandTimeoutMs, ...(input !== undefined ? { input } : {}) });
+            return r.ok ? { ok: true, exitCode: r.value.exitCode, stdout: r.value.stdout, stderr: r.value.stderr } : { ok: false, error: r.error.message };
+        };
+        return {
+            run: (command) => run(command),
+            write: async (abs, bytes) => {
+                const r = await run(`cat > ${shellQuote(abs)}`, bytes);
+                return !r.ok ? r : r.exitCode === 0 ? { ok: true } : { ok: false, error: r.stderr.trim() || `exit ${r.exitCode}` };
+            },
+        };
+    }
     async homeVerdict(signal) {
         if (!this.homeSeat.asks)
             return undefined;
@@ -157,7 +181,7 @@ export class RemoteLocalDockerExecutionEnv {
             return undefined;
         const error = new RemoteExecutionError("connect_failed", verdict.refusal);
         if (verdict.answered)
-            this.homeRefusal = error;
+            this.connectRefusal = error;
         return error;
     }
     async suspendVM(_options) {
@@ -172,8 +196,8 @@ export class RemoteLocalDockerExecutionEnv {
     async reconnect(sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (this.homeRefusal)
-            return { ok: false, error: this.homeRefusal };
+        if (this.connectRefusal)
+            return { ok: false, error: this.connectRefusal };
         if (sessionToken && sessionToken !== this.containerName) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `reconnect token '${String(sessionToken)}' does not match this env's container '${this.containerName}'`) };
         }
@@ -189,8 +213,8 @@ export class RemoteLocalDockerExecutionEnv {
             const home = this.containerId === undefined ? await this.homeVerdict() : undefined;
             if (home !== undefined)
                 return { ok: false, error: home };
-            if (this.destroyed || this.homeRefusal)
-                return { ok: false, error: this.homeRefusal ?? new RemoteExecutionError("connect_failed", "execution env destroyed during reconnect") };
+            if (this.destroyed || this.connectRefusal)
+                return { ok: false, error: this.connectRefusal ?? new RemoteExecutionError("connect_failed", "execution env destroyed during reconnect") };
             this.containerId = this.containerName;
             this.handle ??= { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
             return ok(this.handle);
@@ -682,6 +706,10 @@ function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
 export function localDockerExecutionEnvFactory(config, deps = {}) {
-    return (ctx) => new RemoteLocalDockerExecutionEnv({ ...config, id: config.id ?? ctx.taskId ?? ctx.sessionId }, deps);
+    const { workspaceFillOf, ...base } = config;
+    return (ctx) => {
+        const workspaceFill = workspaceFillOf?.(ctx);
+        return new RemoteLocalDockerExecutionEnv({ ...base, id: base.id ?? ctx.taskId ?? ctx.sessionId, ...(workspaceFill !== undefined ? { workspaceFill } : {}) }, deps);
+    };
 }
 //# sourceMappingURL=remote-env-local-docker.js.map

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

@@ -387,7 +387,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * 它的域完全靠「属主 sessionId 的墓碑」推。而会话 id 是**调用方可自选**的 ⇒ 两个租户先后用过同一个 id
      * 完全合法;两边都删过之后,同一个 row_key 上会有**两个域**的墓碑,这时任何一边的 sweep 拿自己的墓碑
      * 去认领这些字节都只是猜。判据因此是:**存在第二个域的同名墓碑 ⇒ 这批行不可归属 ⇒ 一根不删**,
-     * 实体清理退回既有的 TTL 腿(`reapOlderThan`)。少删一次是可接受的;删掉另一个租户的字节、还跳过它的
+     * 实体清理退回既有的 TTL 腿(core `ToolResultStore.reap`)。少删一次是可接受的;删掉另一个租户的字节、还跳过它的
      * legal hold 与审计域,不可接受。
      */
     protected orphanToolResultCandidates(exec: {
@@ -475,7 +475,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *    也只计 `skipped` 不删。会话本体的清理归 {@link SqlRetentionStore.deleteExpiredSessions}(它会连着
      *    这行一起删),两条腿因此不重叠也不互相抢行。
      *  · **一根不碰的那一支**:`owner_session_id IS NULL` 的**无出处**行。没有出处就没有域,按任何域去删它
-     *    都是猜;实体清理归既有的 TTL 腿(`reapOlderThan`,`boot/reapers.ts` 驱动)。这与 core 的
+     *    都是猜;实体清理归既有的 TTL 腿(core `ToolResultStore.reap`,`boot/reapers.ts` 驱动)。这与 core 的
      *    「an UNOWNED entry is never deleted」是同一条纪律的两处执行点。
      *
      * 事务形与另外两只方法逐字同款(hold 哨兵行锁读 → 删除+墓碑 → 审计行,同 commit 同 rollback)。

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 FencedRun, 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, type SettledLegMemoryObservation } 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";
@@ -228,6 +228,14 @@ export declare class SqlRunStore {
      * 两方言只差占位符(动态子句为零,不像 listRuns/listSessions 那样需要各自的构造器臂)。
      */
     latestRunForSession(sessionId: string): Promise<LatestRunRef | undefined>;
+    /**
+     * [ref] —— 这个会话**最近一条已结腿**与它的记忆观测(规则属主 = `store-contracts.ts` 的 {@link SettledLegMemoryObservation};
+     * 文件 / 内存两店是它的孪生)。排序口径与 {@link latestRunForSession} 逐字同一句;已结词集按本文件头注的惯例写字面(两方言并排可读),
+     * 与属主谓词 `isTerminalRunStatus` 的同源由方言对 parity 门钉(`test/source-hygiene-gate.test.ts` 的语句规则 `settled-leg-observation-read`)。
+     * 同一条索引路径(`idx_task_run_session_status` 的 `(session_id, status)` 前缀),**不新加索引**。
+     * 结果列走 {@link rowToRun} 同一只解码口与同一个失败方向(读不出 ⇒ 拒,不把一条结了的腿读成「没有观测」)。
+     */
+    latestMemoryObservationForSession(sessionId: string): Promise<SettledLegMemoryObservation | undefined>;
     /** GET /v1/sessions (CC /resume picker): DISTINCT sessions newest-first by last activity, keyset-paginated on
      *  (last_activity, session_id). Aggregates task_run by session_id — one window pass picks the latest run per
      *  session (rn=1) for the preview/status and rolls up first/last/count. Owner-scoped when set (the per-user view).

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

@@ -6,7 +6,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, readLegacyHolderDeathCode } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, readLegacyHolderDeathCode, 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";
@@ -413,6 +413,14 @@ export class SqlRunStore {
         const r = rows[0];
         return r === undefined ? undefined : { taskId: String(r.task_id), owner: r.owner ?? null, createdAt: iso(r.created_at) };
     }
+    async latestMemoryObservationForSession(sessionId) {
+        const { rows } = await this.db.query(this.q("SELECT task_id, " + jsonColumnText("mysql", "result") + " FROM task_run WHERE session_id = ? AND status IN ('completed','failed','blocked') ORDER BY created_at DESC, task_id DESC LIMIT 1", "SELECT task_id, " + jsonColumnText("pg", "result") + " FROM task_run WHERE session_id = $1 AND status IN ('completed','failed','blocked') ORDER BY created_at DESC, task_id DESC LIMIT 1"), [sessionId]);
+        const r = rows[0];
+        if (r === undefined)
+            return undefined;
+        const taskId = String(r.task_id);
+        return settledLegObservationOf(taskId, refusing("read a settled leg as if it had observed no memory", () => decodeResultColumn(r.result, taskId)) ?? null);
+    }
     async listSessions(opts) {
         if (this.db.dialect === "mysql") {
             const params = [];

package/dist/plugins/sandbox-read-floor.d.ts

@@ -5,11 +5,9 @@ export declare const READ_FLOOR_UNAVAILABLE_REASONS: readonly ["arch", "user_not
 export type ReadFloorUnavailableReason = (typeof READ_FLOOR_UNAVAILABLE_REASONS)[number];
 /** F2:附着不过的环境上,带地板起动的拒句(纯字符串 ⇒ `build*`)。首句点名原因词;点名表的首行与旋钮。 */
 export declare function buildReadFloorUnavailableMessage(reason: ReadFloorUnavailableReason, detail: string | undefined, floor: ReadFloor | undefined): string;
-/** F6:守地板的环境上,不带地板的引擎起动的拒句。 */
-export declare function buildReadFloorMissingMessage(lane: SandboxFloorLane): string;
 /**
  * 一次起动是什么(闭集,调用方必须表态 —— 没有缺省臂):
- *  · `engine` —— 经执行环境公共起动口要起的命令(引擎的,或替引擎干活的服务端调用方的);带不带地板是它交来的事实。`hold` = 适配器之后还会以
+ *  · `engine` —— 经执行环境公共起动口要起的命令(引擎的,或替引擎干活的服务端调用方的);它带的地板就是它的表,缺席 = 表无行。`hold` = 适配器之后还会以
  *    同一起动号再起 `run`(k8s 后台作业的轮询 / 停 / 收尾读的是这次起动的产物,按这次起动的地板跑),登记留到 {@link SandboxReadFloor.release};
  *  · `under` —— 以一次已登记(`hold`)起动的号再起一只 `run`(上面那类轮询);
  *  · `adapter` —— 适配器自己的固定命令(文件面助手、探针、数据搬运、全杀);附着成功之后经监督者的 `plain` 起;
@@ -29,7 +27,7 @@ export type FloorStart = {
 };
 export declare const ADAPTER_START: FloorStart;
 export declare const BOOTSTRAP_START: FloorStart;
-/** 引擎起动:`readFloor` 原样交(`undefined` = 这次起动不带地板)。 */
+/** 引擎起动:`readFloor` 原样交(`undefined` = 这次起动的表一行都没有)。 */
 export declare function engineStart(readFloor: ReadFloor | undefined, hold?: boolean): FloorStart;
 /** 起动身份:`root` = 车道以 root 起(e2b `user:"root"`、local-docker `-u 0`);`exec-user` = 车道自己的执行身份(改前的形)。 */
 export type FloorLaunchIdentity = "root" | "exec-user";
@@ -125,8 +123,8 @@ export interface RelayAnswer {
 export declare const UNJUDGED_VERDICT = "read floor: no verdict for this start";
 /** 判官:适配器进程里唯一回答「这条路径拒不拒」的东西。live object ⇒ `create*`。 */
 export interface FloorJudge {
-    /** 登记一次带地板的起动,回它的起动号(随机、不可猜)。`held` ⇒ 之后还会以这个号再起 `run`(`under`),直到 {@link release};否则这一次就是它唯一的起动。 */
-    register(floor: ReadFloor, held: boolean): string;
+    /** 登记一次引擎起动(带它的表;`undefined` = 表无行),回它的起动号(随机、不可猜)。`held` ⇒ 之后还会以这个号再起 `run`(`under`),直到 {@link release};否则这一次就是它唯一的起动。 */
+    register(floor: ReadFloor | undefined, held: boolean): string;
     /** 以这个号再起一次 `run`(`under`)之前问:在册且适配器没说过「不再起」⇒ `true`(记下又有一只监督者将连上);否则 `false`(起动拒)。 */
     launch(startId: string): boolean;
     /** 适配器不会再以这个号起 `run` 了。登记要两件都到才撤(协议 §5.5):这一句 ∧ 此后的 `gone` —— `gone` 已在 ⇒ 当即撤;否则等它(还连着的监督者照旧有判官答)。 */
@@ -202,7 +200,7 @@ export interface SandboxReadFloor {
     readonly state: SandboxReadFloorState;
     /** 这只模块钉住的监督者二进制(守地板 ⇒ 在;裸模块 ⇒ 缺席)。k8s 的 pod 座({@link buildFloorPodSeat})只读它 —— 放进 pod 的与自检核的是同一份钉。 */
     readonly binaries: FloorBinaries | undefined;
-    /** 唯一接缝:一次起动 → 答案,或 `spawn_error`(F2 / F6 / 时机不对的引导起动 / 已撤的号)。 */
+    /** 唯一接缝:一次起动 → 答案,或 `spawn_error`(F2 / 时机不对的引导起动 / 已撤的号)。 */
     wrap(start: FloorStart): Result<FloorLaunch, ExecutionError>;
     /** 适配器不会再以这个号起 `run`(`hold` 起动的收尾)。登记在其后的 `gone` 到时撤(还连着的监督者照旧有判官答)。 */
     release(startId: string | undefined): void;

package/dist/plugins/sandbox-read-floor.js

@@ -35,11 +35,6 @@ export function buildReadFloorUnavailableMessage(reason, detail, floor) {
         `This command carries a read-deny table${first !== undefined ? ` (first row "${first}")` : ""} this sandbox cannot keep, so it is refused rather than run with fewer rows. ` +
         `To run this lane without the byte floor, set ${SANDBOX_READ_FLOOR_ENV}=off (the lane then declares keepsReadFloor=false: each run with read-deny rows is announced, or refused when READ_DENY_FLOOR_REQUIRED=true).`);
 }
-export function buildReadFloorMissingMessage(lane) {
-    return (`read floor: this ${lane} sandbox keeps the read-deny byte floor, and this command start carries no floor — it is refused rather than run a process the floor does not judge ` +
-        `(every start on a lane that keeps the floor must carry the run's read-deny table). ` +
-        `To run this lane without the byte floor, set ${SANDBOX_READ_FLOOR_ENV}=off.`);
-}
 export const ADAPTER_START = Object.freeze({ kind: "adapter" });
 export const BOOTSTRAP_START = Object.freeze({ kind: "bootstrap" });
 export function engineStart(readFloor, hold = false) {
@@ -121,6 +116,8 @@ export function parseRelayFrame(line) {
 }
 export const UNJUDGED_VERDICT = "read floor: no verdict for this start";
 function judgeOne(floor, path) {
+    if (floor === undefined)
+        return null;
     let v;
     try {
         v = floor.denies(path);
@@ -433,8 +430,6 @@ export function createKeptSandboxReadFloor(opts) {
                 }
                 case "engine": {
                     const floor = start.readFloor;
-                    if (floor === undefined)
-                        return spawnError(buildReadFloorMissingMessage(lane));
                     if (phase.kind === "unavailable")
                         return spawnError(buildReadFloorUnavailableMessage(phase.reason, phase.detail, floor));
                     if (phase.kind !== "ready" || bin === undefined)

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

@@ -1,7 +1,8 @@
 /**
  * SQL 驱动错误的**方言判别**——「这是不是唯一键冲突」的单一属主([ref] P1-①,病族
  * single-semantic-multi-site-drift)。`sql-escape.ts` / `sql-row-helpers.ts` / `store-contracts.ts`
- * 的同级叶子:零 store 逻辑、零驱动依赖(不 import mysql2/pg),纯谓词。
+ * 的同级叶子:零 store 逻辑、零驱动依赖(不 import mysql2/pg),纯谓词 —— 外加死锁判据唯一的消费形 {@link retryOnDeadlock}
+ * (「撞死锁重来几次」与「什么算死锁」住在一处:上界只有一个数,不在各店各写一个)。
  *
  * ## 为什么必须只有一份
  * 收编前这条谓词在 src/ 手铸 ≥7 处,而且**识别集互相漂移**:一半站点只认 `code === "ER_DUP_ENTRY"`,
@@ -96,6 +97,14 @@ export declare const PG_DEADLOCK_DETECTED_SQLSTATE = "40P01";
  * **MySQL 协议腿**,两方言都认只是为了让店不必自己判引擎。
  */
 export declare function isDeadlockError(dialect: SqlDialect, err: unknown): boolean;
+/** 引擎仲裁之后整段重来的**唯一**上界(全仓每一条「撞死锁就重来」的腿共用这一个数)。8 = 锁形并发套的并发度:缺行首写的 N 路竞争每轮至多多走一轮([ref] 读数 1 成 7 死锁)。 */
+export declare const DEADLOCK_RETRY_LIMIT = 8;
+/**
+ * 「引擎判了死锁 ⇒ 整段重来」的**唯一**写法:有界({@link DEADLOCK_RETRY_LIMIT}),判据 {@link isDeadlockError};用尽 / 其它错误原样抛。
+ * `attempt` 必须整段重做语义等价(读-判-写全在里面的一只事务,或一条幂等语句)。`alsoArbitrated`:店自己认的另一种仲裁产物(例:缺行首写撞主键 ——
+ * 并发的另一只首写赢了,重读即走更新腿),与死锁同族、同一个上界。锁等待超时不在任何一族里(延迟信号,见 {@link isDeadlockError} 的注):它照抛。
+ */
+export declare function retryOnDeadlock<T>(dialect: SqlDialect, attempt: () => Promise<T>, alsoArbitrated?: (err: unknown) => boolean): Promise<T>;
 /** TiDB `ErrEntryTooLarge` (one row's key + value over `txn-entry-size-limit`, 6 MiB by default) — TiDB's own
  *  errno, which mysql2 carries without a symbolic name. */
 export declare const TIDB_ER_ENTRY_TOO_LARGE_ERRNO = 8025;