@sema-agent/server 7.149.0 → 7.151.0

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

@@ -1,3 +1,4 @@
+import { type PlatformPath } from "node:path";
 import { FileError, type InheritEnvPolicy, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, 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 ExecutionEnvFactoryContext, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions, type SecretEnvFinding } from "@sema-agent/core";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { type CustodyMember } from "./workspace-custody.js";
@@ -112,7 +113,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     /**
      * core 7.56.0 [ref]:shell 子进程继承的环境里**收不到**的条目(名 + 规则,从不带值)—— 与 {@link cdPath} 同一只组合的读面
      * (`server-secret-env.ts` 的 `withheldFromHostSubprocess`:继承组合扣下的发现,减去 `cfg.env` 这条显式授予重供的键)。逐命令的 `options.env`
-     * 是引擎自己交的显式授予,它知道(core KL-1963-b 同一残余)。只读:不披露、不计数、不碰 shell。
+     * 是引擎自己交的显式授予,它知道(core [ref] 同一残余)。只读:不披露、不计数、不碰 shell。
      */
     get withheldEnv(): readonly SecretEnvFinding[];
     private readonly workspaceDir;
@@ -194,6 +195,11 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private tenure;
     /** Memoized lazy `mkdir -p` so concurrent first-use prepares the workspace exactly once. */
     private preparing?;
+    /**
+     * 建连座(`remote-env-connect-seat.ts`):`connect` 的唯一次序 —— 建工作目录在飞 ⇒ 等那一次(调用方的取消只退它自己的等待)· 已建好 ⇒ 当下的把手 · 否则建一次。
+     * 本车道不记拒:主张证不了的家目录在构造时就拒了(环境不铸),建目录的失败是那一次的(下一次重来)。
+     */
+    private readonly seat;
     private readonly handle;
     constructor(config?: HostEnvConfig);
     /** 收场的进度(托管表读):活着 ⇒ 缺席;{@link destroy} 开始 ⇒ 那一次收场。 */
@@ -214,6 +220,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** 工作目录已建好时 `connect` 的那一答。 */
+    private preparedAnswer;
+    /** 建工作目录失败时 `connect` 的那一答(那一次的失败:下一次重来)。 */
+    private prepareFailed;
     suspendVM(_options?: VmLifecycleOptions): Promise<{
         ok: true;
         value: SnapshotId;
@@ -474,6 +484,13 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private childHome;
     private fileError;
 }
+/**
+ * host 环境配置座的拼法(构造期的 `workspaceDir` / `workspaceBase` / 托管 `sharedRoot`,与工厂托管判读的腿目录同一只):与执行缝同一只读者
+ * (`exec-path-law.ts` 的 `anchoredPath`)—— 绝对的原样,相对的锚在本进程工作目录上,不折 `..`、不解链接。win32 的盘相对拼写(`C:work`)相对的是
+ * **那只盘**上的工作目录:锚在本进程在那只盘上的工作目录(`resolve("C:")`)下、余下原样接上(不这样读,它会被当成一段名字接在工作目录后面:`<cwd>\C:work`)。
+ * `pathApi` 只为让 POSIX 上的钉量 win32 形;生产读本机的 `path`。
+ */
+export declare function hostSeatPath(p: string, pathApi?: PlatformPath): string;
 /**
  * `ExecutionEnvFactory` for the TOC `host` backend (DUAL-MODE-DESIGN §5). Wiring this onto a deployment makes
  * its agent run DIRECTLY on the worker's machine (no container) — the local-coding-agent default. One fresh

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

@@ -1,10 +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, 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";
@@ -12,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, } 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";
@@ -20,7 +21,9 @@ 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 } from "../memory-scope.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);
@@ -130,18 +133,23 @@ export class RemoteHostExecutionEnv {
     }
     tenure;
     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", root: 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.workspaceDir = anchorUnder(path, base, `sema-host-${sanitizeId(id)}-${suffix}`);
             this.tenure = { kind: "held", root: this.workspaceDir };
         }
         const inheritEnvProblem = inheritEnvPolicyProblem(config.inheritEnv);
@@ -184,18 +192,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");
     }
@@ -1004,7 +1008,7 @@ export class RemoteHostExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.join(...parts));
+        return ok(joinedPath(path, parts));
     }
     async readTextFile(p, abortSignal) {
         const ready = await this.fsReady(p);
@@ -1106,7 +1110,7 @@ export class RemoteHostExecutionEnv {
             const entries = await fs.readdir(abs, { withFileTypes: true });
             const out = [];
             for (const e of entries) {
-                const child = path.join(abs, e.name);
+                const child = anchorUnder(path, abs, e.name);
                 let size = 0;
                 let mtimeMs = 0;
                 try {
@@ -1247,7 +1251,7 @@ export class RemoteHostExecutionEnv {
         });
     }
     resolve(p) {
-        return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
+        return anchoredPath(path, this.cwd, p);
     }
     assertWorkspaceParentWritable() {
         const uid = process.getuid?.();
@@ -1324,14 +1328,22 @@ export class RemoteHostExecutionEnv {
         const abs = this.resolve(p);
         if (!existsSync(abs))
             return false;
-        const real = (x) => { try {
-            return realpathSync(x);
-        }
-        catch {
-            return path.resolve(x);
-        } };
+        const real = (x) => {
+            try {
+                return physicalPathOf(x);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const target = real(abs);
+        if (target === undefined)
+            return false;
         const inside = (root) => {
-            const rel = path.relative(real(root), real(abs));
+            const r = real(root);
+            if (r === undefined)
+                return false;
+            const rel = path.relative(r, target);
             return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
         };
         return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.tenure.kind === "borrowed" && inside(this.workspaceDir));
@@ -1399,6 +1411,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";
 }
@@ -1421,36 +1440,18 @@ function signalNumber(signal) {
 export function hostExecutionEnvFactory(config = {}, legOf = () => ({})) {
     const custody = createWorkspaceCustody();
     const heldElsewhere = (self, root) => custody.holder((m) => m !== self && m.heldWorkspace === root) !== undefined;
+    const rootHolding = (dir) => custody.holder((m) => m.heldWorkspace !== undefined && pathIsWithin(m.heldWorkspace, dir, canonicalPathOf))?.heldWorkspace;
     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 sharedRoot = dir === undefined ? undefined : rootHolding(hostSeatPath(dir));
             const env = new RemoteHostExecutionEnv({ ...config, ...leg, id: config.id ?? identity, custody: { heldElsewhere, ...(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,11 +2,12 @@ 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 { 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";
 export interface K8sEnvConfig extends LaneHomeConfig {
@@ -175,13 +176,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;
@@ -325,11 +319,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)。与其余读得出家目录的车道同一只判官、同一句拒。 */
@@ -381,18 +379,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 +402,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 +430,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 +458,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;
     /**
@@ -591,8 +591,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 +706,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 +877,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?: {