@sema-agent/server 7.125.1 → 7.126.0

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

@@ -88,6 +88,9 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     private readonly cfg;
     /** core `ExecutionEnv.homeDir`([ref]):设备上执行用户的 home。见 `DeviceEnvConfig.homeDir`。 */
     readonly homeDir?: string | undefined;
+    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在设备上(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+     *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
+    readonly cdPath: "unknown";
     /**
      * 🔴 `suspendable: false` 在 core 契约里**同时断言**「工作区在目标上外部持久」(remote-env.ts 的
      * load-bearing 不变量)—— 设备工作区 = 员工机磁盘,真持久 ✅,park-only 降级腿因此合法可用。

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

@@ -120,6 +120,7 @@ function assertPosixDevicePlatform(os, deviceId) {
 export class RemoteDeviceExecutionEnv {
     cfg;
     homeDir;
+    cdPath = "unknown";
     capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true };
     externalContentTarget = true;
     hostLocalPaths = false;

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

@@ -100,6 +100,9 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     cwd: string;
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
+    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 e2b 沙箱里(模板镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+     *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
+    readonly cdPath: "unknown";
     private readonly cfg;
     private readonly sandboxApi;
     private sbx?;
@@ -129,6 +132,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
+        canonicalPathAuthoritative: boolean;
     };
     workspaceHandle(): WorkspaceHandle;
     /**

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

@@ -19,6 +19,7 @@ const ok = (value) => ({ ok: true, value });
 export class RemoteContainerExecutionEnv {
     cwd;
     homeDir;
+    cdPath = "unknown";
     cfg;
     sandboxApi;
     sbx;
@@ -42,7 +43,7 @@ export class RemoteContainerExecutionEnv {
         this.homeDir = config.homeDir;
         this.sandboxApi = deps.sandboxApi ?? Sandbox;
     }
-    capabilities = { isolation: true, suspendable: true };
+    capabilities = { isolation: true, suspendable: true, canonicalPathAuthoritative: true };
     workspaceHandle() {
         if (!this.handle) {
             throw new RemoteExecutionError("connect_failed", "workspaceHandle() called before connect()");

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

@@ -94,6 +94,12 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     cwd: string;
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
+    /**
+     * core 7.49.0 #1554:shell 子进程**真拿到的** `CDPATH` 条目(`[]` = 没有)—— 删除守卫按它解裸 `cd <dir>`。本车道的命令就是本机子进程,
+     * env 是本类自己组合的(继承姿态 + `cfg.env`),所以说得出:读同一只组合({@link childEnv},不披露),切法与 core `NodeExecutionEnv` 同
+     * (缺席 / 空串 ⇒ `[]`,否则按 `:` 切)。逐命令的 `options.env` 由引擎自己交,它知道。
+     */
+    get cdPath(): readonly string[];
     private readonly workspaceDir;
     private readonly cfg;
     /** Workspace created on disk (lazily, on first use). */
@@ -406,7 +412,13 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  source of the shape rule) minus the config catalog's `secret`-typed names (`scrubServerSecrets`, 7.99.0 F7). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
      *  maps `true`→`"all"` / `false`→`[]`. */
     private inheritMode;
+    /** 每次 spawn 交给子进程的 env(组合 + 剥除披露)。 */
     private mergeEnv;
