@sema-agent/server 7.140.0 → 7.142.0

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

@@ -2,6 +2,7 @@ import path from "node:path";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
+import { ADAPTER_START, BOOTSTRAP_START, createSandboxReadFloor, e2bFloorCommand, engineStart, } from "./sandbox-read-floor.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
 import { appendFileStaged, rewriteAppend, numEnvOr, runSymlinkChain, shellQuote, writeFileStaged } from "./remote-shell.js";
@@ -34,7 +35,7 @@ export class RemoteContainerExecutionEnv {
     handle;
     destroyed = false;
     homeSeat;
-    homeRefusal;
+    connectRefusal;
     connecting;
     activeCommands = 0;
     paused = false;
@@ -52,13 +53,92 @@ export class RemoteContainerExecutionEnv {
         this.cwd = this.cfg.mountPath;
         this.homeSeat = new LaneHomeSeat(PROVIDER, config);
         this.sandboxApi = deps.sandboxApi ?? Sandbox;
+        this.floor = deps.readFloor ?? createSandboxReadFloor({ lane: PROVIDER, knob: config.sandboxReadFloor, ...(config.logger !== undefined ? { logger: config.logger } : {}) });
+        this.capabilities = capabilitiesFor({ remoteExec: { provider: PROVIDER }, sandboxReadFloor: config.sandboxReadFloor });
+    }
+    capabilities;
+    floor;
+    startIn(start, command, envs) {
+        const launch = this.floor.wrap(start);
+        return launch.ok ? ok(e2bFloorCommand(launch.value, command, envs)) : launch;
+    }
+    runIn(sbx, s, opts = {}) {
+        const { background, ...rest } = opts;
+        const o = { ...rest, ...(s.user !== undefined ? { user: s.user } : {}), ...(s.envs !== undefined ? { envs: s.envs } : {}) };
+        return background ? sbx.commands.run(s.cmd, { ...o, background: true }) : sbx.commands.run(s.cmd, o);
+    }
+    floorTransport(sbx) {
+        const bootstrap = async (command) => {
+            const s = this.startIn(BOOTSTRAP_START, command, undefined);
+            if (!s.ok)
+                return { ok: false, error: s.error.message };
+            try {
+                const r = await this.rpc("floor.bootstrap", (signal) => this.runIn(sbx, s.value, { signal, timeoutMs: this.cfg.rpcTimeoutMs }));
+                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) };
+            }
+        };
+        return {
+            bootstrap,
+            place: async (dest, bytes) => {
+                const dir = path.posix.dirname(dest);
+                const tmp = `${dest}.${Math.random().toString(16).slice(2, 10)}`;
+                const mk = await bootstrap(`umask 022 && mkdir -p ${shellQuote(dir)}`);
+                if (!mk.ok || mk.exitCode !== 0)
+                    return { ok: false, error: mk.ok ? mk.stderr.trim() || `exit ${mk.exitCode}` : mk.error };
+                try {
+                    const ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+                    await this.rpc("files.write", (signal) => sbx.files.write(tmp, ab, { user: "root", signal }), undefined, this.cfg.dataTimeoutMs);
+                }
+                catch (e) {
+                    return { ok: false, error: errMsg(e) };
+                }
+                const mv = await bootstrap(`chmod 0755 ${shellQuote(tmp)} && mv -f ${shellQuote(tmp)} ${shellQuote(dest)}`);
+                return mv.ok && mv.exitCode === 0 ? { ok: true } : { ok: false, error: mv.ok ? mv.stderr.trim() || `exit ${mv.exitCode}` : mv.error };
+            },
+            openRelay: (identity, command, events) => {
+                let handle;
+                let closed = false;
+                const pending = [];
+                const user = (() => {
+                    switch (identity) {
+                        case "root":
+                            return { user: "root" };
+                        case "exec-user":
+                            return {};
+                    }
+                })();
+                sbx.commands
+                    .run(command, { background: true, stdin: true, timeoutMs: 0, ...user, onStdout: (d) => events.data(d) })
+                    .then((h) => {
+                    handle = h;
+                    if (closed)
+                        return void h.kill().catch(() => { });
+                    for (const line of pending.splice(0))
+                        void h.sendStdin(line).catch(() => { });
+                    h.wait().then(() => events.closed("relay exited"), (e) => events.closed(`relay exited: ${errMsg(e)}`));
+                }, (e) => events.closed(`relay start failed: ${errMsg(e)}`));
+                return {
+                    send: (line) => {
+                        if (handle !== undefined)
+                            void handle.sendStdin(line).catch(() => { });
+                        else
+                            pending.push(line);
+                    },
+                    close: () => {
+                        closed = true;
+                        void handle?.kill().catch(() => { });
+                    },
+                };
+            },
+        };
     }
-    capabilities = capabilitiesFor({ remoteExec: { provider: "e2b" } });
     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();
