@sema-agent/server 7.150.0 → 7.152.0

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

@@ -1,11 +1,11 @@
 import { writeLogText } from "../observability/logger.js";
 import { spawn } from "node:child_process";
 import os from "node:os";
-import path from "node:path";
+import path, {} from "node:path";
 import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import fs from "node:fs/promises";
 import { randomBytes } from "node:crypto";
-import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync, accessSync, constants as FS_CONST } from "node:fs";
+import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, accessSync, renameSync, constants as FS_CONST } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
 import { armPipeDestroyGrace, numEnvOr } from "./remote-shell.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
@@ -13,7 +13,7 @@ import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
-import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, physicalPathOf as kernelRealPathOf, } from "@sema-agent/core";
+import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, physicalPathOf, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { LaneHomeSeat, laneHomeRefusal } from "../lane-home-probe.js";
@@ -21,7 +21,10 @@ import { composeHostSubprocessEnv, hostSubprocessEnv, withheldFromHostSubprocess
 import { nameTooLongCode } from "./remote-env-file-error.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 import { createWorkspaceCustody } from "./workspace-custody.js";
+import { canonicalPathOf, pathIsWithin, presentOnDisk } from "../memory-scope.js";
+import { errorCodeOf } from "../observability/err-text.js";
 import { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
+import { createConnectSeat, withdrawOnAbort } from "./remote-env-connect-seat.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
 const inflightFsDrainWaitMs = () => numEnvOr("HOST_FS_DRAIN_WAIT_MS", 10_000, 1);
@@ -39,6 +42,7 @@ const unsupported = (op) => ({
 });
 const BORROWED = Object.freeze({ kind: "borrowed" });
 const RELEASED = Object.freeze({ kind: "released" });
+const NO_ROOTS = Object.freeze([]);
 const UNSUPPORTED_SCHEDULER_CAPS = {
     supported: false,
     maxScheduledPerScope: 0,
@@ -130,20 +134,26 @@ export class RemoteHostExecutionEnv {
         return this.spoolRootDir;
     }
     tenure;
+    hasLeft = false;
     preparing;
+    seat = createConnectSeat({
+        live: () => (this.prepared && !this.destroyed ? this.handle : undefined),
+        inFlight: () => (this.prepared ? undefined : this.preparing?.then(() => this.preparedAnswer(), (e) => this.prepareFailed(e))),
+        establish: (config) => withdrawOnAbort(this.ensurePrepared().then(() => this.preparedAnswer(), (e) => this.prepareFailed(e)), config?.abortSignal),
+    });
     handle;
     constructor(config = {}) {
         if (config.workspaceDir) {
-            this.workspaceDir = path.resolve(config.workspaceDir);
+            this.workspaceDir = hostSeatPath(config.workspaceDir);
             const shared = config.custody?.sharedRoot;
-            this.tenure = shared !== undefined ? { kind: "held", root: path.resolve(shared) } : BORROWED;
+            this.tenure = shared !== undefined ? { kind: "held", roots: [hostSeatPath(shared)] } : BORROWED;
         }
         else {
-            const base = config.workspaceBase ?? os.tmpdir();
+            const base = hostSeatPath(config.workspaceBase ?? os.tmpdir());
             const id = config.id ?? randomBytes(6).toString("hex");
             const suffix = randomBytes(4).toString("hex");
-            this.workspaceDir = path.resolve(base, `sema-host-${sanitizeId(id)}-${suffix}`);
-            this.tenure = { kind: "held", root: this.workspaceDir };
+            this.workspaceDir = anchorUnder(path, base, `sema-host-${sanitizeId(id)}-${suffix}`);
+            this.tenure = { kind: "held", roots: [this.workspaceDir] };
         }
         const inheritEnvProblem = inheritEnvPolicyProblem(config.inheritEnv);
         if (inheritEnvProblem !== undefined)
@@ -171,11 +181,18 @@ export class RemoteHostExecutionEnv {
         return this.teardownSettled;
     }
     leftover = undefined;
+    get left() {
+        return this.hasLeft;
+    }
     get settled() {
-        return this.teardownSettled && this.tenure.kind !== "held";
+        return this.teardownSettled && this.hasLeft;
+    }
+    get heldRoots() {
+        return this.tenure.kind === "held" ? this.tenure.roots : NO_ROOTS;
     }
-    get heldWorkspace() {
-        return this.tenure.kind === "held" ? this.tenure.root : undefined;
+    assumeRoot(root) {
+        this.tenure = { kind: "held", roots: this.tenure.kind === "held" ? [...this.tenure.roots, root] : [root] };
+        trackUnlessAbsent(root);
     }
     workspaceHandle() {
         return this.handle;
@@ -185,18 +202,14 @@ export class RemoteHostExecutionEnv {
             return unsupported("connect(snapshotId)");
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (config?.abortSignal?.aborted)
-            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
-        try {
-            await this.ensurePrepared();
-        }
-        catch (e) {
-            return { ok: false, error: new RemoteExecutionError("connect_failed", `failed to create host workspace ${this.workspaceDir}: ${errMsg(e)}`, asError(e)) };
-        }
-        if (config?.secrets?.length) {
-        }
+        return this.seat.connect(config);
+    }
+    preparedAnswer() {
         return ok(this.handle);
     }
+    prepareFailed(e) {
+        return { ok: false, error: new RemoteExecutionError("connect_failed", `failed to create host workspace ${this.workspaceDir}: ${errMsg(e)}`, asError(e)) };
+    }
     async suspendVM(_options) {
         return unsupported("suspendVM");
     }
@@ -240,17 +253,37 @@ export class RemoteHostExecutionEnv {
             catch { }
             this.spoolRootDir = undefined;
         }
+        this.hasLeft = true;
         const tenure = this.tenure;
         if (tenure.kind !== "held")
             return;
         this.tenure = RELEASED;
-        if (this.cfg.custody?.heldElsewhere(this, tenure.root) === true)
-            return;
-        try {
-            await fs.rm(tenure.root, { recursive: true, force: true });
-            untrackEphemeralHostWorkspace(tenure.root);
+        const tombs = [];
+        for (const root of tenure.roots) {
+            if (this.cfg.custody?.passOn(this, root) === true)
+                continue;
+            const tomb = removalTombOf(root);
+            try {
+                renameSync(root, tomb);
+            }
+            catch (e) {
+                if (e?.code === "ENOENT")
+                    untrackEphemeralHostWorkspace(root);
+                else
+                    trackUnlessAbsent(root);
+                continue;
+            }
+            trackEphemeralHostWorkspace(tomb);
+            untrackEphemeralHostWorkspace(root);
+            tombs.push(tomb);
         }
-        catch {
+        for (const tomb of tombs) {
+            try {
+                await fs.rm(tomb, { recursive: true, force: true });
+                untrackEphemeralHostWorkspace(tomb);
+            }
+            catch {
+            }
         }
     }
     async cleanup() {
@@ -1294,8 +1327,8 @@ export class RemoteHostExecutionEnv {
                 .mkdir(this.workspaceDir, { recursive: true })
                 .then(() => {
                 this.prepared = true;
-                if (this.tenure.kind === "held")
-                    trackEphemeralHostWorkspace(this.tenure.root);
+                for (const root of this.heldRoots)
+                    trackUnlessAbsent(root);
             })
                 .catch((e) => {
                 this.preparing = undefined;
@@ -1327,7 +1360,7 @@ export class RemoteHostExecutionEnv {
             return false;
         const real = (x) => {
             try {
-                return kernelRealPathOf(x);
+                return physicalPathOf(x);
             }
             catch {
                 return undefined;
@@ -1408,6 +1441,13 @@ export class RemoteHostExecutionEnv {
         return new FileError("unknown", msg, p);
     }
 }
+export function hostSeatPath(p, pathApi = path) {
+    if (pathApi.sep === "\\" && /^[A-Za-z]:(?![\\/])/.test(p)) {
+        const driveCwd = pathApi.resolve(p.slice(0, 2));
+        return p.length === 2 ? driveCwd : anchorUnder(pathApi, driveCwd, p.slice(2));
+    }
+    return anchoredPath(pathApi, process.cwd(), p);
+}
 function sanitizeId(id) {
     return id.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 64) || "task";
 }
@@ -1427,39 +1467,71 @@ function asError(e) {
 function signalNumber(signal) {
     return os.constants.signals[signal];
 }
+function heldRootContaining(custody, dir) {
+    const found = [];
+    custody.holder((m) => {
+        const root = m.heldRoots.find((r) => pathIsWithin(r, dir, canonicalPathOf));
+        if (root !== undefined)
+            found.push(root);
+        return root !== undefined;
+    });
+    return found[0];
+}
+function passOnRoot(custody, self, root) {
+    if (custody.holder((m) => m !== self && m.heldRoots.includes(root)) !== undefined)
+        return true;
+    const unreadable = [];
+    const occupant = custody.holder((m) => {
+        if (m === self || m.left)
+            return false;
+        try {
+            return pathIsWithin(root, m.cwd, canonicalPathOf);
+        }
+        catch (error) {
+            unreadable.push({ dir: m.cwd, error });
+            return false;
+        }
+    });
+    if (occupant !== undefined) {
+        occupant.assumeRoot(root);
+        return true;
+    }
+    const first = unreadable[0];
+    if (first === undefined)
+        return false;
+    trackUnlessAbsent(root);
+    writeLogText("stderr", `RemoteHostExecutionEnv: kept ${root} instead of removing it — could not read whether the working directory ${first.dir} lies inside it ` +
+        `(${errorCodeOf(first.error) ?? "unreadable"}); nobody takes it over, and the exit-time sweep removes it`);
+    return true;
+}
+function trackUnlessAbsent(root) {
+    let absent;
+    try {
+        absent = !presentOnDisk(root);
+    }
+    catch {
+        absent = false;
+    }
+    if (!absent)
+        trackEphemeralHostWorkspace(root);
+}
+function removalTombOf(root) {
+    return anchorUnder(path, path.dirname(root), `.${path.basename(root)}.removing-${randomBytes(4).toString("hex")}`);
+}
 export function hostExecutionEnvFactory(config = {}, legOf = () => ({})) {
     const custody = createWorkspaceCustody();
-    const heldElsewhere = (self, root) => custody.holder((m) => m !== self && m.heldWorkspace === root) !== undefined;
+    const passOn = (self, root) => passOnRoot(custody, self, root);
     return (ctx) => {
         const { minted, ...leg } = legOf(ctx);
         const identity = ctx.taskId ?? ctx.sessionId;
         return custody.envOf(identity, () => {
             const dir = leg.workspaceDir ?? config.workspaceDir;
-            const sharedRoot = dir === undefined ? undefined : custody.holder((m) => m.heldWorkspace !== undefined && dirWithin(dir, m.heldWorkspace))?.heldWorkspace;
-            const env = new RemoteHostExecutionEnv({ ...config, ...leg, id: config.id ?? identity, custody: { heldElsewhere, ...(sharedRoot !== undefined ? { sharedRoot } : {}) } });
+            const sharedRoot = dir === undefined ? undefined : heldRootContaining(custody, hostSeatPath(dir));
+            const env = new RemoteHostExecutionEnv({ ...config, ...leg, id: config.id ?? identity, custody: { passOn, ...(sharedRoot !== undefined ? { sharedRoot } : {}) } });
             minted?.(env);
             return env;
         });
     };
 }
-function dirWithin(dir, root) {
-    const inside = (d, r) => {
-        const rel = path.relative(r, d);
-        return rel === "" || (rel.split(path.sep)[0] !== ".." && !path.isAbsolute(rel));
-    };
-    return inside(path.resolve(dir), path.resolve(root)) || inside(physicalPathOf(dir), physicalPathOf(root));
-}
-function physicalPathOf(p) {
-    let head = path.resolve(p);
-    const tail = [];
-    while (!existsSync(head)) {
-        const up = path.dirname(head);
-        if (up === head)
-            return path.resolve(p);
-        tail.unshift(path.basename(head));
-        head = up;
-    }
-    return path.join(realpathSync(head), ...tail);
-}
 export { localDockerExecutionEnvFactory, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
 //# sourceMappingURL=remote-env-host.js.map

package/dist/plugins/remote-env-k8s.d.ts

@@ -2,13 +2,46 @@ import { type SpaceReclaimer, type WorkspaceSpacePolicy, type CacheReclaimReason
 import { type SpaceCommitFence } from "../workspace-space-commit.js";
 import { type CacheMissMemory, type WorkspaceCacheCapability } from "../workspace-cache.js";
 import { type SandboxEgressGap, type SandboxIpv6 } from "../sandbox-egress-policy.js";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
+import { type K8sApiCredentialFact } from "../k8s-api-credentials.js";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type ExecResult, 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 BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
 import type { PodSpecPatch } from "./k8s-exec-protocol.js";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
+import { type ConnectResult } from "./remote-env-connect-seat.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, buildKillAllScript, parseBgPollOutput, type ParsedBgPoll, } from "./k8s-bg-scripts.js";
+/**
+ * This process's in-cluster identity: the platform's `KUBERNETES_SERVICE_*` and the mounted service-account files. `readMounted` throws when the file is unreadable.
+ * (In this file a bare `read(` names a control-plane GET — the RBAC table's source reader classifies every one — so the mount reader carries its own name.)
+ */
+export interface InClusterIdentity {
+    readonly host: string | undefined;
+    readonly port: string | undefined;
+    readMounted(file: "token" | "ca.crt"): string;
+}
+/** What the control plane can be reached with — or the ONE missing fact (with the adapter code its request-time refusal carries). */
+export type K8sApiAccess = {
+    readonly ok: true;
+    readonly apiUrl: string;
+    readonly token: string;
+    readonly ca: string | undefined;
+} | {
+    readonly ok: false;
+    readonly fact: K8sApiCredentialFact;
+    readonly code: "connect_failed" | "auth_failed";
+};
+/**
+ * The ONE judge of "does this lane have cluster API credentials": explicit config (`K8S_API_URL` / `K8S_TOKEN` / `K8S_CA_CERT_B64`, `K8S_INSECURE_TLS`) first, the
+ * in-cluster service account second, per piece. The request-time reader ({@link RemoteK8sExecutionEnv}'s `creds()`), the boot gate and the per-run credential
+ * reading all read THIS function — what the boot refuses on is exactly what every request would have thrown on. (No kubeconfig: this lane never reads one.)
+ */
+export declare function resolveK8sApiAccess(cfg: {
+    readonly apiUrl?: string | undefined;
+    readonly token?: string | undefined;
+    readonly caCert?: string | undefined;
+    readonly insecureTls?: boolean | undefined;
+}, inCluster?: InClusterIdentity): K8sApiAccess;
 export interface K8sEnvConfig extends LaneHomeConfig {
     /** API server URL. Default: in-cluster (`https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT`). */
     apiUrl?: string;
@@ -175,13 +208,6 @@ export { type PodSpecPatch, applyPodSpecPatch } from "./k8s-exec-protocol.js";
 import { type SandboxPodApi, type SandboxPodListing } from "./k8s-pod-reaper.js";
 import { type SandboxLeaseEntryInput } from "../sandbox-git-lease.js";
 import type { WorkspaceFill } from "./workspace-fill.js";
-type ConnectResult = {
-    ok: true;
-    value: WorkspaceHandle;
-} | {
-    ok: false;
-    error: RemoteExecutionError;
-};
 /** Minimal exec-socket surface (what we use of `ws`) so tests can inject a fake. */
 export interface ExecSocket {
     on(event: "open" | "message" | "close" | "error", listener: (...args: unknown[]) => void): void;
@@ -200,6 +226,21 @@ export interface K8sRequestOptions {
     signal?: AbortSignal;
     contentType?: string;
 }
+/**
+ * The control plane's reading of this lane's credentials, a closed set: `missing` (the judge's fact — nothing to send), `rejected` (the cluster answered HTTP 401),
+ * `accepted` (a 2xx answer: the credentials work), `unproven` (any other answer, or none — see {@link RemoteK8sExecutionEnv.apiCredentialReading}).
+ */
+export type ApiCredentialReading = {
+    readonly state: "missing";
+    readonly fact: K8sApiCredentialFact;
+} | {
+    readonly state: "rejected";
+} | {
+    readonly state: "accepted";
+} | {
+    readonly state: "unproven";
+    readonly detail: string;
+};
 export interface K8sEnvDeps {
     request?: (method: string, apiPath: string, body?: unknown, opts?: K8sRequestOptions) => Promise<{
         status: number;
@@ -209,6 +250,8 @@ export interface K8sEnvDeps {
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
     /** Worker-side object-store requests (the space pointer, listing, deletes). Default: global `fetch`; either way the request goes out through the egress exit (an endpoint that answers with a redirect is refused, never followed). */
     fetch?: typeof fetch;
+    /** This process's in-cluster identity (default: the process env's `KUBERNETES_SERVICE_*` and the mounted service-account files); a test replaces it. */
+    inCluster?: () => InClusterIdentity;
     /** 这只环境手里的读地板模块(缺席 ⇒ `createSandboxReadFloor` 按旋钮选;钉注入守地板的模块)。能力块的 `keepsReadFloor` 读它的状态。 */
     readFloor?: SandboxReadFloor;
 }
@@ -325,11 +368,15 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private connectInFlight?;
     /** The resume among them, with the snapshot it restores: a second `resumeVM` of the same snapshot shares it (one restore, one pod). */
     private resumeInFlight?;
-    /** The env's refusal — a fact of this env until `destroy`, written once ({@link holdRefusal}) and answered as it stands to every later connect (and to
-     *  every later pod creation: {@link provision}): the same refusal, zero pods, zero store requests, no second line. Two causes write it:
-     *  the space restore (`latest` names an archive that is there and did not come back — {@link restoreSnapshot}) and the pod's admission (the cluster created
-     *  the pod and it ended `Failed` before it ran — {@link createPod}). Neither goes away by asking again: the same request answers the same. */
-    private connectRefusal?;
+    /**
+     * This env's connect seat (`remote-env-connect-seat.ts`): the one order of `connect` — a refusal the env holds ⇒ answered as it stands · a walk in flight
+     * ({@link connectInFlight}) ⇒ its answer · a pod already holding the workspace ⇒ its handle · otherwise one walk ({@link establish}). The seat holds the env's
+     * refusal — a standing one, spelled by the seat's refusal table (a missing snapshot bucket, an archive that is there and did not come back, the cluster
+     * refusing the pod at admission, the member-credential broker that cannot be set up, a fill refused the same on any pod, a home the pod answered against
+     * the claim, a session row with no occupant token): a fact of this env until `destroy`, answered to every later connect and every later pod creation
+     * ({@link provision}) — zero pods, zero store requests, no second line. A refusal that heals by itself (a quota, a store that did not answer) is not held.
+     */
+    private readonly seat;
     /** core `ExecutionEnv.homeDir`([ref]):pod 里执行用户的 home —— 声明在场 ⇒ 声明(开环境那一拍与 `$HOME` 对证过),否则 pod 就绪那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时 pod 起来之前缺席)。 */
     get homeDir(): string | undefined;
     /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则 pod 就绪那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
@@ -371,8 +418,18 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     get lifetimeMs(): number;
     private resolve;
     workspaceHandle(): WorkspaceHandle;
-    /** Resolved lazily so an in-cluster pod picks up its service account without explicit config. */
+    /** Resolved lazily so an in-cluster pod picks up its service account without explicit config ({@link resolveK8sApiAccess} is the one judge). */
     private creds;
+    /** The missing credential fact of this env's control-plane access, or `undefined` (nothing missing) — {@link resolveK8sApiAccess}, the one judge. */
+    missingApiCredential(): K8sApiCredentialFact | undefined;
+    /**
+     * The control plane's reading of this lane's credentials, asked once per run before its env is minted ({@link readSandboxApiCredentials}): the judge's missing fact
+     * ({@link missingApiCredential}), else one SelfSubjectAccessReview (answered for every authenticated caller) — an HTTP 401 is the cluster rejecting the credentials,
+     * a 2xx the cluster accepting them. ONLY a positive proof of rejection refuses: any other answer (403, 5xx, a request that threw or timed out) is `unproven` — another
+     * fact (a Role, an outage) that the lane's own connect answers loudly and retries within its own bounds; refusing the run on it would turn every API blip into a failed run.
+     * The caller counts an `unproven` reading (a registered fail-open arm). Never throws.
+     */
+    apiCredentialReading(): Promise<ApiCredentialReading>;
     /** Control-plane REST call (pod create/get/delete), bounded by rpcTimeoutMs. Injectable for tests. */
     private request;
     private openExec;
@@ -381,18 +438,20 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * ({@link awaitSpaceCommit}: the run store's commit row), then read `<prefix>/<incarnation>/space/latest`: present ⇒
      * restore it through {@link restoreSnapshot} (the one tar download, shared with `resumeVM`; an archive that is gone ⇒
      * loud `workspace_latest_dangling`, the pointer deleted, an empty workspace); absent (404 — the key, with the bucket there) ⇒ a fresh pod; a read that
-     * FAILS ⇒ a loud `connect_failed` — a 404 `NoSuchBucket` included ({@link refuseMissingBucket}) — never a silent fresh workspace (a run that believes it resumed while it did not is
+     * FAILS ⇒ a loud refusal — `connect_failed` (that attempt's: the next connect reads again), or, for a 404 `NoSuchBucket`, the env's standing
+     * `env.snapshot_bucket_missing` ({@link refuseMissingBucket}) — never a silent fresh workspace (a run that believes it resumed while it did not is
      * the worst form). Once the pod holds the workspace, this env arms its fence seat (its destroy will commit).
      * The same walk ({@link establish}) is the restore point of a parked run's resumed leg whose park packed nothing ({@link resumeVM}).
      * Persistence off / no store ⇒ a fresh pod, exactly as before. Persistence on but no such session (the occupant absent) ⇒ a
-     * fresh pod and one `workspace_space_unavailable` line (no restore by any other key). The occupant read FAULTED ⇒ the same
-     * loud `connect_failed` as a failed `latest` read, no pod ({@link provision} refuses it — every entry that would create one).
-     * One connect in flight per env: a connect that arrives while another is running — the explicit one, the lazy one of the first operation,
-     * `reconnect` — gets THAT connect's answer (one pod creation, one restore, one refusal line), not a walk of its own; the share is for a connect in flight
-     * only (a connect that failed is not remembered by it — how long a failure stands is {@link connectRefusal}'s). The abort signal of the connect that
-     * started is the one in force.
-     * One refusal per env: a refusal this env holds ({@link connectRefusal} — a restore that did not come back, a pod the cluster refused at admission) is answered
-     * as it stands to every later connect on every lane — the previous commit is not waited on again, `latest` is not read again, no pod is created.
+     * fresh pod and one `workspace_space_unavailable` line (no restore by any other key). The occupant read FAULTED ⇒ a refusal worded as a
+     * failed `latest` read, no pod ({@link provision} refuses it — every entry that would create one; {@link refuseUnreadableOccupant} spells its two facts).
+     * `connect` is idempotent — the one order of the env's {@link seat}: a refusal this env holds (a restore that did not come back, a pod the cluster refused at
+     * admission, a missing bucket …) is answered as it stands to every later connect on every lane — the previous commit is not waited on again, `latest` is not
+     * read again, no pod is created; a walk in flight (the explicit connect, the lazy one of the first operation, `reconnect`, a resume) ⇒ THAT walk's answer (one pod
+     * creation, one restore, one refusal line), a caller's abort withdrawing only its own wait; a pod already holding the workspace ⇒ its handle, nothing created
+     * (the engine's restore seat is commonly not the first connection: a delegated child touched the env during its placement check); otherwise one walk. A
+     * failure that is not held (a pod that could not be created, a space read that failed) ⇒ the next connect walks afresh. The abort signal of the connect that
+     * started the walk is the one in force for the walk.
      */
     connect(config?: RemoteConnectConfig): Promise<ConnectResult>;
     /** The one walk of a connect ({@link connect} runs it once at a time) — also the resumed leg's walk when its park packed nothing ({@link restorePointOf},
@@ -402,7 +461,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * The restore point's fill (`workspace-fill.ts`): a pod whose workspace this env just minted or restored is handed over only once the fill seat placed
      * its content — through {@link fillChannel} (this adapter's own exec, never the public face: inside a connect the public face waits on that very connect).
      * A fill that does not complete releases the pod (no tool and no run-end snapshot may see a half-filled workspace); a refusal that would answer the same
-     * again (`standing`) is held for the env ({@link holdRefusal}). No seat ⇒ the pod as it came. `origin` tells the seat whether the workspace was minted
+     * again (`standing`) is held for the env (its {@link seat}). No seat ⇒ the pod as it came. `origin` tells the seat whether the workspace was minted
      * (a new pod with nothing restored: the space off / unavailable / without `latest`, or a dangling restore point — `latest` or a park snapshot whose archive is gone)
      * or restored (the space's `latest`, or a park snapshot whose archive came back). A park that packed nothing resumes through a new connect, so it reads as that connect does.
      */
@@ -430,21 +489,22 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** The space lane is on but this run's session has no occupant (no such session — {@link SpaceOccupant}) — said once per env
      *  (at connect, or at a destroy with a pod). `reason` = the reading's word. */
     private sayUnavailable;
-    /** Hold `error` as this env's refusal ({@link connectRefusal}) and answer it — the ONE writer of the slot (the restore and the pod's admission both write through it). */
-    private holdRefusal;
     /**
      * The cluster created this env's pod and it ended `Failed` (or `Succeeded`) before it ever ran — the kubelet refused it at admission
      * (`SysctlForbidden` when `K8S_SANDBOX_IPV6=disabled` meets a kubelet that does not allow the two sysctls, a node-affinity miss, no capacity on the
-     * node …): the env's refusal ({@link holdRefusal}), in the one `connect_failed` form with the kubelet's reason in the sentence — so the operation that meets
+     * node …): the env's refusal (held by its {@link seat}: `env.sandbox_refused`, standing) with the kubelet's reason in the sentence — so the operation that meets
      * it, and every later one, says what the cluster said, instead of a new pod per operation. One `sandbox_pod_refused{pod, phase, reason, detail}` line per env
      * (`detail` = the kubelet's own text, cut). A retry of the run builds a fresh env, which asks the cluster afresh.
      */
     private refusePod;
     /**
-     * A lane that is on is keyed by an occupant read that FAULTED (`unreadable`) ⇒ this env creates no pod: the refusal, in the one
-     * space-read failure form ({@link spaceReadFailed} — a failed `latest` / commit-row read says the same), naming the knob of every
-     * lane that refuses; one `workspace_space_unreadable_occupant{sessionId, code}` line per env. `code` = the store error's code,
-     * never its text. Not a knob: there is no honest way to run a space we could not read — a retry of the run reads it again.
+     * A lane that is on is keyed by an occupant read that FAULTED (`unreadable`) ⇒ this env creates no pod: the refusal, worded as the space-read failures are
+     * (a failed `latest` / commit-row read says the same head), naming the knob of every lane that refuses; one `workspace_space_unreadable_occupant{sessionId, code}`
+     * line per env. `code` = the store error's code, never its text. Not a knob: there is no honest way to run a space we could not read. Two facts, by the code:
+     *  - `session.incarnation_missing` — the session row is there and carries no occupant token: a data defect that answers the same to every read ⇒ standing
+     *    (`env.occupant_missing`, held by the {@link seat}); the way out is the row (give it its token, or delete the session) or the knob;
+     *  - any other code (the read timed out, the store failed, an answer the projection could not read) ⇒ it heals by itself: a retry of the run reads it again
+     *    (`connect_failed`). The reading is this env's, fixed at construction, so this env answers it to every operation all the same.
      */
     private refuseUnreadableOccupant;
     /** Every space-lane operator line: the space is named by its incarnation's log prefix only ({@link snapshotLine} does the rest). */
@@ -457,12 +517,11 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  here, before any request ({@link refuseUnreadableOccupant}): never retried (the reading is this env's, fixed at construction). */
     private provision;
     /**
-     * Lazy-connect on first use — 🔴 core NEVER calls `connect()` (verified: the Runner only calls `resumeVM` on
-     * the resume path), so an adapter that demands an explicit connect can never work through the production
-     * hand-tool path (lazy-connect belongs in the adapter). `destroyed` is terminal. Concurrent first ops share ONE pod create — through
-     * {@link connect}'s one connect in flight, the same seat the explicit connect shares. How long a failure stands is {@link connect}'s: a failure of that
-     * attempt (a pod that could not be created, a space read that failed) ⇒ the next op connects afresh; the env's refusal ({@link connectRefusal}) ⇒ the
-     * next op's connect answers that same refusal at once.
+     * Lazy-connect on first use — an operation may meet the env before anything connected it (a delegated child's placement check, a factory layer writing into
+     * the env before handing it over), so the adapter connects itself; the engine's explicit connect at the leg's restore seat then finds it connected (the
+     * {@link seat}'s idempotent order). `destroyed` is terminal. Concurrent first ops share ONE pod create — through {@link connect}'s one walk in flight, the same
+     * seat the explicit connect shares. How long a failure stands is the seat's: a failure of that attempt (a pod that could not be created, a space read that
+     * failed) ⇒ the next op connects afresh; the env's held refusal ⇒ the next op's connect answers that same refusal at once.
      */
     private ensureConnected;
     /**
@@ -554,7 +613,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * snapshotKey()+s3Presign() pair so the two call sites can't diverge.
      */
     private presignSnapshot;
-    /** The key prefix of every snapshot object this env signs — the ONE reading of `keyPrefix` (unset ⇒ the default); its form is judged in {@link presignSnapshot}. */
+    /** The key prefix of every snapshot object this env signs — `workspaceSnapshotPrefixOf`, the ONE reading of `keyPrefix` (unset ⇒ the default; the boot bucket check lists under the same reading); its form is judged in {@link presignSnapshot}. */
     private snapshotKeyPrefix;
     /** A lane's partition prefix inside the bucket — the ONE place it is spelled (`presignSnapshot` signs under it; the reclaim reads the listing against it).
      *  The partition segment is validated by `presignSnapshot` before a URL is signed. */
@@ -591,8 +650,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * The store answered `404 NoSuchBucket` — to the space's `latest` read (`read: "pointer"`) or to a restore's archive GET (`read: "archive"`, either lane:
      * the pod relays the store's answer, {@link restoreSnapshot}): the workspace snapshot bucket does not exist, so this workspace can be neither restored nor
      * saved — a run started on it would work on an empty /workspace and lose everything it wrote. One fact, one consequence on both lanes and both reads: the
-     * env's refusal ({@link holdRefusal}) naming the bucket and the knob that picks it — the pointer read in the one space-read failure form ({@link spaceReadFailed}),
-     * the archive read in the same words — and one `workspace_snapshot_bucket_missing{bucket, code, effect}` line per env, carrying `space` on the space lane and
+     * env's refusal (`env.snapshot_bucket_missing`, standing, held by the {@link seat}) naming the bucket and the knob that picks it — the pointer read worded as the
+     * space-read failures are ({@link spaceReadFailed}), the archive read in the same words — and one `workspace_snapshot_bucket_missing{bucket, code, effect}` line per env, carrying `space` on the space lane and
      * `sessionId` on the park lane (the refusal stands until destroy: later connects and operations answer it without another read or line; a retry of the run
      * builds a fresh env, which asks the store afresh — a bucket created in between is found). The boot probe (`snapshot-bucket-presence.ts`) refuses a boot
      * where the bucket is already missing; this is the same judgement ({@link isNoSuchBucketAnswer}) for a bucket that went missing afterwards or that the probe
@@ -706,7 +765,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  - space: the archive `latest` names is THERE and did not come back ({@link RestoreFailureClass}): the run is refused all the
      *    same — never an empty workspace (the user's changes are still in the bucket) — with exactly one `workspace_restore_failed`
      *    line (its `attempts`; an attempt that failed before one that succeeded is no line) and a refusal naming the two ways out,
-     *    held for the env ({@link connectRefusal}).
+     *    held for the env by its {@link seat} (`env.sandbox_refused`, standing).
      * A pod that could not be created is that attempt's failure, not the archive's: returned as it is — no line, nothing held, the
      * next connect tries again. An abort during the pause ends the restore `aborted` (not the archive's either).
      */
@@ -877,6 +936,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  循环(上限 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?: {
@@ -925,6 +986,13 @@ export declare function createSpaceReclaimer(config: K8sEnvConfig, deps?: K8sEnv
  * nodes that join after boot are read at the next boot. Never throws (a read failure is an `unreadable` gap).
  */
 export declare function checkSandboxEgressPolicy(config: K8sEnvConfig, deps?: K8sEnvDeps): Promise<SandboxEgressGap[]>;
+/**
+ * The missing cluster-API credential fact of this k8s config's control-plane access ({@link RemoteK8sExecutionEnv.missingApiCredential}), or `undefined`. The boot
+ * gate's judgment: the one judge ({@link resolveK8sApiAccess}) over the config and the process's in-cluster identity. Never throws.
+ */
+export declare function sandboxApiCredentialFact(config: K8sEnvConfig, deps?: K8sEnvDeps): K8sApiCredentialFact | undefined;
+/** The control plane's reading of this lane's credentials ({@link RemoteK8sExecutionEnv.apiCredentialReading}; a control-plane env, no pod). Never throws. */
+export declare function readSandboxApiCredentials(config: K8sEnvConfig, deps?: K8sEnvDeps): Promise<ApiCredentialReading>;
 /** The boot reading of one sandbox Secret seat for this k8s config ({@link RemoteK8sExecutionEnv.secretSeatReading}; a control-plane env, no pod). Never throws. */
 export declare function readSandboxSecretSeat(config: K8sEnvConfig, seat: SandboxSecretSeatKind, deps?: K8sEnvDeps): Promise<SandboxSecretSeat>;
 /**