@sema-agent/server 7.146.0 → 7.148.0

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

@@ -1,4 +1,4 @@
-import { FileError, type InheritEnvPolicy, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions, type SecretEnvFinding } from "@sema-agent/core";
+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, 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";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
@@ -54,6 +54,12 @@ export interface HostEnvConfig extends LaneHomeConfig {
      *  single-user TOC host lane. `HOST_BG_ENABLED=false` is an additional global kill switch(🪦 旧名
      *  `HOST_BG_DISABLED` 自 server 3.0.0 起是 fail-loud 墓碑:设了即拒启并指路新名,不再被读取)。 */
     backgroundShell?: boolean;
+    /**
+     * `true` = 本服务自己的 git worktree 基环境(`git worktree add / remove / prune`;`boot/execution-env.ts` 铸一只):它**从不交给引擎**,引擎不读它的 {@link withheldEnv},
+     * 所以它扣了哪些名字没有引擎通告替它说 —— 它的 spawn 记在自己的现场 `server.remote-env-host.git-base`(披露行是唯一读法)。缺省(交给引擎的环境:工厂产物、
+     * worktree 子代环境、嵌入方交给 `Runner` 的环境)记在 `server.remote-env-host.spawn-env`:名字由引擎的 `inherit_env.names_withheld` 说,只记计数。
+     */
+    gitBase?: true;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
     /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
@@ -258,14 +264,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     disposeBackgroundShells(opts?: {
         except?: readonly BackgroundShellId[];
     }): Promise<void>;
-    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>>;
     /** 管道旧形(win32 / spool 打开失败的回退;行为=1.225 及以前的 exec 原样)。 */
     private execViaPipes;
     /** [ref] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"
@@ -428,7 +427,9 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *    `inheritedHostEnv(policy)`:三个继承词(`"all"` / `"scrub"` / `[names]`)只在引擎一处判,本进程自有凭据名(起服声明)任何词都不交 ——
      *    本类不再有三臂字面(7.129.0 / core 7.51.1;修前 `all` 是 `{ ...process.env }` 零剥除)。**不碰 shell**,所以读面(如 {@link cdPath})任何时候
      *    都能读,不依赖 shell 是否已落定。
-     *  · **spawn 层**(`spawnShell` 在场)—— 这一次是真要交给子进程:经 `hostSubprocessEnv` 记剥除(`spawnShell` 缺席 ⇒ 只读组合 `composeHostSubprocessEnv`,
+     *  · **spawn 层**(`spawnShell` 在场)—— 这一次是真要交给子进程:经 `hostSubprocessEnv` 记剥除。交给引擎的环境(缺省)只记**计数**、不写名字:扣了哪些名字由引擎读
+     *    {@link withheldEnv} 说(`inherit_env.names_withheld`;现场 `server.remote-env-host.spawn-env`,表里 `told:"engine-notice"`);本服务自己的 git 基环境({@link HostEnvConfig.gitBase})
+     *    引擎读不到,记在 `server.remote-env-host.git-base`,披露行照写(`spawnShell` 缺席 ⇒ 只读组合 `composeHostSubprocessEnv`,
      *    不计数:一次没发生的 spawn 不进剥除账),win32 上把 `SHELL` 钉到已解析的 Git Bash({@link pinHostShell},在大小写折叠**之前**)。
      * 披露与钉同一个开关(`spawnShell`)—— 「真 spawn」只有一种说法,不再有 `disclose` 与钉各自一个布尔。
      * 引擎对点到自有凭据名的白名单在这里**抛**(spawn 时的拒;构造器已先问过同一只判)—— 子进程不起,拒句带名。

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";
@@ -17,6 +18,7 @@ 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 { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
 const inflightFsDrainWaitMs = () => numEnvOr("HOST_FS_DRAIN_WAIT_MS", 10_000, 1);
@@ -104,7 +106,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)`);
             }
@@ -250,8 +252,8 @@ export class RemoteHostExecutionEnv {
                     await fs.mkdir(dir, { recursive: true });
                     const outPath = path.join(dir, "out");
                     const errPath = path.join(dir, "err");
-                    const outFh = await fs.open(outPath, "w");
-                    const errFh = await fs.open(errPath, "w");
+                    const outFh = await fs.open(outPath, "w", OWNER_ONLY_FILE_MODE);
+                    const errFh = await fs.open(errPath, "w", OWNER_ONLY_FILE_MODE);
                     let child;
                     try {
                         const sh = hostShell();
@@ -419,14 +421,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();
@@ -465,6 +468,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);
@@ -474,9 +479,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);
@@ -487,15 +492,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()); };
@@ -504,11 +511,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) => {
@@ -530,10 +538,10 @@ export class RemoteHostExecutionEnv {
             mkdirSync(dir, { recursive: true });
             const outPath = path.join(dir, "out");
             const errPath = path.join(dir, "err");
-            const fdOut = openSync(outPath, "ax", 0o600);
+            const fdOut = openSync(outPath, "ax", OWNER_ONLY_FILE_MODE);
             let fdErr;
             try {
-                fdErr = openSync(errPath, "ax", 0o600);
+                fdErr = openSync(errPath, "ax", OWNER_ONLY_FILE_MODE);
             }
             catch (e) {
                 try {
@@ -549,7 +557,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;
@@ -739,7 +747,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();
@@ -749,29 +761,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) => {
@@ -1314,7 +1327,7 @@ export class RemoteHostExecutionEnv {
     }
     childEnv(perCommand, spawnShell) {
         const base = spawnShell !== undefined
-            ? hostSubprocessEnv({ site: "server.remote-env-host.spawn-env", policy: this.cfg.inheritEnv, allow: [] })
+            ? hostSubprocessEnv({ site: this.cfg.gitBase === true ? "server.remote-env-host.git-base" : "server.remote-env-host.spawn-env", policy: this.cfg.inheritEnv, allow: [] })
             : composeHostSubprocessEnv({ policy: this.cfg.inheritEnv, allow: [] });
         if (this.cfg.env)
             Object.assign(base, this.cfg.env);

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
@@ -857,10 +852,13 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
-    /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts`;父目录与私有暂存目录由编排的准备那一步建):上传 = 分块整份写进私有目录里的暂存件;
-     *  提交 = 文件面探针 exec。两者同一身份(同一只容器里的 exec)。 */
+    /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts`;父目录与私有暂存目录由编排的准备那一步建):上传 = 分块整份写进私有目录里的暂存件
+     *  (阶段一 = 建连,见 {@link prepareChunked};阶段二 = 分块写);提交 = 文件面探针 exec。两者同一身份(同一只容器里的 exec)。 */
     private stagedLane;
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** 阶段一(备件):建连(懒连接;首块之前 —— 取消落在这里 ⇒ `aborted`、没有一块发出);阶段二:分块写({@link writeChunked}),每一块仍走 {@link execData}
+     *  (它的 {@link ensureConnected} 在建好连之后只剩生命周期的准入判:`destroy` 开始之后,后面的块不再写)。 */
+    private prepareChunked;
     /**
      * Write `content` to `abs` via argv-embedded base64, chunked at WRITE_CHUNK_BYTES (no stdin on the exec
      * channel we use; v4 has no per-channel close). `truncateFirst` → the FIRST chunk uses `>` (overwrite),