@sema-agent/server 7.141.0 → 7.143.0

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

@@ -24,6 +24,7 @@ import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, typ
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
+import type { WorkspaceFill, WorkspaceFillOf } from "./workspace-fill.js";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** Minimal optional observability hooks (kept structural so the adapter stays standalone-testable). */
@@ -75,6 +76,8 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers, LaneHomeCo
     dataTimeoutMs?: number;
     /** `SANDBOX_READ_FLOOR`(keep | off;缺席 ⇒ keep):本沙箱守不守读拒表的字节地板 = 读地板模块服务本车道 ∧ 本键不是 off(`sandbox-read-floor.ts`)。 */
     sandboxReadFloor?: SandboxReadFloorKnob;
+    /** 恢复点的填充座(`workspace-fill.ts`;工厂按 run 装配):沙箱新建 / 恢复之后、交给本环境之前,经本适配器已连上的通道往工作区里放内容。缺席 ⇒ 不放。 */
+    workspaceFill?: WorkspaceFill;
 }
 /** Minimal slice of the E2B `Sandbox` static API the adapter uses — injectable so tests pass a fake. */
 export interface SandboxApi {
@@ -124,9 +127,12 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private destroyed;
     /** 家目录的座(主张在场 ⇒ 每只沙箱对证 · 否则建沙箱那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。 */
     private readonly homeSeat;
-    /** 家目录:沙箱答了而与主张不一致(或答的不是绝对路径)⇒ 这只环境的拒,记一次、此后每次连接 / 恢复原样回它(同一模板同一个答案:不再建沙箱、不再问)。 */
-    private homeRefusal?;
-    /** In-flight connect/resume, memoized so concurrent lazy first-use OR resume provisions exactly one VM (no double-bill). */
+    /** 这只环境的拒 —— 记一次、此后每次连接 / 恢复原样回它(同一模板同一个答案:不再建沙箱、不再问)。两个写者:家目录(沙箱答了而与主张不一致,或答的不是绝对路径)
+     *  与恢复点的填充(换一台沙箱也是同一个答的拒:种子不是项目包、摘要不符、镜像没有 `tar`、镜像预置撞名 —— `FillOutcome.standing`)。 */
+    private connectRefusal?;
+    /** In-flight connect/resume, memoized so concurrent lazy first-use OR resume provisions exactly one VM (no double-bill). `target` = the snapshot a resume
+     *  restores (`undefined` = a fresh sandbox): {@link resumeVM} shares only a resume of the SAME snapshot — a connect for anything else is not the
+     *  workspace it is asked to restore (it waits that one out, then releases the sandbox it left). */
     private connecting?;
     /** Count of exec/execStream calls in flight — `suspendVM` refuses while > 0 (council #4: never snapshot a running command). */
     private activeCommands;
@@ -150,6 +156,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     /** 地板模块的三件原语。引导命令经 {@link startIn}(起动形 `bootstrap`:只在附着中合法);放置 = root 建目录 → `files.write`(root)写暂存件 →
      *  root `chmod 0755 && mv -f`;中继 = 以模块给的身份起一只长连后台命令(stdin 开着:`sendStdin` 写答,stdout 回调读问)。 */
     private floorTransport;
+    /** 收据句柄。还没连上(懒环境:续跑腿的引擎在 `resumeVM` **之前**先取它比车道)⇒ 未连接形 `{ sandboxId: "(unconnected)", provider, mountPath }`(与 k8s 车道同形),
+     *  不抛 —— 抛了,续跑腿在恢复之前就失败。 */
     workspaceHandle(): WorkspaceHandle;
     /**
      * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
@@ -197,6 +205,11 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** The one walk of a resume ({@link resumeVM} memoizes it). */
+    private resumeWalk;
+    /** Kill the fresh sandbox this env holds (minted before a restore point that restores another): no second billable VM, no answer from the wrong workspace.
+     *  The connect memo is the calling resume's own ({@link resumeVM}) — left as it is. */
+    private releaseMinted;
     private doResumeVM;
     /** Cross-replica re-attach to a still-running VM = v2 ([ref] council #15: v1.5 always snapshots→resumeVM). */
     reconnect(_sessionToken: SessionToken): Promise<{
@@ -227,6 +240,10 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      * 上界 = 控制面 RPC 的墙钟(`rpcTimeoutMs`:问一个环境变量,不是跑用户命令)。
      */
     private homeVerdict;
+    /** 恢复点的填充:有座 ⇒ 经这只沙箱的通道({@link fillChannel})放(`origin` = 新建的沙箱 / 恢复出来的沙箱);没有 ⇒ 什么都不放。 */
+    private fillAt;
+    /** 恢复点手里的通道:固定命令经唯一起动接缝(起动形 `adapter`,与引擎命令同一执行用户)、写 = `files.write`(与文件面同一个缺省用户);两件都受数据墙钟。 */
+    private fillChannel;
     /** BL-31 — (re)start the periodic sandbox-lifetime extension. `setTimeout(timeoutMs)` resets the auto-kill window
      *  from now; we re-arm at ~80% of the (clamped, ≤1h) window so a long-held sandbox never expires mid-run. A no-op
      *  when paused/destroyed; `unref`'d so it never keeps the process alive; cleared on destroy. */
@@ -380,6 +397,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
  * so a task that never touches the hand (e.g. a leader that only plans) pays zero VM cost. The Runner owns the
  * lifetime and calls `destroy()` on task end (via `hasDestroy`); a never-used env's destroy is a no-op.
  */
-export declare function e2bExecutionEnvFactory(config: RemoteContainerEnvConfig, deps?: RemoteContainerEnvDeps): ExecutionEnvFactory;
+export declare function e2bExecutionEnvFactory(config: Omit<RemoteContainerEnvConfig, "workspaceFill"> & {
+    readonly workspaceFillOf?: WorkspaceFillOf;
+}, deps?: RemoteContainerEnvDeps): ExecutionEnvFactory;
 export {};
 //# sourceMappingURL=remote-env-e2b.d.ts.map

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

@@ -35,7 +35,7 @@ export class RemoteContainerExecutionEnv {
     handle;
     destroyed = false;
     homeSeat;
-    homeRefusal;
+    connectRefusal;
     connecting;
     activeCommands = 0;
     paused = false;
@@ -138,10 +138,7 @@ export class RemoteContainerExecutionEnv {
         };
     }
     workspaceHandle() {
-        if (!this.handle) {
-            throw new RemoteExecutionError("connect_failed", "workspaceHandle() called before connect()");
-        }
-        return this.handle;
+        return this.handle ?? { sandboxId: "(unconnected)", provider: PROVIDER, mountPath: this.cwd };
     }
     async getHost(port) {
         const conn = await this.ensureConnected();
@@ -162,17 +159,18 @@ export class RemoteContainerExecutionEnv {
         }
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (this.homeRefusal)
-            return { ok: false, error: this.homeRefusal };
+        if (this.connectRefusal)
+            return { ok: false, error: this.connectRefusal };
         if (this.paused)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resumeVM(snapshotId) before use") };
         if (this.sbx)
             return ok(this.workspaceHandle());
         if (this.connecting)
-            return this.connecting;
-        this.connecting = this.doConnect(config);
-        const r = await this.connecting;
-        if (!r.ok)
+            return this.connecting.promise;
+        const mine = { target: undefined, promise: this.doConnect(config) };
+        this.connecting = mine;
+        const r = await mine.promise;
+        if (!r.ok && this.connecting === mine)
             this.connecting = undefined;
         return r;
     }
@@ -201,6 +199,14 @@ export class RemoteContainerExecutionEnv {
                 await sbx.kill().catch(() => { });
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
             }
+            const filled = await this.fillAt(sbx, this.cfg.mountPath, "minted");
+            if (!filled.ok || this.destroyed) {
+                await sbx.kill().catch(() => { });
+                this.cfg.metrics?.inc("remote_env_connect_total", { provider: PROVIDER, result: "error" });
+                if (!filled.ok && filled.standing)
+                    this.connectRefusal = filled.error;
+                return { ok: false, error: filled.ok ? new RemoteExecutionError("connect_failed", "execution env destroyed during connect") : filled.error };
+            }
             this.sbx = sbx;
             this.paused = false;
             this.startKeepAlive();
@@ -250,20 +256,50 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.remoteError(e, options?.abortSignal?.aborted ? "aborted" : "unknown") };
         }
     }
