@sema-agent/server 7.151.0 → 7.152.0

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

@@ -46,7 +46,8 @@ export interface HostEnvConfig extends LaneHomeConfig {
      * user's OWN directory (e.g. the cwd `run-local` was invoked in), not an adapter-created ephemeral sandbox,
      * so the agent's file edits PERSIST and are user-visible (like a local coding agent working in your repo).
      * Takes precedence over `workspaceBase`/`id` (those are ignored). Default unset = ephemeral random + cleanup.
-     * 唯一的例外由托管表说:它落在一只本服务铸的临时根里({@link custody} 的 `sharedRoot`)⇒ 本环境共持那只根,不是调用方自有目录。
+     * 唯一的例外由托管表说:它落在一只本服务铸的临时根里 ⇒ 本环境(也)持有那只根 —— 铸时就判得出的({@link custody} 的 `sharedRoot`)从铸起共持;
+     * 铸时判不出、在那只根的最后一只持有者放手那一拍读得出地落在里面的,当场接过删除({@link RemoteHostExecutionEnv.assumeRoot})。
      */
     workspaceDir?: string;
     /**
@@ -72,10 +73,16 @@ export interface HostEnvConfig extends LaneHomeConfig {
 }
 /** 工作区托管表交给它铸的环境的那一面(`workspace-custody.ts`;host 车道的读法)。 */
 export interface HostWorkspaceCustodySeat {
-    /** `workspaceDir` 落在这只本服务铸的临时根里(委派子代按父的工作目录落根)⇒ 本环境与它的铸者共持这只根:建成后登记、收场时放手、最后放手的持有者删它。 */
+    /**
+     * 铸时那一判:`workspaceDir` 落在这只本服务铸的临时根里(委派子代按父的工作目录落根)⇒ 本环境从铸起与它的持有者共持这只根。
+     * 这是删除责任的**提前交接**,不是删除的闸 —— 删不删只由 {@link passOn} 在放手那一拍答。
+     */
     readonly sharedRoot?: string;
-    /** 表里除 `self` 之外还有没有成员持有 `root` —— 收场放手时问;有 ⇒ 删交给最后放手的那一只。 */
-    heldElsewhere(self: RemoteHostExecutionEnv, root: string): boolean;
+    /**
+     * 删前那一判(本环境放手 `root` 的同一同步段里问;同步、永不抛):「此刻还有谁在 `root` 里」—— 另有持有者 / 有还没离场的环境读得出地落在里面(它当场接过)/
+     * 有读不出的(留给退出兜底)⇒ `true`,不删;读得出地没人 ⇒ `false`,本环境在同一同步段里把它移出原路径再删。
+     */
+    passOn(self: RemoteHostExecutionEnv, root: string): boolean;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability, CustodyMember<never> {
     /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
@@ -191,8 +198,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     private drainInflightFs;
     private ensureSpoolRoot;
-    /** 本环境对它工作区的租期({@link HostWorkspaceTenure}):借用的永不删;持有的收场放手、最后放手的持有者删。唯一写处 = 构造与 {@link removeOwnedTrees}。 */
+    /** 本环境对它工作区的租期({@link HostWorkspaceTenure}):借用的永不删;持有的收场放手、放手那一拍判得没人才删。唯一写处 = 构造、{@link assumeRoot} 与 {@link removeOwnedTrees}。 */
     private tenure;
+    /** 离场({@link left}):唯一写处 = {@link removeOwnedTrees} 的放手段。 */
+    private hasLeft;
     /** Memoized lazy `mkdir -p` so concurrent first-use prepares the workspace exactly once. */
     private preparing?;
     /**
@@ -208,10 +217,20 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     get released(): boolean;
     /** 本车道收场不欠同一身份下一只环境任何账(删不掉的根留在退出兜底簿上,不交接)。 */
     readonly leftover: undefined;
-    /** 收场落定且已放手 ⇒ 出托管表(超时臂里放手挂在在飞写之后:落定了还持有 ⇒ 仍是持有者)。 */
+    /**
+     * 离场:本环境自己的收场放手那一段({@link removeOwnedTrees},在飞写落地之后)跑过。删前那一判只问还没离场的环境「你在不在这只根里」——
+     * 收场开始了而写还没落地的仍在场(它的写还会落进去);离场之后它不再动工作区(残余镜像写只许落在借用目录 / spool 根上)。
+     */
+    get left(): boolean;
+    /** 收场落定且已离场 ⇒ 出托管表(超时臂里放手挂在在飞写之后:落定了还没离场 ⇒ 仍在表里,借用的与持有的同一句)。 */
     get settled(): boolean;
-    /** 本环境此刻持有的、本服务铸的临时根(托管表的持有读法读它);借用 / 已放手 ⇒ 缺席。 */
-    get heldWorkspace(): string | undefined;
+    /** 本环境此刻持有的、本服务铸的临时根(托管表的持有读法读它;正常流至多一只);借用 / 已放手 ⇒ 空。 */
+    get heldRoots(): readonly string[];
+    /**
+     * 删前那一判把 `root` 的删除交给本环境。唯一调用方 = 工厂的 {@link passOnRoot}(与放手者的判在同一同步段;前提:本环境还没离场、工作目录读得出地落在 `root` 里):
+     * 持有集合加上它(借用的从此持有;已持有别的根的两只都持有),离场时按同一句律逐根再判。`root` 在盘或读不出 ⇒ 当场登记退出兜底簿(本环境的 prepare 可能早已跑过、不会再登记)。
+     */
+    assumeRoot(root: string): void;
     workspaceHandle(): WorkspaceHandle;
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
@@ -507,8 +526,8 @@ export interface HostLegConfig extends Pick<HostEnvConfig, "workspaceDir" | "env
 /**
  * host 车道的工厂。**一只身份一只工作区**:经工作区托管表(`workspace-custody.ts`,与 local-docker 车道同一只)铸环境 ——
  * 同一身份(`ctx.taskId ?? ctx.sessionId`)还有一只没收场的环境 ⇒ 交回它(停驻腿的环境 = 续跑腿的环境:引擎 park-only 契约要的「重连到同一工作区」);
- * 正在收场 ⇒ 等它落定再铸。铸的时候问同一张表「腿的目录落在哪只本服务铸的临时根里」:落在里面(委派子代按父的工作目录落根)⇒ 与铸者共持那只根,
- * 父收场时子代还持有它就不删,最后放手的持有者删。`legOf` 先于交回 / 铸判(它可以拒)。
+ * 正在收场 ⇒ 等它落定再铸。本服务铸的临时根只在它的最后一只持有者放手那一拍、按表里还没离场的环境此刻的工作目录判得没人之后才删({@link passOnRoot});
+ * 铸时那一判({@link heldRootContaining})只把落在持有根里的新腿当场记成共持者。`legOf` 先于交回 / 铸判(它可以拒)。
  * 起服铸**一只**工厂(每次调用另铸一只工厂 = 没有表)。
  */
 export declare function hostExecutionEnvFactory(config?: HostEnvConfig, legOf?: (ctx: ExecutionEnvFactoryContext) => HostLegConfig): ExecutionEnvFactory;

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

@@ -5,7 +5,7 @@ import path, {} from "node:path";
 import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import fs from "node:fs/promises";
 import { randomBytes } from "node:crypto";
-import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, accessSync, constants as FS_CONST } from "node:fs";
+import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, accessSync, renameSync, constants as FS_CONST } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
 import { armPipeDestroyGrace, numEnvOr } from "./remote-shell.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
@@ -21,7 +21,8 @@ import { composeHostSubprocessEnv, hostSubprocessEnv, withheldFromHostSubprocess
 import { nameTooLongCode } from "./remote-env-file-error.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 import { createWorkspaceCustody } from "./workspace-custody.js";
-import { canonicalPathOf, pathIsWithin } from "../memory-scope.js";
+import { canonicalPathOf, pathIsWithin, presentOnDisk } from "../memory-scope.js";
+import { errorCodeOf } from "../observability/err-text.js";
 import { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
 import { createConnectSeat, withdrawOnAbort } from "./remote-env-connect-seat.js";
 const PROVIDER = "host";
@@ -41,6 +42,7 @@ const unsupported = (op) => ({
 });
 const BORROWED = Object.freeze({ kind: "borrowed" });
 const RELEASED = Object.freeze({ kind: "released" });
+const NO_ROOTS = Object.freeze([]);
 const UNSUPPORTED_SCHEDULER_CAPS = {
     supported: false,
     maxScheduledPerScope: 0,
@@ -132,6 +134,7 @@ export class RemoteHostExecutionEnv {
         return this.spoolRootDir;
     }
     tenure;
+    hasLeft = false;
     preparing;
     seat = createConnectSeat({
         live: () => (this.prepared && !this.destroyed ? this.handle : undefined),
@@ -143,14 +146,14 @@ export class RemoteHostExecutionEnv {
         if (config.workspaceDir) {
             this.workspaceDir = hostSeatPath(config.workspaceDir);
             const shared = config.custody?.sharedRoot;
-            this.tenure = shared !== undefined ? { kind: "held", root: hostSeatPath(shared) } : BORROWED;
+            this.tenure = shared !== undefined ? { kind: "held", roots: [hostSeatPath(shared)] } : BORROWED;
         }
         else {
             const base = hostSeatPath(config.workspaceBase ?? os.tmpdir());
             const id = config.id ?? randomBytes(6).toString("hex");
             const suffix = randomBytes(4).toString("hex");
             this.workspaceDir = anchorUnder(path, base, `sema-host-${sanitizeId(id)}-${suffix}`);
-            this.tenure = { kind: "held", root: this.workspaceDir };
+            this.tenure = { kind: "held", roots: [this.workspaceDir] };
         }
         const inheritEnvProblem = inheritEnvPolicyProblem(config.inheritEnv);
         if (inheritEnvProblem !== undefined)
@@ -178,11 +181,18 @@ export class RemoteHostExecutionEnv {
         return this.teardownSettled;
     }
     leftover = undefined;
+    get left() {
+        return this.hasLeft;
+    }
     get settled() {
-        return this.teardownSettled && this.tenure.kind !== "held";
+        return this.teardownSettled && this.hasLeft;
+    }
+    get heldRoots() {
+        return this.tenure.kind === "held" ? this.tenure.roots : NO_ROOTS;
     }
-    get heldWorkspace() {
-        return this.tenure.kind === "held" ? this.tenure.root : undefined;
+    assumeRoot(root) {
+        this.tenure = { kind: "held", roots: this.tenure.kind === "held" ? [...this.tenure.roots, root] : [root] };
+        trackUnlessAbsent(root);
     }
     workspaceHandle() {
         return this.handle;
@@ -243,17 +253,37 @@ export class RemoteHostExecutionEnv {
             catch { }
             this.spoolRootDir = undefined;
         }
+        this.hasLeft = true;
         const tenure = this.tenure;
         if (tenure.kind !== "held")
             return;
         this.tenure = RELEASED;
-        if (this.cfg.custody?.heldElsewhere(this, tenure.root) === true)
-            return;
-        try {
-            await fs.rm(tenure.root, { recursive: true, force: true });
-            untrackEphemeralHostWorkspace(tenure.root);
+        const tombs = [];
+        for (const root of tenure.roots) {
+            if (this.cfg.custody?.passOn(this, root) === true)
+                continue;
+            const tomb = removalTombOf(root);
+            try {
+                renameSync(root, tomb);
+            }
+            catch (e) {
+                if (e?.code === "ENOENT")
+                    untrackEphemeralHostWorkspace(root);
+                else
+                    trackUnlessAbsent(root);
+                continue;
+            }
+            trackEphemeralHostWorkspace(tomb);
+            untrackEphemeralHostWorkspace(root);
+            tombs.push(tomb);
         }
-        catch {
+        for (const tomb of tombs) {
+            try {
+                await fs.rm(tomb, { recursive: true, force: true });
+                untrackEphemeralHostWorkspace(tomb);
+            }
+            catch {
+            }
         }
     }
     async cleanup() {
@@ -1297,8 +1327,8 @@ export class RemoteHostExecutionEnv {
                 .mkdir(this.workspaceDir, { recursive: true })
                 .then(() => {
                 this.prepared = true;
-                if (this.tenure.kind === "held")
-                    trackEphemeralHostWorkspace(this.tenure.root);
+                for (const root of this.heldRoots)
+                    trackUnlessAbsent(root);
             })
                 .catch((e) => {
                 this.preparing = undefined;
@@ -1437,17 +1467,67 @@ function asError(e) {
 function signalNumber(signal) {
     return os.constants.signals[signal];
 }
+function heldRootContaining(custody, dir) {
+    const found = [];
+    custody.holder((m) => {
+        const root = m.heldRoots.find((r) => pathIsWithin(r, dir, canonicalPathOf));
+        if (root !== undefined)
+            found.push(root);
+        return root !== undefined;
+    });
+    return found[0];
+}
+function passOnRoot(custody, self, root) {
+    if (custody.holder((m) => m !== self && m.heldRoots.includes(root)) !== undefined)
+        return true;
+    const unreadable = [];
+    const occupant = custody.holder((m) => {
+        if (m === self || m.left)
+            return false;
+        try {
+            return pathIsWithin(root, m.cwd, canonicalPathOf);
+        }
+        catch (error) {
+            unreadable.push({ dir: m.cwd, error });
+            return false;
+        }
+    });
+    if (occupant !== undefined) {
+        occupant.assumeRoot(root);
+        return true;
+    }
+    const first = unreadable[0];
+    if (first === undefined)
+        return false;
+    trackUnlessAbsent(root);
+    writeLogText("stderr", `RemoteHostExecutionEnv: kept ${root} instead of removing it — could not read whether the working directory ${first.dir} lies inside it ` +
+        `(${errorCodeOf(first.error) ?? "unreadable"}); nobody takes it over, and the exit-time sweep removes it`);
+    return true;
+}
+function trackUnlessAbsent(root) {
+    let absent;
+    try {
+        absent = !presentOnDisk(root);
+    }
+    catch {
+        absent = false;
+    }
+    if (!absent)
+        trackEphemeralHostWorkspace(root);
+}
+function removalTombOf(root) {
+    return anchorUnder(path, path.dirname(root), `.${path.basename(root)}.removing-${randomBytes(4).toString("hex")}`);
+}
 export function hostExecutionEnvFactory(config = {}, legOf = () => ({})) {
     const custody = createWorkspaceCustody();
-    const heldElsewhere = (self, root) => custody.holder((m) => m !== self && m.heldWorkspace === root) !== undefined;
-    const rootHolding = (dir) => custody.holder((m) => m.heldWorkspace !== undefined && pathIsWithin(m.heldWorkspace, dir, canonicalPathOf))?.heldWorkspace;
+    const passOn = (self, root) => passOnRoot(custody, self, root);
     return (ctx) => {
         const { minted, ...leg } = legOf(ctx);
         const identity = ctx.taskId ?? ctx.sessionId;
         return custody.envOf(identity, () => {
             const dir = leg.workspaceDir ?? config.workspaceDir;
-            const sharedRoot = dir === undefined ? undefined : rootHolding(hostSeatPath(dir));
-            const env = new RemoteHostExecutionEnv({ ...config, ...leg, id: config.id ?? identity, custody: { heldElsewhere, ...(sharedRoot !== undefined ? { sharedRoot } : {}) } });
+            const sharedRoot = dir === undefined ? undefined : heldRootContaining(custody, hostSeatPath(dir));
+            const env = new RemoteHostExecutionEnv({ ...config, ...leg, id: config.id ?? identity, custody: { passOn, ...(sharedRoot !== undefined ? { sharedRoot } : {}) } });
             minted?.(env);
             return env;
         });

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

@@ -2,6 +2,7 @@ import { type SpaceReclaimer, type WorkspaceSpacePolicy, type CacheReclaimReason
 import { type SpaceCommitFence } from "../workspace-space-commit.js";
 import { type CacheMissMemory, type WorkspaceCacheCapability } from "../workspace-cache.js";
 import { type SandboxEgressGap, type SandboxIpv6 } from "../sandbox-egress-policy.js";
+import { type K8sApiCredentialFact } from "../k8s-api-credentials.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
@@ -10,6 +11,37 @@ import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { type ConnectResult } from "./remote-env-connect-seat.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, buildKillAllScript, parseBgPollOutput, type ParsedBgPoll, } from "./k8s-bg-scripts.js";
+/**
+ * This process's in-cluster identity: the platform's `KUBERNETES_SERVICE_*` and the mounted service-account files. `readMounted` throws when the file is unreadable.
+ * (In this file a bare `read(` names a control-plane GET — the RBAC table's source reader classifies every one — so the mount reader carries its own name.)
+ */
+export interface InClusterIdentity {
+    readonly host: string | undefined;
+    readonly port: string | undefined;
+    readMounted(file: "token" | "ca.crt"): string;
+}
+/** What the control plane can be reached with — or the ONE missing fact (with the adapter code its request-time refusal carries). */
+export type K8sApiAccess = {
+    readonly ok: true;
+    readonly apiUrl: string;
+    readonly token: string;
+    readonly ca: string | undefined;
+} | {
+    readonly ok: false;
+    readonly fact: K8sApiCredentialFact;
+    readonly code: "connect_failed" | "auth_failed";
+};
+/**
+ * The ONE judge of "does this lane have cluster API credentials": explicit config (`K8S_API_URL` / `K8S_TOKEN` / `K8S_CA_CERT_B64`, `K8S_INSECURE_TLS`) first, the
+ * in-cluster service account second, per piece. The request-time reader ({@link RemoteK8sExecutionEnv}'s `creds()`), the boot gate and the per-run credential
+ * reading all read THIS function — what the boot refuses on is exactly what every request would have thrown on. (No kubeconfig: this lane never reads one.)
+ */
+export declare function resolveK8sApiAccess(cfg: {
+    readonly apiUrl?: string | undefined;
+    readonly token?: string | undefined;
+    readonly caCert?: string | undefined;
+    readonly insecureTls?: boolean | undefined;
+}, inCluster?: InClusterIdentity): K8sApiAccess;
 export interface K8sEnvConfig extends LaneHomeConfig {
     /** API server URL. Default: in-cluster (`https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT`). */
     apiUrl?: string;
@@ -194,6 +226,21 @@ export interface K8sRequestOptions {
     signal?: AbortSignal;
     contentType?: string;
 }
+/**
+ * The control plane's reading of this lane's credentials, a closed set: `missing` (the judge's fact — nothing to send), `rejected` (the cluster answered HTTP 401),
+ * `accepted` (a 2xx answer: the credentials work), `unproven` (any other answer, or none — see {@link RemoteK8sExecutionEnv.apiCredentialReading}).
+ */
+export type ApiCredentialReading = {
+    readonly state: "missing";
+    readonly fact: K8sApiCredentialFact;
+} | {
+    readonly state: "rejected";
+} | {
+    readonly state: "accepted";
+} | {
+    readonly state: "unproven";
+    readonly detail: string;
+};
 export interface K8sEnvDeps {
     request?: (method: string, apiPath: string, body?: unknown, opts?: K8sRequestOptions) => Promise<{
         status: number;
@@ -203,6 +250,8 @@ export interface K8sEnvDeps {
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
     /** Worker-side object-store requests (the space pointer, listing, deletes). Default: global `fetch`; either way the request goes out through the egress exit (an endpoint that answers with a redirect is refused, never followed). */
     fetch?: typeof fetch;
+    /** This process's in-cluster identity (default: the process env's `KUBERNETES_SERVICE_*` and the mounted service-account files); a test replaces it. */
+    inCluster?: () => InClusterIdentity;
     /** 这只环境手里的读地板模块(缺席 ⇒ `createSandboxReadFloor` 按旋钮选;钉注入守地板的模块)。能力块的 `keepsReadFloor` 读它的状态。 */
     readFloor?: SandboxReadFloor;
 }
@@ -369,8 +418,18 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     get lifetimeMs(): number;
     private resolve;
     workspaceHandle(): WorkspaceHandle;
-    /** Resolved lazily so an in-cluster pod picks up its service account without explicit config. */
+    /** Resolved lazily so an in-cluster pod picks up its service account without explicit config ({@link resolveK8sApiAccess} is the one judge). */
     private creds;
+    /** The missing credential fact of this env's control-plane access, or `undefined` (nothing missing) — {@link resolveK8sApiAccess}, the one judge. */
+    missingApiCredential(): K8sApiCredentialFact | undefined;
+    /**
+     * The control plane's reading of this lane's credentials, asked once per run before its env is minted ({@link readSandboxApiCredentials}): the judge's missing fact
+     * ({@link missingApiCredential}), else one SelfSubjectAccessReview (answered for every authenticated caller) — an HTTP 401 is the cluster rejecting the credentials,
+     * a 2xx the cluster accepting them. ONLY a positive proof of rejection refuses: any other answer (403, 5xx, a request that threw or timed out) is `unproven` — another
+     * fact (a Role, an outage) that the lane's own connect answers loudly and retries within its own bounds; refusing the run on it would turn every API blip into a failed run.
+     * The caller counts an `unproven` reading (a registered fail-open arm). Never throws.
+     */
+    apiCredentialReading(): Promise<ApiCredentialReading>;
     /** Control-plane REST call (pod create/get/delete), bounded by rpcTimeoutMs. Injectable for tests. */
     private request;
     private openExec;
@@ -554,7 +613,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 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}. */
+    /** The key prefix of every snapshot object this env signs — `workspaceSnapshotPrefixOf`, the ONE reading of `keyPrefix` (unset ⇒ the default; the boot bucket check lists under the same reading); 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. */
@@ -927,6 +986,13 @@ 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 missing cluster-API credential fact of this k8s config's control-plane access ({@link RemoteK8sExecutionEnv.missingApiCredential}), or `undefined`. The boot
+ * gate's judgment: the one judge ({@link resolveK8sApiAccess}) over the config and the process's in-cluster identity. Never throws.
+ */
+export declare function sandboxApiCredentialFact(config: K8sEnvConfig, deps?: K8sEnvDeps): K8sApiCredentialFact | undefined;
+/** The control plane's reading of this lane's credentials ({@link RemoteK8sExecutionEnv.apiCredentialReading}; a control-plane env, no pod). Never throws. */
+export declare function readSandboxApiCredentials(config: K8sEnvConfig, deps?: K8sEnvDeps): Promise<ApiCredentialReading>;
 /** 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>;
 /**

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

@@ -9,7 +9,7 @@ import { appendFileStaged, buildCwdEnvCommand, createCwdGuardedCall, shellQuote,
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
 import { WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { SNAPSHOT_BUCKET_MISSING, isNoSuchBucketAnswer } from "./s3-answer.js";
-import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotIdHolds, snapshotKeyPrefixProblem, snapshotNameOwnedBy } from "../workspace-space.js";
+import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotIdHolds, snapshotKeyPrefixProblem, snapshotNameOwnedBy, workspaceSnapshotPrefixOf } from "../workspace-space.js";
 import { spaceCommitAlive } from "../workspace-space-commit.js";
 import { SESSION_INCARNATION_MISSING, incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
 import { WORKSPACE_CACHE_SPACE_LABEL, workspaceCacheClaimOf, workspaceCacheEnv } from "../workspace-cache.js";
@@ -18,6 +18,7 @@ import { PodDeleteRefused, reportPodDeleteFailed } from "./k8s-pod-delete-failur
 import { buildLivenessCut, commandBoundsOf, laneLivenessOf, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
 import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { SANDBOX_IPV6_DEFAULT, sandboxEgressGaps, sandboxPodSysctls } from "../sandbox-egress-policy.js";
+import { describeMissingK8sCredential } from "../k8s-api-credentials.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
@@ -44,6 +45,42 @@ const unsupported = (op) => ({
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a Kata pod sandbox (no managed memory snapshot — capabilities.suspendable=false; durable suspend degrades to checkpoint + cold rebuild)`),
 });
 const SA_DIR = "/var/run/secrets/kubernetes.io/serviceaccount";
+const processInCluster = () => ({
+    host: process.env.KUBERNETES_SERVICE_HOST,
+    port: process.env.KUBERNETES_SERVICE_PORT,
+    readMounted: (file) => readFileSync(`${SA_DIR}/${file}`, "utf8"),
+});
+export function resolveK8sApiAccess(cfg, inCluster = processInCluster()) {
+    const given = (v) => v !== undefined && v.trim() !== "";
+    const apiUrl = given(cfg.apiUrl) ? cfg.apiUrl : given(inCluster.host) ? `https://${inCluster.host}:${inCluster.port ?? "443"}` : undefined;
+    if (apiUrl === undefined)
+        return { ok: false, fact: "api_url", code: "connect_failed" };
+    let token = given(cfg.token) ? cfg.token : undefined;
+    if (token === undefined) {
+        try {
+            const mounted = inCluster.readMounted("token").trim();
+            token = mounted === "" ? undefined : mounted;
+        }
+        catch {
+            token = undefined;
+        }
+        if (token === undefined)
+            return { ok: false, fact: "token", code: "auth_failed" };
+    }
+    let ca = given(cfg.caCert) ? cfg.caCert : undefined;
+    if (ca === undefined && !cfg.insecureTls) {
+        try {
+            const mounted = inCluster.readMounted("ca.crt");
+            ca = given(mounted) ? mounted : undefined;
+        }
+        catch {
+            ca = undefined;
+        }
+        if (ca === undefined)
+            return { ok: false, fact: "ca", code: "auth_failed" };
+    }
+    return { ok: true, apiUrl, token, ca };
+}
 const EXEC_SUBPROTOCOLS = ["v5.channel.k8s.io", "v4.channel.k8s.io"];
 const WRITE_CHUNK_BYTES = 64 * 1024;
 import { applyPodSpecPatch, ADAPTER_VOLUME_NAMES, SANDBOX_POD_LABELS, SANDBOX_RUN_END_HOLD_ANNOTATION, SANDBOX_RUN_LABEL, SANDBOX_SECRET_SEAT_VERBS, isLabelValue } from "./k8s-exec-protocol.js";
@@ -179,6 +216,42 @@ export function boundedStoreCall(op, bound) {
         });
     });
 }
+function snapshotOpOf(req) {
+    if (req.method === "LIST")
+        return req.lane === "space" ? "k8s-space/prefix:LIST" : "k8s-park/prefix:LIST";
+    if ("object" in req)
+        return req.lane === "space" ? "k8s-space/object:DELETE" : "k8s-park/object:DELETE";
+    if ("pointer" in req) {
+        switch (req.method) {
+            case "GET":
+                return "k8s-space/latest:GET";
+            case "PUT":
+                return "k8s-space/latest:PUT";
+            case "DELETE":
+                return "k8s-space/latest:DELETE";
+        }
+    }
+    if (req.lane === "park") {
+        switch (req.method) {
+            case "GET":
+                return "k8s-park/archive:GET";
+            case "PUT":
+                return "k8s-park/archive:PUT";
+            case "HEAD":
+                return "k8s-park/archive:HEAD";
+        }
+    }
+    switch (req.method) {
+        case "GET":
+            return "k8s-space/archive:GET";
+        case "PUT":
+            return "k8s-space/archive:PUT";
+        case "DELETE":
+            return "k8s-space/archive:DELETE";
+        case "HEAD":
+            return "k8s-space/archive:HEAD";
+    }
+}
 import { execSocketTlsOptions, exitCodeFromStatus } from "./k8s-exec-protocol.js";
 export { execSocketTlsOptions } from "./k8s-exec-protocol.js";
 export function errorMessageOf(e) {
@@ -323,29 +396,32 @@ export class RemoteK8sExecutionEnv {
         return { sandboxId: this.podName ?? "(unconnected)", provider: PROVIDER, mountPath: this.cwd, ...(this.handleSnapshotId ? { snapshotId: this.handleSnapshotId } : {}) };
     }
     creds() {
-        const apiUrl = this.cfg.apiUrl ??
-            (process.env.KUBERNETES_SERVICE_HOST ? `https://${process.env.KUBERNETES_SERVICE_HOST}:${process.env.KUBERNETES_SERVICE_PORT ?? "443"}` : undefined);
-        if (!apiUrl)
-            throw new RemoteExecutionError("connect_failed", "no k8s API: set K8S_API_URL or run in-cluster");
-        let token = this.cfg.token;
-        let ca = this.cfg.caCert;
-        if (!token) {
-            try {
-                token = readFileSync(`${SA_DIR}/token`, "utf8").trim();
-            }
-            catch {
-                throw new RemoteExecutionError("auth_failed", "no k8s token: set K8S_TOKEN or run in-cluster with a service account");
-            }
+        const access = resolveK8sApiAccess(this.cfg, this.deps.inCluster?.());
+        if (!access.ok)
+            throw new RemoteExecutionError(access.code, describeMissingK8sCredential(access.fact));
+        return { apiUrl: access.apiUrl.replace(/\/+$/, ""), token: access.token, ca: access.ca };
+    }
+    missingApiCredential() {
+        const access = resolveK8sApiAccess(this.cfg, this.deps.inCluster?.());
+        return access.ok ? undefined : access.fact;
+    }
+    async apiCredentialReading() {
+        const fact = this.missingApiCredential();
+        if (fact !== undefined)
+            return { state: "missing", fact };
+        try {
+            const r = await this.request("POST", "/apis/authorization.k8s.io/v1/selfsubjectaccessreviews", {
+                apiVersion: "authorization.k8s.io/v1",
+                kind: "SelfSubjectAccessReview",
+                spec: { resourceAttributes: { namespace: this.cfg.namespace, verb: "create", resource: "pods" } },
+            });
+            if (r.status === 401)
+                return { state: "rejected" };
+            return r.status >= 200 && r.status < 300 ? { state: "accepted" } : { state: "unproven", detail: `HTTP ${r.status}` };
         }
-        if (!ca && !this.cfg.insecureTls) {
-            try {
-                ca = readFileSync(`${SA_DIR}/ca.crt`, "utf8");
-            }
-            catch {
-                throw new RemoteExecutionError("auth_failed", "no k8s CA: set K8S_CA_CERT_B64, K8S_INSECURE_TLS=true (lab), or run in-cluster");
-            }
+        catch (e) {
+            return { state: "unproven", detail: errorMessageOf(e) };
         }
-        return { apiUrl: apiUrl.replace(/\/+$/, ""), token, ca };
     }
     async request(method, apiPath, body, opts) {
         if (this.deps.request)
@@ -1002,12 +1078,13 @@ export class RemoteK8sExecutionEnv {
         if (snapshotKeyPrefixProblem(this.snapshotKeyPrefix()) !== undefined)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "unsafe snapshot key segment (keyPrefix): refusing to build a traversing object key") };
         const common = {
+            op: snapshotOpOf(req),
             endpoint: s3.endpoint,
             bucket: s3.bucket,
             accessKey: s3.accessKey,
             secretKey: s3.secretKey,
             ...(s3.region ? { region: s3.region } : {}),
-            expiresSec: Math.min(s3.presignTtlSec ?? 600, 3600),
+            ...(s3.presignTtlSec !== undefined ? { expiresSec: s3.presignTtlSec } : {}),
         };
         const base = this.snapshotBase(req);
         if (req.method === "LIST")
@@ -1016,7 +1093,7 @@ export class RemoteK8sExecutionEnv {
         return { ok: true, value: presignS3Url({ ...common, key: `${base}${object}`, method: req.method }) };
     }
     snapshotKeyPrefix() {
-        return this.cfg.s3Snapshot?.keyPrefix ?? WORKSPACE_SNAPSHOT_PREFIX_DEFAULT;
+        return workspaceSnapshotPrefixOf(this.cfg.s3Snapshot);
     }
     snapshotBase(req) {
         const prefix = this.snapshotKeyPrefix();
@@ -2426,6 +2503,12 @@ export function createSpaceReclaimer(config, deps) {
 export async function checkSandboxEgressPolicy(config, deps) {
     return new RemoteK8sExecutionEnv(config, deps).egressPolicyGaps();
 }
+export function sandboxApiCredentialFact(config, deps) {
+    return new RemoteK8sExecutionEnv(config, deps).missingApiCredential();
+}
+export async function readSandboxApiCredentials(config, deps) {
+    return new RemoteK8sExecutionEnv(config, deps).apiCredentialReading();
+}
 export async function readSandboxSecretSeat(config, seat, deps) {
     return new RemoteK8sExecutionEnv(config, deps).secretSeatReading(seat);
 }

package/dist/plugins/replica-registration.d.ts

@@ -5,7 +5,7 @@ export declare const REPLICA_REGISTRATION_TABLE = "replica_registration";
  * 本构建的能力名单(常设、只增):每一条读停-迁-起证据的一次性迁移一个名。删码之后名字留着 —— 名单只增不减(钉:`test/replica-registration.test.ts`)。
  * 守卫读证据时传的名在型上就要在这里(`ReplicaCapability`):不在名单里的迁移读不了证据,编译期红。
  */
-export declare const REPLICA_CAPABILITIES: readonly ["M40", "M41", "M42", "M43", "M51"];
+export declare const REPLICA_CAPABILITIES: readonly ["M40", "M41", "M42", "M43", "M51", "M54"];
 export type ReplicaCapability = (typeof REPLICA_CAPABILITIES)[number];
 /** 留存视界(写者钟):登记早于此的别人的行在下一次登记时删。量级取远大于任一副本的寿命与副本间钟差。 */
 export declare const REPLICA_REGISTRATION_HORIZON_MS: number;

package/dist/plugins/replica-registration.js

@@ -2,7 +2,7 @@ import { hostname } from "node:os";
 import { processInstanceId } from "../process-instance.js";
 import { serviceVersion } from "../service-version.js";
 export const REPLICA_REGISTRATION_TABLE = "replica_registration";
-export const REPLICA_CAPABILITIES = ["M40", "M41", "M42", "M43", "M51"];
+export const REPLICA_CAPABILITIES = ["M40", "M41", "M42", "M43", "M51", "M54"];
 export const REPLICA_REGISTRATION_HORIZON_MS = 90 * 24 * 60 * 60 * 1000;
 export function buildThisReplicaRegistration() {
     return { instanceId: processInstanceId(), releaseLine: serviceVersion(), capabilities: REPLICA_CAPABILITIES, hostName: hostname(), pid: process.pid };