@sema-agent/server 7.146.0 → 7.148.0

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

@@ -2,8 +2,8 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
-import { randomBytes } from "node:crypto";
-import { shellQuote, armPipeDestroyGrace, appendFileStaged, writeFileStaged } from "./remote-shell.js";
+import { createHash, randomBytes } from "node:crypto";
+import { shellQuote, armPipeDestroyGrace, appendFileStaged, readyUpload, writeFileStaged } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { buildCapturedOutput, createCutError } from "../exec-cut.js";
@@ -16,6 +16,12 @@ const PROVIDER = "local-docker";
 const DEFAULT_MOUNT_PATH = "/workspace";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
 const DEFAULT_CONTROL_TIMEOUT_MS = 60_000;
+const INSPECT_ID_STATE_AND_LABELS = "{{.Id}}\t{{.State.Status}}\t{{json .Config.Labels}}";
+const DOCKER_STATES = ["created", "running", "paused", "restarting", "removing", "exited", "dead"];
+const NO_CUSTODY = Object.freeze({ kind: "none" });
+function isNameConflict(stderr, name) {
+    return stderr.includes(`The container name "/${name}" is already in use`);
+}
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
     ok: false,
@@ -33,12 +39,18 @@ export class RemoteLocalDockerExecutionEnv {
     cfg;
     spawnFn;
     containerName;
+    custody;
     containerId;
+    removedAny = false;
+    teardown;
+    teardownSettled = false;
     handle;
     destroyed = false;
     connecting;
     connectRefusal;
     homeSeat;
+    lifecycle = new AbortController();
+    capacityDeadline;
     constructor(config, deps = {}) {
         if (!config.image || !config.image.trim()) {
             config = { ...config, image: config.image ?? "" };
@@ -56,9 +68,21 @@ export class RemoteLocalDockerExecutionEnv {
         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}`;
+        this.containerName = localDockerContainerNameOf(config.workerLabel, config.id ?? randomBytes(6).toString("hex"));
+        this.custody = config.leftover ?? NO_CUSTODY;
+    }
+    get instance() {
+        return this.custody.kind === "held" ? this.custody.id : undefined;
+    }
+    get leftover() {
+        const c = this.custody;
+        return c.kind === "doomed" || c.kind === "doomed-unknown" ? c : undefined;
+    }
+    get releasing() {
+        return this.teardown;
+    }
+    get released() {
+        return this.teardownSettled;
     }
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
@@ -77,18 +101,142 @@ export class RemoteLocalDockerExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
         if (this.containerId)
             return ok(this.workspaceHandle());
+        return this.connectOnce(config, "start-or-attach");
+    }
+    async connectOnce(config, mode) {
         if (this.connecting)
             return this.connecting;
-        this.connecting = this.doConnect(config);
+        this.connecting = this.doConnect(config, mode);
         const r = await this.connecting;
         if (!r.ok)
             this.connecting = undefined;
         return r;
     }
-    async doConnect(config) {
-        if (!this.cfg.image.trim()) {
+    async doConnect(config, mode) {
+        if (mode === "start-or-attach" && !this.cfg.image.trim()) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", "local-docker: no base image configured (the image is required — no docker.io default)") };
         }
+        const owed = this.custody;
+        if (owed.kind === "doomed" && !(await this.removeInstance(owed.id)))
+            return this.stillOwed(owed.id);
+        let seen = await this.sightContainer(config?.abortSignal);
+        if (this.custody.kind === "doomed-unknown") {
+            switch (seen.kind) {
+                case "unreadable":
+                    return { ok: false, error: seen.error };
+                case "ours":
+                    if (!(await this.removeInstance(seen.id)))
+                        return this.stillOwed(seen.id);
+                    seen = { kind: "absent" };
+                    break;
+                case "absent":
+                    this.custody = NO_CUSTODY;
+                    this.cfg.capacity?.removed(this.containerName);
+                    break;
+                case "foreign":
+                    this.custody = NO_CUSTODY;
+                    break;
+            }
+        }
+        switch (seen.kind) {
+            case "unreadable":
+                return { ok: false, error: seen.error };
+            case "foreign":
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `a container named '${this.containerName}' exists on the docker daemon but this worker did not start it (it does not carry the label ${this.cfg.workerLabel}) — nothing was started or removed; remove or rename that container`) };
+            case "absent":
+                return mode === "attach-only" ? this.notResumable("gone") : this.startContainer(config);
+            case "ours":
+                switch (seen.state) {
+                    case "running":
+                        return this.attachContainer(seen.id, config?.abortSignal);
+                    case "exited": {
+                        const admitted = await this.admitStart(config);
+                        if (!admitted.ok)
+                            return admitted;
+                        this.custody = { kind: "held", id: seen.id };
+                        const started = await this.docker(["start", seen.id], { signal: config?.abortSignal, timeoutMs: this.cfg.controlTimeoutMs });
+                        admitted.ticket?.settle(this.startOutcomeOf(started));
+                        if (!started.ok)
+                            return { ok: false, error: this.dockerToRemoteError(started.error, "connect_failed") };
+                        if (started.value.exitCode !== 0)
+                            return { ok: false, error: new RemoteExecutionError("connect_failed", `container '${this.containerName}' of this worker is exited and docker start failed: ${started.value.stderr.trim() || `exit ${started.value.exitCode}`} — nothing was removed`) };
+                        return this.attachContainer(seen.id, config?.abortSignal);
+                    }
+                    case "created": {
+                        if (mode === "attach-only")
+                            return this.notResumable("created, never started");
+                        if (!(await this.removeInstance(seen.id))) {
+                            return { ok: false, error: new RemoteExecutionError("connect_failed", `container '${this.containerName}' of this worker was created but never started and could not be removed — nothing was started; remove it and retry`) };
+                        }
+                        return this.startContainer(config);
+                    }
+                    case "paused":
+                    case "restarting":
+                    case "removing":
+                    case "dead":
+                        return { ok: false, error: new RemoteExecutionError("connect_failed", `container '${this.containerName}' of this worker is ${seen.state} — it was neither attached nor removed (its workspace may still be there); resolve it with docker and retry`) };
+                    default: {
+                        const unhandled = seen.state;
+                        throw new Error(`local-docker: no ruling for container state ${String(unhandled)}`);
+                    }
+                }
+        }
+    }
+    stillOwed(id) {
+        return { ok: false, error: new RemoteExecutionError("connect_failed", `container ${id.slice(0, 12)} of this worker ('${this.containerName}') is due for removal and docker rm could not confirm it — it is never attached; nothing was started; remove it and retry`) };
+    }
+    notResumable(why) {
+        return { ok: false, error: new RemoteExecutionError("connect_failed", `container '${this.containerName}' is not running (${why}) — no managed snapshot to resume`) };
+    }
+    async sightContainer(signal) {
+        const r = await this.docker(["inspect", "--type", "container", "--format", INSPECT_ID_STATE_AND_LABELS, this.containerName], { signal, timeoutMs: this.cfg.controlTimeoutMs });
+        if (!r.ok)
+            return { kind: "unreadable", error: this.dockerToRemoteError(r.error, "connect_failed") };
+        if (r.value.exitCode !== 0) {
+            return /no such (object|container)/i.test(r.value.stderr)
+                ? { kind: "absent" }
+                : { kind: "unreadable", error: new RemoteExecutionError("connect_failed", `docker inspect of '${this.containerName}' failed: ${r.value.stderr.trim() || `exit ${r.value.exitCode}`}`) };
+        }
+        const line = r.value.stdout.trim();
+        const [id = "", state = "", ...rest] = line.split("\t");
+        let labels;
+        try {
+            labels = rest.length === 1 ? JSON.parse(rest[0]) : undefined;
+        }
+        catch {
+            labels = undefined;
+        }
+        const known = DOCKER_STATES.find((s) => s === state);
+        if (!/^[0-9a-f]{12,64}$/.test(id) || known === undefined || labels === undefined || (labels !== null && typeof labels !== "object")) {
+            return { kind: "unreadable", error: new RemoteExecutionError("connect_failed", `docker inspect of '${this.containerName}' answered a form this adapter does not read (${JSON.stringify(line.slice(0, 160))}) — nothing was started or removed`) };
+        }
+        const ours = labels !== null && Object.entries(labels).some(([k, v]) => `${k}=${String(v)}` === this.cfg.workerLabel);
+        return ours ? { kind: "ours", id, state: known } : { kind: "foreign" };
+    }
+    async attachContainer(id, signal) {
+        this.custody = { kind: "held", id };
+        if (this.homeSeat.asks && !(await this.untilOrAborted(this.probeContainerShell(), signal))) {
+            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while detecting the container's shell") };
+        }
+        const home = await this.homeVerdict(signal);
+        if (home !== undefined)
+            return { ok: false, error: home };
+        await this.floor.attach(this.floorTransport(), { origin: "resumed", workspaceRoot: this.cfg.mountPath });
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
+        const filled = await this.fillWorkspace("restored");
+        if (!filled.ok) {
+            if (filled.standing)
+                this.connectRefusal = filled.error;
+            return { ok: false, error: filled.error };
+        }
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
+        this.containerId = id;
+        this.handle = { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
+        return ok(this.handle);
+    }
+    async startContainer(config) {
         const pidsLimit = this.cfg.pidsLimit ?? 512;
         const runArgs = [
             "run",
@@ -96,6 +244,7 @@ export class RemoteLocalDockerExecutionEnv {
             "--init",
             "--name",
             this.containerName,
+            "--label", this.cfg.workerLabel,
             "-w",
             this.cfg.mountPath,
             "--security-opt",
@@ -110,48 +259,71 @@ export class RemoteLocalDockerExecutionEnv {
             "-c",
             `mkdir -p ${shellQuote(this.cfg.mountPath)} && exec tail -f /dev/null`,
         ];
+        const admitted = await this.admitStart(config);
+        if (!admitted.ok)
+            return admitted;
         const run = await this.docker(runArgs, { signal: config?.abortSignal, timeoutMs: this.cfg.controlTimeoutMs });
-        if (!run.ok) {
-            await this.forceRemove().catch(() => { });
-            return { ok: false, error: this.dockerToRemoteError(run.error, "connect_failed") };
-        }
-        if (run.value.exitCode !== 0) {
-            await this.forceRemove().catch(() => { });
-            return { ok: false, error: new RemoteExecutionError("connect_failed", `docker run failed: ${run.value.stderr.trim() || `exit ${run.value.exitCode}`}`) };
+        const outcome = this.startOutcomeOf(run);
+        admitted.ticket?.settle(outcome);
+        const id = run.ok && run.value.exitCode === 0 ? run.value.stdout.trim() : "";
+        if (id === "") {
+            if (outcome !== "absent")
+                await this.claimLeftoverOfThisStart();
+            const error = !run.ok ? this.dockerToRemoteError(run.error, "connect_failed") : new RemoteExecutionError("connect_failed", `docker run failed: ${run.value.stderr.trim() || (run.value.exitCode === 0 ? "it printed no container id" : `exit ${run.value.exitCode}`)}`);
+            return { ok: false, error };
         }
+        this.custody = { kind: "held", id };
         if (this.destroyed) {
-            await this.forceRemove().catch(() => { });
+            await this.removeInstance(id);
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         }
         if (this.homeSeat.asks && !(await this.untilOrAborted(this.probeContainerShell(), config?.abortSignal))) {
-            await this.forceRemove().catch(() => { });
+            await this.removeInstance(id);
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while detecting the container's shell") };
         }
         const home = await this.homeVerdict(config?.abortSignal);
         if (home !== undefined) {
-            await this.forceRemove().catch(() => { });
+            await this.removeInstance(id);
             return { ok: false, error: home };
         }
         await this.floor.attach(this.floorTransport(), { origin: "created", workspaceRoot: this.cfg.mountPath });
         if (this.destroyed) {
-            await this.forceRemove().catch(() => { });
+            await this.removeInstance(id);
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         }
-        const filled = await this.fillWorkspace();
+        const filled = await this.fillWorkspace("minted");
         if (!filled.ok || this.destroyed) {
-            await this.forceRemove().catch(() => { });
+            await this.removeInstance(id);
             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.containerId = id;
         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");
+    async admitStart(config) {
+        const capacity = this.cfg.capacity;
+        if (capacity === undefined)
+            return { ok: true };
+        this.capacityDeadline ??= Date.now() + this.cfg.controlTimeoutMs;
+        const signal = config?.abortSignal ? AbortSignal.any([config.abortSignal, this.lifecycle.signal]) : this.lifecycle.signal;
+        const admitted = await capacity.admit({ name: this.containerName, read: (budgetMs, readSignal) => this.readLaneRegistry(budgetMs, readSignal), deadline: this.capacityDeadline, readBoundMs: this.cfg.controlTimeoutMs, signal });
+        if (!admitted.ok)
+            return { ok: false, error: new RemoteExecutionError(admitted.refusal.verdict === "aborted" ? "aborted" : "connect_failed", admitted.refusal.message) };
+        return { ok: true, ticket: admitted.ticket };
+    }
+    startOutcomeOf(r) {
+        if (!r.ok)
+            return r.error.code === "spawn_error" ? "absent" : "unknown";
+        if (r.value.exitCode === 0)
+            return "present";
+        return isNameConflict(r.value.stderr, this.containerName) ? "absent" : "unknown";
+    }
+    fillWorkspace(origin) {
+        return this.cfg.workspaceFill === undefined ? Promise.resolve({ ok: true }) : this.cfg.workspaceFill.fill(this.fillChannel(), this.cfg.mountPath, origin);
     }
     fillChannel() {
         const run = async (command, input) => {
@@ -201,47 +373,100 @@ export class RemoteLocalDockerExecutionEnv {
         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}'`) };
         }