+    /**
+     * 子进程 env 的**唯一组合**。`disclose` = 这一次是不是真要交给子进程(是 ⇒ scrub 腿经 `hostSubprocessEnv` 记剥除;否 ⇒ 只读组合,
+     * 不计数 —— {@link cdPath} 这类「子进程会拿到什么」的读者走这一臂,一次没发生的 spawn 不进剥除账)。
+     */
+    private childEnv;
     private fileError;
 }
 /**

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

@@ -10,7 +10,7 @@ import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
-import { allowlistedEnv, hostSubprocessEnv } from "../server-secret-env.js";
+import { allowlistedEnv, composeHostSubprocessEnv, hostSubprocessEnv } from "../server-secret-env.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
@@ -57,6 +57,10 @@ export class RemoteHostExecutionEnv {
     }
     cwd;
     homeDir;
+    get cdPath() {
+        const value = this.childEnv(undefined, false).CDPATH;
+        return value === undefined || value === "" ? [] : value.split(":");
+    }
     workspaceDir;
     cfg;
     prepared = false;
@@ -1308,6 +1312,9 @@ export class RemoteHostExecutionEnv {
         return "scrub";
     }
     mergeEnv(perCommand) {
+        return this.childEnv(perCommand, true);
+    }
+    childEnv(perCommand, disclose) {
         const mode = this.inheritMode();
         let base;
         if (mode === "all")
@@ -1315,6 +1322,9 @@ export class RemoteHostExecutionEnv {
         else if (Array.isArray(mode)) {
             base = allowlistedEnv(mode, process.env);
         }
+        else if (!disclose) {
+            base = composeHostSubprocessEnv([]);
+        }
         else {
             base = hostSubprocessEnv({ site: "server.remote-env-host.inherit-scrub", allow: [] });
         }

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

@@ -1,4 +1,6 @@
-import type { WorkspaceSyncCapability } from "../workspace-space.js";
+import { type SpaceReclaimer, type WorkspaceSpacePolicy, type CacheReclaimReason } from "../workspace-space.js";
+import { type SpaceCommitFence } from "../workspace-space-commit.js";
+import { type WorkspaceCacheCapability } from "../workspace-cache.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 } from "@sema-agent/core";
 import type { PodSpecPatch } from "./k8s-exec-protocol.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
@@ -37,8 +39,15 @@ export interface K8sEnvConfig {
     rpcTimeoutMs?: number;
     /** Zero-progress liveness bound for commands (no output AND not finished ⇒ hang). */
     livenessMs?: number;
-    /** File-transfer bound. */
+    /** The ONE data bound (`WORKSPACE_SNAPSHOT_TIMEOUT_MS`; default = `WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT`, owned by
+     *  `workspace-space.ts`): the snapshot upload's and restore's wall-clock, the deadline this replica's commits write into
+     *  their space-commit fence row (a reader judges another run's row by the deadline IN that row, never by this field), and
+     *  a large file transfer's wall-clock. Every use reads this field — never a second number. */
     dataTimeoutMs?: number;
