@sema-agent/server 7.141.0 → 7.142.0

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

@@ -35,7 +35,7 @@ export class RemoteContainerExecutionEnv {
     handle;
     destroyed = false;
     homeSeat;
-    homeRefusal;
+    connectRefusal;
     connecting;
     activeCommands = 0;
     paused = false;
@@ -138,10 +138,7 @@ export class RemoteContainerExecutionEnv {
         };
     }
     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.cwd };
     }
     async getHost(port) {
         const conn = await this.ensureConnected();
@@ -162,17 +159,18 @@ export class RemoteContainerExecutionEnv {
         }
         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 (this.paused)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resumeVM(snapshotId) before use") };
         if (this.sbx)
             return ok(this.workspaceHandle());
         if (this.connecting)
-            return this.connecting;
-        this.connecting = this.doConnect(config);
-        const r = await this.connecting;
-        if (!r.ok)
+            return this.connecting.promise;
+        const mine = { target: undefined, promise: this.doConnect(config) };
+        this.connecting = mine;
+        const r = await mine.promise;
+        if (!r.ok && this.connecting === mine)
             this.connecting = undefined;
         return r;
     }
@@ -201,6 +199,14 @@ export class RemoteContainerExecutionEnv {
                 await sbx.kill().catch(() => { });
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
             }
+            const filled = await this.fillAt(sbx, this.cfg.mountPath, "minted");
+            if (!filled.ok || this.destroyed) {
+                await sbx.kill().catch(() => { });
+                this.cfg.metrics?.inc("remote_env_connect_total", { provider: PROVIDER, result: "error" });
+                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.sbx = sbx;
             this.paused = false;
             this.startKeepAlive();
@@ -250,20 +256,50 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.remoteError(e, options?.abortSignal?.aborted ? "aborted" : "unknown") };
         }
     }