-        if (this.connecting !== undefined && this.containerId === undefined) {
-            const joined = await this.connecting;
-            if (!joined.ok || this.containerId !== undefined)
-                return joined;
-        }
-        const insp = await this.docker(["inspect", "-f", "{{.State.Running}}", this.containerName], { timeoutMs: this.cfg.controlTimeoutMs });
-        if (insp.ok && insp.value.exitCode === 0 && insp.value.stdout.trim() === "true") {
-            if (this.containerId === undefined && this.homeSeat.asks)
-                await this.probeContainerShell();
-            const home = this.containerId === undefined ? await this.homeVerdict() : undefined;
-            if (home !== undefined)
-                return { ok: false, error: home };
-            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);
-        }
-        return { ok: false, error: new RemoteExecutionError("connect_failed", `container '${this.containerName}' is not running (gone or stopped) — no managed snapshot to resume`) };
-    }
-    async destroy() {
-        if (this.destroyed)
-            return;
-        this.destroyed = true;
-        const inflight = this.connecting;
-        this.connecting = undefined;
-        this.containerId = undefined;
-        await inflight?.catch(() => { });
-        this.floor.dispose();
-        await this.forceRemove().catch(() => { });
+        if (this.containerId === undefined)
+            return this.connectOnce(undefined, "attach-only");
+        const seen = await this.sightContainer(undefined);
+        if (seen.kind === "ours" && seen.state === "running" && seen.id === this.containerId)
+            return ok(this.workspaceHandle());
+        if (seen.kind === "unreadable")
+            return { ok: false, error: seen.error };
+        return this.notResumable(seen.kind === "absent" ? "gone" : seen.kind === "foreign" ? "the name now holds a container this worker did not start" : seen.id !== this.containerId ? "the name now holds another container" : seen.state);
+    }
+    destroy() {
+        this.teardown ??= (async () => {
+            this.destroyed = true;
+            this.lifecycle.abort();
+            const inflight = this.connecting;
+            this.connecting = undefined;
+            this.containerId = undefined;
+            await inflight?.catch(() => { });
+            this.floor.dispose();
+            const owed = this.custody;
+            switch (owed.kind) {
+                case "held":
+                case "doomed":
+                    await this.removeInstance(owed.id);
+                    break;
+                case "doomed-unknown":
+                    await this.claimLeftoverOfThisStart();
+                    break;
+                case "none":
+                    break;
+            }
+        })().finally(() => {
+            this.teardownSettled = true;
+        });
+        return this.teardown;
     }
     async cleanup() {
         return this.destroy();
     }