+    /** The snapshot's exclusion table (`WORKSPACE_SNAPSHOT_EXCLUDE`, items already in the closed form — `workspace-space.ts`):
+     *  the ONE tar upload ({@link RemoteK8sExecutionEnv.uploadSnapshot}, both lanes) passes `--exclude=./<item>` per item.
+     *  Absent / empty ⇒ the upload command is what it always was. */
+    snapshotExclude?: readonly string[];
     cpu?: string;
     memory?: string;
     retry?: {
@@ -58,8 +67,8 @@ export interface K8sEnvConfig {
      * trifecta. The presigned URL is used only inside an adapter-issued exec at suspend/resume time, so it never
      * reaches an agent turn.
      *
-     * WORKSPACE SPACE (`workspacePersist`, default `off` — opt-in `space`): the same store also carries the workspace ACROSS
-     * RUNS, in its own sub-prefix `<prefix>/<spaceIncarnation>/space/` — `space/latest` (body = the newest snapshotId) names the
+     * WORKSPACE SPACE (`workspacePersist`, default `space`; `off` = a fresh workspace every run): the same store also carries the workspace ACROSS
+     * RUNS, in its own sub-prefix `<prefix>/<incarnation>/space/` — `space/latest` (body = the newest snapshotId) names the
      * snapshot `connect()` restores; `destroy()` snapshots into `space/`, moves `latest`, keeps the newest `workspaceSnapshotKeep`
      * (the same one upload / one download as suspend / resume, see `SnapshotTarget`). The pointer read / write, the listing and the deletes are
      * WORKER-side requests to `endpoint` (the snapshot-BLOB offload dials the same `MINIO_ENDPOINT` from the worker).
@@ -74,7 +83,7 @@ export interface K8sEnvConfig {
         presignTtlSec?: number;
         /** The workspace-space policy (the capability fact `workspaceSpace`'s witness, handed in by the factory; the adapter
          *  never resolves defaults itself). Absent or `persist: "off"` ⇒ no persistence across runs. */
-        space?: WorkspaceSyncCapability;
+        space?: WorkspaceSpacePolicy;
     };
     /**
      * The PARK lane's partition (`<prefix>/<sessionId>/<snapshotId>.tar.gz`), set by {@link k8sExecutionEnvFactory} from
@@ -84,18 +93,22 @@ export interface K8sEnvConfig {
      * it never decides who reads. Segment shape is validated in exactly one place ({@link RemoteK8sExecutionEnv.presignSnapshot}).
      */
     sessionId?: string;
+    /** The SPACE lane's occupant — handed in per run by the factory binding (`boot/execution-env.ts`); see {@link SpaceOccupant}. */
+    spaceOccupant?: SpaceOccupant;
     /**
-     * The SPACE lane's partition (`<prefix>/<spaceIncarnation>/space/…`): the session OCCUPANT's incarnation token
-     * (`session-incarnation.ts`, the one owner of "is this the same occupant"), handed in per run by the factory binding
-     * (`boot/execution-env.ts`) from the same seat the memory engine reads. Why not the session id: the space lane is read
-     * by whoever runs next in the session, so its partition decides WHO reads — a session id deleted and registered again
-     * (by anyone) is a new occupant and starts from an empty workspace. Absent while persistence is on ⇒ the space lane
-     * does not open for this env (connect restores nothing, destroy saves nothing) and one `workspace_space_unavailable`
-     * line says so — never a fallback to the session id. Never logged whole: operator lines carry `incarnationLogPrefix`.
+     * The build-cache volume per workspace space (`WORKSPACE_CACHE=volume`; the capability fact `workspaceCache`'s witness, handed
+     * in by the factory — absent for a delegated child, whose env opens no space). Keyed by the SAME space key as the space lane
+     * (`spaceOccupant.incarnation`): connect finds / creates the space's claim (`workspaceCacheClaimOf`) and mounts it at `mount`
+     * — outside the workspace mount, so no snapshot ever covers it — and layers the cache env closed table under `podEnv`
+     * (an explicit operator value of the same name wins). A volume that cannot be had (create refused, not bound within
+     * `dataTimeoutMs`, no such session ⇒ no space key) ⇒ the pod starts WITHOUT it and without the cache env: `recordFailOpen` + one
+     * `workspace_cache_unavailable` line. An occupant read that FAULTED is not a miss: the run is refused, as on the space lane
+     * ({@link SpaceOccupant}). Absent ⇒ no claim request, the pod as before.
      */
-    spaceIncarnation?: string;
+    cache?: WorkspaceCacheCapability;
     /** Operator log seat (the e2b adapter's shape): `workspace_snapshot_failed` / `workspace_snapshot_prune_failed` /
-     *  `workspace_space_unavailable` / `workspace_commit_abandoned` / `workspace_commit_marker_stuck`. */
+     *  `workspace_space_unavailable` / `workspace_space_unreadable_occupant` / `workspace_commit_abandoned` / `workspace_latest_dangling` /
+     *  `workspace_restore_failed` / `workspace_cache_fresh` / `workspace_cache_unavailable`. */
     logger?: {
         warn(event: string, fields?: Record<string, unknown>): void;
     };
@@ -115,8 +128,10 @@ export interface K8sEnvConfig {
     podSpecPatch?: PodSpecPatch;
     /** RFC B5 (sema-internal server/docs/design/ENV-SELECT-AND-REGION-SOURCE.md 抽象点②): operator-trusted env injected into the
      *  sandbox container (e.g. `SEMA_PKG_SOURCE=cn|global` — the runtime package-source selector the image's
-     *  pkg-source.sh hook materializes at start). Deployment-region config, NEVER task-controlled. Absent = the
-     *  pod is byte-identical to today. */
+     *  pkg-source.sh hook materializes at start). Deployment config, NEVER task-controlled. This is the pod's ONE container-env
+     *  seat: the region package-source set AND the deployer-named forwarding (`K8S_SANDBOX_ENV` keys, original values) arrive
+     *  here already merged by the boot assembly (explicit names win). Values go into `containers[0].env[]` and nowhere else —
+     *  never a command string, the workspace or a snapshot. Absent = the pod is byte-identical to today. */
     podEnv?: Record<string, string>;
 }
 export { type PodSpecPatch, applyPodSpecPatch } from "./k8s-exec-protocol.js";
@@ -150,6 +165,45 @@ export interface K8sEnvDeps {
     /** Worker-side object-store requests (the space pointer, listing, deletes). Default: global `fetch`. */
     fetch?: typeof fetch;
 }
+/**
+ * One run's space occupant — the space key of both lanes keyed by it (the space lane, the cache volume) — a closed set of three
+ * readings of the session row's cell, read by id from the session store (`SessionStore.incarnationOf`) when the run's env is built:
+ *  - known: `incarnation` — the partition (`<prefix>/<incarnation>/space/…`): the session OCCUPANT's incarnation token
+ *    (`session-incarnation.ts`, the one owner of "is this the same occupant"). Why not the session id: the space lane is read by
+ *    whoever runs next in the session, so its partition decides WHO reads — a session id deleted and registered again (by anyone)
+ *    is a new occupant and starts from an empty workspace. Never logged whole: operator lines carry `incarnationLogPrefix`;
+ *    `fence` — this env's seat on the space's commit fence (the run store's `workspace_space_commit` row,
+ *    `workspace-space-commit.ts`): `connect()` waits on it, the run-end commit holds it;
+ *  - absent: `unread: "incarnation_unknown"` — there is NO space for this run: the store answered that it has no such session
+ *    (deleted / never registered), or this replica holds no commit fence to key one by (see `occupantOf`) ⇒ a lane keyed by it
+ *    does not open (no restore, no save, no volume) and says so in one line;
+ *  - faulted: `fault` — the read did not answer (it threw, or answered something that is not a token): the code of the store's
+ *    error (never its text), `incarnation_read_failed` without one. A space we could not read is not "no space" ⇒ a lane keyed by
+ *    it refuses this env (`RemoteK8sExecutionEnv.provision`, the one pod seat): the run never starts on a workspace it believes is its own.
+ * Never a fallback to the session id.
+ */
+export type SpaceOccupant = {
+    readonly incarnation: string;
+    readonly fence: SpaceCommitFence;
+} | {
+    readonly unread: "incarnation_unknown";
+} | {
+    readonly fault: string;
+};
+/** One failed stage of {@link RemoteK8sExecutionEnv.reclaimSpaceSnapshots}: whose partition (the space's `space/` or the park lane's), listing it, deleting from it,
+ *  or the reclaim call's deadline passing before or while on it (`budget`: the rest was not attempted). */
+export interface ReclaimFailure {
+    readonly lane: "space" | "park";
+    readonly stage: "list" | "delete" | "budget";
+    readonly detail: string;
+}
+/** The failed cache-volume half of a reclaim ({@link RemoteK8sExecutionEnv.reclaimSpaceCache}); `reason` is the closed word set of
+ *  `workspace_cache_reclaim_failed` from the reclaim seat: the delete-by-label failed or answered non-2xx (`delete_failed`), or the reclaim call's
+ *  deadline passed before it was sent or while it was in flight (`budget` — the same word the object half's `stage` uses for the same cause). */
+export interface CacheReclaimFailure {
+    readonly reason: Exclude<CacheReclaimReason, "occupant_unreadable">;
+    readonly detail: string;
+}
 export { execSocketTlsOptions } from "./k8s-exec-protocol.js";
 /** `Error`-or-event → message. Bun's ws shim emits browser-style ErrorEvents (NOT instanceof Error) whose
  *  String() is "[object ErrorEvent]" — that masked the real TLS failure for a whole drill. */
@@ -185,12 +239,24 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private connectPromise?;
     /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
     readonly homeDir?: string | undefined;
+    /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 pod 里(镜像与 pod spec 的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
+     *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
+    readonly cdPath: "unknown";
     private readonly cfg;
     private readonly deps;
+    /** The known occupant's incarnation (`undefined` = this run has no known occupant: a delegated child, an unread session, a direct construction) — the
+     *  ownership mark of every snapshot id this env mints, both lanes ({@link mintSnapshotId}); the space lane's partition is the same reading. */
+    private readonly occupantIncarnation;
     /** This env's space lane (resolved once from the policy + the occupant's incarnation; see {@link SpaceLane}). */
     private readonly spaceLane;
     /** `workspace_space_unavailable` is said once per env. */
     private spaceUnavailableSaid;
+    /** `workspace_space_unreadable_occupant` is said once per env (a retried lazy connect is refused again, silently). */
+    private unreadableOccupantSaid;
+    /** This env's cache volume lane (resolved once from the cache policy + the space key; see {@link CacheLane}). */
+    private readonly cacheLane;
+    /** A cache volume that could not be had is counted and said once per env (a retried connect does not count again). */
+    private cacheUnavailableSaid;
     private readonly logger?;
     private readonly onWorkspaceSnapshot?;
     constructor(config: K8sEnvConfig, deps?: K8sEnvDeps);
@@ -208,20 +274,47 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private openExec;
     /**
      * Connect = the workspace SPACE's restore point. Space lane open ⇒ first wait out a commit still in flight
-     * ({@link awaitSpaceCommit}), then read `<prefix>/<incarnation>/space/latest`: present ⇒
-     * restore it through {@link restoreSnapshot} (the one tar download, shared with `resumeVM`; a missing archive is
-     * refused); absent (404) ⇒ a fresh pod; a read that FAILS ⇒ a loud
-     * `connect_failed` — never a silent fresh workspace (a run that believes it resumed while it did not is the worst form).
-     * Persistence off / no store ⇒ a fresh pod, exactly as before. Persistence on but the occupant unknown ⇒ a fresh pod
-     * and one `workspace_space_unavailable` line (no restore by any other key).
+     * ({@link awaitSpaceCommit}: the run store's commit row), then read `<prefix>/<incarnation>/space/latest`: present ⇒
+     * restore it through {@link restoreSnapshot} (the one tar download, shared with `resumeVM`; an archive that is gone ⇒
+     * loud `workspace_latest_dangling`, the pointer deleted, an empty workspace); absent (404) ⇒ a fresh pod; a read that
+     * FAILS ⇒ a loud `connect_failed` — 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).
+     * 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).
      */
     connect(config?: RemoteConnectConfig): Promise<ConnectResult>;
-    /** The space lane is on but this env's occupant is unknown — said once per env (at connect, or at a destroy with a pod). */
+    /** 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. */
+    private armSpace;
+    /** The env no longer holds a workspace to commit (a commit ended, a park released the pod, or destroy found no pod) ⇒
+     *  end its fence seat: the row this run wrote, if any, is deleted. A delete that fails leaves the row until its deadline —
+     *  the next run waits at most that long and says `workspace_commit_abandoned` (the loud form of a stuck row). */
+    private endSpace;
+    /**
+     * One call to the space's commit fence (the run store), bounded like every other request this adapter makes
+     * (`rpcTimeoutMs`) and abortable: a store that never answers never hangs connect or destroy. The store call itself is
+     * not cancellable — a late answer is dropped; what it may have written dies at its own deadline (the fence's one rule).
+     * Rejects with {@link FenceCallAborted} on abort.
+     */
+    private fenceCall;
+    /** The space lane is on but this run's session has no occupant (no such session — {@link SpaceOccupant}) — said once per env
+     *  (at connect, or at a destroy with a pod). `reason` = the reading's word. */
     private sayUnavailable;
+    /**
+     * A lane that is on is keyed by an occupant read that FAULTED (`unreadable`) ⇒ this env creates no pod: the refusal, in the one
+     * space-read failure form ({@link spaceReadFailed} — a failed `latest` / commit-row read says the same), naming the knob of every
+     * lane that refuses; one `workspace_space_unreadable_occupant{sessionId, code}` line per env. `code` = the store error's code,
+     * never its text. Not a knob: there is no honest way to run a space we could not read — a retry of the run reads it again.
+     */
+    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. */
     private spaceLine;
-    /** A fresh pod (create → Running → workspace root), bounded retry. Shared by {@link connect} and {@link resumeVM}. */
+    /** 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). */
     private provision;
     /**
      * Lazy-connect on first use — 🔴 core NEVER calls `connect()` (verified: the Runner only calls `resumeVM` on
@@ -230,7 +323,38 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * pod create; a failed connect clears the memo (next op retries); `destroyed` is terminal.
      */
     private ensureConnected;
+    /**
+     * One pod creation attempt. With the cache volume open: first the space's claim ({@link attachCache} — found, or created),
+     * then the pod carrying it; a pod that only waits on a claim that does not bind within the data bound is deleted and ONE pod
+     * without the volume is created in its place (the run starts; the miss is counted). Every other failure is the attempt's.
+     */
     private connectOnce;
+    /** The cache volume for this pod creation, or `undefined` (off, or not to be had — counted and said there). */
+    private attachCache;
+    /** Find the space's claim, or create it (labelled with the space digest; size = the policy's; the cluster's default
+     *  StorageClass). `fresh` = this call created it. A concurrent creator (409) is a find. Any other answer is a miss. */
+    private ensureCacheClaim;
+    /** Is the claim bound? (A read that fails counts as not bound — the bind deadline still decides.) */
+    private cacheClaimBound;
+    /**
+     * Reclaim one ended space's cache volume: delete the claims labelled `sema.space=<its digest>` (one deletecollection —
+     * a claim still mounted by a terminating pod is kept by the cluster's pvc-protection until the pod is gone). None ⇒ zero
+     * action. The request runs under the reclaim call's `deadline` (built once per call by {@link createSpaceReclaimer}): already passed ⇒
+     * nothing is sent; passing while the request is in flight ⇒ the request is cut (its own `rpcTimeoutMs` stays as this control-plane request's socket-idle bound; the object half's `storeFetch` bound is a whole-request wall clock — the deadline is what bounds both). Answers the outcome; never throws. Used by {@link createSpaceReclaimer} only (a control-plane env, no pod).
+     */
+    reclaimSpaceCache(spaceKey: string, deadline: AbortSignal): Promise<{
+        ok: true;
+        deleted: number;
+    } | ({
+        ok: false;
+    } & CacheReclaimFailure)>;
+    /** The one spelling of "the reclaim call's deadline passed" — both halves of the reclaim (volume and objects) say it with this. */
+    private reclaimDeadlinePassed;
+    /** The cache volume could not be had: counted (`recordFailOpen`) and one operator line — once per env. */
+    private cacheUnavailable;
+    /** Create one pod (with the cache volume when given) and wait for it to run. A {@link CacheMiss} = a pod carrying the
+     *  volume did not become ready (its claim unbound past the bind deadline, or bound and still not ready) — already deleted. */
+    private createPod;
     /**
      * Build a validated, presigned URL for a snapshot object of either lane (see {@link SnapshotTarget}) — the ONE place a
      * snapshot object key is spelled, and the one place each lane's partition is chosen (park = the session id, space = the
@@ -243,6 +367,30 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * snapshotKey()+s3Presign() pair so the two call sites can't diverge.
      */
     private presignSnapshot;
+    /** A lane's partition prefix inside the bucket — the ONE place it is spelled (`presignSnapshot` signs under it; the reclaim reads the listing against it).
+     *  The partition segment is validated by `presignSnapshot` before a URL is signed. */
+    private snapshotBase;
+    /**
+     * Reclaim an ENDED space's snapshot objects (the reclaim seat's half of {@link createSpaceReclaimer}): list the whole `space/` partition
+     * of `spaceKey` (archives, `latest`, anything else this adapter ever wrote there) and, when this env is keyed by a session
+     * (`cfg.sessionId`), the park lane's `<prefix>/<sessionId>/*.tar.gz` whose names carry the ended occupant's ownership mark (see the two
+     * paragraphs below: unmarked / `none` objects stay) — the session is gone, so nothing can ever read either again.
+     * Each object is deleted over the same presigned DELETE the prune uses. Never throws: answers the failed stages (an empty answer = all
+     * gone, or nothing was there). An object whose name this adapter could not have written, or that sits deeper than the lane's own
+     * partition, is left alone. A truncated listing (more than 1000 objects) deletes what it saw and says so.
+     * Every LIST and DELETE of both partitions runs under the reclaim call's `deadline` — ONE absolute deadline per call of {@link createSpaceReclaimer}, built at its
+     * entry from `dataTimeoutMs` (the snapshot time bound; no knob of its own) and shared by every space of the call and by the cache-volume half; this method builds
+     * none of its own. Passed before this space is reached ⇒ nothing is sent; passing on the way ⇒ the request in flight is cut and nothing further is sent. Either
+     * way the answer carries one `stage: "budget"` failure for the lane it stopped on: what was not yet deleted stays for the bucket's lifecycle rule. (Each request
+     * also keeps its own `rpcTimeoutMs`; the deadline is what bounds their sum.)
+     * The park partition is keyed by the SESSION ID, which another tenant may register again once the old row is gone — and a reclaim can run
+     * late (a retention sweep walks many sessions). So the park lane deletes only objects whose NAME carries the ended occupant's ownership mark
+     * ({@link snapshotNameOwnedBy}; the mark is minted into every snapshot id by {@link mintSnapshotId}, `uploadSnapshot`): a later occupant's
+     * objects carry its own mark, and a name with no mark (written before marks existed, or by a run with no occupant) is nobody's to delete here —
+     * the bucket's lifecycle rule is its fallback. The judgment reads NO clock (not the object store's stamp, not this replica's). The `space/`
+     * partition needs no such guard (its partition is the incarnation, which a new occupant does not share).
+     */
+    reclaimSpaceSnapshots(spaceKey: string, deadline: AbortSignal): Promise<ReclaimFailure[]>;
     /** 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;
@@ -256,12 +404,20 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  caller deadline tighter than the RPC bound. */
     private writePointer;
     /**
-     * Wait out the previous run's space commit. `space/committing` present and younger than the upload's own wall-clock
-     * bound (`dataTimeoutMs` — the SAME number `uploadSnapshot` gives its tar + curl exec) ⇒ re-read every
-     * {@link SPACE_COMMIT_POLL_MS} until it is gone or has aged past that bound. A marker at / past the bound = a commit
-     * whose worker died inside it (a live upload fails at the bound and clears its marker) ⇒ one
-     * `workspace_commit_abandoned` line; `latest` still names the previous COMPLETE snapshot. A marker read that fails, or
-     * a body that is not an epoch-ms timestamp, is a loud `connect_failed` (the same form as a failed `latest` read).
+     * Wait out the previous run's space commit — its row in the run store's `workspace_space_commit` (the ONE seat of
+     * "a commit of this space is in flight", `workspace-space-commit.ts`; written by that run's terminal write before the
+     * session's slot was released, so a next run can never start before it). The row carries its WRITER's deadline; this
+     * reader brings no number of its own: alive (`spaceCommitAlive`) ⇒ re-read every {@link SPACE_COMMIT_POLL_MS} until the
+     * row is gone. Read dead = a run whose worker died between its terminal write and its destroy (state `pending`), inside
+     * the upload, or while moving `latest` — or a writer whose renewal lands at this very moment. So the read alone
+     * decides nothing: the reader ABANDONS the row ({@link SpaceCommitFence.abandon} — one locked conditional delete, judged
+     * on the store's clock under the row's lock). Deleted ⇒ one `workspace_commit_abandoned{space, remainingMs, state}` line
+     * (`remainingMs` ≤ 0: how far past the writer's deadline, as read) and `latest` (still the previous COMPLETE snapshot)
+     * is restored; not deleted (renewed / taken / gone) ⇒ re-read at once. A row read or an abandon that fails is a loud
+     * `connect_failed` (never a guess that no commit is in flight).
+     * How long connect may wait here has no bound of its own (no knob, and NOT this replica's `dataTimeoutMs`): it is the
+     * deadline the writer keeps in its row — each of that run's at most three writes (terminal, commit start, publish) sets
+     * it to now + the writer's bound — plus the run's abort signal, which ends the wait at once.
      */
     private awaitSpaceCommit;
     /**
@@ -292,7 +448,9 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     }>;
     /**
      * 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).
+     * 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;
     /**
@@ -309,12 +467,25 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     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.
-     * `missing: "empty"` (park: a plan-only suspend has no object) tolerates a 404 as a clean workspace; `missing:
-     * "refuse"` (space: its pointer is only ever written after a successful upload ⇒ a 404 there is lost data) refuses it.
+     * 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`.
      * A restore that does not complete releases the pod it provisioned: no tool and no run-end snapshot may ever see a
-     * torn or empty-by-accident workspace.
+     * torn workspace. On the space lane that failure is the archive `latest` names being THERE but not coming back
+     * ({@link RestoreFailureClass}): the run is refused all the same — never an empty workspace (the user's changes are still in
+     * the bucket) — with exactly one `workspace_restore_failed` line and a refusal naming the two ways out.
      */
     private restoreSnapshot;
+    /**
+     * `latest` names an archive that is not there (S-1438): 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;
     /**
      * 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
@@ -334,15 +505,18 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * Delete the sandbox pod. Idempotent, never throws. Space lane open and a pod exists ⇒ FIRST the run-end space
      * snapshot ({@link persistWorkspace}); its failure is loud and never blocks the delete (the pod lifetime is the
      * leak guard). A run that never connected has no workspace to save — `latest` stays where it was. Space lane
-     * unavailable (occupant unknown) ⇒ nothing is saved (the once-per-env line says so).
+     * unavailable (no such session) ⇒ nothing is saved (the once-per-env line says so); unreadable ⇒ there is no pod
+     * ({@link provision} refused every creation).
      */
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
     /**
-     * Run-end space snapshot: PUT the `committing` marker → the one tar upload ({@link uploadSnapshot}, lane `space` — it
-     * also releases the pod) → move `latest` → keep N → DELETE the marker (always, saved or failed).
-     * Upload or pointer failure ⇒ one `workspace_snapshot_failed` line + the `failed` outcome; `latest` keeps naming the
-     * previous snapshot, so the next run restores THAT — never an empty workspace dressed up as a restore.
+     * Run-end space snapshot, under the space's commit fence (the run store's row, `workspace-space-commit.ts`): the fence
+     * first (this run's row moves to its upload state; lost ⇒ no upload, loud) → the one tar upload ({@link uploadSnapshot},
+     * lane `space` — it also releases the pod) → the fence again (this run's row moves to its publishing state; lost ⇒
+     * `latest` is not published, loud) → move `latest` → keep N → the row is deleted (always, saved or failed).
+     * A lost fence, an upload or a pointer failure ⇒ one `workspace_snapshot_failed` line + the `failed` outcome; `latest`
+     * keeps naming the previous snapshot, so the next run restores THAT — never an empty workspace dressed up as a restore.
      */
     private persistWorkspace;
     private execUrl;
@@ -457,6 +631,20 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  车PL:buffered `exec` 上守卫触发 ⇒ `spawn_error`)。 */
     private workingDirOf;
 }
