@sema-agent/server 7.139.0 → 7.141.0

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];
@@ -162,6 +164,8 @@ 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";
@@ -179,6 +183,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 +205,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,19 +298,10 @@ export type SandboxLeaseWrite = {
     readonly message: string;
 };
 export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
-    /**
-     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
-     * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,经 pod exec 解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
-     * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
-     * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
-     * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
-     * 布尔字面量零影响(四键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
-     * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
-     * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
-     */
-    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在沙箱 pod 自己的 PID 命名空间里(不开 hostPID),不在本进程所在的进程表。 */
-    /** 能力块(引擎 [ref],八键必填、各键只经引擎读器读):`hostLocalPaths` = 这条车道答出的路径是不是本进程所在机器上的文件;`externalContentTarget` = 产出是否来自部署信任边界之外;`io` = 文件与 shell 两面真到达目标;`keepsReadFloor` = 是否守住读拒表的字节地板(本车道不守 ⇒ 读拒表非空的 run 被告知,部署要求地板时准备期拒)。 */
+    /** 能力块的唯一作者 = `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.
@@ -327,9 +326,9 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  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
      *  the pod and it ended `Failed` before it ran — {@link createPod}). Neither goes away by asking again: the same request answers the same. */
     private connectRefusal?;
-    /** core `ExecutionEnv.homeDir`([ref]):pod 里执行用户的 home —— 声明胜,否则 pod 就绪那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时 pod 起来之前缺席)。 */
+    /** core `ExecutionEnv.homeDir`([ref]):pod 里执行用户的 home —— 声明在场 ⇒ 声明(开环境那一拍与 `$HOME` 对证过),否则 pod 就绪那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时 pod 起来之前缺席)。 */
     get homeDir(): string | undefined;
-    /** 家目录的座(声明胜 · 否则 pod 就绪那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证(与 local-docker / ssh 同一只判官、同一句拒)。 */
+    /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则 pod 就绪那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 pod 里(镜像与 pod spec 的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
@@ -742,6 +741,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

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

@@ -18,6 +18,8 @@ import { buildLivenessCut, commandBoundsOf, laneLivenessOf, LIVENESS_MS_DEFAULT
 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";
@@ -201,6 +203,7 @@ function brokerContainer(image) {
 }
 export class RemoteK8sExecutionEnv {
     capabilities;
+    floor;
     cwd;
     podName;
     podIP;
@@ -258,7 +261,7 @@ export class RemoteK8sExecutionEnv {
             ...(config.snapshotExclude && config.snapshotExclude.length > 0 ? { snapshotExclude: config.snapshotExclude } : {}),
         };
         this.cwd = this.cfg.mountPath;
-        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
+        this.homeSeat = new LaneHomeSeat(PROVIDER, config);
         this.deps = deps ?? {};
         this.laneLiveness = laneLivenessOf(this.cfg.livenessMs, "K8S_LIVENESS_MS");
         const occupant = occupantKeyOf(config.spaceOccupant);
@@ -268,7 +271,8 @@ export class RemoteK8sExecutionEnv {
         this.logger = config.logger;
         this.onWorkspaceSnapshot = config.onWorkspaceSnapshot;
         this.cacheMisses = config.cacheMisses;
-        this.capabilities = { isolation: true, suspendable: !!this.cfg.s3Snapshot, canonicalPathAuthoritative: true, sharesProcessTable: false, hostLocalPaths: false, externalContentTarget: false, io: true, keepsReadFloor: false };
+        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,
@@ -666,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",
@@ -690,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)] : []),
@@ -698,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 ?? []),
                 ]),
             },
         };
@@ -805,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;
@@ -824,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) {
@@ -1183,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)
@@ -1219,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
@@ -1325,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) {
@@ -1409,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) {
@@ -1462,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) {
@@ -1672,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;
@@ -1686,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,
@@ -1698,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,
@@ -1715,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);
@@ -1758,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,
@@ -1827,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();
@@ -1838,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) {
@@ -1858,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);
@@ -1873,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 {
@@ -1885,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 = () => {
@@ -1898,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);
             },
         };
     }
@@ -2012,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,28 +57,23 @@ 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 {
-    /** DUAL-MODE-DESIGN §5: a container is a real isolation boundary; v1 has no managed memory snapshot. */
-    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在本机容器自己的 PID 命名空间里(不传 `--pid=host`),不在本进程所在的进程表。 */
-    /** 能力块(引擎 [ref],八键必填、各键只经引擎读器读):`hostLocalPaths` = 这条车道答出的路径是不是本进程所在机器上的文件;`externalContentTarget` = 产出是否来自部署信任边界之外;`io` = 文件与 shell 两面真到达目标;`keepsReadFloor` = 是否守住读拒表的字节地板(本车道不守 ⇒ 读拒表非空的 run 被告知,部署要求地板时准备期拒)。 */
-    readonly capabilities: {
-        isolation: true;
-        suspendable: false;
-        canonicalPathAuthoritative: true;
-        sharesProcessTable: false;
-        hostLocalPaths: false;
-        externalContentTarget: false;
-        io: true;
-        keepsReadFloor: false;
-    };
+    /** 能力块的唯一作者 = `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`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    /** core `ExecutionEnv.homeDir`([ref]):本容器里执行用户的 home —— 声明在场 ⇒ 声明(开环境那一拍与 `$HOME` 对证过),否则开容器那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
     get homeDir(): string | undefined;
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在容器里(镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
@@ -97,7 +94,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     private connecting?;
     /** 家目录:环境答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。 */
     private homeRefusal?;
-    /** 家目录的座(声明胜 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
     constructor(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps);
     private resolve;
@@ -170,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 身份):传输中途断 / 取消时目标剩什么取决于守护进程的解包实现,本适配器不依赖它。 */
@@ -216,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). */