@sema-agent/server 7.147.0 → 7.149.0

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

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 import { spawn } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
@@ -13,10 +14,12 @@ import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions,
 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 { capabilitiesFor } from "../execution-lane-caps.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { LaneHomeSeat, laneHomeRefusal } from "../lane-home-probe.js";
 import { composeHostSubprocessEnv, hostSubprocessEnv, withheldFromHostSubprocess } from "../server-secret-env.js";
 import { nameTooLongCode } from "./remote-env-file-error.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
+import { createWorkspaceCustody } from "./workspace-custody.js";
 import { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
@@ -33,6 +36,8 @@ const unsupported = (op) => ({
     ok: false,
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a host target (the operator's own machine — no container boundary, not snapshotable; capabilities.suspendable=false)`),
 });
+const BORROWED = Object.freeze({ kind: "borrowed" });
+const RELEASED = Object.freeze({ kind: "released" });
 const UNSUPPORTED_SCHEDULER_CAPS = {
     supported: false,
     maxScheduledPerScope: 0,
@@ -79,6 +84,8 @@ export class RemoteHostExecutionEnv {
     cfg;
     prepared = false;
     destroyed = false;
+    teardown;
+    teardownSettled = false;
     spoolRootDir;
     liveFgSpools = new Set();
     inflightFs = new Set();
@@ -105,7 +112,7 @@ export class RemoteHostExecutionEnv {
             const drained = (await Promise.race([settled, deadline])) !== timedOut;
             if (!drained && !this.inflightFsDrainWarned) {
                 this.inflightFsDrainWarned = true;
-                console.warn(`RemoteHostExecutionEnv.destroy: ${this.inflightFs.size} in-flight filesystem write(s) did not settle within ` +
+                writeLogText("stderr", `RemoteHostExecutionEnv.destroy: ${this.inflightFs.size} in-flight filesystem write(s) did not settle within ` +
                     `${waitMs}ms — returning from teardown now; removal of ${this.workspaceDir} stays ordered AFTER those writes ` +
                     `and will land when they finish (a write that never settles, e.g. a FIFO target inside the workspace, defers it)`);
             }
@@ -121,20 +128,21 @@ export class RemoteHostExecutionEnv {
             this.spoolRootDir = mkdtempSync(path.join(os.tmpdir(), "sema-host-spool-"));
         return this.spoolRootDir;
     }
-    persistent;
+    tenure;
     preparing;
     handle;
     constructor(config = {}) {
         if (config.workspaceDir) {
             this.workspaceDir = path.resolve(config.workspaceDir);
-            this.persistent = true;
+            const shared = config.custody?.sharedRoot;
+            this.tenure = shared !== undefined ? { kind: "held", root: path.resolve(shared) } : BORROWED;
         }
         else {
             const base = 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.persistent = false;
+            this.tenure = { kind: "held", root: this.workspaceDir };
         }
         const inheritEnvProblem = inheritEnvPolicyProblem(config.inheritEnv);
         if (inheritEnvProblem !== undefined)
@@ -155,6 +163,19 @@ export class RemoteHostExecutionEnv {
         if (homeVerdict !== undefined)
             throw laneHomeRefusal(homeVerdict);
     }
+    get releasing() {
+        return this.teardown;
+    }
+    get released() {
+        return this.teardownSettled;
+    }
+    leftover = undefined;
+    get settled() {
+        return this.teardownSettled && this.tenure.kind !== "held";
+    }
+    get heldWorkspace() {
+        return this.tenure.kind === "held" ? this.tenure.root : undefined;
+    }
     workspaceHandle() {
         return this.handle;
     }
@@ -189,9 +210,13 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
         return ok(this.handle);
     }
-    async destroy() {
-        if (this.destroyed)
-            return;
+    destroy() {
+        this.teardown ??= this.tearDown().finally(() => {
+            this.teardownSettled = true;
+        });
+        return this.teardown;
+    }
+    async tearDown() {
         this.destroyed = true;
         const p = this.preparing;
         this.preparing = undefined;
@@ -214,11 +239,15 @@ export class RemoteHostExecutionEnv {
             catch { }
             this.spoolRootDir = undefined;
         }
-        if (this.persistent)
+        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(this.workspaceDir, { recursive: true, force: true });
-            untrackEphemeralHostWorkspace(this.workspaceDir);
+            await fs.rm(tenure.root, { recursive: true, force: true });
+            untrackEphemeralHostWorkspace(tenure.root);
         }
         catch {
         }
@@ -227,12 +256,13 @@ export class RemoteHostExecutionEnv {
         return this.destroy();
     }
     get backgroundCapabilities() {
+        const backgroundShellOn = (this.cfg.backgroundShell ?? DEPLOYMENT_SHAPE_PREDICATES.backgroundShell.holds({ remoteExec: { provider: PROVIDER } })) && hostBackgroundShellEnabled();
         return {
-            supported: (this.cfg.backgroundShell ?? true) && hostBackgroundShellEnabled(),
+            supported: backgroundShellOn,
             maxConcurrent: HOST_BG_MAX_CONCURRENT,
             defaultBgTimeoutSec: HOST_BG_DEFAULT_TIMEOUT_SEC,
             maxBgTimeoutSec: HOST_BG_MAX_TIMEOUT_SEC,
-            supportsDetach: (this.cfg.backgroundShell ?? true) && hostBackgroundShellEnabled(),
+            supportsDetach: backgroundShellOn,
         };
     }
     _bgManager;
@@ -420,14 +450,15 @@ export class RemoteHostExecutionEnv {
         const cwd = this.resolve(options?.cwd ?? this.cwd);
         const timeoutMs = options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs;
         const detachSignal = options?.detachSignal;
+        const adoptOnTimeout = detachSignal !== undefined && options?.autoBackgroundOnTimeout === true;
         if (!IS_WIN32 && hostExecSpoolEnabled()) {
             const spool = this.openFgSpool();
             if (spool)
-                return this.execViaSpool(command, options, cwd, timeoutMs, detachSignal, spool);
+                return this.execViaSpool(command, options, cwd, timeoutMs, detachSignal, adoptOnTimeout, spool);
         }
-        return this.execViaPipes(command, options, cwd, timeoutMs, detachSignal);
+        return this.execViaPipes(command, options, cwd, timeoutMs, detachSignal, adoptOnTimeout);
     }
-    execViaPipes(command, options, cwd, timeoutMs, detachSignal) {
+    execViaPipes(command, options, cwd, timeoutMs, detachSignal, adoptOnTimeout) {
         return new Promise((resolve) => {
             const outBuf = new RollingTailBuffer();
             const errBuf = new RollingTailBuffer();
@@ -466,6 +497,8 @@ export class RemoteHostExecutionEnv {
                 forceSettleTimer ??= armPipeDestroyGrace(child);
             };
             const timer = setTimeout(() => {
+                if (adoptOnTimeout && onDetach("timeout"))
+                    return;
                 kill();
                 finish({ ok: false, error: createCutError({ code: "timeout", message: `host exec exceeded ${timeoutMs}ms` }, buildCapturedOutput(outBuf, errBuf)) });
             }, timeoutMs);
@@ -475,9 +508,9 @@ export class RemoteHostExecutionEnv {
             };
             if (options?.abortSignal)
                 options.abortSignal.addEventListener("abort", onAbort, { once: true });
-            const onDetach = () => {
+            const onDetach = (cause) => {
                 if (settled)
-                    return;
+                    return false;
                 const out = outBuf.result();
                 const err = errBuf.result();
                 child.stdout?.off("data", onExecOut);
@@ -488,15 +521,17 @@ export class RemoteHostExecutionEnv {
                 if (shellId === undefined) {
                     child.stdout?.on("data", onExecOut);
                     child.stderr?.on("data", onExecErr);
-                    return;
+                    return false;
                 }
                 clearTimeout(timer);
                 if (forceSettleTimer)
                     clearTimeout(forceSettleTimer);
                 options?.abortSignal?.removeEventListener("abort", onAbort);
+                removeDetachListener?.();
                 ticket?.release();
                 settled = true;
-                resolve(ok({ stdout: seedOut, stderr: seedErr, exitCode: 0, detached: { shellId } }));
+                resolve(ok({ stdout: seedOut, stderr: seedErr, exitCode: 0, detached: { shellId, ...(cause !== undefined ? { cause } : {}) } }));
+                return true;
             };
             const onExecOut = (d) => { outBuf.push(d); if (tee)
                 feedMemStream(tee.out, d, HOST_BG_MEM_CAP); options?.onStdout?.(d.toString()); };
@@ -505,11 +540,12 @@ export class RemoteHostExecutionEnv {
             child.stdout?.on("data", onExecOut);
             child.stderr?.on("data", onExecErr);
             if (detachSignal) {
+                const onDetachSignal = () => void onDetach();
                 if (detachSignal.aborted)
-                    onDetach();
+                    onDetachSignal();
                 else {
-                    detachSignal.addEventListener("abort", onDetach, { once: true });
-                    removeDetachListener = () => detachSignal.removeEventListener("abort", onDetach);
+                    detachSignal.addEventListener("abort", onDetachSignal, { once: true });
+                    removeDetachListener = () => detachSignal.removeEventListener("abort", onDetachSignal);
                 }
             }
             child.on("error", (e) => {
@@ -550,7 +586,7 @@ export class RemoteHostExecutionEnv {
             return undefined;
         }
     }
-    execViaSpool(command, options, cwd, timeoutMs, detachSignal, spool) {
+    execViaSpool(command, options, cwd, timeoutMs, detachSignal, adoptOnTimeout, spool) {
         const EXIT_SETTLE_DRAIN_MS = 500;
         const PUMP_MS = 200;
         const ROTATE_BYTES = 8 * 1024 * 1024;
@@ -740,7 +776,11 @@ export class RemoteHostExecutionEnv {
                     return { ok: false, error: createCutError(c, captured()) };
                 });
             };
-            const timer = setTimeout(() => cut({ code: "timeout", message: `host exec exceeded ${timeoutMs}ms` }), timeoutMs);
+            const timer = setTimeout(() => {
+                if (adoptOnTimeout && onDetach("timeout"))
+                    return;
+                cut({ code: "timeout", message: `host exec exceeded ${timeoutMs}ms` });
+            }, timeoutMs);
             const onAbort = () => cut({ code: "aborted", message: "host exec aborted" });
             if (options?.abortSignal?.aborted) {
                 onAbort();
@@ -750,29 +790,30 @@ export class RemoteHostExecutionEnv {
                 options.abortSignal.addEventListener("abort", onAbort, { once: true });
             pump = setInterval(() => pumpOnce(feed), PUMP_MS);
             pump.unref?.();
-            const onDetach = () => {
+            const onDetach = (cause) => {
                 if (settled || exited)
-                    return;
+                    return false;
                 pumpOnce(feed);
                 if (settled)
-                    return;
+                    return false;
                 const fgDropped = spoolRemoved.out + spoolRemoved.err;
                 const shellId = this.adoptRunningExecSpool(child, spool, { out: 0, err: 0 }, fgDropped);
                 if (shellId === undefined)
-                    return;
+                    return false;
                 handedOver = true;
-                finish(() => {
+                return finish(() => {
                     const o = outBuf.result();
                     const e = errBuf.result();
-                    return ok({ stdout: markTruncated(o.text, o.droppedBytes), stderr: markTruncated(e.text, e.droppedBytes), exitCode: 0, detached: { shellId } });
+                    return ok({ stdout: markTruncated(o.text, o.droppedBytes), stderr: markTruncated(e.text, e.droppedBytes), exitCode: 0, detached: { shellId, ...(cause !== undefined ? { cause } : {}) } });
                 });
             };
             if (detachSignal) {
+                const onDetachSignal = () => void onDetach();
                 if (detachSignal.aborted)
-                    onDetach();
+                    onDetachSignal();
                 else {
-                    detachSignal.addEventListener("abort", onDetach, { once: true });
-                    removeDetachListener = () => detachSignal.removeEventListener("abort", onDetach);
+                    detachSignal.addEventListener("abort", onDetachSignal, { once: true });
+                    removeDetachListener = () => detachSignal.removeEventListener("abort", onDetachSignal);
                 }
             }
             const settleFromTermination = (code, signal) => {
@@ -1239,7 +1280,7 @@ export class RemoteHostExecutionEnv {
     ensurePrepared() {
         if (this.prepared)
             return Promise.resolve();
-        if (!this.persistent) {
+        if (this.cfg.workspaceDir === undefined) {
             try {
                 this.assertWorkspaceParentWritable();
             }
@@ -1252,8 +1293,8 @@ export class RemoteHostExecutionEnv {
                 .mkdir(this.workspaceDir, { recursive: true })
                 .then(() => {
                 this.prepared = true;
-                if (!this.persistent)
-                    trackEphemeralHostWorkspace(this.workspaceDir);
+                if (this.tenure.kind === "held")
+                    trackEphemeralHostWorkspace(this.tenure.root);
             })
                 .catch((e) => {
                 this.preparing = undefined;
@@ -1293,7 +1334,7 @@ export class RemoteHostExecutionEnv {
             const rel = path.relative(real(root), real(abs));
             return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
         };
-        return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.persistent && inside(this.workspaceDir));
+        return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.tenure.kind === "borrowed" && inside(this.workspaceDir));
     }
     async fsReady(p, opts) {
         if (this.destroyed) {
@@ -1377,11 +1418,39 @@ function asError(e) {
 function signalNumber(signal) {
     return os.constants.signals[signal];
 }
-export function hostExecutionEnvFactory(config = {}) {
-    return (ctx) => new RemoteHostExecutionEnv({
-        ...config,
-        id: config.id ?? ctx.taskId ?? ctx.sessionId,
-    });
+export function hostExecutionEnvFactory(config = {}, legOf = () => ({})) {
+    const custody = createWorkspaceCustody();
+    const heldElsewhere = (self, root) => custody.holder((m) => m !== self && m.heldWorkspace === root) !== undefined;
+    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 } : {}) } });
+            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,7 +2,7 @@ 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 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 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";
@@ -207,7 +207,7 @@ export interface K8sEnvDeps {
     }>;
     openExec?: (url: string, headers: Record<string, string>) => ExecSocket;
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
-    /** Worker-side object-store requests (the space pointer, listing, deletes). Default: global `fetch`. */
+    /** 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;
     /** 这只环境手里的读地板模块(缺席 ⇒ `createSandboxReadFloor` 按旋钮选;钉注入守地板的模块)。能力块的 `keepsReadFloor` 读它的状态。 */
     readFloor?: SandboxReadFloor;
@@ -308,9 +308,6 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private readonly floor;
     cwd: string;
     private podName?;
-    /** Cluster-internal pod address, captured when the pod reaches Running — the LSP `getHost` surface.
-     *  Lifecycle mirrors podName exactly (set on connect, cleared on suspend/destroy/dead-reconnect). */
-    private podIP?;
     /** The broker lease seat of the pod this env holds (set with {@link podName}; read through {@link sandboxLeaseRef}). */
     private leaseRef?;
     private destroyed;
@@ -586,24 +583,33 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** Worker-side object-store request, bounded by the control-plane RPC wall-clock — or a tighter caller deadline — and
      *  the caller's abort. */
     private storeFetch;
-    /** Read one space pointer object: its trimmed body, or `undefined` = absent (404 — the bucket is there, the key is not); a 404 that says
-     *  `NoSuchBucket` is NOT absence — the bucket itself is missing, and the run is refused ({@link refuseMissingBucket}); any other failure is a typed
-     *  `connect_failed` naming the pointer. */
+    /** Read one space pointer object — the ONE reading of a pointer answer: its trimmed body, or `undefined` = absent (404 — the bucket is there, the key is
+     *  not); a 404 that says `NoSuchBucket` is NOT absence — the bucket itself is missing (`bucketMissing`; what that means is the caller's: a connect refuses
+     *  the run, {@link readLatest}; a write's read-back reads it as not done, {@link writePointer}); any other failure is a typed `connect_failed` naming the pointer. */
     private readPointer;
     /**
-     * The store answered the `latest` read with `404 NoSuchBucket`: the workspace snapshot bucket does not exist, so this space can be neither restored
-     * nor saved — a run started on it would work on an empty /workspace and lose everything it wrote. The env's refusal ({@link holdRefusal}), in the one
-     * space-read failure form ({@link spaceReadFailed}), naming the bucket and the knob that picks it; one `workspace_snapshot_bucket_missing{space, bucket, code, effect}`
-     * line per env (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 could not prove either way.
+     * 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
+     * `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
+     * could not prove either way.
      */
     private refuseMissingBucket;
-    /** Read the space's `latest` pointer. The body's shape is checked where it is used — restoreSnapshot → presignSnapshot
-     *  (the one segment check). */
+    /** Read the space's `latest` pointer for a connect: a `NoSuchBucket` answer refuses the run ({@link refuseMissingBucket}). The body's shape is checked
+     *  where it is used — restoreSnapshot → presignSnapshot (the one segment check). */
     private readLatest;
     /** PUT one space pointer object (a single-object PUT replaces the object atomically) or DELETE it; `timeoutMs` = a
-     *  caller deadline tighter than the RPC bound. */
+     *  caller deadline tighter than the RPC bound. The outcome is what an answer the worker holds proves: the store's own answer to the request
+     *  when it reached the worker (2xx — or 404 to a DELETE — ⇒ done; any other status ⇒ not done); a request whose answer did NOT reach the worker
+     *  (it threw: a reset, the bound, a refused redirect) may have taken effect all the same ⇒ decided by reading the pointer back ({@link readPointer},
+     *  the one pointer reading): it names `body` (a DELETE: it is absent) ⇒ done; anything else, or a read-back that fails ⇒ not done. The read-back decides
+     *  only INSIDE the caller's deadline (`timeoutMs`, counted from the call): the commit's deadline is its fence's, and past it a next run may already have
+     *  abandoned this commit and be restoring the previous `latest` — a write seen landing after that is not this commit's to call done (its `done` would
+     *  let the commit prune the archive that run is restoring). No time left, or a read-back that answers after the deadline ⇒ not done. */
     private writePointer;
     /**
      * Wait out the previous run's space commit — its row in the run store's `workspace_space_commit` (the ONE seat of
@@ -649,12 +655,20 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
         error: RemoteExecutionError;
     }>;
     /**
-     * The ONE tar upload (both lanes): tar the workspace to a pod-local file, presigned PUT into the lane's namespace,
-     * release the pod. `suspendVM` = lane `park`; the run-end space snapshot = lane `space` (its open space). The exclusion
+     * The ONE tar upload (both lanes): tar the workspace to a pod-local file, presigned PUT into the lane's namespace, read the object back
+     * ({@link archiveStored} — the ONE success judgement), release the pod. `suspendVM` = lane `park`; the run-end space snapshot = lane `space` (its open space). The exclusion
      * table (`snapshotExclude`) is applied HERE and nowhere else — each item one `--exclude=./<item>` argument through the one
      * `shellQuote`, anchored at the workspace root (`-C <mount> .` names every member `./…`); no table ⇒ the command as it always was.
      */
     private uploadSnapshot;
+    /**
+     * Is the archive the upload just wrote in the store? — a presigned HEAD of the object, sent by the worker: the ONE success judgement of the tar upload
+     * (both lanes; the space lane moves `latest` only after it, the park lane hands the id to the engine only after it). The id is minted fresh for this
+     * upload, and an object PUT is atomic, so an object under it is this upload, whole. 2xx ⇒ stored; any other status, or a request that failed (a
+     * redirect is refused by the store egress) ⇒ not proven, a failed upload. `timeoutMs` = what is left of the upload's bound (the save's one data
+     * bound covers its proof too); none left ⇒ not proven. `why` never carries the presigned URL.
+     */
+    private archiveStored;
     /**
      * 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:
@@ -679,9 +693,11 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /**
      * 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).
+     * that was written). A 404 is read off the store's own answer, which the pod relays ({@link RESTORE_404_MARKER}): `NoSuchBucket` ({@link isNoSuchBucketAnswer})
+     * ⇒ the bucket itself is missing — the pod is released and the env refused, both lanes ({@link refuseMissingBucket}, never an empty workspace); any other 404
+     * is a missing archive, 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
@@ -713,7 +729,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /**
      * 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
-     * process state (a language server) is gone by design; core/the LSP manager re-establishes it lazily. So
+     * process state (a background process) is gone by design; whoever needs it re-establishes it lazily. So
      * this is a successful no-op rather than the previous `unsupported` (which forced a cold rebuild).
      */
     postResumeInit(): Promise<{
@@ -798,33 +814,12 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * kill the remote process (disposable-pod posture, see header).
      */
     private runExec;
-    exec(command: string, options?: ExecOpts): Promise<Result<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-        detached?: {
-            shellId: string;
-        };
-    }, ExecutionError>>;
+    exec(command: string, options?: ExecOpts): Promise<Result<ExecResult, ExecutionError>>;
     /** 文件面探针的 exec(车PL 验修 ③):只用绝对路径,**不进工作目录**、没有 cwd 守卫 —— 工作目录进不去时探针照样答真话(`permission_denied` /
      *  `not_found` 由命令自己的 stderr 归),core 的 `isDeadCwd` 不会把「进不去」读成「没了」。 */
     private fsExec;
     /** buffered exec 的唯一体:`call` 定了整串、stderr 的 started 行剥法与收口(`remote-shell.ts` `createCwdGuardedCall`)。 */
     private execCall;
-    /**
-     * LSP surface (lsp/manager.ts `isLspCapable` duck-type, [ref] §13.1): cluster-internal address for a
-     * port on the sandbox pod. The E2B counterpart returns a public proxy host; a pod has none — the WORKER
-     * must be able to reach pod IPs (in-cluster deployment, or on-node), and the transport is plain `ws://`
-     * (cluster network, no TLS — the per-session bridge token still gates access like on E2B).
-     */
-    getHost(port: number): Promise<string | undefined>;
-    /**
-     * Start a long-lived helper (the LSP bridge) detached from this exec session. Unlike E2B — which reaps a
-     * foreground command's process group on completion, forcing a native background API — k8s exec just closes
-     * the session: a `nohup`'d child with detached stdio survives, reparented to the container's PID 1 (the
-     * gate#2 background-gradle runs proved this through the production path). Output goes to /tmp for postmortem.
-     */
-    startBackground(command: string): Promise<void>;
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
     /**
      * A background job cannot outlive its pod (`activeDeadlineSeconds` ≈ `timeoutMs`), so the BG ceiling is clamped to