@sema-agent/server 7.125.1 → 7.127.0

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

@@ -1,4 +1,7 @@
-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 { 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 } from "@sema-agent/core";
 import type { PodSpecPatch } from "./k8s-exec-protocol.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
@@ -37,10 +40,20 @@ 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;
+    /** The sandbox pod's IPv6 posture (`K8S_SANDBOX_IPV6`; closed set + default owned by `sandbox-egress-policy.ts`): `disabled` ⇒ the
+     *  pod-level sysctls of {@link sandboxPodSysctls}; `enabled` (default) ⇒ no `securityContext` key, the pod byte-identical to before. */
+    ipv6?: SandboxIpv6;
     retry?: {
         maxAttempts?: number;
         backoffMs?: number;
@@ -58,8 +71,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 +87,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 +97,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 +132,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,11 +169,52 @@ 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. */
 export declare function errorMessageOf(e: unknown): string;
 export { exitCodeFromStatus } from "./k8s-exec-protocol.js";
+/** The sandbox namespace when `K8S_NAMESPACE` is unset (the one spelling: the adapter and the boot's egress line read it). */
+export declare const K8S_SANDBOX_NAMESPACE_DEFAULT = "sandboxes";
 export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
     /**
      * 🔴 **S-354 / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
@@ -183,14 +243,30 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private inFlightExecs;
     /** Memoized in-flight connect (lazy-connect; prevents concurrent double pod-create — the E2B race lesson). */
     private connectPromise?;
+    /** The space restore's refusal: `latest` names an archive that is there and did not come back. A fact of this env until `destroy` —
+     *  written once, by {@link restoreSnapshot} at the restore's end; read by {@link connect} alone (the lazy and the explicit connect alike),
+     *  which answers it to every later connect: the same refusal, zero pods, zero store requests, no second line. */
+    private restoreRefusal?;
     /** 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,29 +284,97 @@ 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).
+     * One restore per env: a restore that ended refused ({@link restoreRefusal}) is answered as it stands to every later connect — the
+     * previous commit is not waited on again, `latest` is not read again, no pod is created.
      */
     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
      * the resume path), so an adapter that demands an explicit connect can never work through the production
      * hand-tool path (lazy-connect belongs in the adapter). Memoized so concurrent first ops share ONE
-     * pod create; a failed connect clears the memo (next op retries); `destroyed` is terminal.
+     * pod create; `destroyed` is terminal. A failed connect clears the memo — how long a failure stands is {@link connect}'s, not
+     * this memo's: a failure of that attempt (a pod that could not be created, a space read that failed) ⇒ the next op connects
+     * afresh; the space restore's refusal is the env's ({@link restoreRefusal}) ⇒ the next op's connect answers that same refusal at once.
      */
     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 egress self-check's two reads (`GET` nodes, `GET` the sandbox namespace's NetworkPolicies) judged by the one rule
+     * ({@link sandboxEgressGaps}) against the labels this env mints on its pods (base identity + the pod-spec patch's additions, the
+     * same merge `createPod` applies). A read that is refused / fails / times out is a `unreadable` gap, never a guess. Never throws.
+     */
+    egressPolicyGaps(): Promise<SandboxEgressGap[]>;
+    /** 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 +387,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 +424,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 +468,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 +487,34 @@ 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 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.
+     * 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`.
+     * 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
+     * the end means:
+     *  - park: a plain `connect_failed` — its caller retries; nothing said, nothing held;
+     *  - space: the archive `latest` names is THERE and did not come back ({@link RestoreFailureClass}): the run is refused all the
+     *    same — never an empty workspace (the user's changes are still in the bucket) — with exactly one `workspace_restore_failed`
+     *    line (its `attempts`; an attempt that failed before one that succeeded is no line) and a refusal naming the two ways out,
+     *    held for the env ({@link restoreRefusal}).
+     * A pod that could not be created is that attempt's failure, not the archive's: returned as it is — no line, nothing held, the
+     * next connect tries again. An abort during the pause ends the restore `aborted` (not the archive's either).
      */
     private restoreSnapshot;
+    /** The pause before a restore's next attempt (`retry.backoffMs`, the adapter's one retry pause). `false` ⇒ aborted (now or during it). */
+    private restorePause;
+    /**
+     * `latest` names an archive that is not there (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 +534,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 +660,26 @@ 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;
+/**
+ * The k8s lane's boot-time egress self-check (once per boot, never holds the boot): the gaps between the sandbox pods' egress
+ * policy and what the cluster API shows (`sandbox-egress-policy.ts` — the closed set and the rule). A reading, not the boundary:
+ * nodes that join after boot are read at the next boot. Never throws (a read failure is an `unreadable` gap).
+ */
+export declare function checkSandboxEgressPolicy(config: K8sEnvConfig, deps?: K8sEnvDeps): Promise<SandboxEgressGap[]>;
 /**
  * `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