@sema-agent/server 7.150.0 → 7.152.0

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

@@ -9,15 +9,16 @@ import { appendFileStaged, buildCwdEnvCommand, createCwdGuardedCall, shellQuote,
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
 import { WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { SNAPSHOT_BUCKET_MISSING, isNoSuchBucketAnswer } from "./s3-answer.js";
-import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotIdHolds, snapshotKeyPrefixProblem, snapshotNameOwnedBy } from "../workspace-space.js";
+import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotIdHolds, snapshotKeyPrefixProblem, snapshotNameOwnedBy, workspaceSnapshotPrefixOf } from "../workspace-space.js";
 import { spaceCommitAlive } from "../workspace-space-commit.js";
-import { incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
+import { SESSION_INCARNATION_MISSING, 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 { PodDeleteRefused, reportPodDeleteFailed } from "./k8s-pod-delete-failure.js";
 import { buildLivenessCut, commandBoundsOf, laneLivenessOf, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
 import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { SANDBOX_IPV6_DEFAULT, sandboxEgressGaps, sandboxPodSysctls } from "../sandbox-egress-policy.js";
+import { describeMissingK8sCredential } from "../k8s-api-credentials.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
@@ -27,6 +28,7 @@ import { createPosixShellFs } from "./posix-shell-fs.js";
 import { randomUUID } from "node:crypto";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
+import { connectRefusal, createConnectSeat } from "./remote-env-connect-seat.js";
 const PROVIDER = "k8s";
 const K8S_BG_DIR_ROOT = "/tmp/.sema-bg";
 const K8S_BG_MAX_CONCURRENT = numEnvOr("K8S_BG_MAX_CONCURRENT", 8, 1);
@@ -43,6 +45,42 @@ const unsupported = (op) => ({
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a Kata pod sandbox (no managed memory snapshot — capabilities.suspendable=false; durable suspend degrades to checkpoint + cold rebuild)`),
 });
 const SA_DIR = "/var/run/secrets/kubernetes.io/serviceaccount";
+const processInCluster = () => ({
+    host: process.env.KUBERNETES_SERVICE_HOST,
+    port: process.env.KUBERNETES_SERVICE_PORT,
+    readMounted: (file) => readFileSync(`${SA_DIR}/${file}`, "utf8"),
+});
+export function resolveK8sApiAccess(cfg, inCluster = processInCluster()) {
+    const given = (v) => v !== undefined && v.trim() !== "";
+    const apiUrl = given(cfg.apiUrl) ? cfg.apiUrl : given(inCluster.host) ? `https://${inCluster.host}:${inCluster.port ?? "443"}` : undefined;
+    if (apiUrl === undefined)
+        return { ok: false, fact: "api_url", code: "connect_failed" };
+    let token = given(cfg.token) ? cfg.token : undefined;
+    if (token === undefined) {
+        try {
+            const mounted = inCluster.readMounted("token").trim();
+            token = mounted === "" ? undefined : mounted;
+        }
+        catch {
+            token = undefined;
+        }
+        if (token === undefined)
+            return { ok: false, fact: "token", code: "auth_failed" };
+    }
+    let ca = given(cfg.caCert) ? cfg.caCert : undefined;
+    if (ca === undefined && !cfg.insecureTls) {
+        try {
+            const mounted = inCluster.readMounted("ca.crt");
+            ca = given(mounted) ? mounted : undefined;
+        }
+        catch {
+            ca = undefined;
+        }
+        if (ca === undefined)
+            return { ok: false, fact: "ca", code: "auth_failed" };
+    }
+    return { ok: true, apiUrl, token, ca };
+}
 const EXEC_SUBPROTOCOLS = ["v5.channel.k8s.io", "v4.channel.k8s.io"];
 const WRITE_CHUNK_BYTES = 64 * 1024;
 import { applyPodSpecPatch, ADAPTER_VOLUME_NAMES, SANDBOX_POD_LABELS, SANDBOX_RUN_END_HOLD_ANNOTATION, SANDBOX_RUN_LABEL, SANDBOX_SECRET_SEAT_VERBS, isLabelValue } from "./k8s-exec-protocol.js";
@@ -92,6 +130,10 @@ function spaceLaneOf(policy, occupant) {
 function spaceReadFailed(what, detail, cause) {
     return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace space ${what} read failed${detail}`, cause instanceof Error ? cause : undefined) };
 }
+function isQuotaExceeded(json) {
+    const message = typeof json === "object" && json !== null ? json.message : undefined;
+    return typeof message === "string" && /\bexceeded quota\b/.test(message);
+}
 function restoreFailureIsTransient(cls) {
     switch (cls) {
         case "timeout":
@@ -174,6 +216,42 @@ export function boundedStoreCall(op, bound) {
         });
     });
 }
+function snapshotOpOf(req) {
+    if (req.method === "LIST")
+        return req.lane === "space" ? "k8s-space/prefix:LIST" : "k8s-park/prefix:LIST";
+    if ("object" in req)
+        return req.lane === "space" ? "k8s-space/object:DELETE" : "k8s-park/object:DELETE";
+    if ("pointer" in req) {
+        switch (req.method) {
+            case "GET":
+                return "k8s-space/latest:GET";
+            case "PUT":
+                return "k8s-space/latest:PUT";
+            case "DELETE":
+                return "k8s-space/latest:DELETE";
+        }
+    }
+    if (req.lane === "park") {
+        switch (req.method) {
+            case "GET":
+                return "k8s-park/archive:GET";
+            case "PUT":
+                return "k8s-park/archive:PUT";
+            case "HEAD":
+                return "k8s-park/archive:HEAD";
+        }
+    }
+    switch (req.method) {
+        case "GET":
+            return "k8s-space/archive:GET";
+        case "PUT":
+            return "k8s-space/archive:PUT";
+        case "DELETE":
+            return "k8s-space/archive:DELETE";
+        case "HEAD":
+            return "k8s-space/archive:HEAD";
+    }
+}
 import { execSocketTlsOptions, exitCodeFromStatus } from "./k8s-exec-protocol.js";
 export { execSocketTlsOptions } from "./k8s-exec-protocol.js";
 export function errorMessageOf(e) {
@@ -222,7 +300,18 @@ export class RemoteK8sExecutionEnv {
     idleWaiters = [];
     connectInFlight;
     resumeInFlight;
-    connectRefusal;
+    seat = createConnectSeat({
+        live: () => (this.podName !== undefined && this.connectInFlight === undefined && !this.destroyed ? this.workspaceHandle() : undefined),
+        inFlight: () => this.connectInFlight,
+        establish: (config) => {
+            const walk = this.establish(config).finally(() => {
+                if (this.connectInFlight === walk)
+                    this.connectInFlight = undefined;
+            });
+            this.connectInFlight = walk;
+            return walk;
+        },
+    });
     get homeDir() {
         return this.homeSeat.home;
     }
@@ -307,29 +396,32 @@ export class RemoteK8sExecutionEnv {
         return { sandboxId: this.podName ?? "(unconnected)", provider: PROVIDER, mountPath: this.cwd, ...(this.handleSnapshotId ? { snapshotId: this.handleSnapshotId } : {}) };
     }
     creds() {
-        const apiUrl = this.cfg.apiUrl ??
-            (process.env.KUBERNETES_SERVICE_HOST ? `https://${process.env.KUBERNETES_SERVICE_HOST}:${process.env.KUBERNETES_SERVICE_PORT ?? "443"}` : undefined);
-        if (!apiUrl)
-            throw new RemoteExecutionError("connect_failed", "no k8s API: set K8S_API_URL or run in-cluster");
-        let token = this.cfg.token;
-        let ca = this.cfg.caCert;
-        if (!token) {
-            try {
-                token = readFileSync(`${SA_DIR}/token`, "utf8").trim();
-            }
-            catch {
-                throw new RemoteExecutionError("auth_failed", "no k8s token: set K8S_TOKEN or run in-cluster with a service account");
-            }
+        const access = resolveK8sApiAccess(this.cfg, this.deps.inCluster?.());
+        if (!access.ok)
+            throw new RemoteExecutionError(access.code, describeMissingK8sCredential(access.fact));
+        return { apiUrl: access.apiUrl.replace(/\/+$/, ""), token: access.token, ca: access.ca };
+    }
+    missingApiCredential() {
+        const access = resolveK8sApiAccess(this.cfg, this.deps.inCluster?.());
+        return access.ok ? undefined : access.fact;
+    }
+    async apiCredentialReading() {
+        const fact = this.missingApiCredential();
+        if (fact !== undefined)
+            return { state: "missing", fact };
+        try {
+            const r = await this.request("POST", "/apis/authorization.k8s.io/v1/selfsubjectaccessreviews", {
+                apiVersion: "authorization.k8s.io/v1",
+                kind: "SelfSubjectAccessReview",
+                spec: { resourceAttributes: { namespace: this.cfg.namespace, verb: "create", resource: "pods" } },
+            });
+            if (r.status === 401)
+                return { state: "rejected" };
+            return r.status >= 200 && r.status < 300 ? { state: "accepted" } : { state: "unproven", detail: `HTTP ${r.status}` };
         }
-        if (!ca && !this.cfg.insecureTls) {
-            try {
-                ca = readFileSync(`${SA_DIR}/ca.crt`, "utf8");
-            }
-            catch {
-                throw new RemoteExecutionError("auth_failed", "no k8s CA: set K8S_CA_CERT_B64, K8S_INSECURE_TLS=true (lab), or run in-cluster");
-            }
+        catch (e) {
+            return { state: "unproven", detail: errorMessageOf(e) };
         }
-        return { apiUrl: apiUrl.replace(/\/+$/, ""), token, ca };
     }
     async request(method, apiPath, body, opts) {
         if (this.deps.request)
@@ -386,18 +478,12 @@ export class RemoteK8sExecutionEnv {
         });
     }
     connect(config) {
-        if (this.connectInFlight)
-            return this.connectInFlight;
-        const walk = this.establish(config).finally(() => {
-            if (this.connectInFlight === walk)
-                this.connectInFlight = undefined;
-        });
-        this.connectInFlight = walk;
-        return walk;
+        return this.seat.connect(config);
     }
     async establish(config) {
-        if (this.connectRefusal)
-            return this.connectRefusal;
+        const held = this.seat.held;
+        if (held)
+            return held;
         const signal = config?.abortSignal;
         const lane = this.spaceLane;
         switch (lane.state) {
@@ -434,7 +520,7 @@ export class RemoteK8sExecutionEnv {
             const filled = await fill.fill(this.fillChannel(), this.cwd, c.origin);
             if (!filled.ok) {
                 await this.releasePod();
-                return filled.standing ? this.holdRefusal(filled.error) : { ok: false, error: filled.error };
+                return this.seat.answer(filled);
             }
         }
         if (this.destroyed) {
@@ -488,10 +574,6 @@ 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,
@@ -501,19 +583,24 @@ export class RemoteK8sExecutionEnv {
             ...(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`));
+        return this.seat.answer(connectRefusal("pod_admission_refused", `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 ");
+        const missing = code === SESSION_INCARNATION_MISSING;
         if (!this.unreadableOccupantSaid) {
             this.unreadableOccupantSaid = true;
             this.logger?.warn("workspace_space_unreadable_occupant", {
                 sessionId: this.cfg.sessionId,
                 code,
-                effect: `the session store did not answer for this run's session occupant (incarnation) — this run is refused rather than started on a workspace that is neither restored nor saved; ${ways} runs without it`,
+                effect: missing
+                    ? `the session row for this run carries no occupant (incarnation) token — this run is refused rather than started on a workspace that is neither restored nor saved; ${ways} runs without it`
+                    : `the session store did not answer for this run's session occupant (incarnation) — this run is refused rather than started on a workspace that is neither restored nor saved; ${ways} runs without it`,
             });
         }
-        return spaceReadFailed("occupant", ` (${code}) — refusing to start this run on a workspace that could be neither restored nor saved; retry the run once the session store answers, or set ${ways}`);
+        return missing
+            ? this.seat.answer(connectRefusal("occupant_missing", `workspace space occupant read failed (${code}) — the session row carries no occupant token, so this run is not started on a workspace that could be neither restored nor saved; give the row its token or delete the session, or set ${ways}`))
+            : connectRefusal("occupant_unreadable", `workspace space occupant read failed (${code}) — refusing to start this run on a workspace that could be neither restored nor saved; retry the run once the session store answers, or set ${ways}`);
     }
     spaceLine(event, space, fields) {
         this.snapshotLine(event, { space: incarnationLogPrefix(space.incarnation), ...fields });
@@ -524,8 +611,9 @@ export class RemoteK8sExecutionEnv {
     provision(signal) {
         const space = this.spaceLane;
         const cache = this.cacheLane;
-        if (this.connectRefusal)
-            return Promise.resolve(this.connectRefusal);
+        const held = this.seat.held;
+        if (held)
+            return Promise.resolve(held);
         if (space.state === "unreadable")
             return Promise.resolve(this.refuseUnreadableOccupant(space.code));
         if (cache.state === "unreadable")
@@ -540,7 +628,7 @@ export class RemoteK8sExecutionEnv {
         const halt = signal ? AbortSignal.any([signal, refused.signal]) : refused.signal;
         return withRetry(async () => {
             const r = await once(signal);
-            if (!r.ok && this.connectRefusal)
+            if (!r.ok && this.seat.held)
                 refused.abort();
             return r;
         }, policy, { signal: halt });
@@ -716,7 +804,7 @@ export class RemoteK8sExecutionEnv {
         const leaseName = broker !== undefined ? `${SANDBOX_LEASE_NAME_PREFIX}${randomUUID()}` : undefined;
         const placeholder = broker !== undefined ? buildSandboxLeaseFile(broker.origins, placeholderLeaseEntries(broker.origins)) : undefined;
         if (placeholder !== undefined && !placeholder.ok) {
-            return this.holdRefusal(new RemoteExecutionError("connect_failed", `the member-credential broker cannot be set up for this pod: ${placeholder.problem}`));
+            return this.seat.answer(connectRefusal("credential_broker_refused", `the member-credential broker cannot be set up for this pod: ${placeholder.problem}`));
         }
         const layered = { ...(cache ? workspaceCacheEnv(cache.mount) : {}), ...(this.cfg.podEnv ?? {}) };
         const envEntries = [
@@ -770,7 +858,7 @@ export class RemoteK8sExecutionEnv {
                 applyPodSpecPatch(pod, this.cfg.podSpecPatch, { broker: true });
             }
             catch (e) {
-                return this.holdRefusal(new RemoteExecutionError("connect_failed", `${errorMessageOf(e)} — no pod is created (the member-credential broker never shares a pod with a patch that could reach it)`));
+                return this.seat.answer(connectRefusal("credential_broker_refused", `${errorMessageOf(e)} — no pod is created (the member-credential broker never shares a pod with a patch that could reach it)`));
             }
         }
         else if (this.cfg.podSpecPatch)
@@ -783,7 +871,8 @@ export class RemoteK8sExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `pod create RPC failed: ${e instanceof Error ? e.message : String(e)}`, e instanceof Error ? e : undefined) };
         }
         if (created.status === 401 || created.status === 403) {
-            return { ok: false, error: new RemoteExecutionError("auth_failed", `pod create denied (${created.status}): ${JSON.stringify(created.json).slice(0, 200)}`) };
+            const denied = `pod create denied (${created.status}): ${JSON.stringify(created.json).slice(0, 200)}`;
+            return created.status === 403 && isQuotaExceeded(created.json) ? connectRefusal("pod_quota_exceeded", denied) : { ok: false, error: new RemoteExecutionError("auth_failed", denied) };
         }
         if (created.status >= 300) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `pod create failed (${created.status}): ${JSON.stringify(created.json).slice(0, 300)}`) };
@@ -876,8 +965,7 @@ export class RemoteK8sExecutionEnv {
             if (verdict !== undefined) {
                 await this.deletePod(name).catch(() => { });
                 this.podName = undefined;
-                const error = new RemoteExecutionError("connect_failed", verdict.refusal);
-                return verdict.answered ? this.holdRefusal(error) : { ok: false, error };
+                return verdict.answered ? this.seat.answer(connectRefusal("home_unconfirmed", verdict.refusal)) : { ok: false, error: new RemoteExecutionError("connect_failed", verdict.refusal) };
             }
         }
         if (cache?.fresh)
@@ -990,12 +1078,13 @@ export class RemoteK8sExecutionEnv {
         if (snapshotKeyPrefixProblem(this.snapshotKeyPrefix()) !== undefined)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "unsafe snapshot key segment (keyPrefix): refusing to build a traversing object key") };
         const common = {
+            op: snapshotOpOf(req),
             endpoint: s3.endpoint,
             bucket: s3.bucket,
             accessKey: s3.accessKey,
             secretKey: s3.secretKey,
             ...(s3.region ? { region: s3.region } : {}),
-            expiresSec: Math.min(s3.presignTtlSec ?? 600, 3600),
+            ...(s3.presignTtlSec !== undefined ? { expiresSec: s3.presignTtlSec } : {}),
         };
         const base = this.snapshotBase(req);
         if (req.method === "LIST")
@@ -1004,7 +1093,7 @@ export class RemoteK8sExecutionEnv {
         return { ok: true, value: presignS3Url({ ...common, key: `${base}${object}`, method: req.method }) };
     }
     snapshotKeyPrefix() {
-        return this.cfg.s3Snapshot?.keyPrefix ?? WORKSPACE_SNAPSHOT_PREFIX_DEFAULT;
+        return workspaceSnapshotPrefixOf(this.cfg.s3Snapshot);
     }
     snapshotBase(req) {
         const prefix = this.snapshotKeyPrefix();
@@ -1129,7 +1218,7 @@ export class RemoteK8sExecutionEnv {
         const detail = ` (${SNAPSHOT_BUCKET_MISSING}): the workspace snapshot bucket "${bucket}" (WORKSPACE_SNAPSHOT_BUCKET; default ${WORKSPACE_SNAPSHOT_BUCKET_DEFAULT}) does not exist in the object store — ` +
             `refusing to start this run on a workspace that could be neither restored nor saved. Ways out: create the bucket, or set WORKSPACE_SNAPSHOT_BUCKET to one that exists, ` +
             "or set WORKSPACE_PERSIST=off for a deployment that keeps no workspace between runs";
-        return this.holdRefusal(read === "pointer" ? spaceReadFailed("pointer", detail).error : new RemoteExecutionError("connect_failed", `workspace snapshot archive read failed${detail}`));
+        return this.seat.answer(connectRefusal("snapshot_bucket_missing", read === "pointer" ? `workspace space pointer read failed${detail}` : `workspace snapshot archive read failed${detail}`));
     }
     async readLatest(space, signal) {
         const r = await this.readPointer(space, "latest", signal);
@@ -1391,7 +1480,7 @@ 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 });
-                    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), ` +
+                    return this.seat.answer(connectRefusal("archive_unrecoverable", `${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));
                 }
@@ -2263,6 +2352,14 @@ export class RemoteK8sExecutionEnv {
             run: (cmd, abortSignal) => this.fsExec(cmd, abortSignal),
             resolve: (p) => this.resolve(p),
             tempDir: () => this.cwd,
+            boundLane: {
+                run: async (cmd, _cap, abortSignal) => {
+                    const r = await this.execData(cmd, abortSignal);
+                    return r.ok ? { ok: true, value: { stdout: Buffer.from(r.value.stdout, "utf8"), stderr: r.value.stderr, exitCode: r.value.exitCode } } : r;
+                },
+                payload: "base64",
+                boundSec: this.cfg.dataTimeoutMs / 1000,
+            },
         }));
     }
     async fileInfo(p, abortSignal) {
@@ -2277,6 +2374,9 @@ export class RemoteK8sExecutionEnv {
     async canonicalChain(p, abortSignal) {
         return this.posixFs.canonicalChain(p, abortSignal);
     }
+    async openBound(p, abortSignal) {
+        return this.posixFs.openBound(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }
@@ -2403,6 +2503,12 @@ export function createSpaceReclaimer(config, deps) {
 export async function checkSandboxEgressPolicy(config, deps) {
     return new RemoteK8sExecutionEnv(config, deps).egressPolicyGaps();
 }
+export function sandboxApiCredentialFact(config, deps) {
+    return new RemoteK8sExecutionEnv(config, deps).missingApiCredential();
+}
+export async function readSandboxApiCredentials(config, deps) {
+    return new RemoteK8sExecutionEnv(config, deps).apiCredentialReading();
+}
 export async function readSandboxSecretSeat(config, seat, deps) {
     return new RemoteK8sExecutionEnv(config, deps).secretSeatReading(seat);
 }

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

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { type LaneLogger } from "./remote-shell.js";
 import { type CustodyMember } from "./workspace-custody.js";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type ExecutionEnvCapabilities } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, 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";
@@ -140,9 +140,12 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
     private destroyed;
     /** In-flight connect, memoized so concurrent lazy first-use starts exactly one container (no double-run). */
     private connecting?;
-    /** 这只环境的拒 —— 记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。两个写者:家目录(环境答了而与声明不一致)
-     *  与恢复点的填充(换一只容器也是同一个答的拒:种子不是项目包、摘要不符、镜像没有 `tar`、镜像预置撞名 —— `FillOutcome.standing`)。 */
-    private connectRefusal?;
+    /**
+     * 建连座(`remote-env-connect-seat.ts`):`connect` 的唯一次序(记住的拒 ⇒ 原样再答 · 起容器在飞 ⇒ 等那一次 · 已连 ⇒ 当下的把手 · 否则起或附着一只),并持有这只环境记住的拒 ——
+     * 记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。两件立定的事实写它:家目录(环境答了而与声明不一致;`env.home_unconfirmed`)
+     * 与恢复点的填充(换一只容器也是同一个答的拒:种子不是项目包、摘要不符、镜像没有 `tar`、镜像预置撞名 —— `FillOutcome.standing`;`env.sandbox_refused`)。
+     */
+    private readonly seat;
     /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
     /** 本环境的生命期信号:{@link destroy} 先断它 —— 在帽前等空位的那一次起动立刻收场(不拖满预算)。 */
@@ -171,7 +174,7 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
         ok: false;
         error: RemoteExecutionError;
     }>;
-    /** 一只在飞的连接(并发的首用调用方 / 附着都 join 它 —— 只起一只容器、只附着一次);失败 ⇒ 清掉备忘,下一次重来。 */
+    /** 一只在飞的连接(并发的首用调用方 / 附着都 join 它 —— 只起一只容器、只附着一次);落定即清(按身份):连上 = `containerId`,失败 ⇒ 下一次重来。 */
     private connectOnce;
     /**
      * 先问 daemon 这只身份的容器({@link sightContainer}),再按它的样子(状态闭集,穷举):
@@ -214,8 +217,8 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
     private fillChannel;
     /**
      * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 实测)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、同一份 `-e` env),读数交座。
-     * 声明在场:环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,
-     * 但不记(与任何一次起容器失败同:下一次连接重问)。没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,环境照开(没声明就没有声明可拒)。
+     * 声明在场:环境答了而不一致 / 不是绝对路径 ⇒ 立定的拒(`env.home_unconfirmed`,建连座记住它:同一镜像同一答案,此后每次连接原样回它,不再起容器、不再问);
+     * 没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开(`connect_failed`),但不记(与任何一次起容器失败同:下一次连接重问)。没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,环境照开(没声明就没有声明可拒)。
      * 调用方中止 ⇒ `aborted`、不记、不交座。容器由调用方收。
      */
     private homeVerdict;
@@ -306,7 +309,7 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
     private get posixFs();
     /** 文件面的一次容器内 shell 往返(基座、暂存写的准备 / 上传 / 提交 / 清理共用)。承 fsReady 契约(其余三腿走公有 exec、守卫天然在;本腿直用私有
      *  docker,必须自带):destroyed 守卫 + 懒连接,fail closed 不抛 —— 消息保留 "destroyed" 字样(测试钉的就是它)。`input` 在场 ⇒ 同一只 argv 多一个
-     *  `-i`、载荷走 stdin({@link pipeIn});身份与工作目录与不带载荷的往返逐字相同。 */
+     *  `-i`、载荷走 stdin({@link pipeIn});身份与工作目录与不带载荷的往返逐字相同。`binary` ⇒ stdout 逐字节收(`stdoutBytes`,绑定读的载荷;与 readBinaryFile 同一收集器)。 */
     private fsExec;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
@@ -315,6 +318,8 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
      *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
      *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
+    /** 绑定读(逐答重绑,Linux 读法;脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份)。 */
+    openBound(p: string, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

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

@@ -13,6 +13,7 @@ import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, mar
 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 { connectRefusal, createConnectSeat, withdrawOnAbort } from "./remote-env-connect-seat.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 const PROVIDER = "local-docker";
 const DEFAULT_MOUNT_PATH = "/workspace";
@@ -49,7 +50,11 @@ export class RemoteLocalDockerExecutionEnv {
     handle;
     destroyed = false;
     connecting;
-    connectRefusal;
+    seat = createConnectSeat({
+        live: () => (this.containerId !== undefined ? this.workspaceHandle() : undefined),
+        inFlight: () => this.connecting,
+        establish: (config) => this.connectOnce(config, "start-or-attach"),
+    });
     homeSeat;
     lifecycle = new AbortController();
     capacityDeadline;
@@ -100,20 +105,15 @@ export class RemoteLocalDockerExecutionEnv {
             return unsupported("connect(snapshotId)");
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        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)
-            return ok(this.workspaceHandle());
-        return this.connectOnce(config, "start-or-attach");
+        return this.seat.connect(config);
     }
     async connectOnce(config, mode) {
         if (this.connecting)
             return this.connecting;
-        this.connecting = this.doConnect(config, mode);
-        const r = await this.connecting;
-        if (!r.ok)
+        const mine = this.doConnect(config, mode);
+        this.connecting = mine;
+        const r = await mine;
+        if (this.connecting === mine)
             this.connecting = undefined;
         return r;
     }
@@ -230,11 +230,8 @@ export class RemoteLocalDockerExecutionEnv {
         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 (!filled.ok)
+            return this.seat.answer(filled);
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         this.containerId = id;
@@ -299,9 +296,7 @@ export class RemoteLocalDockerExecutionEnv {
         const filled = await this.fillWorkspace("minted");
         if (!filled.ok || this.destroyed) {
             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 };
+            return filled.ok ? { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") } : this.seat.answer(filled);
         }
         this.containerId = id;
         this.handle = { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
@@ -356,10 +351,7 @@ export class RemoteLocalDockerExecutionEnv {
         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 });
         if (verdict === undefined)
             return undefined;
-        const error = new RemoteExecutionError("connect_failed", verdict.refusal);
-        if (verdict.answered)
-            this.connectRefusal = error;
-        return error;
+        return verdict.answered ? this.seat.answer(connectRefusal("home_unconfirmed", verdict.refusal)).error : new RemoteExecutionError("connect_failed", verdict.refusal);
     }
     async suspendVM(_options) {
         return unsupported("suspendVM");
@@ -373,8 +365,9 @@ export class RemoteLocalDockerExecutionEnv {
     async reconnect(sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (this.connectRefusal)
-            return { ok: false, error: this.connectRefusal };
+        const held = this.seat.held;
+        if (held)
+            return held;
         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}'`) };
         }
@@ -666,7 +659,7 @@ export class RemoteLocalDockerExecutionEnv {
         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);
+        const r = await this.fsExec(`cat ${redirect} ${shellQuote(dest)}`, abortSignal, { input: typeof content === "string" ? Buffer.from(content, "utf8") : content });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, dest) };
         if (r.value.exitCode !== 0)
@@ -679,9 +672,18 @@ export class RemoteLocalDockerExecutionEnv {
             run: (cmd, abortSignal) => this.fsExec(cmd, abortSignal),
             resolve: (p) => this.resolve(p),
             tempDir: () => this.cwd,
+            boundLane: {
+                run: async (cmd, _cap, abortSignal) => {
+                    const r = await this.fsExec(cmd, abortSignal, { binary: true });
+                    return r.ok ? { ok: true, value: { stdout: r.value.stdoutBytes ?? new Uint8Array(), stderr: r.value.stderr, exitCode: r.value.exitCode } } : r;
+                },
+                payload: "raw",
+                boundSec: this.cfg.commandTimeoutMs / 1000,
+            },
         }));
     }
-    async fsExec(cmd, abortSignal, input) {
+    async fsExec(cmd, abortSignal, o = {}) {
+        const input = o.input;
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
         if (!this.containerId) {
@@ -694,7 +696,7 @@ export class RemoteLocalDockerExecutionEnv {
         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 } : {}) });
+        return this.docker(argv.value, { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, ...(input !== undefined ? { input } : {}), ...(o.binary === true ? { binary: true } : {}) });
     }
     async fileInfo(p, abortSignal) {
         return this.posixFs.statFileInfo(p, abortSignal);
@@ -708,6 +710,9 @@ export class RemoteLocalDockerExecutionEnv {
     async canonicalChain(p, abortSignal) {
         return this.posixFs.canonicalChain(p, abortSignal);
     }
+    async openBound(p, abortSignal) {
+        return this.posixFs.openBound(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }
@@ -882,19 +887,7 @@ 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);
-            });
-        });
+        return withdrawOnAbort(this.connect(), signal);
     }
     containerShell = "/bin/sh";
     containerShellReady;