@sema-agent/server 7.140.0 → 7.141.0

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

@@ -19,6 +19,7 @@ import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { SANDBOX_IPV6_DEFAULT, sandboxEgressGaps, sandboxPodSysctls } from "../sandbox-egress-policy.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
+import { ADAPTER_START, BOOTSTRAP_START, buildFloorPodSeat, createSandboxReadFloor, FLOOR_K8S_CONFIGMAP_KEY, engineStart, floorArgv, } from "./sandbox-read-floor.js";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 import { randomUUID } from "node:crypto";
@@ -202,6 +203,7 @@ function brokerContainer(image) {
 }
 export class RemoteK8sExecutionEnv {
     capabilities;
+    floor;
     cwd;
     podName;
     podIP;
@@ -269,7 +271,8 @@ export class RemoteK8sExecutionEnv {
         this.logger = config.logger;
         this.onWorkspaceSnapshot = config.onWorkspaceSnapshot;
         this.cacheMisses = config.cacheMisses;
-        this.capabilities = capabilitiesFor({ remoteExec: { provider: PROVIDER, s3Snapshot: this.cfg.s3Snapshot } });
+        this.floor = this.deps.readFloor ?? createSandboxReadFloor({ lane: PROVIDER, knob: config.sandboxReadFloor, ...(config.logger !== undefined ? { logger: config.logger } : {}) });
+        this.capabilities = capabilitiesFor({ remoteExec: { provider: PROVIDER, s3Snapshot: this.cfg.s3Snapshot }, sandboxReadFloor: config.sandboxReadFloor });
         const bgMax = Math.max(1, Math.min(K8S_BG_MAX_TIMEOUT_SEC, Math.floor(this.cfg.timeoutMs / 1000)));
         this.backgroundCapabilities = {
             supported: true,
@@ -667,6 +670,8 @@ export class RemoteK8sExecutionEnv {
         ];
         const pkgSourceMarked = Boolean(this.cfg.podEnv?.SEMA_PKG_SOURCE || secretEnv.SEMA_PKG_SOURCE);
         const sysctls = sandboxPodSysctls(this.cfg.ipv6);
+        const floorSeat = await this.ensureFloorSeat(signal);
+        const mounts = [...(cache ? [{ name: CACHE_VOLUME, mountPath: cache.mount }] : []), ...(floorSeat?.mounts ?? [])];
         const pod = {
             apiVersion: "v1",
             kind: "Pod",
@@ -691,7 +696,7 @@ export class RemoteK8sExecutionEnv {
                             ? ["sh", "-c", "[ -f /opt/sema/pkg-source.sh ] && sh /opt/sema/pkg-source.sh || true; sleep infinity"]
                             : ["sh", "-c", "sleep infinity"],
                         ...(envEntries.length > 0 ? { env: envEntries } : {}),
-                        ...(cache ? { volumeMounts: [{ name: CACHE_VOLUME, mountPath: cache.mount }] } : {}),
+                        ...(mounts.length > 0 ? { volumeMounts: mounts } : {}),
                         resources: { limits: { cpu: this.cfg.cpu, memory: this.cfg.memory } },
                     },
                     ...(broker !== undefined ? [brokerContainer(broker.image)] : []),
@@ -699,6 +704,7 @@ export class RemoteK8sExecutionEnv {
                 ...((volumes) => (volumes.length > 0 ? { volumes } : {}))([
                     ...(cache ? [{ name: CACHE_VOLUME, persistentVolumeClaim: { claimName: cache.claim.name } }] : []),
                     ...(leaseName !== undefined ? [{ name: BROKER_VOLUME_NAME, secret: { secretName: leaseName, items: [{ key: BROKER_LEASE_KEY, path: BROKER_LEASE_KEY }], defaultMode: 0o400 } }] : []),
+                    ...(floorSeat?.volumes ?? []),
                 ]),
             },
         };
@@ -806,7 +812,7 @@ export class RemoteK8sExecutionEnv {
         this.podIP = podIP;
         this.leaseRef = leaseName !== undefined && broker !== undefined ? { namespace: ns, podName: name, leaseSecretName: leaseName, origins: [...broker.origins] } : undefined;
         const askHome = this.homeSeat.asks;
-        const mk = await this.runExec(`mkdir -p ${shellQuote(this.cfg.mountPath)}${askHome ? ` && { ${LANE_HOME_PROBE_COMMAND} || true; }` : ""}`);
+        const mk = await this.runExec(ADAPTER_START, `mkdir -p ${shellQuote(this.cfg.mountPath)}${askHome ? ` && { ${LANE_HOME_PROBE_COMMAND} || true; }` : ""}`);
         if (!mk.ok || mk.value.exitCode !== 0) {
             await this.deletePod(name).catch(() => { });
             this.podName = undefined;
@@ -825,6 +831,7 @@ export class RemoteK8sExecutionEnv {
         }
         if (cache?.fresh)
             this.logger?.warn("workspace_cache_fresh", { space: incarnationLogPrefix(cache.spaceKey), claim: cache.claim.name, size: cache.size });
+        await this.floor.attach(this.floorTransport(), { origin: "created", workspaceRoot: this.cfg.mountPath });
         return ok(this.workspaceHandle());
     }
     async createPodSecret(secretName, podName, podUid, values, signal) {
@@ -1184,7 +1191,7 @@ export class RemoteK8sExecutionEnv {
         const excludes = (this.cfg.snapshotExclude ?? []).map((item) => ` --exclude=${shellQuote(`./${item}`)}`).join("");
         const cmd = `tar czf ${tmp}${excludes} -C ${shellQuote(this.cfg.mountPath)} . && curl -fsS -X PUT -T ${tmp} ${shellQuote(url)}; ` +
             `rc=$?; rm -f ${tmp}; exit $rc`;
-        const r = await this.runExec(cmd, { timeoutMs: boundMs });
+        const r = await this.runExec(ADAPTER_START, cmd, { timeoutMs: boundMs });
         if (!r.ok)
             return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace snapshot upload failed: ${this.redactUrl(r.error.message, url)}`, r.error) };
         if (r.value.exitCode !== 0)
@@ -1220,7 +1227,7 @@ export class RemoteK8sExecutionEnv {
             const c = await this.provision(abortSignal);
             if (!c.ok)
                 return c;
-            const r = await this.runExec(cmd, { timeoutMs: this.cfg.dataTimeoutMs });
+            const r = await this.runExec(ADAPTER_START, cmd, { timeoutMs: this.cfg.dataTimeoutMs });
             const failure = !r.ok
                 ? { cls: r.error.code === "timeout" ? "timeout" : "transport", detail: `workspace snapshot restore failed: ${this.redactUrl(r.error.message, url)}`, cause: r.error }
                 : r.value.exitCode !== 0
@@ -1326,6 +1333,7 @@ export class RemoteK8sExecutionEnv {
     }
     async destroy() {
         await this.disposeBackgroundShells().catch(() => { });
+        this.floor.dispose();
         this.destroyed = true;
         const lane = this.spaceLane;
         switch (lane.state) {
@@ -1410,7 +1418,7 @@ export class RemoteK8sExecutionEnv {
     async killPodProcesses() {
         if (!this.podName)
             return false;
-        const r = await this.runExec(buildKillAllScript(), { timeoutMs: this.cfg.rpcTimeoutMs + KILL_ALL_RECHECK_MS });
+        const r = await this.runExec(ADAPTER_START, buildKillAllScript(), { timeoutMs: this.cfg.rpcTimeoutMs + KILL_ALL_RECHECK_MS });
         return r.ok && r.value.exitCode === 0;
     }
     async persistWorkspace(space) {
@@ -1463,23 +1471,124 @@ export class RemoteK8sExecutionEnv {
             await this.endSpace(space);
         }
     }
-    execUrl(command) {
+    async ensureFloorSeat(signal) {
+        const seat = buildFloorPodSeat(this.floor);
+        if (seat === undefined)
+            return undefined;
+        if (seat.configMaps.length === 0) {
+            this.floor.refusePlacement("this server carries no pinned supervisor build");
+            return undefined;
+        }
+        for (const cm of seat.configMaps) {
+            const body = { apiVersion: "v1", kind: "ConfigMap", metadata: { name: cm.name }, immutable: true, binaryData: { [FLOOR_K8S_CONFIGMAP_KEY]: cm.binaryDataB64 } };
+            let r;
+            try {
+                r = await this.request("POST", `/api/v1/namespaces/${this.cfg.namespace}/configmaps`, body, { signal });
+            }
+            catch (e) {
+                this.floor.refusePlacement(`creating the supervisor ConfigMap ${cm.name} failed: ${errorMessageOf(e)}`);
+                return undefined;
+            }
+            if (r.status !== 409 && (r.status < 200 || r.status >= 300)) {
+                this.floor.refusePlacement(`creating the supervisor ConfigMap ${cm.name} was answered ${r.status}${r.status === 401 || r.status === 403 ? " (the server's service account needs create on configmaps in this namespace)" : ""}`);
+                return undefined;
+            }
+        }
+        return seat;
+    }
+    floorTransport() {
+        return {
+            bootstrap: async (command) => {
+                const r = await this.runExec(BOOTSTRAP_START, command, { timeoutMs: this.cfg.rpcTimeoutMs });
+                return r.ok ? { ok: true, exitCode: r.value.exitCode, stdout: r.value.stdout, stderr: r.value.stderr } : { ok: false, error: r.error.message };
+            },
+            place: async () => ({ ok: true }),
+            openRelay: (identity, command, events) => {
+                let closed = false;
+                const close = (why) => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    events.closed(why);
+                };
+                switch (identity) {
+                    case "root":
+                        queueMicrotask(() => close("a k8s exec cannot start the relay as root"));
+                        return { send: () => { }, close: () => { } };
+                    case "exec-user":
+                        break;
+                }
+                let sock;
+                try {
+                    const { url, headers } = this.execUrl(["sh", "-c", command], true);
+                    sock = this.openExec(url, headers);
+                }
+                catch (e) {
+                    queueMicrotask(() => close(`the relay exec could not be opened: ${errorMessageOf(e)}`));
+                    return { send: () => { }, close: () => { } };
+                }
+                const decoder = new StringDecoder("utf8");
+                let open = false;
+                const pending = [];
+                const write = (frame) => {
+                    if (sock.send === undefined)
+                        return close("the exec socket cannot write (no stdin channel)");
+                    try {
+                        sock.send(frame);
+                    }
+                    catch (e) {
+                        close(`writing to the relay failed: ${errorMessageOf(e)}`);
+                    }
+                };
+                sock.on("open", () => {
+                    open = true;
+                    for (const f of pending.splice(0))
+                        write(f);
+                });
+                sock.on("message", (...args) => {
+                    const data = args[0];
+                    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+                    if (buf.length > 1 && buf[0] === 1)
+                        events.data(decoder.write(buf.subarray(1)));
+                });
+                sock.on("close", () => close("the relay exec closed"));
+                sock.on("error", (e) => close(`the relay exec failed: ${errorMessageOf(e)}`));
+                return {
+                    send: (line) => {
+                        const frame = Buffer.concat([Buffer.from([0]), Buffer.from(line, "utf8")]);
+                        if (open)
+                            write(frame);
+                        else
+                            pending.push(frame);
+                    },
+                    close: () => (sock.terminate ?? sock.close).call(sock),
+                };
+            },
+        };
+    }
+    execUrl(argv, stdin = false) {
         const { apiUrl, token } = this.creds();
         const base = apiUrl.replace(/^http/, "ws");
         const q = new URLSearchParams();
         q.append("container", "sandbox");
+        if (stdin)
+            q.append("stdin", "true");
         q.append("stdout", "true");
         q.append("stderr", "true");
-        for (const part of ["sh", "-c", command])
+        for (const part of argv)
             q.append("command", part);
         return { url: `${base}/api/v1/namespaces/${this.cfg.namespace}/pods/${this.podName}/exec?${q.toString()}`, headers: { authorization: `Bearer ${token}` } };
     }
-    runExec(command, opts) {
+    runExec(start, command, opts) {
+        const launch = this.floor.wrap(start);
+        if (!launch.ok)
+            return Promise.resolve(launch);
+        opts?.onLaunch?.(launch.value);
         let sock;
         let headers;
         let url;
         try {
-            ({ url, headers } = this.execUrl(command));
+            ({ url, headers } = this.execUrl(floorArgv(launch.value, ["sh", "-c", command])));
             sock = this.openExec(url, headers);
         }
         catch (e) {
@@ -1673,12 +1782,12 @@ export class RemoteK8sExecutionEnv {
         });
     }
     async exec(command, options) {
-        return this.execCall(createCwdGuardedCall("k8s", command, this.workingDirOf(options?.cwd), options?.env), options);
+        return this.execCall(engineStart(options?.readFloor), createCwdGuardedCall("k8s", command, this.workingDirOf(options?.cwd), options?.env), options);
     }
     fsExec(command, abortSignal) {
-        return this.execCall(createCwdGuardedCall("k8s", command, undefined, undefined), { abortSignal });
+        return this.execCall(ADAPTER_START, createCwdGuardedCall("k8s", command, undefined, undefined), { abortSignal });
     }
-    async execCall(call, options) {
+    async execCall(start, call, options) {
         const c = await this.ensureConnected();
         if (!c.ok)
             return c;
@@ -1687,7 +1796,7 @@ export class RemoteK8sExecutionEnv {
         const abortSignal = options?.abortSignal ? AbortSignal.any([options.abortSignal, inflight.signal]) : inflight.signal;
         try {
             if (!detachSignal) {
-                return call.settle(await this.runExec(call.command, {
+                return call.settle(await this.runExec(start, call.command, {
                     signal: abortSignal,
                     timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined,
                     boundOutput: true,
@@ -1699,7 +1808,10 @@ export class RemoteK8sExecutionEnv {
             const adoptId = randomUUID();
             const dir = `${K8S_BG_DIR_ROOT}/exec-${adoptId}`;
             const tee = { out: seedMemStream(""), err: seedMemStream("") };
-            return call.settle(await this.runExec(buildDetachCapableExec(dir, call.command), {
+            let startId;
+            let adoptedHere = false;
+            const settled = call.settle(await this.runExec(start.kind === "engine" ? engineStart(start.readFloor, true) : start, buildDetachCapableExec(dir, call.command), {
+                onLaunch: (l) => void (startId = l.mode === "run" ? l.startId : undefined),
                 signal: abortSignal,
                 timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined,
                 boundOutput: true,
@@ -1716,12 +1828,17 @@ export class RemoteK8sExecutionEnv {
                                 data: (channel, payload) => feedMemStream(channel === 1 ? mem.out : mem.err, payload, K8S_BG_MEM_CAP),
                                 closed: (terminal) => ctx.onTerminal(terminal.failed, terminal.exitCode),
                             });
-                            return { jobId: adoptId, dir, stdoutCursor: 0, stderrCursor: 0, adopt: { mem, sock: io.sock } };
+                            return { jobId: adoptId, dir, stdoutCursor: 0, stderrCursor: 0, adopt: { mem, sock: io.sock }, ...(startId !== undefined ? { startId } : {}) };
                         });
+                        if (adopted !== undefined)
+                            adoptedHere = true;
                         return adopted?.shellId;
                     },
                 },
             }));
+            if (!adoptedHere)
+                this.floor.release(startId);
+            return settled;
         }
         finally {
             this.endExec(inflight);
@@ -1759,7 +1876,7 @@ export class RemoteK8sExecutionEnv {
         const cap = options?.maxOutputBytes;
         let bytes = 0;
         const signal = options?.signal ? AbortSignal.any([options.signal, ac.signal]) : ac.signal;
-        const done = this.runExec(buildCwdEnvCommand(command, this.workingDirOf(options?.cwd), options?.env, "raw").command, {
+        const done = this.runExec(engineStart(undefined), buildCwdEnvCommand(command, this.workingDirOf(options?.cwd), options?.env, "raw").command, {
             signal,
             timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined,
             readTimeoutMs: options?.readTimeoutMs,
@@ -1828,7 +1945,8 @@ export class RemoteK8sExecutionEnv {
     }
     makeBgDriver() {
         const self = this;
-        const bgExec = (script, boundOutput) => self.runExec(script, { timeoutMs: self.cfg.rpcTimeoutMs, boundOutput });
+        const bgExec = (start, script, boundOutput, onLaunch) => self.runExec(start, script, { timeoutMs: self.cfg.rpcTimeoutMs, boundOutput, ...(onLaunch !== undefined ? { onLaunch } : {}) });
+        const under = (state) => ({ kind: "under", startId: state.startId });
         return {
             async launch(command, options, ctx) {
                 const conn = await self.ensureConnected();
@@ -1839,14 +1957,17 @@ export class RemoteK8sExecutionEnv {
                 const inner = buildCwdEnvCommand(command, self.workingDirOf(options?.cwd), options?.env, "raw").command;
                 const cmdB64 = Buffer.from(inner, "utf8").toString("base64");
                 const runnerB64 = Buffer.from(buildBgRunnerScript(dir), "utf8").toString("base64");
-                const r = await bgExec(buildBgLauncherScript(dir, cmdB64, runnerB64), true);
+                let startId;
+                const r = await bgExec(engineStart(options?.readFloor, true), buildBgLauncherScript(dir, cmdB64, runnerB64), true, (l) => void (startId = l.mode === "run" ? l.startId : undefined));
+                if (!r.ok || r.value.exitCode !== 0 || !r.value.stdout.includes("SEMABG_LAUNCHED"))
+                    self.floor.release(startId);
                 if (!r.ok)
                     throw new Error(`background launch failed: ${r.error.message}`);
                 if (r.value.exitCode !== 0 || !r.value.stdout.includes("SEMABG_LAUNCHED")) {
                     throw new Error(`background launch exited ${r.value.exitCode}: ${r.value.stderr.slice(0, 200)}`);
                 }
                 void ctx;
-                return { jobId, dir, stdoutCursor: 0, stderrCursor: 0 };
+                return { jobId, dir, stdoutCursor: 0, stderrCursor: 0, ...(startId !== undefined ? { startId } : {}) };
             },
             async read(state) {
                 if (state.adopt) {
@@ -1859,7 +1980,7 @@ export class RemoteK8sExecutionEnv {
                         bytesDroppedBeforeCursor: o.dropped + e.dropped,
                     };
                 }
-                const r = await bgExec(buildBgPollScript(state.dir, state.stdoutCursor, state.stderrCursor, K8S_BG_READ_CAP), false);
+                const r = await bgExec(under(state), buildBgPollScript(state.dir, state.stdoutCursor, state.stderrCursor, K8S_BG_READ_CAP), false);
                 if (!r.ok)
                     throw new Error(`background poll failed: ${r.error.message}`);
                 const p = parseBgPollOutput(r.value.stdout);
@@ -1874,7 +1995,7 @@ export class RemoteK8sExecutionEnv {
                 state.stderrCursor = p.errTotal;
                 let terminal = p.exitCode !== undefined ? { failed: false, exitCode: p.exitCode } : !p.alive ? { failed: true } : undefined;
                 if (!terminal && (p.outTotal > K8S_BG_FILE_CAP || p.errTotal > K8S_BG_FILE_CAP)) {
-                    void bgExec(buildBgKillScript(state.dir), true).catch(() => { });
+                    void bgExec(under(state), buildBgKillScript(state.dir), true).catch(() => { });
                     terminal = { failed: true };
                 }
                 return {
@@ -1886,7 +2007,7 @@ export class RemoteK8sExecutionEnv {
                 };
             },
             async kill(state) {
-                await bgExec(buildBgKillScript(state.dir), true).catch(() => { });
+                await bgExec(under(state), buildBgKillScript(state.dir), true).catch(() => { });
             },
             async disposeOne(state) {
                 const closeAdopted = () => {
@@ -1899,10 +2020,12 @@ export class RemoteK8sExecutionEnv {
                 };
                 if (self.destroyed) {
                     closeAdopted();
+                    self.floor.release(state.startId);
                     return;
                 }
-                await bgExec(buildBgDisposeScript(state.dir), true).catch(() => { });
+                await bgExec(under(state), buildBgDisposeScript(state.dir), true).catch(() => { });
                 closeAdopted();
+                self.floor.release(state.startId);
             },
         };
     }
@@ -2013,7 +2136,7 @@ export class RemoteK8sExecutionEnv {
         const c = await this.ensureConnected();
         if (!c.ok)
             return c;
-        return this.runExec(command, { signal: abortSignal, capMs: this.cfg.dataTimeoutMs });
+        return this.runExec(ADAPTER_START, command, { signal: abortSignal, capMs: this.cfg.dataTimeoutMs });
     }
     workingDirOf(cwd) {
         const dir = cwd ?? this.cwd;

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

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 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 } from "@sema-agent/core";
+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";
 /** 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}. */
@@ -55,14 +57,20 @@ export interface LocalDockerEnvConfig extends LaneHomeConfig {
     /** Stable id mixed into the container NAME (e.g. the sessionId). A random suffix is always appended so two
      *  envs sharing an id never collide. Default = a random id. */
     id?: string;
+    /** `SANDBOX_READ_FLOOR`(keep | off;缺席 ⇒ keep):本容器守不守读拒表的字节地板 = 读地板模块服务本车道 ∧ 本键不是 off(`sandbox-read-floor.ts`)。 */
+    sandboxReadFloor?: SandboxReadFloorKnob;
 }
 /** Inject `spawn` for tests (a fake docker CLI). Defaults to node's child_process spawn. */
 export interface LocalDockerEnvDeps {
     spawn?: typeof spawn;
+    /** 这只环境手里的读地板模块(缺席 ⇒ `createSandboxReadFloor` 按旋钮选;钉注入守地板的模块)。能力块的 `keepsReadFloor` 读它的状态。 */
+    readFloor?: SandboxReadFloor;
 }
 export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv {
-    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
-    readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。读地板旋钮是它的输入,{@link floor} 由同一只判据、同一个旋钮值选出。 */
+    readonly capabilities: ExecutionEnvCapabilities;
+    /** 读拒表字节地板模块:容器里每一次 `docker exec` 起动都先经它的 `wrap`({@link startArgv},唯一接缝)。 */
+    private readonly floor;
     /** Working directory inside the container; relative paths resolve against it (ExecutionEnv contract). */
     cwd: string;
     /** core `ExecutionEnv.homeDir`([ref]):本容器里执行用户的 home —— 声明在场 ⇒ 声明(开环境那一拍与 `$HOME` 对证过),否则开容器那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
@@ -159,7 +167,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     }): Promise<Result<string[], FileError>>;
     /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;父目录与私有暂存目录由编排的准备那一步建):
      *  上传 = 容器内 `cat` 从 stdin 收整份字节落到私有目录里的暂存件({@link pipeIn});提交 = 容器内一次 shell 往返。两者同一身份 ——
-     *  同一只 argv 构造({@link execArgv}),都是镜像的用户。不用 `docker cp`:它由守护进程以 root 落盘,镜像用户 ≠ root 时暂存件属 root、
+     *  同一只 argv 构造({@link startArgv}),都是镜像的用户。不用 `docker cp`:它由守护进程以 root 落盘,镜像用户 ≠ root 时暂存件属 root、
      *  提交方拿不走也清不掉,「目录不收新名字」也探不出来(root 哪里都写得进)。 */
     private stagedLane;
     /** 整旧或整新(暂存 → 一次 `mv -f`)。修前 `docker cp` 直落目标(以守护进程的 root 身份):传输中途断 / 取消时目标剩什么取决于守护进程的解包实现,本适配器不依赖它。 */
@@ -205,17 +213,23 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     /**
      * 交给宿主 `docker` CLI 的 env —— 宿主子进程 env 的唯一组合(`server-secret-env.ts` `hostSubprocessEnv`),继承词 `"all"`:本服务自有凭据(起服声明的名与值)
      * 任何词都不交,CLI 与它拉起的凭据助手 / CLI 插件要读的变量(`DOCKER_*` / `AWS_*` …)照交 —— 形状剥会剥 `AWS_SECRET_ACCESS_KEY` 一类,ECR / GCR 凭据助手因此断。
-     * 命令本身跑在容器里,容器的 env 只由 `execArgv` 的 `-e K=V` 显式给,本 env 到不了容器。每次起进程现算一次(与 host shell 同)。
+     * 命令本身跑在容器里,容器的 env 只由 `startArgv` 的 `-e K=V` 显式给,本 env 到不了容器。每次起进程现算一次(与 host shell 同)。
      */
     private cliEnv;
     /** Prepend `-H <dockerHost>` to a docker argv when configured (per-invocation, not the process env). */
     private withHostFlag;
-    /** Build the `docker exec` argv for a command, applying cwd (`-w`) and per-command env (`-e K=V`).
-     *  argv elements are SEPARATE (no host-side shell join) — the command runs in the CONTAINER's `/bin/sh -c`.
-     *  `stdin` ⇒ `-i` (the payload of {@link pipeIn}); nothing else differs, so a piped upload runs as the same user as every other exec. */
-    private execArgv;
-    /** Like {@link execArgv} but for an internal FileSystem helper command (uses the workspace cwd + adapter env). */
-    private execRaw;
+    /**
+     * **唯一起动接缝**:容器里的每一次 `docker exec` 起动(引擎的命令、文件面助手、探针、地板的引导命令)都从这里拿 argv —— 先问地板模块
+     * `wrap(起动形)`,再按答案编码(身份旗标 + 监督者命令行头;不守地板 ⇒ 与改前逐字同)。本适配器对地板零判断;模块拒 ⇒ `spawn_error`,命令从未起。
+     * argv elements are SEPARATE (no host-side shell join) — the command runs in the CONTAINER's shell (`-c`). `stdin` ⇒ `-i` (the payload of
+     * {@link pipeIn}); nothing else differs, so a piped upload runs as the same user as every other exec. cwd (`-w`) and per-command env (`-e K=V`;
+     * adapter base env under, per-command wins) — except `containerDefaults`: the command asks about the container's OWN defaults (the shell probe),
+     * so it carries neither (the bare argv is then `exec <name> <shell> -c <cmd>`, byte-identical to the pre-floor probe).
+     */
+    private startArgv;
+    /** 地板模块的三件原语(引导命令 / 放置 / 中继)。引导与放置经 {@link startArgv}(起动形 `bootstrap`:只在附着中合法);中继以模块给的身份起一只
+     *  长连的 `docker exec -i`(stdin / stdout 作双工),随本环境 `destroy` 由模块关。 */
+    private floorTransport;
     /** Spawn the docker binary with argv; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private docker;
     /** Lazy connect for an exec path → ExecutionError on failure (fail closed, never throws). */

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

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