-    async resumeVM(snapshotId, options) {
+    resumeVM(snapshotId, options) {
         if (this.destroyed)
-            return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
-        if (this.homeRefusal)
-            return { ok: false, error: this.homeRefusal };
+            return Promise.resolve({ ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") });
+        if (this.connectRefusal)
+            return Promise.resolve({ ok: false, error: this.connectRefusal });
         if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
-            return ok(this.workspaceHandle());
-        if (this.connecting)
-            return this.connecting;
-        this.connecting = this.doResumeVM(snapshotId, options);
-        const r = await this.connecting;
-        if (!r.ok)
-            this.connecting = undefined;
-        return r;
+            return Promise.resolve(ok(this.workspaceHandle()));
+        const inFlight = this.connecting;
+        if (inFlight?.target === snapshotId)
+            return inFlight.promise;
+        const mine = { target: snapshotId, promise: this.resumeWalk(inFlight, snapshotId, options) };
+        this.connecting = mine;
+        const forget = () => {
+            if (this.connecting === mine)
+                this.connecting = undefined;
+        };
+        mine.promise.then((r) => {
+            if (!r.ok)
+                forget();
+        }, forget);
+        return mine.promise;
+    }
+    async resumeWalk(inFlight, snapshotId, options) {
+        if (inFlight !== undefined) {
+            await inFlight.promise;
+            if (this.destroyed)
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
+            if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
+                return ok(this.workspaceHandle());
+        }
+        if (this.sbx && !this.paused)
+            await this.releaseMinted(snapshotId);
+        return this.doResumeVM(snapshotId, options);
+    }
+    async releaseMinted(resumed) {
+        const sbx = this.sbx;
+        if (sbx === undefined)
+            return;
+        this.sbx = undefined;
+        this.handle = undefined;
+        this.stopKeepAlive();
+        await this.disposeBackgroundShells();
+        await this.rpc("sandbox.kill", () => sbx.kill()).catch((e) => this.cfg.logger?.warn("remote_env_minted_release_failed", { sandboxId: sbx.sandboxId, error: errMsg(e) }));
+        this.cfg.logger?.info?.("remote_env_minted_released", { sandboxId: sbx.sandboxId, resumed });
     }
     async doResumeVM(snapshotId, options) {
         try {
@@ -288,6 +324,18 @@ export class RemoteContainerExecutionEnv {
                 this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "error" });
                 return { ok: false, error: home };
             }
+            const filled = await this.fillAt(sbx, restoredRoot, "restored");
+            if (this.destroyed) {
+                await sbx.kill().catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
+            }
+            if (!filled.ok) {
+                await this.rpc("sandbox.pause", (signal) => sbx.pause({ signal }), undefined, this.cfg.dataTimeoutMs).catch((e) => this.cfg.logger?.warn?.("remote_env_fill_refused_repause_failed", { sandboxId: sbx.sandboxId, error: errMsg(e) }));
+                this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "error" });
+                if (filled.standing)
+                    this.connectRefusal = filled.error;
+                return { ok: false, error: filled.error };
+            }
             this.sbx = sbx;
             this.paused = false;
             this.startKeepAlive();
@@ -340,9 +388,39 @@ export class RemoteContainerExecutionEnv {
             return undefined;
         const error = new RemoteExecutionError("connect_failed", verdict.refusal);
         if (verdict.answered)
-            this.homeRefusal = error;
+            this.connectRefusal = error;
         return error;
     }
+    fillAt(sbx, root, origin) {
+        return this.cfg.workspaceFill === undefined ? Promise.resolve({ ok: true }) : this.cfg.workspaceFill.fill(this.fillChannel(sbx), root, origin);
+    }
+    fillChannel(sbx) {
+        return {
+            run: async (command) => {
+                const s = this.startIn(ADAPTER_START, command, undefined);
+                if (!s.ok)
+                    return { ok: false, error: s.error.message };
+                try {
+                    const r = await this.rpc("workspace.fill", (signal) => this.runIn(sbx, s.value, { signal, timeoutMs: this.cfg.dataTimeoutMs }), undefined, this.cfg.dataTimeoutMs);
+                    return { ok: true, exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+                }
+                catch (e) {
+                    if (e instanceof CommandExitError)
+                        return { ok: true, exitCode: e.exitCode, stdout: e.stdout, stderr: e.stderr };
+                    return { ok: false, error: errMsg(e) };
+                }
+            },
+            write: async (abs, bytes) => {
+                try {
+                    await this.rpc("files.write", (signal) => sbx.files.write(abs, toArrayBuffer(bytes), { signal }), undefined, this.cfg.dataTimeoutMs);
+                    return { ok: true };
+                }
+                catch (e) {
+                    return { ok: false, error: errMsg(e) };
+                }
+            },
+        };
+    }
     startKeepAlive() {
         this.stopKeepAlive();
         const everyMs = Math.max(30_000, Math.floor(this.cfg.timeoutMs * 0.8));
@@ -1130,10 +1208,15 @@ export class RemoteContainerExecutionEnv {
     }
 }
 export function e2bExecutionEnvFactory(config, deps) {
-    return (ctx) => new RemoteContainerExecutionEnv({
-        ...config,
-        metadata: { ...config.metadata, semaManaged: "1", sessionId: ctx.sessionId, ...(ctx.taskId ? { taskId: ctx.taskId } : {}) },
-    }, deps);
+    const { workspaceFillOf, ...base } = config;
+    return (ctx) => {
+        const workspaceFill = workspaceFillOf?.(ctx);
+        return new RemoteContainerExecutionEnv({
+            ...base,
+            metadata: { ...base.metadata, semaManaged: "1", sessionId: ctx.sessionId, ...(ctx.taskId ? { taskId: ctx.taskId } : {}) },
+            ...(workspaceFill !== undefined ? { workspaceFill } : {}),
+        }, deps);
+    };
 }
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);

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

@@ -123,6 +123,9 @@ export interface K8sEnvConfig extends LaneHomeConfig {
     /** Run-end outcome seat — called once per `destroy()` that attempted a space snapshot (the factory's caller binds it
      *  to the run, so the run's terminal frame can carry `workspaceSnapshot: "failed"`). */
     onWorkspaceSnapshot?: (outcome: "saved" | "failed") => void;
+    /** 恢复点的填充座(`workspace-fill.ts`;工厂按 run 装配):pod 的工作区铸出 / 恢复之后、`connect` / `resumeVM` 交还之前,经 {@link RemoteK8sExecutionEnv} 自己的
+     *  exec 通道(不经公开面 —— 连接进行中公开面会等同一只连接记忆)往工作区里放内容。缺席 ⇒ 不放。 */
+    workspaceFill?: WorkspaceFill;
     /**
      * 🔴 ADDITIVE pod-spec patch (a SERVICE-side adapter seam, NOT a core seam: the K8s pod shape is
      * provider-specific, so it stays in the adapter per [ref]). A deployment supplies extra volumes / volumeMounts
@@ -171,6 +174,7 @@ import { type SandboxSecretSeatKind, type SandboxSecretVerb } from "./k8s-exec-p
 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;
@@ -318,9 +322,12 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private readonly inFlight;
     /** Resolvers of {@link whenIdle}: woken when the last command in flight ends. */
     private idleWaiters;
-    /** This env's one connect in flight (see {@link connect}): the explicit connect, the lazy connect and `reconnect` that arrive while it runs
-     *  share it — one pod creation, one restore (the E2B race lesson). Cleared the moment it settles, whatever the outcome. */
+    /** This env's one lifecycle walk in flight — a connect ({@link connect}) or a resume ({@link resumeVM}): the explicit connect, the lazy connect of
+     *  the first operation and `reconnect` that arrive while it runs share its answer — one pod creation, one restore, one fill (the E2B race lesson).
+     *  Cleared the moment it settles, whatever the outcome (by the walk that set it, never by an earlier one). */
     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
@@ -355,6 +362,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private cacheUnavailableSaid;
     private readonly logger?;
     private readonly onWorkspaceSnapshot?;
+    private readonly workspaceFill?;
     private readonly cacheMisses?;
     constructor(config: K8sEnvConfig, deps?: K8sEnvDeps);
     /** The lease seat of the pod this env holds now — `undefined` without a broker seat or without a pod (the server's lease writes follow it: a resumed env holds a new pod and a new seat). */
@@ -378,6 +386,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 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
      * 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).
@@ -389,8 +398,23 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 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.
      */
     connect(config?: RemoteConnectConfig): Promise<ConnectResult>;
-    /** The one walk of a connect ({@link connect} runs it once at a time). */
+    /** 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},
+     *  under the resume's own hold of the same gate). */
     private establish;
+    /**
+     * 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
+     * (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.
+     */
+    private settle;
+    /** The restore point's channel: a fixed command through the one start seam (start form `adapter`, the engine's commands' identity) and a write in
+     *  {@link writeChunked}'s form — both straight on {@link runExec} with the data bound (never {@link ensureConnected}). */
+    private fillChannel;
+    /** Release the pod this env holds (its workspace is not handed over): the pod deleted, its seats cleared. No pod ⇒ nothing. */
+    private releasePod;
     /** This env holds a workspace its `destroy()` will commit ⇒ arm its seat on the space's commit fence (from here the
      *  run's terminal write fences the space; `workspace-space-commit.ts`). Each write of this run's row sets its deadline to
      *  now + the upload's own wall-clock bound (`dataTimeoutMs`). No-op unless the space lane is open. */
@@ -426,9 +450,11 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 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.
      */
     private refuseUnreadableOccupant;
-    /** Every space-lane operator line: the space is named by its incarnation's log prefix only, and free text (a curl
-     *  stderr, a fetch error) passes {@link redactIncarnations} — the full token never reaches a log body. */
+    /** Every space-lane operator line: the space is named by its incarnation's log prefix only ({@link snapshotLine} does the rest). */
     private spaceLine;
+    /** Every snapshot operator line, both lanes — the ONE redaction seat: each string field (a key, a curl stderr, a fetch error, an effect) passes
+     *  {@link redactIncarnations}, so a full incarnation-shaped token never reaches a log body, whatever text carried it there. */
+    private snapshotLine;
     /** A fresh pod (create → Running → workspace root), bounded retry — THE seat every pod of this env is created through
      *  ({@link connect} and, via {@link restoreSnapshot}, {@link resumeVM}). A lane keyed by an occupant read that faulted ⇒ refused
      *  here, before any request ({@link refuseUnreadableOccupant}): never retried (the reading is this env's, fixed at construction). */
@@ -630,9 +656,14 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      */
     private uploadSnapshot;
     /**
-     * Resume a workspace snapshot onto a FRESH pod (resume = executionEnvFactory rebuild + resumeVM):
-     * provision a pod, then download + untar the snapshot into the workspace ({@link restoreSnapshot}, lane `park`). A
-     * missing object (empty/plan-only snapshot) resumes as a clean workspace.
+     * Resume a parked run's workspace onto a FRESH pod (resume = executionEnvFactory rebuild + resumeVM). Where the leg's workspace comes from is
+     * read off the park's snapshot id — it says what the park packed ({@link snapshotIdHolds}), never guessed from what the store answers:
+     *  - an archive ⇒ provision a pod, then download + untar it into the workspace ({@link restoreSnapshot}, lane `park`): it came back ⇒ `restored`
+     *    (never seeded); it is not there ⇒ a dangling restore point, the same rule on both lanes ({@link dropDangling}: one line, an empty workspace);
+     *  - nothing (the env held no pod when it parked — the run parked before anything touched its hand) ⇒ there is no workspace of the park to
+     *    restore, so the leg's restore point is the one a new connect has ({@link establish}): space open ⇒ the previous commit waited out and
+     *    `latest` restored (none ⇒ a fresh workspace), space off ⇒ a fresh workspace — never a fresh workspace beside a `latest` that the leg's
+     *    run-end commit would then overwrite. No archive is asked for under such an id.
      *
      * [ref]①(priorHandle 根保真)——k8s 走**诚实臂**而非绑定臂:pod 的 workspace volume 挂在**当前**
      * 配置根(cfg.mountPath),往 priorHandle.mountPath 绑=往容器 rootfs untar 大工作区,ephemeral-storage
@@ -641,14 +672,16 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 变更窗的分歧由 core 侧 fail-closed reopen 兜底,审批不烧错根。
      */
     resumeVM(snapshotId: SnapshotId, options?: VmLifecycleOptions): Promise<ConnectResult>;
-    /**
-     * The ONE tar download (both lanes): provision a FRESH pod, download + untar the lane's archive into the workspace.
-     * A missing archive (404) starts from the clean workspace on both lanes — what differs is what it means:
-     *  - park: a plan-only suspend has no object — nothing to say;
-     *  - space: `latest` dangles (its pointer is only written after a successful upload, so the archive was removed later —
-     *    by the bucket's lifecycle rule or a hand): the data is gone by an operator rule ⇒ loud and continuable —
-     *    {@link dropDanglingLatest} (one `workspace_latest_dangling` line, the pointer deleted); the run's own run-end
-     *    snapshot then becomes the new `latest`.
+    /** The one walk of a resume ({@link resumeVM} runs it under the connect gate). */
+    private resumeWalk;
+    /** The resumed leg's restore point, chosen by what the park's id names ({@link resumeVM}) — a closed set, one arm each. */
+    private restorePointOf;
+    /**
+     * The ONE tar download (both lanes): provision a FRESH pod, download + untar the lane's archive into the workspace. Only an id that names an
+     * archive reaches it ({@link snapshotIdHolds}: a park that packed nothing resumes through {@link establish}; `latest` names only an object
+     * that was written). So a missing archive (404) is one fact on both lanes — the restore point names data that is gone (removed later, by the
+     * bucket's lifecycle rule or a hand) ⇒ loud and continuable, ONE rule: {@link dropDangling} (one `workspace_latest_dangling` line), and the
+     * run continues on the clean workspace, origin `minted` (no restorable tree ⇒ the restore point seeds it, exactly as on a fresh connect).
      * An attempt that does not complete releases the pod it provisioned: no tool and no run-end snapshot may ever see a torn
      * workspace. A transient class ({@link restoreFailureIsTransient}) is tried again on a fresh pod after the `retry.backoffMs`
      * pause, up to the lane's {@link RESTORE_MAX_ATTEMPTS}; a non-transient one ends the restore at once. The lane then says what
@@ -665,12 +698,18 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** The pause before a restore's next attempt (`retry.backoffMs`, the adapter's one retry pause). `false` ⇒ aborted (now or during it). */
     private restorePause;
     /**
-     * `latest` names an archive that is not there ([ref]): one `workspace_latest_dangling{space, key, deleted}` line and the
-     * pointer is deleted (the next run must not trip on it again); the run continues on the empty workspace. A pointer
-     * delete that fails rides on the same line (`deleted: false` + the error) — the next run then says it once more.
-     * This env is the space's only writer here (the commit fence admits one per space), so the delete is a plain one.
-     */
-    private dropDanglingLatest;
+     * A restore point names an archive that is not there — the data is gone by an operator rule (a bucket lifecycle rule, a hand): loud and
+     * continuable, ONE rule on both lanes — one `workspace_latest_dangling{lane, key, …}` line, and the run continues on the empty workspace
+     * {@link restoreSnapshot} hands over. `key` = the object the id names, spelled by {@link snapshotBase} (the one spelling of both partitions).
+     * What each lane adds is only what it holds:
+     *  - space: its `latest` pointer is deleted (the next run must not trip on it again); the line carries `space` and `deleted` — a delete that
+     *    fails rides on the same line (`deleted: false` + the error) and the next run says it once more. This env is the space's only writer here
+     *    (the commit fence admits one per space), so the delete is a plain one. The run's own run-end snapshot then becomes the new `latest`;
+     *  - park: there is no pointer to drop (the id lives in the engine's checkpoint); the line carries the session id. With the space open, the
+     *    resumed leg's run-end snapshot then becomes the space's new `latest`.
+     * Both lines pass the one redaction seat ({@link snapshotLine}).
+     */
+    private dropDangling;
     /**
      * Honest post-resume consistency ([ref] §5 council #8): the workspace FILES are restored byte-for-byte
      * from the snapshot, so read-before-edit hashing already lines up — there's nothing to re-fetch. In-VM