@sema-agent/server 7.130.0 → 7.132.0

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

@@ -11,7 +11,7 @@ import { spaceCommitAlive } from "../workspace-space-commit.js";
 import { incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
 import { WORKSPACE_CACHE_SPACE_LABEL, workspaceCacheClaimOf, workspaceCacheEnv } from "../workspace-cache.js";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { commandBoundsOf, laneLivenessOf, livenessCutMessage, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
+import { buildLivenessCut, commandBoundsOf, laneLivenessOf, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
 import { SANDBOX_IPV6_DEFAULT, sandboxEgressGaps, sandboxPodSysctls } from "../sandbox-egress-policy.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
@@ -26,8 +26,8 @@ const K8S_BG_MAX_TIMEOUT_SEC = numEnvOr("K8S_BG_MAX_TIMEOUT_SEC", 1800, K8S_BG_D
 const K8S_BG_READ_CAP = numEnvOr("K8S_BG_READ_CAP", 1024 * 1024, 64 * 1024);
 const K8S_BG_FILE_CAP = numEnvOr("K8S_BG_FILE_CAP", 64 * 1024 * 1024, K8S_BG_READ_CAP);
 const K8S_BG_MEM_CAP = numEnvOr("K8S_BG_MEM_CAP", 8 * 1024 * 1024, 64 * 1024);
-import { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, parseBgPollOutput, } from "./k8s-bg-scripts.js";
-export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, parseBgPollOutput, } from "./k8s-bg-scripts.js";
+import { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, buildKillAllScript, KILL_ALL_RECHECK_MS, parseBgPollOutput, } from "./k8s-bg-scripts.js";
+export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, buildKillAllScript, parseBgPollOutput, } from "./k8s-bg-scripts.js";
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
     ok: false,
@@ -116,6 +116,45 @@ class FenceCallAborted extends Error {
 function dataTimeoutMsOf(config) {
     return config.dataTimeoutMs ?? WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT;
 }
+const RPC_TIMEOUT_MS_DEFAULT = 30_000;
+export function rpcTimeoutMsOf(config) {
+    return config.rpcTimeoutMs ?? RPC_TIMEOUT_MS_DEFAULT;
+}
+export function boundedStoreCall(op, bound) {
+    const signal = bound.abort?.signal;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(bound.abort.error());
+        const settle = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            settle();
+            reject(bound.abort.error());
+        };
+        const timer = setTimeout(() => {
+            settle();
+            reject(bound.onTimeout());
+        }, bound.ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        let pending;
+        try {
+            pending = op();
+        }
+        catch (e) {
+            settle();
+            return reject(e);
+        }
+        pending.then((v) => {
+            settle();
+            resolve(v);
+        }, (e) => {
+            settle();
+            reject(e);
+        });
+    });
+}
 import { execSocketTlsOptions, exitCodeFromStatus } from "./k8s-exec-protocol.js";
 export { execSocketTlsOptions } from "./k8s-exec-protocol.js";
 export function errorMessageOf(e) {
@@ -134,9 +173,10 @@ export class RemoteK8sExecutionEnv {
     podIP;
     destroyed = false;
     handleSnapshotId;
-    inFlightExecs = 0;
-    connectPromise;
-    restoreRefusal;
+    inFlight = new Set();
+    idleWaiters = [];
+    connectInFlight;
+    connectRefusal;
     homeDir;
     cdPath = "unknown";
     cfg;
@@ -150,6 +190,7 @@ export class RemoteK8sExecutionEnv {
     cacheUnavailableSaid = false;
     logger;
     onWorkspaceSnapshot;
+    cacheMisses;
     constructor(config, deps) {
         this.cfg = {
             apiUrl: config.apiUrl,
@@ -162,7 +203,7 @@ export class RemoteK8sExecutionEnv {
             mountPath: config.mountPath ?? K8S_WORKSPACE_MOUNT_DEFAULT,
             timeoutMs: config.timeoutMs ?? 30 * 60_000,
             readyTimeoutMs: config.readyTimeoutMs ?? 120_000,
-            rpcTimeoutMs: config.rpcTimeoutMs ?? 30_000,
+            rpcTimeoutMs: rpcTimeoutMsOf(config),
             livenessMs: config.livenessMs ?? LIVENESS_MS_DEFAULT,
             dataTimeoutMs: dataTimeoutMsOf(config),
             cpu: config.cpu ?? "1",
@@ -185,6 +226,7 @@ export class RemoteK8sExecutionEnv {
         this.cacheLane = cacheLaneOf(config.cache, config.spaceOccupant);
         this.logger = config.logger;
         this.onWorkspaceSnapshot = config.onWorkspaceSnapshot;
+        this.cacheMisses = config.cacheMisses;
         this.capabilities = { isolation: true, suspendable: !!this.cfg.s3Snapshot, canonicalPathAuthoritative: true };
         const bgMax = Math.max(1, Math.min(K8S_BG_MAX_TIMEOUT_SEC, Math.floor(this.cfg.timeoutMs / 1000)));
         this.backgroundCapabilities = {
@@ -283,7 +325,15 @@ export class RemoteK8sExecutionEnv {
             ...(url.startsWith("wss:") ? execSocketTlsOptions(ca, this.cfg.insecureTls) : {}),
         });
     }
-    async connect(config) {
+    connect(config) {
+        this.connectInFlight ??= this.establish(config).finally(() => {
+            this.connectInFlight = undefined;
+        });
+        return this.connectInFlight;
+    }
+    async establish(config) {
+        if (this.connectRefusal)
+            return this.connectRefusal;
         const signal = config?.abortSignal;
         const lane = this.spaceLane;
         switch (lane.state) {
@@ -295,8 +345,6 @@ export class RemoteK8sExecutionEnv {
             case "unreadable":
                 return this.provision(signal);
             case "open": {
-                if (this.restoreRefusal)
-                    return this.restoreRefusal;
                 const settled = await this.awaitSpaceCommit(lane.space, signal);
                 if (!settled.ok)
                     return settled;
@@ -322,27 +370,10 @@ export class RemoteK8sExecutionEnv {
         await this.fenceCall(() => space.fence.end(), "delete").catch(() => undefined);
     }
     fenceCall(op, what, signal) {
-        return new Promise((resolve, reject) => {
-            if (signal?.aborted)
-                return reject(new FenceCallAborted());
-            const onAbort = () => {
-                clearTimeout(timer);
-                reject(new FenceCallAborted());
-            };
-            const timer = setTimeout(() => {
-                signal?.removeEventListener("abort", onAbort);
-                reject(new Error(`workspace space commit state ${what} did not answer within ${this.cfg.rpcTimeoutMs}ms`));
-            }, this.cfg.rpcTimeoutMs);
-            signal?.addEventListener("abort", onAbort, { once: true });
-            op().then((v) => {
-                clearTimeout(timer);
-                signal?.removeEventListener("abort", onAbort);
-                resolve(v);
-            }, (e) => {
-                clearTimeout(timer);
-                signal?.removeEventListener("abort", onAbort);
-                reject(e);
-            });
+        return boundedStoreCall(op, {
+            ms: this.cfg.rpcTimeoutMs,
+            onTimeout: () => new Error(`workspace space commit state ${what} did not answer within ${this.cfg.rpcTimeoutMs}ms`),
+            ...(signal ? { abort: { signal, error: () => new FenceCallAborted() } } : {}),
         });
     }
     sayUnavailable(reason) {
@@ -355,6 +386,21 @@ export class RemoteK8sExecutionEnv {
             effect: "WORKSPACE_PERSIST=space, but the session store has no occupant (incarnation) for this run's session — its /workspace is neither restored nor saved (it is never keyed by the session id instead)",
         });
     }
+    holdRefusal(error) {
+        this.connectRefusal = { ok: false, error };
+        return this.connectRefusal;
+    }
+    refusePod(pod, phase, reason, message) {
+        this.logger?.warn("sandbox_pod_refused", {
+            pod,
+            phase,
+            reason: reason ?? "?",
+            ...(message ? { detail: message.slice(0, 300) } : {}),
+            ...(this.cfg.sessionId ? { sessionId: this.cfg.sessionId } : {}),
+            effect: "the cluster created this run's sandbox pod and it ended before it ran — this run's operations answer the same refusal without creating another pod; a retry of the run builds a fresh sandbox",
+        });
+        return this.holdRefusal(new RemoteExecutionError("connect_failed", `pod entered ${phase} before Running (${reason ?? "?"}) — the cluster refused this run's sandbox pod; the refusal stands for the run (no pod is created again), a retry of the run asks the cluster afresh`));
+    }
     refuseUnreadableOccupant(code) {
         const ways = [...(this.spaceLane.state === "unreadable" ? ["WORKSPACE_PERSIST=off"] : []), ...(this.cacheLane.state === "unreadable" ? ["WORKSPACE_CACHE=off"] : [])].join(" and ");
         if (!this.unreadableOccupantSaid) {
@@ -374,6 +420,8 @@ export class RemoteK8sExecutionEnv {
     provision(signal) {
         const space = this.spaceLane;
         const cache = this.cacheLane;
+        if (this.connectRefusal)
+            return Promise.resolve(this.connectRefusal);
         if (space.state === "unreadable")
             return Promise.resolve(this.refuseUnreadableOccupant(space.code));
         if (cache.state === "unreadable")
@@ -384,19 +432,23 @@ export class RemoteK8sExecutionEnv {
             backoffMs: (failed) => this.cfg.retry.backoffMs * failed,
         };
         const once = this.deps.connectOnce ?? ((s) => this.connectOnce(cache, s));
-        return withRetry(() => once(signal), policy, { signal });
+        const refused = new AbortController();
+        const halt = signal ? AbortSignal.any([signal, refused.signal]) : refused.signal;
+        return withRetry(async () => {
+            const r = await once(signal);
+            if (!r.ok && this.connectRefusal)
+                refused.abort();
+            return r;
+        }, policy, { signal: halt });
     }
     async ensureConnected() {
-        if (this.podName)
-            return ok(undefined);
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "k8s sandbox destroyed") };
-        this.connectPromise ??= this.connect();
-        const r = await this.connectPromise;
-        if (!r.ok) {
-            this.connectPromise = undefined;
+        if (this.podName && this.connectInFlight === undefined)
+            return ok(undefined);
+        const r = await this.connect();
+        if (!r.ok)
             return { ok: false, error: new ExecutionError("shell_unavailable", `k8s sandbox connect failed: ${r.error.message}`, r.error) };
-        }
         return ok(undefined);
     }
     async connectOnce(cacheLane, signal) {
@@ -409,6 +461,8 @@ export class RemoteK8sExecutionEnv {
         if (!("cacheMiss" in first))
             return first;
         this.cacheUnavailable(first.cacheMiss, first.detail, cache);
+        if (cache)
+            this.cacheMisses?.remember(cache.spaceKey, { reason: first.cacheMiss, detail: first.detail }, this.cfg.dataTimeoutMs);
         const second = await this.createPod(signal, undefined);
         return "cacheMiss" in second ? { ok: false, error: new RemoteExecutionError("connect_failed", "unreachable: a pod without the cache volume was given up for it") } : second;
     }
@@ -420,6 +474,11 @@ export class RemoteK8sExecutionEnv {
                 this.cacheUnavailable(lane.reason, "the session store has no occupant (incarnation) for this run's session — no space key to find its cache volume by (never keyed by the session id instead)");
                 return undefined;
             case "open": {
+                const remembered = this.cacheMisses?.recall(lane.cache.spaceKey);
+                if (remembered !== undefined) {
+                    this.cacheUnavailable(remembered.reason, `${remembered.detail} — remembered from an earlier run of this space; not asked for again within ${this.cfg.dataTimeoutMs}ms`, lane.cache);
+                    return undefined;
+                }
                 const ensured = await this.ensureCacheClaim(lane.cache, signal);
                 if (!ensured.ok) {
                     this.cacheUnavailable("claim_failed", ensured.detail, lane.cache);
@@ -586,7 +645,7 @@ export class RemoteK8sExecutionEnv {
             }
             if (phase === "Failed" || phase === "Succeeded") {
                 await this.deletePod(name).catch(() => { });
-                return { ok: false, error: new RemoteExecutionError("connect_failed", `pod entered ${phase} before Running (${status?.reason ?? "?"})`) };
+                return this.refusePod(name, phase, status?.reason, status?.message);
             }
             const waiting = status?.containerStatuses?.[0]?.state?.waiting;
             if (waiting?.reason === "ImagePullBackOff" || waiting?.reason === "ErrImagePull") {
@@ -864,8 +923,8 @@ export class RemoteK8sExecutionEnv {
             await this.endSpace(this.spaceLane.space);
         return r;
     }
-    async uploadSnapshot(target) {
-        if (this.inFlightExecs > 0)
+    async uploadSnapshot(target, boundMs = this.cfg.dataTimeoutMs) {
+        if (target.lane === "park" && this.inFlight.size > 0)
             return { ok: false, error: new RemoteExecutionError("command_in_flight", "cannot suspend while a command is in flight (would snapshot a torn workspace)") };
         const snapshotId = mintSnapshotId(this.occupantIncarnation);
         if (!this.podName)
@@ -878,7 +937,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: this.cfg.dataTimeoutMs });
+        const r = await this.runExec(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)
@@ -941,13 +1000,9 @@ export class RemoteK8sExecutionEnv {
                 case "space": {
                     const tries = attempt === 1 ? "1 attempt" : `${attempt} attempts`;
                     this.spaceLine("workspace_restore_failed", target.space, { snapshotId, class: failure.cls, attempts: attempt, boundMs: this.cfg.dataTimeoutMs, error: failure.detail });
-                    this.restoreRefusal = {
-                        ok: false,
-                        error: new RemoteExecutionError("connect_failed", `${failure.detail} — the workspace's latest snapshot (${snapshotId}) is in the store but did not come back (${failure.cls}, ${tries}, bound ${this.cfg.dataTimeoutMs}ms each), ` +
-                            "so this run does not start on an empty /workspace. Ways out: raise WORKSPACE_SNAPSHOT_TIMEOUT_MS if the archive is large, " +
-                            "or set WORKSPACE_PERSIST=off for one run (it starts from an empty /workspace and deletes no snapshot)", failure.cause),
-                    };
-                    return this.restoreRefusal;
+                    return this.holdRefusal(new RemoteExecutionError("connect_failed", `${failure.detail} — the workspace's latest snapshot (${snapshotId}) is in the store but did not come back (${failure.cls}, ${tries}, bound ${this.cfg.dataTimeoutMs}ms each), ` +
+                        "so this run does not start on an empty /workspace. Ways out: raise WORKSPACE_SNAPSHOT_TIMEOUT_MS if the archive is large, " +
+                        "or set WORKSPACE_PERSIST=off for one run (it starts from an empty /workspace and deletes no snapshot)", failure.cause));
                 }
                 default: {
                     const unreachable = target;
@@ -987,6 +1042,8 @@ export class RemoteK8sExecutionEnv {
         return ok(undefined);
     }
     async reconnect(_sessionToken) {
+        if (this.connectInFlight)
+            return this.connectInFlight;
         if (this.podName) {
             const alive = await this.request("GET", `/api/v1/namespaces/${this.cfg.namespace}/pods/${this.podName}`).catch(() => undefined);
             const phase = alive?.json?.status?.phase;
@@ -1032,6 +1089,63 @@ export class RemoteK8sExecutionEnv {
     async cleanup() {
         return this.destroy();
     }
+    beginExec() {
+        const ac = new AbortController();
+        this.inFlight.add(ac);
+        return ac;
+    }
+    endExec(ac) {
+        this.inFlight.delete(ac);
+        if (this.inFlight.size > 0)
+            return;
+        for (const wake of this.idleWaiters.splice(0))
+            wake();
+    }
+    whenIdle(ms) {
+        if (this.inFlight.size === 0)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const idle = () => {
+                clearTimeout(timer);
+                resolve(true);
+            };
+            const timer = setTimeout(() => {
+                this.idleWaiters = this.idleWaiters.filter((w) => w !== idle);
+                resolve(false);
+            }, ms);
+            this.idleWaiters.push(idle);
+        });
+    }
+    async quiesce(space) {
+        const inFlight = this.inFlight.size;
+        if (inFlight === 0 && !this.podName)
+            return { ok: true, waitedMs: 0 };
+        const startedAt = Date.now();
+        const ended = await this.whenIdle(this.cfg.rpcTimeoutMs);
+        const killed = await this.killPodProcesses();
+        for (const ac of [...this.inFlight])
+            ac.abort();
+        const waitedMs = Date.now() - startedAt;
+        if (!ended) {
+            this.spaceLine("workspace_snapshot_commands_cut", space, {
+                inFlight,
+                waitedMs,
+                killed,
+                effect: killed
+                    ? "the run is over but its commands were still running after the wait — their processes were killed (the sandbox is deleted right after) so the run-end snapshot reads a still tree; the workspace is saved as it stood"
+                    : "the run is over but its commands were still running after the wait and the pod's processes could not be confirmed stopped — the workspace is NOT saved (it may still be changing); `latest` keeps naming the previous snapshot",
+            });
+        }
+        return killed
+            ? { ok: true, waitedMs }
+            : { ok: false, error: new RemoteExecutionError("command_in_flight", "the pod's processes could not be confirmed stopped when the run ended — not saving a workspace that may still be changing") };
+    }
+    async killPodProcesses() {
+        if (!this.podName)
+            return false;
+        const r = await this.runExec(buildKillAllScript(), { timeoutMs: this.cfg.rpcTimeoutMs + KILL_ALL_RECHECK_MS });
+        return r.ok && r.value.exitCode === 0;
+    }
     async persistWorkspace(space) {
         const failed = (stage, error) => {
             this.spaceLine("workspace_snapshot_failed", space, { stage, code: error.code, error: error.message });
@@ -1052,7 +1166,10 @@ export class RemoteK8sExecutionEnv {
         try {
             let snap;
             try {
-                snap = await this.uploadSnapshot({ lane: "space", space });
+                const quiet = await this.quiesce(space);
+                if (!quiet.ok)
+                    return failed("upload", quiet.error);
+                snap = await this.uploadSnapshot({ lane: "space", space }, Math.max(1, this.cfg.dataTimeoutMs - quiet.waitedMs));
             }
             catch (e) {
                 return failed("upload", new RemoteExecutionError("unknown", errorMessageOf(e)));
@@ -1142,7 +1259,8 @@ export class RemoteK8sExecutionEnv {
                 clearTimeout(livenessTimer);
                 const idle = Date.now() - lastProgress;
                 if (idle >= liveness.ms) {
-                    finish({ ok: false, error: new ExecutionError("timeout", livenessCutMessage(liveness)) });
+                    const cut = buildLivenessCut(liveness);
+                    finish({ ok: false, error: new ExecutionError(cut.code, cut.message, undefined, undefined, cut.noOutputSec) });
                     return;
                 }
                 livenessTimer = setTimeout(armLiveness, liveness.ms - idle);
@@ -1276,11 +1394,12 @@ export class RemoteK8sExecutionEnv {
         if (!c.ok)
             return c;
         const detachSignal = options?.detachSignal;
-        this.inFlightExecs++;
+        const inflight = this.beginExec();
+        const abortSignal = options?.abortSignal ? AbortSignal.any([options.abortSignal, inflight.signal]) : inflight.signal;
         try {
             if (!detachSignal) {
                 return call.settle(await this.runExec(call.command, {
-                    signal: options?.abortSignal,
+                    signal: abortSignal,
                     timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined,
                     boundOutput: true,
                     onStdout: options?.onStdout,
@@ -1292,7 +1411,7 @@ export class RemoteK8sExecutionEnv {
             const dir = `${K8S_BG_DIR_ROOT}/exec-${adoptId}`;
             const tee = { out: seedMemStream(""), err: seedMemStream("") };
             return call.settle(await this.runExec(buildDetachCapableExec(dir, call.command), {
-                signal: options?.abortSignal,
+                signal: abortSignal,
                 timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined,
                 boundOutput: true,
                 onStdout: options?.onStdout,
@@ -1316,7 +1435,7 @@ export class RemoteK8sExecutionEnv {
             }));
         }
         finally {
-            this.inFlightExecs--;
+            this.endExec(inflight);
         }
     }
     async getHost(port) {
@@ -1337,7 +1456,7 @@ export class RemoteK8sExecutionEnv {
         const c = await this.ensureConnected();
         if (!c.ok)
             throw new RemoteExecutionError("connect_failed", c.error.message, c.error);
-        this.inFlightExecs++;
+        const ac = this.beginExec();
         const queue = [];
         let finished = false;
         let failure;
@@ -1350,7 +1469,6 @@ export class RemoteK8sExecutionEnv {
         };
         const cap = options?.maxOutputBytes;
         let bytes = 0;
-        const ac = new AbortController();
         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, {
             signal,
@@ -1375,9 +1493,11 @@ export class RemoteK8sExecutionEnv {
                         ? "transport_lost"
                         : r.error.code === "timeout"
                             ? "timeout"
-                            : r.error.code === "spawn_error" || r.error.code === "shell_unavailable"
-                                ? "unknown"
-                                : "connect_failed";
+                            : r.error.code === "liveness_no_output"
+                                ? "liveness_no_output"
+                                : r.error.code === "spawn_error" || r.error.code === "shell_unavailable"
+                                    ? "unknown"
+                                    : "connect_failed";
                 failure = new RemoteExecutionError(code, r.error.message, r.error);
             }
             finished = true;
@@ -1409,7 +1529,7 @@ export class RemoteK8sExecutionEnv {
         finally {
             ac.abort();
             await done.catch(() => { });
-            this.inFlightExecs--;
+            this.endExec(ac);
         }
     }
     backgroundCapabilities;
@@ -1626,42 +1746,97 @@ export class RemoteK8sExecutionEnv {
         return dir ? this.resolve(dir) : undefined;
     }
 }
+const SPACE_RECLAIM_CONCURRENCY = 4;
+function createGate(limit) {
+    let active = 0;
+    const waiting = [];
+    const release = () => {
+        const next = waiting.shift();
+        if (next)
+            next();
+        else
+            active--;
+    };
+    return async (task) => {
+        if (active < limit)
+            active++;
+        else
+            await new Promise((resolve) => waiting.push(resolve));
+        try {
+            return await task();
+        }
+        finally {
+            release();
+        }
+    };
+}
+function tallyFailure(classes, key, at, pos, sample) {
+    const seen = classes.get(key);
+    if (seen === undefined)
+        classes.set(key, { count: 1, at, pos, sample });
+    else {
+        seen.count++;
+        if (at < seen.at || (at === seen.at && pos < seen.pos)) {
+            seen.at = at;
+            seen.pos = pos;
+            seen.sample = sample;
+        }
+    }
+}
+function failureClassesInOrder(classes) {
+    return [...classes.values()].sort((a, b) => a.at - b.at || a.pos - b.pos);
+}
 export function createSpaceReclaimer(config, deps) {
+    const gate = createGate(SPACE_RECLAIM_CONCURRENCY);
     return {
         async reclaim(spaces) {
             const deadline = AbortSignal.timeout(dataTimeoutMsOf(config));
-            for (const { sessionId, spaceKey } of spaces) {
-                if (spaceKey === "")
-                    continue;
-                const env = new RemoteK8sExecutionEnv({ ...config, sessionId }, deps);
-                if (config.cache !== undefined) {
-                    const r = await env.reclaimSpaceCache(spaceKey, deadline).catch((e) => ({ ok: false, reason: "delete_failed", detail: errorMessageOf(e) }));
-                    if (!r.ok) {
-                        recordFailOpen("server.workspace-cache.reclaim-failed", `reason=${r.reason} label=${workspaceCacheClaimOf(spaceKey).label}`);
-                        config.logger?.warn("workspace_cache_reclaim_failed", {
-                            reason: r.reason,
-                            space: incarnationLogPrefix(spaceKey),
-                            label: workspaceCacheClaimOf(spaceKey).label,
-                            error: redactIncarnations(r.detail),
-                            effect: `the ended space's cache volume stays — delete it by label ${WORKSPACE_CACHE_SPACE_LABEL}=<label> (the deletion it belongs to went ahead)`,
-                        });
+            const volumeFailures = new Map();
+            const objectFailures = new Map();
+            const settled = await Promise.allSettled(spaces.map(({ sessionId, spaceKey }, at) => spaceKey === ""
+                ? Promise.resolve()
+                : gate(async () => {
+                    const env = new RemoteK8sExecutionEnv({ ...config, sessionId }, deps);
+                    if (config.cache !== undefined) {
+                        const r = await env.reclaimSpaceCache(spaceKey, deadline).catch((e) => ({ ok: false, reason: "delete_failed", detail: errorMessageOf(e) }));
+                        if (!r.ok) {
+                            recordFailOpen("server.workspace-cache.reclaim-failed", `reason=${r.reason} label=${workspaceCacheClaimOf(spaceKey).label}`);
+                            tallyFailure(volumeFailures, r.reason, at, 0, { spaceKey, failure: r });
+                        }
                     }
-                }
-                if (config.s3Snapshot !== undefined) {
-                    const failures = await env.reclaimSpaceSnapshots(spaceKey, deadline).catch((e) => [{ lane: "space", stage: "delete", detail: errorMessageOf(e) }]);
-                    for (const f of failures) {
-                        recordFailOpen("server.workspace-space.reclaim-failed", `lane=${f.lane} stage=${f.stage}`);
-                        config.logger?.warn("workspace_space_reclaim_failed", {
-                            space: incarnationLogPrefix(spaceKey),
-                            sessionId,
-                            lane: f.lane,
-                            stage: f.stage,
-                            error: redactIncarnations(f.detail),
-                            effect: `the ended space's ${f.lane === "space" ? "workspace snapshots" : "park snapshots"} may stay in the bucket (unreadable through the API; the bucket's lifecycle rule is the fallback) — the deletion it belongs to went ahead`,
+                    if (config.s3Snapshot !== undefined) {
+                        const failures = await env.reclaimSpaceSnapshots(spaceKey, deadline).catch((e) => [{ lane: "space", stage: "delete", detail: errorMessageOf(e) }]);
+                        failures.forEach((f, pos) => {
+                            recordFailOpen("server.workspace-space.reclaim-failed", `lane=${f.lane} stage=${f.stage}`);
+                            tallyFailure(objectFailures, `${f.lane}/${f.stage}`, at, pos, { sessionId, spaceKey, failure: f });
                         });
                     }
-                }
+                })));
+            for (const { count, sample } of failureClassesInOrder(volumeFailures)) {
+                config.logger?.warn("workspace_cache_reclaim_failed", {
+                    reason: sample.failure.reason,
+                    count,
+                    space: incarnationLogPrefix(sample.spaceKey),
+                    label: workspaceCacheClaimOf(sample.spaceKey).label,
+                    error: redactIncarnations(sample.failure.detail),
+                    effect: `the ended space's cache volume stays — delete it by label ${WORKSPACE_CACHE_SPACE_LABEL}=<label> (the deletion it belongs to went ahead)${count > 1 ? `; ${count} spaces of this call met the same failure, the line names the first` : ""}`,
+                });
+            }
+            for (const { count, sample } of failureClassesInOrder(objectFailures)) {
+                const { sessionId, spaceKey, failure: f } = sample;
+                config.logger?.warn("workspace_space_reclaim_failed", {
+                    space: incarnationLogPrefix(spaceKey),
+                    sessionId,
+                    lane: f.lane,
+                    stage: f.stage,
+                    count,
+                    error: redactIncarnations(f.detail),
+                    effect: `the ended space's ${f.lane === "space" ? "workspace snapshots" : "park snapshots"} may stay in the bucket (unreadable through the API; the bucket's lifecycle rule is the fallback) — the deletion it belongs to went ahead${count > 1 ? `; ${count} spaces of this call met the same failure, the line names the first` : ""}`,
+                });
             }
+            const threw = settled.find((r) => r.status === "rejected");
+            if (threw)
+                throw threw.reason;
         },
     };
 }

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

@@ -93,6 +93,8 @@ 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?;
     constructor(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps);
     private resolve;
     workspaceHandle(): WorkspaceHandle;
@@ -104,6 +106,12 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         error: RemoteExecutionError;
     }>;
     private doConnect;
+    /**
+     * 家目录:声明在场(`homeDir`,只来自 `REMOTE_EXEC_HOME_DIR` —— 本车道没有自己的缺省)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、
+     * 同一份 `-e` env),交唯一判官 `judgeLaneHome`。环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);
+     * 没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,但不记(与任何一次起容器失败同:下一次连接重问);调用方中止 ⇒ `aborted`、不记。没声明 ⇒ 不问(`undefined`)。容器由调用方收。
+     */
+    private homeVerdict;
     suspendVM(_options?: VmLifecycleOptions): Promise<{
         ok: true;
         value: SnapshotId;
@@ -183,6 +191,12 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
+    /**
+     * 交给宿主 `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 同)。
+     */
+    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`).
@@ -198,8 +212,13 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
      *  ⇒ 保 sh(修前字节形,诚实降级);探测自身失败同。容器**创建**引导命令(mkdir && tail)不走
      *  本 shell——无 bash 语法且探测尚不可能。 */
     private containerShell;
-    private containerShellProbed;
+    /** shell 探测的**一只在飞承诺**:并发的调用方(首用 exec / fs、connect、reconnect)都 join 它 —— 修前是先置真的布尔,第二个调用方在探测落定之前就拿 /bin/sh 往下走,
+     *  探测随后才把命令切到 bash(家目录对证因此可能问的是另一只 shell)。 */
+    private containerShellReady?;
+    /** 等一只共享的承诺,调用方的取消只退**它自己的**等待(承诺照常落定、照常服务其余等待者)。`false` = 取消了。 */
+    private untilOrAborted;
     private probeContainerShell;
+    private detectContainerShell;
     private ensureConnectedExec;
     /** Lazy connect for a FileSystem path → FileError on failure (fail closed, never throws). */
     private fsReady;