-    async forceRemove() {
-        await this.docker(["rm", "-f", this.containerName], { timeoutMs: this.cfg.controlTimeoutMs }).catch(() => { });
+    async reapWorkspace() {
+        if (this.custody.kind === "none")
+            this.custody = { kind: "doomed-unknown" };
+        await this.destroy();
+        return this.leftover !== undefined ? "owed" : this.removedAny ? "removed" : "nothing";
+    }
+    async removeInstance(id) {
+        this.custody = { kind: "doomed", id };
+        const r = await this.docker(["rm", "-f", id], { timeoutMs: this.cfg.controlTimeoutMs }).catch(() => undefined);
+        const removed = r?.ok === true && (r.value.exitCode === 0 || /no such container/i.test(r.value.stderr));
+        if (r?.ok === true && r.value.exitCode === 0)
+            this.removedAny = true;
+        if (removed) {
+            this.cfg.capacity?.removed(this.containerName);
+            if (this.custody.kind === "doomed" && this.custody.id === id)
+                this.custody = NO_CUSTODY;
+        }
+        return removed;
+    }
+    async claimLeftoverOfThisStart() {
+        const seen = await this.sightContainer(undefined);
+        switch (seen.kind) {
+            case "ours":
+                await this.removeInstance(seen.id);
+                return;
+            case "absent":
+                this.custody = NO_CUSTODY;
+                this.cfg.capacity?.removed(this.containerName);
+                return;
+            case "foreign":
+                this.custody = NO_CUSTODY;
+                return;
+            case "unreadable":
+                this.custody = { kind: "doomed-unknown" };
+                return;
+        }
+    }
+    async readLaneRegistry(budgetMs, signal) {
+        const r = await this.docker(["ps", "-a", "--filter", `label=${this.cfg.workerLabel}`, "--format", "{{.Names}}\t{{.State}}"], { timeoutMs: Math.max(1, budgetMs), ...(signal !== undefined ? { signal } : {}) });
+        if (!r.ok)
+            return { ok: false, reason: r.error.message };
+        if (r.value.exitCode !== 0)
+            return { ok: false, reason: r.value.stderr.trim() || `exit ${r.value.exitCode}` };
+        const rows = r.value.stdout
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            const [name = "", state = ""] = line.split("\t");
+            return { name: name.trim(), state: state.trim().toLowerCase() };
+        });
+        return { ok: true, rows };
     }
     async exec(command, options) {
         if (options?.abortSignal?.aborted)
             return { ok: false, error: new ExecutionError("aborted", "exec aborted before start") };
-        const ready = await this.ensureConnectedExec();
+        const ready = await this.ensureConnectedExec(options?.abortSignal);
         if (!ready.ok)
             return ready;
         const execArgs = this.startArgv(engineStart(options?.readFloor), command, { cwd: options?.cwd, env: options?.env });
@@ -258,9 +483,9 @@ export class RemoteLocalDockerExecutionEnv {
         return ok({ stdout: r.value.stdout, stderr: r.value.stderr, exitCode: r.value.exitCode });
     }
     async *execStream(command, options) {
-        const ready = await this.ensureConnectedExec();
+        const ready = await this.ensureConnectedExec(options?.signal);
         if (!ready.ok)
-            throw new RemoteExecutionError("connect_failed", ready.error.message, ready.error);
+            throw new RemoteExecutionError(ready.error.code === "aborted" ? "aborted" : "connect_failed", ready.error.message, ready.error);
         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);
@@ -392,7 +617,7 @@ export class RemoteLocalDockerExecutionEnv {
         return ok(path.posix.join(...parts));
     }
     async readBinaryFile(p, abortSignal) {
-        const ready = await this.fsReady(p);
+        const ready = await this.fsReady(p, abortSignal);
         if (!ready.ok)
             return ready;
         const abs = this.resolve(p);
@@ -420,20 +645,20 @@ export class RemoteLocalDockerExecutionEnv {
         return ok(lines);
     }
     stagedLane(content) {
-        return { upload: (dest, signal) => this.pipeIn(content, dest, signal), run: (cmd, signal) => this.fsExec(cmd, signal) };
+        return { prepare: readyUpload((dest, signal) => this.pipeIn(content, dest, signal)), run: (cmd, signal) => this.fsExec(cmd, signal), provider: PROVIDER, logger: this.cfg.logger };
     }
     async writeFile(p, content, abortSignal) {
-        const ready = await this.fsReady(p);
+        const ready = await this.fsReady(p, abortSignal);
         if (!ready.ok)
             return ready;
         return writeFileStaged(this.stagedLane(content), this.resolve(p), abortSignal);
     }
     async appendFile(p, content, abortSignal) {
-        const ready = await this.fsReady(p);
+        const ready = await this.fsReady(p, abortSignal);
         if (!ready.ok)
             return ready;
         const abs = this.resolve(p);
-        return appendFileStaged(this.stagedLane(content), abs, abortSignal, (ctx) => ctx.inPlace((signal) => this.pipeIn(content, abs, signal, ">>")));
+        return appendFileStaged(this.stagedLane(content), abs, abortSignal, readyUpload((dest, signal) => this.pipeIn(content, dest, signal, ">>")));
     }
     async pipeIn(content, dest, abortSignal, redirect = ">") {
         const r = await this.fsExec(`cat ${redirect} ${shellQuote(dest)}`, abortSignal, typeof content === "string" ? Buffer.from(content, "utf8") : content);
@@ -455,7 +680,9 @@ export class RemoteLocalDockerExecutionEnv {
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
         if (!this.containerId) {
-            const c = await this.connect();
+            const c = await this.joinConnect(abortSignal);
+            if (!c.ok && c.error.code === "aborted" && abortSignal?.aborted)
+                return { ok: false, error: new ExecutionError("aborted", "exec aborted before start (file operation; the container was still connecting)", c.error) };
             if (!c.ok)
                 return { ok: false, error: new ExecutionError("shell_unavailable", `local-docker connect failed: ${c.error.message}`, c.error) };
         }
@@ -512,7 +739,9 @@ export class RemoteLocalDockerExecutionEnv {
             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]));
+        if (this.instance === undefined)
+            return { ok: false, error: new ExecutionError("shell_unavailable", "no container instance is held by this execution env") };
+        args.push(this.instance, ...floorArgv(launch.value, [o.shell ?? this.containerShell, "-c", command]));
         return ok(args);
     }
     floorTransport() {
@@ -538,7 +767,12 @@ export class RemoteLocalDockerExecutionEnv {
                 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 instance = this.instance;
+                if (instance === undefined) {
+                    queueMicrotask(() => events.closed("no container instance is held by this execution env"));
+                    return { send: () => { }, close: () => { } };
+                }
+                const args = ["exec", "-i", ...dockerIdentityFlags({ mode: "control", identity }), instance, "/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) => {
@@ -567,7 +801,14 @@ export class RemoteLocalDockerExecutionEnv {
         return new Promise((resolve) => {
             let settled = false;
             let forceSettleTimer;
-            const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: [opts?.input !== undefined ? "pipe" : "ignore", "pipe", "pipe"], env: this.cliEnv() });
+            let child;
+            try {
+                child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: [opts?.input !== undefined ? "pipe" : "ignore", "pipe", "pipe"], env: this.cliEnv() });
+            }
+            catch (e) {
+                resolve({ ok: false, error: new ExecutionError("spawn_error", `docker spawn failed (is '${this.cfg.dockerPath}' installed?): ${errMsg(e)}`, e instanceof Error ? e : undefined) });
+                return;
+            }
             const killGrace = () => {
                 try {
                     child.kill("SIGKILL");
@@ -635,6 +876,21 @@ export class RemoteLocalDockerExecutionEnv {
             });
         });
     }
+    joinConnect(signal) {
+        const shared = this.connect();
+        if (signal === undefined)
+            return shared;
+        if (signal.aborted)
+            return Promise.resolve({ ok: false, error: new RemoteExecutionError("aborted", "aborted while connecting") });
+        return new Promise((resolve) => {
+            const onAbort = () => resolve({ ok: false, error: new RemoteExecutionError("aborted", "aborted while connecting") });
+            signal.addEventListener("abort", onAbort, { once: true });
+            void shared.then((r) => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(r);
+            });
+        });
+    }
     containerShell = "/bin/sh";
     containerShellReady;
     async untilOrAborted(shared, signal) {
@@ -668,25 +924,27 @@ export class RemoteLocalDockerExecutionEnv {
         catch {
         }
     }
-    async ensureConnectedExec() {
+    async ensureConnectedExec(signal) {
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
         if (this.containerId) {
             await this.probeContainerShell();
             return ok(undefined);
         }
-        const c = await this.connect();
+        const c = await this.joinConnect(signal);
+        if (!c.ok && c.error.code === "aborted" && signal?.aborted)
+            return { ok: false, error: new ExecutionError("aborted", "exec aborted before start (the container was still connecting)", c.error) };
         if (!c.ok)
             return { ok: false, error: new ExecutionError("shell_unavailable", `local-docker connect failed: ${c.error.message}`, c.error) };
         await this.probeContainerShell();
         return ok(undefined);
     }
-    async fsReady(p) {
+    async fsReady(p, signal) {
         if (this.destroyed)
             return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
         if (this.containerId)
             return ok(undefined);
-        const c = await this.connect();
+        const c = await this.joinConnect(signal);
         if (!c.ok)
             return { ok: false, error: fileErrorFromExec(c.error, this.resolve(p)) };
         return ok(undefined);
@@ -702,14 +960,51 @@ export class RemoteLocalDockerExecutionEnv {
 function sanitizeId(id) {
     return id.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 48) || "task";
 }
+export function localDockerContainerNameOf(workerLabel, identity) {
+    const digest = createHash("sha256").update(workerLabel).update("\0").update(identity).digest("hex").slice(0, 12);
+    return `sema-docker-${sanitizeId(identity)}-${digest}`;
+}
+export function localDockerIdentityOfName(workerLabel, name) {
+    const m = /^sema-docker-(.+)-[0-9a-f]{12}$/.exec(name);
+    const candidate = m?.[1];
+    return candidate !== undefined && localDockerContainerNameOf(workerLabel, candidate) === name ? candidate : undefined;
+}
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
 export function localDockerExecutionEnvFactory(config, 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);
+    const live = new Map();
+    const envOf = async (identity, ctx) => {
+        sweep();
+        let leftover;
+        for (let held = live.get(identity); held !== undefined; held = live.get(identity)) {
+            const releasing = held.releasing;
+            if (releasing === undefined)
+                return held;
+            await releasing;
+            if (live.get(identity) === held) {
+                leftover = held.leftover;
+                live.delete(identity);
+            }
+        }
+        const workspaceFill = ctx !== undefined ? workspaceFillOf?.(ctx) : undefined;
+        const env = new RemoteLocalDockerExecutionEnv({ ...base, id: identity, ...(workspaceFill !== undefined ? { workspaceFill } : {}), ...(leftover !== undefined ? { leftover } : {}) }, deps);
+        live.set(identity, env);
+        return env;
+    };
+    const sweep = () => {
+        for (const [identity, env] of live)
+            if (env.released && env.leftover === undefined)
+                live.delete(identity);
+    };
+    let lister;
+    const reapPort = {
+        label: base.workerLabel,
+        list: () => (lister ??= new RemoteLocalDockerExecutionEnv({ ...base, id: "reaper-lister" }, deps)).readLaneRegistry(base.controlTimeoutMs ?? DEFAULT_CONTROL_TIMEOUT_MS, undefined),
+        identityOf: (name) => localDockerIdentityOfName(base.workerLabel, name),
+        settle: async (identity) => (await envOf(identity, undefined)).reapWorkspace(),
     };
+    return Object.assign((ctx) => envOf(ctx.taskId ?? ctx.sessionId, ctx), { reapPort });
 }
 //# sourceMappingURL=remote-env-local-docker.js.map