-    async resumeVM(snapshotId, options) {
+    resumeVM(snapshotId, options) {
         if (this.destroyed)
-            return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
-        if (this.homeRefusal)
-            return { ok: false, error: this.homeRefusal };
+            return Promise.resolve({ ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") });
+        if (this.connectRefusal)
+            return Promise.resolve({ ok: false, error: this.connectRefusal });
         if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
-            return ok(this.workspaceHandle());
-        if (this.connecting)
-            return this.connecting;
-        this.connecting = this.doResumeVM(snapshotId, options);
-        const r = await this.connecting;
-        if (!r.ok)
-            this.connecting = undefined;
-        return r;
+            return Promise.resolve(ok(this.workspaceHandle()));
+        const inFlight = this.connecting;
+        if (inFlight?.target === snapshotId)
+            return inFlight.promise;
+        const mine = { target: snapshotId, promise: this.resumeWalk(inFlight, snapshotId, options) };
+        this.connecting = mine;
+        const forget = () => {
+            if (this.connecting === mine)
+                this.connecting = undefined;
+        };
+        mine.promise.then((r) => {
+            if (!r.ok)
+                forget();
+        }, forget);
+        return mine.promise;
+    }
+    async resumeWalk(inFlight, snapshotId, options) {
+        if (inFlight !== undefined) {
+            await inFlight.promise;
+            if (this.destroyed)
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
+            if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
+                return ok(this.workspaceHandle());
+        }
+        if (this.sbx && !this.paused)
+            await this.releaseMinted(snapshotId);
+        return this.doResumeVM(snapshotId, options);
+    }
+    async releaseMinted(resumed) {
+        const sbx = this.sbx;
+        if (sbx === undefined)
+            return;
+        this.sbx = undefined;
+        this.handle = undefined;
+        this.stopKeepAlive();
+        await this.disposeBackgroundShells();
+        await this.rpc("sandbox.kill", () => sbx.kill()).catch((e) => this.cfg.logger?.warn("remote_env_minted_release_failed", { sandboxId: sbx.sandboxId, error: errMsg(e) }));
+        this.cfg.logger?.info?.("remote_env_minted_released", { sandboxId: sbx.sandboxId, resumed });
     }
     async doResumeVM(snapshotId, options) {
         try {
@@ -288,6 +324,18 @@ export class RemoteContainerExecutionEnv {
                 this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "error" });
                 return { ok: false, error: home };
             }
+            const filled = await this.fillAt(sbx, restoredRoot, "restored");
+            if (this.destroyed) {
+                await sbx.kill().catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
+            }
+            if (!filled.ok) {
+                await this.rpc("sandbox.pause", (signal) => sbx.pause({ signal }), undefined, this.cfg.dataTimeoutMs).catch((e) => this.cfg.logger?.warn?.("remote_env_fill_refused_repause_failed", { sandboxId: sbx.sandboxId, error: errMsg(e) }));
+                this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "error" });
+                if (filled.standing)
+                    this.connectRefusal = filled.error;
+                return { ok: false, error: filled.error };
+            }
             this.sbx = sbx;
             this.paused = false;
             this.startKeepAlive();
@@ -340,9 +388,39 @@ export class RemoteContainerExecutionEnv {
             return undefined;
         const error = new RemoteExecutionError("connect_failed", verdict.refusal);
         if (verdict.answered)
-            this.homeRefusal = error;
+            this.connectRefusal = error;
         return error;
     }
+    fillAt(sbx, root, origin) {
+        return this.cfg.workspaceFill === undefined ? Promise.resolve({ ok: true }) : this.cfg.workspaceFill.fill(this.fillChannel(sbx), root, origin);
+    }
+    fillChannel(sbx) {
+        return {
+            run: async (command) => {
+                const s = this.startIn(ADAPTER_START, command, undefined);
+                if (!s.ok)
+                    return { ok: false, error: s.error.message };
+                try {
+                    const r = await this.rpc("workspace.fill", (signal) => this.runIn(sbx, s.value, { signal, timeoutMs: this.cfg.dataTimeoutMs }), undefined, this.cfg.dataTimeoutMs);
+                    return { ok: true, exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+                }
+                catch (e) {
+                    if (e instanceof CommandExitError)
+                        return { ok: true, exitCode: e.exitCode, stdout: e.stdout, stderr: e.stderr };
+                    return { ok: false, error: errMsg(e) };
+                }
+            },
+            write: async (abs, bytes) => {
+                try {
+                    await this.rpc("files.write", (signal) => sbx.files.write(abs, toArrayBuffer(bytes), { signal }), undefined, this.cfg.dataTimeoutMs);
+                    return { ok: true };
+                }
+                catch (e) {
+                    return { ok: false, error: errMsg(e) };
+                }
+            },
+        };
+    }
     startKeepAlive() {
         this.stopKeepAlive();
         const everyMs = Math.max(30_000, Math.floor(this.cfg.timeoutMs * 0.8));
@@ -1130,10 +1208,15 @@ export class RemoteContainerExecutionEnv {
     }
 }
 export function e2bExecutionEnvFactory(config, deps) {
-    return (ctx) => new RemoteContainerExecutionEnv({
-        ...config,
-        metadata: { ...config.metadata, semaManaged: "1", sessionId: ctx.sessionId, ...(ctx.taskId ? { taskId: ctx.taskId } : {}) },
-    }, deps);
+    const { workspaceFillOf, ...base } = config;
+    return (ctx) => {
+        const workspaceFill = workspaceFillOf?.(ctx);
+        return new RemoteContainerExecutionEnv({
+            ...base,
+            metadata: { ...base.metadata, semaManaged: "1", sessionId: ctx.sessionId, ...(ctx.taskId ? { taskId: ctx.taskId } : {}) },
+            ...(workspaceFill !== undefined ? { workspaceFill } : {}),
+        }, deps);
+    };
 }
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);

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

@@ -123,6 +123,9 @@ export interface K8sEnvConfig extends LaneHomeConfig {
     /** Run-end outcome seat — called once per `destroy()` that attempted a space snapshot (the factory's caller binds it
      *  to the run, so the run's terminal frame can carry `workspaceSnapshot: "failed"`). */
     onWorkspaceSnapshot?: (outcome: "saved" | "failed") => void;
+    /** 恢复点的填充座(`workspace-fill.ts`;工厂按 run 装配):pod 的工作区铸出 / 恢复之后、`connect` / `resumeVM` 交还之前,经 {@link RemoteK8sExecutionEnv} 自己的
+     *  exec 通道(不经公开面 —— 连接进行中公开面会等同一只连接记忆)往工作区里放内容。缺席 ⇒ 不放。 */
+    workspaceFill?: WorkspaceFill;
     /**
      * 🔴 ADDITIVE pod-spec patch (a SERVICE-side adapter seam, NOT a core seam: the K8s pod shape is
      * provider-specific, so it stays in the adapter per [ref]). A deployment supplies extra volumes / volumeMounts
@@ -171,6 +174,7 @@ import { type SandboxSecretSeatKind, type SandboxSecretVerb } from "./k8s-exec-p
 export { type PodSpecPatch, applyPodSpecPatch } from "./k8s-exec-protocol.js";
 import { type SandboxPodApi, type SandboxPodListing } from "./k8s-pod-reaper.js";
 import { type SandboxLeaseEntryInput } from "../sandbox-git-lease.js";
+import type { WorkspaceFill } from "./workspace-fill.js";
 type ConnectResult = {
     ok: true;
     value: WorkspaceHandle;
@@ -318,9 +322,12 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private readonly inFlight;
     /** Resolvers of {@link whenIdle}: woken when the last command in flight ends. */
     private idleWaiters;
-    /** This env's one connect in flight (see {@link connect}): the explicit connect, the lazy connect and `reconnect` that arrive while it runs
-     *  share it — one pod creation, one restore (the E2B race lesson). Cleared the moment it settles, whatever the outcome. */
+    /** This env's one lifecycle walk in flight — a connect ({@link connect}) or a resume ({@link resumeVM}): the explicit connect, the lazy connect of
+     *  the first operation and `reconnect` that arrive while it runs share its answer — one pod creation, one restore, one fill (the E2B race lesson).
+     *  Cleared the moment it settles, whatever the outcome (by the walk that set it, never by an earlier one). */
     private connectInFlight?;
+    /** The resume among them, with the snapshot it restores: a second `resumeVM` of the same snapshot shares it (one restore, one pod). */
+    private resumeInFlight?;
     /** The env's refusal — a fact of this env until `destroy`, written once ({@link holdRefusal}) and answered as it stands to every later connect (and to
      *  every later pod creation: {@link provision}): the same refusal, zero pods, zero store requests, no second line. Two causes write it:
      *  the space restore (`latest` names an archive that is there and did not come back — {@link restoreSnapshot}) and the pod's admission (the cluster created
@@ -355,6 +362,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private cacheUnavailableSaid;
     private readonly logger?;
     private readonly onWorkspaceSnapshot?;
+    private readonly workspaceFill?;
     private readonly cacheMisses?;
     constructor(config: K8sEnvConfig, deps?: K8sEnvDeps);
     /** The lease seat of the pod this env holds now — `undefined` without a broker seat or without a pod (the server's lease writes follow it: a resumed env holds a new pod and a new seat). */
@@ -391,6 +399,19 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     connect(config?: RemoteConnectConfig): Promise<ConnectResult>;
     /** The one walk of a connect ({@link connect} runs it once at a time). */
     private establish;
+    /**
+     * The restore point's fill (`workspace-fill.ts`): a pod whose workspace this env just minted or restored is handed over only once the fill seat placed
+     * its content — through {@link fillChannel} (this adapter's own exec, never the public face: inside a connect the public face waits on that very connect).
+     * A fill that does not complete releases the pod (no tool and no run-end snapshot may see a half-filled workspace); a refusal that would answer the same
+     * again (`standing`) is held for the env ({@link holdRefusal}). No seat ⇒ the pod as it came. `origin` tells the seat whether the workspace was minted
+     * (a new pod with nothing restored: the space off / unavailable / without `latest`, or `latest` dangling) or restored (the space's `latest`, or a park snapshot whose archive came back; a park snapshot with no archive — a plan-only park — is minted).
+     */
+    private settle;
+    /** The restore point's channel: a fixed command through the one start seam (start form `adapter`, the engine's commands' identity) and a write in
+     *  {@link writeChunked}'s form — both straight on {@link runExec} with the data bound (never {@link ensureConnected}). */
+    private fillChannel;
+    /** Release the pod this env holds (its workspace is not handed over): the pod deleted, its seats cleared. No pod ⇒ nothing. */
+    private releasePod;
     /** This env holds a workspace its `destroy()` will commit ⇒ arm its seat on the space's commit fence (from here the
      *  run's terminal write fences the space; `workspace-space-commit.ts`). Each write of this run's row sets its deadline to
      *  now + the upload's own wall-clock bound (`dataTimeoutMs`). No-op unless the space lane is open. */
@@ -632,7 +653,9 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /**
      * Resume a workspace snapshot onto a FRESH pod (resume = executionEnvFactory rebuild + resumeVM):
      * provision a pod, then download + untar the snapshot into the workspace ({@link restoreSnapshot}, lane `park`). A
-     * missing object (empty/plan-only snapshot) resumes as a clean workspace.
+     * missing object (a plan-only park: no pod was ever minted, so nothing was uploaded) resumes as a clean workspace whose origin is `minted` —
+     * no restorable tree — so the restore point seeds it; the resume walks the park lane and never reads the space's `latest` (which a fresh connect with the space on
+     * would restore); a snapshot that came back is `restored` and never seeded.
      *
      * [ref]①(priorHandle 根保真)——k8s 走**诚实臂**而非绑定臂:pod 的 workspace volume 挂在**当前**
      * 配置根(cfg.mountPath),往 priorHandle.mountPath 绑=往容器 rootfs untar 大工作区,ephemeral-storage
@@ -641,10 +664,13 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 变更窗的分歧由 core 侧 fail-closed reopen 兜底,审批不烧错根。
      */
     resumeVM(snapshotId: SnapshotId, options?: VmLifecycleOptions): Promise<ConnectResult>;
+    /** The one walk of a resume ({@link resumeVM} runs it under the connect gate). */
+    private resumeWalk;
     /**
      * The ONE tar download (both lanes): provision a FRESH pod, download + untar the lane's archive into the workspace.
-     * A missing archive (404) starts from the clean workspace on both lanes — what differs is what it means:
-     *  - park: a plan-only suspend has no object — nothing to say;
+     * A missing archive (404) starts from the clean workspace on both lanes, and on both it is the same fact — no restorable tree ⇒ origin
+     * `minted` (the restore point seeds it, exactly as on a fresh connect). What differs is only what it means:
+     *  - park: a plan-only suspend has no object (the park came before anything touched the hand) — nothing to say;
      *  - space: `latest` dangles (its pointer is only written after a successful upload, so the archive was removed later —
      *    by the bucket's lifecycle rule or a hand): the data is gone by an operator rule ⇒ loud and continuable —
      *    {@link dropDanglingLatest} (one `workspace_latest_dangling` line, the pointer deleted); the run's own run-end

package/dist/plugins/remote-env-k8s.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);
@@ -1202,10 +1249,31 @@ 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.settle(await this.restoreSnapshot({ lane: "park" }, snapshotId, options?.abortSignal));
         if (!r.ok)
             return r;
         this.handleSnapshotId = snapshotId;
@@ -1234,15 +1302,14 @@ 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")) {
+                    if (target.lane === "space")
+                        await this.dropDanglingLatest(target.space, 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;
@@ -2081,12 +2148,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