+/**
+ * The ONE reclaim seat for an ended space ({@link SpaceReclaimer}) — called where a space ENDS (the session-delete coordinator and the
+ * managed-retention sweep). For each ended space it reclaims everything the space left behind, over this deployment's k8s config (it
+ * never creates a pod): its build-cache volume (the claims labelled by the space key; only when the cache volume is configured),
+ * its snapshot objects — the `space/` partition (archives + `latest`) and the park lane's objects in `<prefix>/<sessionId>/` that carry the ended occupant's mark (only when a
+ * snapshot store is configured). Each part is independent: one part failing never skips another. A failed part ⇒ one operator line
+ * (`workspace_cache_reclaim_failed{reason}` for the volume, `workspace_space_reclaim_failed{stage}` for the objects) + `recordFailOpen`; never throws.
+ * ONE call = ONE absolute deadline (the snapshot bound, `dataTimeoutMs`; no knob of its own), built at the entry and nowhere else: every request of the call — each
+ * space's cache-volume delete and every LIST / DELETE of its objects — runs under it. A session delete calls with its one space; the managed-retention sweep calls
+ * once per domain per round with the spaces that round ended there. When the deadline passes the request in flight is cut and every space not yet done is still
+ * walked but sends nothing: its volume says `reason: "budget"`, its objects `stage: "budget"` (the volume stays for deletion by label, the objects for the
+ * bucket's lifecycle rule). A caller that must not wait for the seat (the session-delete answer) starts it and does not await it.
+ */
+export declare function createSpaceReclaimer(config: K8sEnvConfig, deps?: K8sEnvDeps): SpaceReclaimer;
 /**
  * `ExecutionEnvFactory` for the k8s pod-sandbox backend — one fresh (unconnected) env per task; the pod is
  * created lazily on connect and deleted by `destroy()` (Runner-owned lifetime; `activeDeadlineSeconds` is the