@sema-agent/server 7.140.0 → 7.142.0

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

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

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

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

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

@@ -2,7 +2,7 @@ import type { TaskStatus } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
-import { type ClaimFenced, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { type ClaimFenced, type CreateRunOutcome, type FencedRun, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } from "./store-contracts.js";
 import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
@@ -171,7 +171,7 @@ export declare class SqlRunStore {
     /**
      * 认领当写栅栏用(进程内两孪生的契约 = `store-contracts.ts` 的 `InProcessClaimFence`;本孪生是它的事务形):一个事务 ——
      *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
-     *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑;提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
+     *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑(另收锁住那一行的 {@link FencedRun});提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
      * 🔴 **取锁序 = task_run → task_active**,与 `setTerminal` / `reapStale` / `reapSuspended` 同序(它们先改 run 行、再删认领行):两行用两条语句按序锁,
      *    不用连表锁读(那一形的先后由计划器定,与终局 / 收割相反时两只事务各攥一行成环)。`createRun` 先锁根会话行再插认领行(本序从不碰 `session_meta`)、
      *    `deleteBySession` 先锁根会话行、见认领行在就中止,都不与本序成环。锁住之后:收割的改行 / 终局与收割的删认领 / 别人的建行都排在本事务之后,收割器提交后重判 `updated_at` 看到的是刚刷的。
@@ -180,7 +180,7 @@ export declare class SqlRunStore {
      * 🔴 **`write` 不许写 `session_meta`**:本事务持着 `task_active`,而 `createRun` 与改根行的写者都先锁根会话行再碰 `task_*`(全局锁序见 {@link createRun})——
      *    回调去锁根行就是反序,与等着本会话认领的 `createRun` 各攥一行成环。门:`test/submission-root-contract.test.ts` 扫每个调用点的回调体。
      */
-    whileHoldingClaim<T>(sessionId: string, taskId: string, write: (tx: SqlTxConn) => Promise<T>): Promise<ClaimFenced<T>>;
+    whileHoldingClaim<T>(sessionId: string, taskId: string, write: (tx: SqlTxConn, run: FencedRun) => Promise<T>): Promise<ClaimFenced<T>>;
     /** The active run's taskId for a session (the `task_active` claim) — lets resume find the suspended run row. */
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     /** Shared row→record mapper — byte-identical between dialects (both drivers hand back the same column
@@ -228,6 +228,14 @@ export declare class SqlRunStore {
      * 两方言只差占位符(动态子句为零,不像 listRuns/listSessions 那样需要各自的构造器臂)。
      */
     latestRunForSession(sessionId: string): Promise<LatestRunRef | undefined>;
+    /**
+     * [ref] —— 这个会话**最近一条已结腿**与它的记忆观测(规则属主 = `store-contracts.ts` 的 {@link SettledLegMemoryObservation};
+     * 文件 / 内存两店是它的孪生)。排序口径与 {@link latestRunForSession} 逐字同一句;已结词集按本文件头注的惯例写字面(两方言并排可读),
+     * 与属主谓词 `isTerminalRunStatus` 的同源由方言对 parity 门钉(`test/source-hygiene-gate.test.ts` 的语句规则 `settled-leg-observation-read`)。
+     * 同一条索引路径(`idx_task_run_session_status` 的 `(session_id, status)` 前缀),**不新加索引**。
+     * 结果列走 {@link rowToRun} 同一只解码口与同一个失败方向(读不出 ⇒ 拒,不把一条结了的腿读成「没有观测」)。
+     */
+    latestMemoryObservationForSession(sessionId: string): Promise<SettledLegMemoryObservation | undefined>;
     /** GET /v1/sessions (CC /resume picker): DISTINCT sessions newest-first by last activity, keyset-paginated on
      *  (last_activity, session_id). Aggregates task_run by session_id — one window pass picks the latest run per
      *  session (rn=1) for the preview/status and rolls up first/last/count. Owner-scoped when set (the per-user view).

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

@@ -6,7 +6,7 @@ import { pgSanitizeText } from "./pg-safe-json.js";
 import { toIso as iso } from "./sql-row-helpers.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonObjectColumn, readNonNullJsonValueColumn } from "./sql-json-column.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, readLegacyHolderDeathCode } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, readLegacyHolderDeathCode, settledLegObservationOf } from "./store-contracts.js";
 import { notifyRunTerminal, runTerminalLogLevel } from "../observability/run-terminal.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder, SQL_DB_NOW_MS, sqlDbNowMs } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
@@ -282,15 +282,16 @@ export class SqlRunStore {
     async whileHoldingClaim(sessionId, taskId, write) {
         let fenced = { held: false };
         await this.tx(async (conn) => {
-            const run = await conn.query(this.q("SELECT task_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
-            if (run.rows.length === 0)
+            const run = await conn.query(this.q("SELECT task_id, instance_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id, instance_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
+            const row = run.rows[0];
+            if (row === undefined)
                 return;
             const claim = await conn.query(this.q("SELECT task_id FROM task_active WHERE session_id = ? FOR UPDATE", "SELECT task_id FROM task_active WHERE session_id = $1 FOR UPDATE"), [sessionId]);
             const holder = claim.rows[0];
             if (holder === undefined || String(holder.task_id) !== taskId)
                 return;
             await conn.query(this.q("UPDATE task_run SET updated_at = ? WHERE task_id = ?", "UPDATE task_run SET updated_at = $1 WHERE task_id = $2"), [new Date(), taskId]);
-            fenced = { held: true, value: await write(conn) };
+            fenced = { held: true, value: await write(conn, { instanceId: row.instance_id ?? null }) };
         });
         return fenced;
     }
@@ -412,6 +413,14 @@ export class SqlRunStore {
         const r = rows[0];
         return r === undefined ? undefined : { taskId: String(r.task_id), owner: r.owner ?? null, createdAt: iso(r.created_at) };
     }
+    async latestMemoryObservationForSession(sessionId) {
+        const { rows } = await this.db.query(this.q("SELECT task_id, " + jsonColumnText("mysql", "result") + " FROM task_run WHERE session_id = ? AND status IN ('completed','failed','blocked') ORDER BY created_at DESC, task_id DESC LIMIT 1", "SELECT task_id, " + jsonColumnText("pg", "result") + " FROM task_run WHERE session_id = $1 AND status IN ('completed','failed','blocked') ORDER BY created_at DESC, task_id DESC LIMIT 1"), [sessionId]);
+        const r = rows[0];
+        if (r === undefined)
+            return undefined;
+        const taskId = String(r.task_id);
+        return settledLegObservationOf(taskId, refusing("read a settled leg as if it had observed no memory", () => decodeResultColumn(r.result, taskId)) ?? null);
+    }
     async listSessions(opts) {
         if (this.db.dialect === "mysql") {
             const params = [];