@@ -66,8 +146,12 @@ export class RemoteContainerExecutionEnv {
     }
     async startBackground(command) {
         const conn = await this.ensureConnected();
-        if (conn.ok)
-            await conn.value.commands.run(command, { background: true });
+        if (!conn.ok)
+            return;
+        const s = this.startIn(engineStart(undefined), command, undefined);
+        if (!s.ok)
+            return void this.cfg.logger?.warn?.("remote_env_background_refused", { error: s.error.message });
+        await this.runIn(conn.value, s.value, { background: true });
     }
     async connect(config) {
         if (config?.snapshotId) {
@@ -75,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;
     }
@@ -109,6 +194,19 @@ export class RemoteContainerExecutionEnv {
                 this.cfg.metrics?.inc("remote_env_connect_total", { provider: PROVIDER, result: "error" });
                 return { ok: false, error: home ?? new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
             }
+            await this.floor.attach(this.floorTransport(sbx), { origin: "created", workspaceRoot: this.cfg.mountPath });
+            if (this.destroyed) {
+                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();
@@ -158,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 {
@@ -180,6 +308,12 @@ export class RemoteContainerExecutionEnv {
                 await sbx.kill().catch(() => { });
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
             }
+            const restoredRoot = options?.priorHandle?.mountPath ?? this.cfg.mountPath;
+            await this.floor.attach(this.floorTransport(sbx), { origin: "resumed", workspaceRoot: restoredRoot });
+            if (this.destroyed) {
+                await sbx.kill().catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
+            }
             const home = await this.homeVerdict(sbx, options?.abortSignal);
             if (this.destroyed) {
                 await sbx.kill().catch(() => { });
@@ -190,11 +324,22 @@ 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();
             this.cfg.logger?.info?.("remote_env_resume", { requested: snapshotId, connected: sbx.sandboxId });
-            const restoredRoot = options?.priorHandle?.mountPath ?? this.cfg.mountPath;
             this.cwd = restoredRoot;
             this.handle = { sandboxId: sbx.sandboxId, provider: PROVIDER, mountPath: restoredRoot, snapshotId, sessionToken: sbx.sandboxId };
             this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "ok" });
@@ -227,7 +372,10 @@ export class RemoteContainerExecutionEnv {
             return undefined;
         let probe;
         try {
-            const r = await this.rpc("sandbox.home", (s) => sbx.commands.run(LANE_HOME_PROBE_COMMAND, { signal: s }), signal);
+            const start = this.startIn(ADAPTER_START, LANE_HOME_PROBE_COMMAND, undefined);
+            if (!start.ok)
+                throw start.error;
+            const r = await this.rpc("sandbox.home", (s) => this.runIn(sbx, start.value, { signal: s }), signal);
             probe = r.exitCode === 0 ? { ok: true, stdout: r.stdout } : { ok: false, reason: `exit ${r.exitCode}` };
         }
         catch (e) {
@@ -240,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));
@@ -265,6 +443,7 @@ export class RemoteContainerExecutionEnv {
         this.destroyed = true;
         this.connecting = undefined;
         this.stopKeepAlive();
+        this.floor.dispose();
         await this.disposeBackgroundShells();
         const sbx = this.sbx;
         this.sbx = undefined;
@@ -285,12 +464,21 @@ export class RemoteContainerExecutionEnv {
         await this.destroy();
     }
     async exec(command, options) {
+        return this.execAs(engineStart(options?.readFloor), command, options);
+    }
+    execInternal(command, options) {
+        return this.execAs(ADAPTER_START, command, options);
+    }
+    async execAs(start, command, options) {
         if (options?.abortSignal?.aborted)
             return { ok: false, error: new ExecutionError("aborted", "exec aborted before start") };
         const conn = await this.ensureConnected();
         if (!conn.ok)
             return { ok: false, error: new ExecutionError("shell_unavailable", `remote connect failed: ${conn.error.message}`, conn.error) };
         const sbx = conn.value;
+        const launch = this.startIn(start, command, options?.env);
+        if (!launch.ok)
+            return launch;
         this.activeCommands++;
         const detachSignal = options?.detachSignal;
         const tee = detachSignal
@@ -315,10 +503,9 @@ export class RemoteContainerExecutionEnv {
         let starting;
         let startCut = false;
         try {
-            handle = await this.rpc("commands.run", () => (starting = sbx.commands.run(command, {
+            handle = await this.rpc("commands.run", () => (starting = this.runIn(sbx, launch.value, {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
-                ...(options?.env ? { envs: options.env } : {}),
                 timeoutMs: tee
                     ? Math.max(this.commandTimeoutMs(options?.timeout), (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000)
                     : this.commandTimeoutMs(options?.timeout),
@@ -442,6 +629,9 @@ export class RemoteContainerExecutionEnv {
         if (!conn.ok)
             throw conn.error;
         const sbx = conn.value;
+        const launch = this.startIn(engineStart(undefined), command, options?.env);
+        if (!launch.ok)
+            throw new RemoteExecutionError("unsupported", launch.error.message, launch.error);
         const queue = [];
         let finished = false;
         let failure;
@@ -468,10 +658,9 @@ export class RemoteContainerExecutionEnv {
         let handle;
         let starting;
         try {
-            handle = await this.rpc("commands.run", () => (starting = sbx.commands.run(command, {
+            handle = await this.rpc("commands.run", () => (starting = this.runIn(sbx, launch.value, {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
-                ...(options?.env ? { envs: options.env } : {}),
                 timeoutMs: this.commandTimeoutMs(options?.timeout),
                 onStdout: (d) => push("stdout", d),
                 onStderr: (d) => push("stderr", d),
@@ -599,12 +788,14 @@ export class RemoteContainerExecutionEnv {
                 if (!conn.ok)
                     throw new Error(`remote connect failed: ${conn.error.message}`);
                 const sbx = conn.value;
+                const launch = self.startIn(engineStart(options?.readFloor), command, options?.env);
+                if (!launch.ok)
+                    throw launch.error;
                 const stdout = { tail: new RollingTailBuffer(), total: 0, cursor: 0 };
                 const stderr = { tail: new RollingTailBuffer(), total: 0, cursor: 0 };
-                const handle = await self.rpc("commands.run.bg", () => sbx.commands.run(command, {
+                const handle = await self.rpc("commands.run.bg", () => self.runIn(sbx, launch.value, {
                     background: true,
                     cwd: self.resolve(options?.cwd ?? self.cwd),
-                    ...(options?.env ? { envs: options.env } : {}),
                     timeoutMs: (ctx.bgTimeoutSec + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000,
                     onStdout: (d) => {
                         const b = Buffer.from(d, "utf8");
@@ -722,7 +913,7 @@ export class RemoteContainerExecutionEnv {
                     return { ok: false, error: this.fileError(e, dest, signal) };
                 }
             },
-            run: (cmd, signal) => this.exec(cmd, { cwd: "/", ...(signal !== undefined ? { abortSignal: signal } : {}) }),
+            run: (cmd, signal) => this.execInternal(cmd, { cwd: "/", ...(signal !== undefined ? { abortSignal: signal } : {}) }),
         };
     }
     async writeFile(p, content, abortSignal) {
@@ -764,7 +955,7 @@ export class RemoteContainerExecutionEnv {
     }
     async readLink(p, abortSignal) {
         const abs = this.resolve(p);
-        const r = await this.exec(`readlink -- ${shellQuote(abs)}`, { abortSignal });
+        const r = await this.execInternal(`readlink -- ${shellQuote(abs)}`, { abortSignal });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
         if (r.value.exitCode !== 0)
@@ -772,11 +963,11 @@ export class RemoteContainerExecutionEnv {
         return ok(r.value.stdout.trim());
     }
     async canonicalChain(p, abortSignal) {
-        return runSymlinkChain(this.resolve(p), (cmd) => this.exec(cmd, { abortSignal }));
+        return runSymlinkChain(this.resolve(p), (cmd) => this.execInternal(cmd, { abortSignal }));
     }
     async canonicalPath(p, abortSignal) {
         const abs = this.resolve(p);
-        const r = await this.exec(`realpath -- ${shellQuote(abs)}`, { abortSignal });
+        const r = await this.execInternal(`realpath -- ${shellQuote(abs)}`, { abortSignal });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
         if (r.value.exitCode !== 0) {
@@ -823,7 +1014,7 @@ export class RemoteContainerExecutionEnv {
         const abs = this.resolve(p);
         if (options?.recursive) {
             const flags = options.force ? "-rf" : "-r";
-            const r = await this.exec(`rm ${flags} -- ${shellQuote(abs)}`, { abortSignal: options.abortSignal });
+            const r = await this.execInternal(`rm ${flags} -- ${shellQuote(abs)}`, { abortSignal: options.abortSignal });
             if (!r.ok)
                 return { ok: false, error: fileErrorFromExec(r.error, abs) };
             if (r.value.exitCode !== 0)
@@ -842,14 +1033,14 @@ export class RemoteContainerExecutionEnv {
         }
     }
     async createTempDir(prefix = "tmp-", abortSignal) {
-        const r = await this.exec(`mktemp -d -t ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal });
+        const r = await this.execInternal(`mktemp -d -t ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal });
         return this.tempResult(r, "mktemp -d");
     }
     async createTempFile(options) {
         const prefix = options?.prefix ?? "";
         const suffix = options?.suffix ?? "";
         const suffixArg = suffix ? `--suffix=${shellQuote(suffix)} -t` : "-t";
-        const r = await this.exec(`mktemp ${suffixArg} ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal: options?.abortSignal });
+        const r = await this.execInternal(`mktemp ${suffixArg} ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal: options?.abortSignal });
         return this.tempResult(r, "mktemp");
     }
     resolve(p) {
@@ -1017,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

@@ -3,6 +3,8 @@ import { type SpaceCommitFence } from "../workspace-space-commit.js";
 import { type CacheMissMemory, type WorkspaceCacheCapability } from "../workspace-cache.js";
 import { type SandboxEgressGap, type SandboxIpv6 } from "../sandbox-egress-policy.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 BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
+import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
+import { type SandboxReadFloor } from "./sandbox-read-floor.js";
 import type { PodSpecPatch } from "./k8s-exec-protocol.js";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
@@ -121,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
@@ -162,11 +167,14 @@ export interface K8sEnvConfig extends LaneHomeConfig {
         readonly image: string;
         readonly origins: readonly string[];
     };
+    /** `SANDBOX_READ_FLOOR`(keep | off;缺席 ⇒ keep):本 pod 守不守读拒表的字节地板 = 读地板模块服务本车道 ∧ 本键不是 off(`sandbox-read-floor.ts`)。 */
+    sandboxReadFloor?: SandboxReadFloorKnob;
 }
 import { type SandboxSecretSeatKind, type SandboxSecretVerb } from "./k8s-exec-protocol.js";
 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;
@@ -179,6 +187,8 @@ export interface ExecSocket {
     on(event: "open" | "message" | "close" | "error", listener: (...args: unknown[]) => void): void;
     close(): void;
     terminate?(): void;
+    /** 写一帧(读地板中继的 stdin:首字节 = 通道 0)。只读的 exec 不用;没有它的套接字起不了中继(附着按 `relay_silent` 拒)。 */
+    send?(data: Buffer): void;
 }
 /**
  * Test seam ([ref] §9.3 fault-injection): inject the REST `request` and/or the exec-socket factory, so pod
@@ -199,6 +209,8 @@ export interface K8sEnvDeps {
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
     /** Worker-side object-store requests (the space pointer, listing, deletes). Default: global `fetch`. */
     fetch?: typeof fetch;
+    /** 这只环境手里的读地板模块(缺席 ⇒ `createSandboxReadFloor` 按旋钮选;钉注入守地板的模块)。能力块的 `keepsReadFloor` 读它的状态。 */
+    readFloor?: SandboxReadFloor;
 }
 /**
  * One run's space occupant — the space key of both lanes keyed by it (the space lane, the cache volume) — a closed set of three
@@ -290,8 +302,10 @@ export type SandboxLeaseWrite = {
     readonly message: string;
 };
 export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
-    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。快照店是它的输入(构造期铸,见下)。 */
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。快照店与读地板旋钮是它的输入(构造期铸,见下);{@link floor} 由同一只判据、同一个旋钮值选出。 */
     readonly capabilities: ExecutionEnvCapabilities;
+    /** 读拒表字节地板模块:pod 里每一次 exec 起动都先经它的 `wrap`({@link runExec},唯一接缝)。 */
+    private readonly floor;
     cwd: string;
     private podName?;
     /** Cluster-internal pod address, captured when the pod reaches Running — the LSP `getHost` surface.
@@ -308,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
@@ -345,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). */
@@ -381,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. */
@@ -622,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
@@ -631,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
@@ -731,6 +767,15 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * being claimed) uploads nothing, and is that same upload failure.
      */
     private persistWorkspace;
+    /**
+     * 守地板的 pod 的二进制座:本包带的每个架构一只 ConfigMap(名 = 架构 + 摘要前 16 位,不可变;201 = 新建,409 = 同名同内容已在)。建不成
+     * ⇒ 告诉地板模块(附着按 `binary_digest` 拒,pod 照起、不带这只卷);不守地板 ⇒ `undefined`(pod 与改前逐字同)。部署前提:命名空间里 configmaps 的 create。
+     */
+    private ensureFloorSeat;
+    /** 地板模块的三件原语。引导命令经 {@link runExec}(起动形 `bootstrap`:只在附着中合法);放置由 pod 的只读卷完成(自检 `--digest` 证字节);
+     *  中继 = 一只开着 stdin 的长连 exec(与命令同一身份 —— k8s 的 exec 没有换身份的口),stdout 帧是中继的问,stdin 帧(首字节 0)是判官的答。 */
+    private floorTransport;
+    /** exec 的 URL:`argv` 原样作 `command` 参数(唯一来源 = {@link runExec} 里模块答案的编码,或地板模块自己的中继);`stdin` ⇒ 开 stdin 通道。 */
     private execUrl;
     /**
      * Run a command over the exec WebSocket. Frames: byte0=channel (1 stdout / 2 stderr / 3 status JSON with the