@sema-agent/server 7.135.0 → 7.137.0

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

@@ -13,6 +13,7 @@ export const DEVICE_OUTCOME_TO_FILE_ERROR = {
     invalid: "invalid",
     is_directory: "is_directory",
     liveness_no_output: "unknown",
+    name_too_long: "name_too_long",
     not_directory: "not_directory",
     not_found: "not_found",
     not_supported: "not_supported",
@@ -35,6 +36,7 @@ export const DEVICE_OUTCOME_TO_EXEC_ERROR = {
     invalid: "unknown",
     is_directory: "unknown",
     liveness_no_output: "liveness_no_output",
+    name_too_long: "unknown",
     not_directory: "unknown",
     not_found: "unknown",
     not_supported: "shell_unavailable",
@@ -123,6 +125,7 @@ export class RemoteDeviceExecutionEnv {
     cfg;
     homeDir;
     cdPath = "unknown";
+    withheldEnv = [];
     capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true };
     externalContentTarget = true;
     hostLocalPaths = false;
@@ -766,6 +769,7 @@ const OUTCOME_TO_REMOTE_ERROR = {
     invalid: "unknown",
     is_directory: "unknown",
     liveness_no_output: "liveness_no_output",
+    name_too_long: "unknown",
     not_directory: "unknown",
     not_found: "unknown",
     not_supported: "unsupported",

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

@@ -104,6 +104,9 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 e2b 沙箱里(模板镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
+    /** core 7.56.0 [ref]:shell 子进程继承的环境里收不到的条目 —— 本车道 shell 的环境在沙箱里**构建**(本进程的 env 从不注入,只有引擎逐次交的 `env`
+     *  这条显式授予),没有一条是从本进程继承的 ⇒ `[]`(core 契约:「`[]` when its shell environment is built rather than inherited」)。 */
+    readonly withheldEnv: readonly [];
     private readonly cfg;
     private readonly sandboxApi;
     /** This lane's own liveness bound — what {@link commandBoundsOf} falls back to when a command's caller stated no bound. */

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

@@ -20,6 +20,7 @@ export class RemoteContainerExecutionEnv {
     cwd;
     homeDir;
     cdPath = "unknown";
+    withheldEnv = [];
     cfg;
     sandboxApi;
     laneLiveness;

package/dist/plugins/remote-env-file-error.d.ts

@@ -18,6 +18,12 @@
 import { FileError, type ExecutionError, type RemoteExecutionError } from "@sema-agent/core";
 /** exec 层的错误码 → 文件层的码。只映射**有对应语义**的那些,其余落 `unknown`(诚实降级)。 */
 export declare function fileErrorFromExec(e: ExecutionError | RemoteExecutionError, path?: string): FileError;
+/**
+ * core 7.56.0 [ref]:`ENAMETOOLONG` 的**一只读法**(本文件的 stderr 分类器与 host 车道的 errno 映射同调)—— 路径有一段超过 NAME_MAX(按 UTF-8 字节量)⇒
+ * `name_too_long`:没有目录装得下这个名字,引擎读站把它读作缺席(与 `not_found` 同读);段都短、只是整条超 PATH_MAX ⇒ `unknown`(那种文件可能存在,从下层目录够得着)。
+ * 没有路径可判 ⇒ `unknown`。与 core `NodeExecutionEnv` 同判(按 `/` 与 `\` 切段)。
+ */
+export declare function nameTooLongCode(p: string | undefined): "name_too_long" | "unknown";
 /**
  * shell 命令 exit≠0 时把 **stderr** 分类成 `FileError` 的共享分类器([ref] B6 R2 裁决:k8s 形=正形)。
  *
@@ -29,7 +35,8 @@ export declare function fileErrorFromExec(e: ExecutionError | RemoteExecutionErr
  *  1. 命令缺失形(`command not found` / `applet not found` / `: not found`)→ `unknown` —— 工具不存在
  *     不是文件不存在;probe 族的 not_found fallback 绝不能吞它。
  *  2. 完整硬失败(EIO/ELOOP/ENAMETOOLONG/ENOSPC)→ `unknown` —— 同 k8s 原注:真错不被 read-op 的
- *     not_found fallback 吞掉。
+ *     not_found fallback 吞掉。**例外**(core 7.56.0 [ref]):`ENAMETOOLONG` 且路径有一段超过 NAME_MAX ⇒ `name_too_long`
+ *     ({@link nameTooLongCode},一只读法,host 车道的 errno 映射同调)—— 那个名字没有目录装得下,是一种「不存在」,不是硬失败。
  *
  * `fallback` 由站点显式给:probe 族(readlink/realpath/stat——"它在吗"类问题)传 `not_found`
  * (空 stderr + exit≠0 的主导原因就是缺文件);mutate 族(mkdir/rm/mktemp)传 `unknown`(诚实降级)。

package/dist/plugins/remote-env-file-error.js

@@ -3,11 +3,17 @@ export function fileErrorFromExec(e, path) {
     const code = e.code === "aborted" ? "aborted" : "unknown";
     return new FileError(code, e.message, path, e);
 }
+const NAME_MAX_BYTES = 255;
+export function nameTooLongCode(p) {
+    return p !== undefined && p.split(/[\\/]/).some((part) => Buffer.byteLength(part, "utf8") > NAME_MAX_BYTES) ? "name_too_long" : "unknown";
+}
 export function classifyFsStderr(stderr, p, fallback = "unknown") {
     const msg = stderr.trim();
     if (/command not found|applet not found|:\s+not found\s*$/im.test(msg))
         return new FileError("unknown", msg, p);
-    if (/input\/output error|too many levels|file name too long|no space left/i.test(msg))
+    if (/file name too long/i.test(msg))
+        return new FileError(nameTooLongCode(p), msg, p);
+    if (/input\/output error|too many levels|no space left/i.test(msg))
         return new FileError("unknown", msg, p);
     if (/no such file/i.test(msg))
         return new FileError("not_found", msg, p);

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 } from "@sema-agent/core";
+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";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** SIGTERM → grace → SIGKILL (no host isolation). 🔴 宽限的**唯一属主**:本 driver 的 `kill` 梯子用它排升级定时器;会话级收敛
@@ -101,6 +101,12 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      * {@link hostShell}(win32 上未落定同步抛 —— 修前每条 Bash 的策略链都因此被拒)。
      */
     get cdPath(): readonly string[];
+    /**
+     * core 7.56.0 [ref]:shell 子进程继承的环境里**收不到**的条目(名 + 规则,从不带值)—— 与 {@link cdPath} 同一只组合的读面
+     * (`server-secret-env.ts` 的 `withheldFromHostSubprocess`:继承组合扣下的发现,减去 `cfg.env` 这条显式授予重供的键)。逐命令的 `options.env`
+     * 是引擎自己交的显式授予,它知道(core KL-1963-b 同一残余)。只读:不披露、不计数、不碰 shell。
+     */
+    get withheldEnv(): readonly SecretEnvFinding[];
     private readonly workspaceDir;
     private readonly cfg;
     /** Workspace created on disk (lazily, on first use). */

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

@@ -11,7 +11,8 @@ import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
-import { composeHostSubprocessEnv, hostSubprocessEnv } from "../server-secret-env.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";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
@@ -61,6 +62,9 @@ export class RemoteHostExecutionEnv {
         const value = this.childEnv(undefined, undefined).CDPATH;
         return value === undefined || value === "" ? [] : value.split(":");
     }
+    get withheldEnv() {
+        return withheldFromHostSubprocess({ policy: this.cfg.inheritEnv, allow: [] }, this.cfg.env);
+    }
     workspaceDir;
     cfg;
     prepared = false;
@@ -1331,6 +1335,8 @@ export class RemoteHostExecutionEnv {
             return new FileError("not_directory", msg, p);
         if (code === "EINVAL")
             return new FileError("invalid", msg, p);
+        if (code === "ENAMETOOLONG")
+            return new FileError(nameTooLongCode(p), msg, p);
         return new FileError("unknown", msg, p);
     }
 }

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

@@ -110,9 +110,11 @@ export interface K8sEnvConfig extends LaneHomeConfig {
     cacheMisses?: CacheMissMemory;
     /** Operator log seat (the e2b adapter's shape): `workspace_snapshot_failed` / `workspace_snapshot_prune_failed` /
      *  `workspace_space_unavailable` / `workspace_space_unreadable_occupant` / `workspace_commit_abandoned` / `workspace_latest_dangling` /
-     *  `workspace_restore_failed` / `workspace_cache_fresh` / `workspace_cache_unavailable`. */
+     *  `workspace_restore_failed` / `workspace_snapshot_bucket_missing` / `workspace_cache_fresh` / `workspace_cache_unavailable`, and — at `error` level, on a seat
+     *  that has one (the deployment's logger does; the seat itself is optional, and the counter behind the line does not depend on it) — `sandbox_pod_delete_failed`. */
     logger?: {
         warn(event: string, fields?: Record<string, unknown>): void;
+        error?(event: string, fields?: Record<string, unknown>): void;
     };
     /** Run-end outcome seat — called once per `destroy()` that attempted a space snapshot (the factory's caller binds it
      *  to the run, so the run's terminal frame can carry `workspaceSnapshot: "failed"`). */
@@ -130,13 +132,39 @@ export interface K8sEnvConfig extends LaneHomeConfig {
     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 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. */
+     *  pkg-source.sh hook materializes at start). Deployment config, NEVER task-controlled. The pod's NON-SECRET env seat: the region
+     *  package-source set (and the cache env layered under it) — values that are no secret go into `containers[0].env[]` as `{ name, value }`.
+     *  Never a command string, the workspace or a snapshot. Absent = no such entries. */
     podEnv?: Record<string, string>;
+    /** The pod's SECRET env seat: the deployer-named forwarding (`K8S_SANDBOX_ENV` keys, original values; disjoint from {@link podEnv} — the boot
+     *  assembly drops a collided name from the non-secret seat, explicit wins; a name in both is read here). The values reach the agent container
+     *  ONLY through this pod's own Secret: the pod spec carries `valueFrom.secretKeyRef` and no value; the Secret is created after the pod, owned by
+     *  it (`ownerReferences`, `immutable`) — a Secret that cannot be created ⇒ the pod is deleted and the connect refused, never a plaintext fallback.
+     *  Absent / empty ⇒ no Secret, the pod as without it. */
+    podSecretEnv?: Record<string, string>;
+    /** The server run that owns this env — the TOP-LEVEL run's id (its task id), handed in by the per-run binding (`boot/execution-env.ts`), which
+     *  hands none to a delegated child, a run the service starts for itself, or a run without a task id. Carried as the pod label `sema.io/run`
+     *  (the reaper's key: a pod whose run is over is removed); a value that is no label value is not carried. Absent ⇒ the pod names no run. */
+    runId?: string;
+    /**
+     * The member git-credential broker seat — present ⇔ the per-run binding found the plane on and this run a member's (`sso`) run
+     * (`sandbox-git-plane.ts` `sandboxBrokerSeatOf`). The pod then carries the broker container (`containers[1]`: the fixed program of
+     * `broker/constants.ts`, image = `image`, the securityContext written key by key, an exec readiness probe), its lease volume (a SECOND
+     * per-pod Secret, `sema.io/sandbox-lease` — mutable, owned by the pod, only `broker.json`; created after the pod holding a placeholder lease
+     * in which every entry is withdrawn), `shareProcessNamespace: false`, and on the agent container one `GIT_CONFIG_*` insteadOf route per
+     * origin (`origins` = the pod's origin table, in order — the same table every lease write is stamped from). The connect waits for the
+     * broker container to be ready; any failure on that path deletes the pod and refuses the connect. A deployment patch that could reach
+     * the broker refuses the connect before any pod is created. Absent ⇒ the pod as without it (byte-identical).
+     */
+    sandboxBroker?: {
+        readonly image: string;
+        readonly origins: readonly string[];
+    };
 }
+import { type SandboxSecretSeatKind, type SandboxSecretVerb } from "./k8s-exec-protocol.js";
 export { type PodSpecPatch, applyPodSpecPatch } from "./k8s-exec-protocol.js";
+import { type SandboxPodApi, type SandboxPodListing } from "./k8s-pod-reaper.js";
+import { type SandboxLeaseEntryInput } from "../sandbox-git-lease.js";
 type ConnectResult = {
     ok: true;
     value: WorkspaceHandle;
@@ -154,11 +182,14 @@ export interface ExecSocket {
  * Test seam ([ref] §9.3 fault-injection): inject the REST `request` and/or the exec-socket factory, so pod
  * lifecycle, retry policy, channel framing and liveness are deterministically testable without a cluster.
  */
+/** One control-plane request's options: its wall-clock, its abort, and the body's media type (default `application/json`; a merge-patch says so). */
+export interface K8sRequestOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    contentType?: string;
+}
 export interface K8sEnvDeps {
-    request?: (method: string, apiPath: string, body?: unknown, opts?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }) => Promise<{
+    request?: (method: string, apiPath: string, body?: unknown, opts?: K8sRequestOptions) => Promise<{
         status: number;
         json: unknown;
     }>;
@@ -229,6 +260,35 @@ 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";
+/**
+ * The boot reading of the sandbox Secret seat, a closed set: `granted` — every verb allowed · `denied` — the API answered "not allowed" for these
+ * verbs (a definite answer; it wins over a verb that could not be asked) · `unverified` — some verb could not be asked (the request failed, the
+ * review itself was refused, the answer had no `status.allowed`) and none was denied.
+ */
+export type SandboxSecretSeat = {
+    readonly state: "granted";
+} | {
+    readonly state: "denied";
+    readonly verbs: SandboxSecretVerb[];
+} | {
+    readonly state: "unverified";
+    readonly detail: string;
+};
+/** Where a pod's lease lives and which origin table it was built with — what {@link writeSandboxLease} needs (read it from {@link RemoteK8sExecutionEnv.sandboxLeaseRef}). */
+export interface SandboxLeaseRef {
+    readonly namespace: string;
+    readonly podName: string;
+    readonly leaseSecretName: string;
+    readonly origins: readonly string[];
+}
+/** One lease write's outcome (closed set): written · refused before sending (the broker would refuse it) · refused by the API · the Secret is gone (so is its pod) · any other failure. */
+export type SandboxLeaseWrite = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: "lease_invalid" | "auth_failed" | "gone" | "write_failed";
+    readonly message: string;
+};
 export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
     /**
      * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
@@ -250,6 +310,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** 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;
     /** Set after a successful resumeVM so workspaceHandle() carries the snapshot it was restored from. */
     private handleSnapshotId?;
@@ -274,6 +336,9 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 pod 里(镜像与 pod spec 的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
+    /** core 7.56.0 [ref]:shell 子进程继承的环境里收不到的条目 —— 本车道 shell 的环境在 pod 里**构建**(本进程的 env 从不注入,只有引擎逐次交的 `env`
+     *  这条显式授予),没有一条是从本进程继承的 ⇒ `[]`(core 契约:「`[]` when its shell environment is built rather than inherited」)。 */
+    readonly withheldEnv: readonly [];
     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
@@ -295,6 +360,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private readonly onWorkspaceSnapshot?;
     private readonly cacheMisses?;
     constructor(config: K8sEnvConfig, deps?: K8sEnvDeps);
+    /** The lease seat of the pod this env holds now — `undefined` without a broker seat or without a pod (the server's lease writes follow it: a resumed env holds a new pod and a new seat). */
+    get sandboxLeaseRef(): SandboxLeaseRef | undefined;
     /** 166-T2 — ExecutionEnv 寿命声明:pod `activeDeadlineSeconds = ceil(timeoutMs/1000)` 是平台真硬死线
      *  (k8s 到点杀 pod,无 keepalive 续期机制)⇒ 恒声明,core 在死线−60s 处 suspend(基建合格)或响亮
      *  终局(env.lifetime_expired)。`lifetimeStartedAt` 有意不声明:core 只在 prepare 期读一次,lazy-connect
@@ -311,8 +378,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * Connect = the workspace SPACE's restore point. Space lane open ⇒ first wait out a commit still in flight
      * ({@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
+     * loud `workspace_latest_dangling`, the pointer deleted, an empty workspace); absent (404 — the key, with the bucket there) ⇒ a fresh pod; a read that
+     * FAILS ⇒ a loud `connect_failed` — a 404 `NoSuchBucket` included ({@link refuseMissingBucket}) — never a silent fresh workspace (a run that believes it resumed while it did not is
      * the worst form). Once the pod holds the workspace, this env arms its fence seat (its destroy will commit).
      * 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
@@ -410,6 +477,15 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 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 boot reading of one sandbox Secret seat ({@link SandboxSecretSeat}): one SelfSubjectAccessReview per verb of that seat's row in {@link SANDBOX_SECRET_SEAT_VERBS}
+     * on `secrets` in this env's namespace. An answer with `status.allowed: false` is a denial (RBAC never answers `denied: true` — "no rule allows
+     * it" IS its refusal); a failed request, a refused review or an answer without a boolean `status.allowed` is a verb not asked. The verbs are
+     * asked at once (the boot waits one control-plane bound, not four). Never throws.
+     */
+    secretSeatReading(seat: SandboxSecretSeatKind): Promise<SandboxSecretSeat>;
+    /** The sandbox pods of this env's namespace (selected by the identity labels), read for the reaper ({@link createSandboxPodApi}). Throws on a failed / refused listing. */
+    listSandboxPods(): Promise<SandboxPodListing[]>;
     /** 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. */
@@ -417,6 +493,34 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** 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;
+    /**
+     * This pod's own Secret — the secret env seat ({@link K8sEnvConfig.podSecretEnv}): created AFTER the pod, owned by it (`ownerReferences` → the
+     * pod's uid, `blockOwnerDeletion: false` — the cluster's garbage collector removes it with the pod), `immutable`, `data["env.<NAME>"]` = the
+     * value (base64). The caller deletes the pod on any refusal: no uid to bind (`connect_failed`), refused (401 / 403 ⇒ `auth_failed`, not
+     * retried), any other answer or a failed request (`connect_failed`). A refusal never carries a value: the API's text is scrubbed of every value
+     * (raw and base64) before it enters the sentence.
+     */
+    private createPodSecret;
+    /**
+     * This pod's lease Secret — the member-credential broker's seat ({@link K8sEnvConfig.sandboxBroker}): created after the pod, owned by it
+     * (the same `ownerReferences` as the env Secret), NOT immutable (the server rewrites the lease: {@link writeSandboxLease}), one data key
+     * `broker.json` = the placeholder lease. Refusals as for the env Secret; the caller deletes the pod on any of them.
+     */
+    private createLeaseSecret;
+    /**
+     * One Secret owned by this pod (`ownerReferences` → its uid, `blockOwnerDeletion: false`; the cluster's garbage collector removes it with
+     * the pod). No uid to bind ⇒ `connect_failed`; refused (401 / 403) ⇒ `auth_failed`; any other answer or a failed request ⇒ `connect_failed`.
+     * A refusal never carries a value: the API's text is scrubbed of every `hidden` string before it enters the sentence.
+     */
+    private createOwnedSecret;
+    /**
+     * Rewrite one pod's lease (the server's ONLY lease write — {@link writeSandboxLease}): the file is built by the one lease builder from the
+     * pod's origin table (fresh `leaseId` per ready entry, the broker's own parser judges it — a file the broker would refuse is never sent) and
+     * lands as a merge-patch of `broker.json` on the pod's lease Secret. Every failure is typed, says one operator line
+     * (`sandbox_lease_write_failed`), carries no credential (the API's text is scrubbed of every secret and of the encoded file), and falls
+     * back to nothing: the broker keeps the lease it has, which lapses on its own clock.
+     */
+    writeLease(ref: SandboxLeaseRef, entries: readonly SandboxLeaseEntryInput[]): Promise<SandboxLeaseWrite>;
     /**
      * 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
@@ -425,10 +529,13 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * charset-validated upstream, so each path segment is allowlisted here (`^[A-Za-z0-9][A-Za-z0-9._-]*$`) before it enters
      * the object key: a segment of `..` / `../x` / one containing `/` would otherwise let one tenant's snapshot key normalize into
      * another tenant's prefix (cross-tenant read on resume / clobber on suspend). The space partition (a minted v4 uuid) goes
-     * through the same one allowlist. Returns a typed error instead of signing a traversing key. Folds the old
+     * through the same one allowlist ({@link SNAPSHOT_KEY_SEGMENT}); the key prefix is a `/`-separated path of the same segments
+     * ({@link snapshotKeyPrefixProblem}, the rule the config loader refuses boot with). Returns a typed error instead of signing a traversing key. Folds the old
      * snapshotKey()+s3Presign() pair so the two call sites can't diverge.
      */
     private presignSnapshot;
+    /** The key prefix of every snapshot object this env signs — the ONE reading of `keyPrefix` (unset ⇒ the default); its form is judged in {@link presignSnapshot}. */
+    private snapshotKeyPrefix;
     /** 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;
@@ -456,9 +563,19 @@ 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); any other failure is a typed
+    /** 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. */
     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.
+     */
+    private refuseMissingBucket;
     /** Read the space's `latest` pointer. The body's shape is checked where it is used — restoreSnapshot → presignSnapshot
      *  (the one segment check). */
     private readLatest;
@@ -571,7 +688,20 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
         error: RemoteExecutionError;
     }>;
     reconnect(_sessionToken: SessionToken): Promise<ConnectResult>;
-    private deletePod;
+    /**
+     * Delete one pod — the ONE request path of "delete a sandbox pod" (the run-end delete, every refusal / reconnect clean-up, and the reaper's face: no grace).
+     * Resolves `"deleted"` (2xx) or `"gone"` (404: the pod never was / is already gone); throws {@link PodDeleteRefused} on any other answer and the request's own error on a transport failure.
+     */
+    deletePod(name: string): Promise<"deleted" | "gone">;
+    /**
+     * Give up the pod a refused connect had already created. The refusal is the caller's answer; the delete is the clean-up behind it — and a clean-up that FAILS leaves
+     * the pod, and the Secret(s) it owns (the deployer-named env values / the lease placeholder: data at rest that no connection carries), in the sandbox namespace until
+     * the pod reaper's backstop reaches them. That is said, not swallowed — through the ONE reporter the reaper's own delete step shares
+     * ({@link reportPodDeleteFailed}: the F-class counter `server.sandbox-pod.delete-failed` and one error line naming the pod, the namespace, why the pod was being
+     * given up and how the delete failed (`http_<status>` / `request_failed`) — never a value, never the API's own text).
+     * Never throws: the refusal the caller goes on to return stays the original one.
+     */
+    private discardRefusedPod;
     /**
      * Delete the sandbox pod. Idempotent, never throws. Space lane open and a pod exists ⇒ FIRST the run-end space
      * snapshot ({@link persistWorkspace}) — after the pod's processes are confirmed stopped, the commands still in flight having ended or been cut first ({@link quiesce}); from the
@@ -753,6 +883,16 @@ export declare function createSpaceReclaimer(config: K8sEnvConfig, deps?: K8sEnv
  * 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[]>;
+/** The boot reading of one sandbox Secret seat for this k8s config ({@link RemoteK8sExecutionEnv.secretSeatReading}; a control-plane env, no pod). Never throws. */
+export declare function readSandboxSecretSeat(config: K8sEnvConfig, seat: SandboxSecretSeatKind, deps?: K8sEnvDeps): Promise<SandboxSecretSeat>;
+/**
+ * The server's one lease writer for a pod that carries the member-credential broker ({@link RemoteK8sExecutionEnv.writeLease}): `ref` is the
+ * pod's lease seat ({@link RemoteK8sExecutionEnv.sandboxLeaseRef}), `entries` one per origin of its table. A control-plane env, no pod.
+ */
+export declare function writeSandboxLease(config: K8sEnvConfig, ref: SandboxLeaseRef, entries: readonly SandboxLeaseEntryInput[], deps?: K8sEnvDeps): Promise<SandboxLeaseWrite>;
+/** The reaper's narrow face onto the sandbox namespace (list by identity labels, delete one) — a control-plane env, no pod, built at first use
+ *  (as the space reclaimer builds its envs per call: the boot never constructs an env just to hold this face). */
+export declare function createSandboxPodApi(config: K8sEnvConfig, deps?: K8sEnvDeps): SandboxPodApi;
 /**
  * `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