@sema-agent/server 7.126.0 → 7.127.1

package/dist/plugins/host-platform.js

@@ -4,6 +4,7 @@ export const IS_WIN32 = process.platform === "win32";
 const POSIX_SH_FALLBACK = { shell: "/bin/sh", args: ["-c"] };
 let cachedWinShell;
 let cachedPosixShell;
+let winShellFailure;
 export async function resolveHostShell() {
     if (!IS_WIN32) {
         if (cachedPosixShell)
@@ -15,26 +16,38 @@ export async function resolveHostShell() {
     if (cachedWinShell)
         return cachedWinShell;
     const custom = process.env.HOST_SHELL_PATH;
-    const cfg = await getShellConfig(custom || undefined);
-    if (!cfg.ok) {
-        throw new Error(`host lane needs a POSIX shell on Windows and none was found${custom ? ` (HOST_SHELL_PATH=${custom})` : ""}: ` +
-            `${cfg.error.message}. Install Git for Windows (https://gitforwindows.org) or set HOST_SHELL_PATH to a bash.exe. ` +
-            `Note: System32\\bash.exe is the WSL launcher, not a Windows bash — it is deliberately rejected.`);
+    try {
+        const cfg = await getShellConfig(custom || undefined);
+        if (!cfg.ok) {
+            throw new Error(`host lane needs a POSIX shell on Windows and none was found${custom ? ` (HOST_SHELL_PATH=${custom})` : ""}: ` +
+                `${cfg.error.message}. Install Git for Windows (https://gitforwindows.org) or set HOST_SHELL_PATH to a bash.exe. ` +
+                `Note: System32\\bash.exe is the WSL launcher, not a Windows bash — it is deliberately rejected.`);
+        }
+        cachedWinShell = { shell: cfg.value.shell, args: cfg.value.args };
+        return cachedWinShell;
+    }
+    catch (e) {
+        winShellFailure = e instanceof Error ? e : new Error(String(e));
+        throw winShellFailure;
     }
-    cachedWinShell = { shell: cfg.value.shell, args: cfg.value.args };
-    return cachedWinShell;
 }
 export function hostShell() {
     if (!IS_WIN32) {
         return cachedPosixShell ?? POSIX_SH_FALLBACK;
     }
-    if (!cachedWinShell)
-        throw new Error("host shell not resolved yet — resolveHostShell() must settle before any spawn (shellReady ordering bug)");
-    return cachedWinShell;
+    if (cachedWinShell)
+        return cachedWinShell;
+    throw winShellFailure ?? new Error("host shell not resolved yet — resolveHostShell() must settle before any spawn (shellReady ordering bug)");
+}
+export function pinHostShell(env, sh) {
+    if (IS_WIN32)
+        env.SHELL = sh.shell;
+    return env;
 }
 export function resetHostShellCacheForTest() {
     cachedWinShell = undefined;
     cachedPosixShell = undefined;
+    winShellFailure = undefined;
 }
 export function spawnGroupOptions() {
     return IS_WIN32 ? { detached: false, windowsHide: true } : { detached: true };

package/dist/plugins/k8s-exec-protocol.js

@@ -1,5 +1,8 @@
 export function applyPodSpecPatch(pod, patch) {
     assertHardeningOnly(patch.podSecurityContext, "podSecurityContext");
+    if (patch.podSecurityContext !== undefined && "sysctls" in patch.podSecurityContext) {
+        throw new Error("podSpecPatch.podSecurityContext rejected — `sysctls` is not a patch key (the pod's sysctls are minted only by the lane's IPv6 posture, K8S_SANDBOX_IPV6)");
+    }
     assertHardeningOnly(patch.containerSecurityContext, "containerSecurityContext");
     if (patch.labels) {
         const identity = {};

package/dist/plugins/one-time-migrations.d.ts

@@ -12,8 +12,8 @@
  * **≥** 某条未发布形的 `introducedIn` 而两格仍是 `null` ⇒ 红(发布准备提交就是回填时刻,忘了就当场红;版本更低 = 还在开发,不红)。
  * 最后一条删掉时,整个文件连同 `StoreBackend.runOneTimeMigrations()`(npm 公面上的接口成员)、`NO_SQL_MIGRATIONS`、
  * `logOneTimeMigrations`、三只后端与两只测试夹具上的实现、`boot/stores.ts` 的调用点一起删 —— 唯一例外是退役 schema 的拒启臂
- * ({@link assertRetiredSchemaAbsent} 与它的错误类型、两件退役 schema 的坐标):它没有窗,跳版升级的库永远可能出现,删最后一条的车要把它搬进启动期对账
- * (`schema-consistency.ts` 一族)并保住它先于一切改写的位置,不要随文件删掉。
+ * ({@link assertRetiredSchemaAbsent}、探针口 {@link assertRetiredSchemaAbsentOnPool} 与它们的错误类型、两件退役 schema 的坐标):它没有窗,跳版升级的库永远可能出现,
+ * 删最后一条的车要把它搬进启动期对账(`schema-consistency.ts` 一族)并保住它先于一切建表与改写的位置(现位:`store-backend.ts` 里 SQL 两后端的 `ensureSchema()` 自身,探针先于它的第一条 CREATE),不要随文件删掉。
  * 其余文件一律只写「窗口见本文件登记表」,不各写一个日期或版本 —— S-590 之前本文件头写死了一个删除版本号(7.75.0),
  * 连同 11 个文件里的复述共 23 行;那一版过去了 28 个 minor 也没删,7.93.5 反倒往本文件里又加了 M4。
  *
@@ -33,6 +33,10 @@
  * 7.64.0–7.71.0 恒带两者),所以**旧拼法不另扫**:一条对账本 `task_event` 的无索引整表扫正是当年被判不许成为每次启动固定开销的东西
  * (账本是全站最大的表,PG 池级 `statement_timeout` 会把它切成拒启、每次启动重演)。两件任一在场 ⇒ 这只库没有经过带迁移的版本 ⇒ 旧拼法的改写同样没跑过 ⇒ 拒句一并点名。
  * 出路:先在 7.125.x(最后一个带这三条迁移的版)上起服一次让它们跑完,再升。
+ * **判据一只、读一处**:判据只有 {@link assertRetiredSchemaAbsent} 一只,唯一的读处是**探针口**({@link assertRetiredSchemaAbsentOnPool}):库一连上就探,先于 `ensureSchema()`
+ * 发出的任何一条 CREATE —— 一次会拒的起服不许先在库里建出几十张本版新表(`task_run` 还带着新列),否则拒句里「没动过库」就是假话,而按拒句指路去 7.125.x 起服的人会撞上
+ * 「库比 7.125.x 新」的第二道拒。探针与建表的先后只写在 `store-backend.ts` 里 SQL 两后端的 `ensureSchema()` 自身(装配处包一次)。迁移段入口({@link runSqlOneTimeMigrations})**不再问**这一问:
+ * 它只在 `ensureSchema()` 之后被起服序列调用,一个事实不在两处各读一遍;嵌入方走公开序列 `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()` 即得到这一问,零动作。
  * 残余(如实):运维在第一次起带迁移的版本之前就把两件退役 schema 都手工删掉的库,残留的旧拼法由读腿既有的 `server.trace.gate-outcome-defective`
  * (整条 withhold + 计数 + 一次 warn)接住;local 文件车道没有表与列,没有这一问的探针 —— 引擎 File 店里已决 checkpoint 的记录按契约物理不可变,本仓没有合法缝改写它们
  * (下游不改上游盘上格式),同由那条读腿接住。
@@ -125,6 +129,7 @@
  */
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+import { StoreBootRefusalError } from "./store-contracts.js";
 import { type UndurableScopeRuleRow, type UnreadableRuleBucket } from "./permission-rule-store-sql.js";
 /** 迁移读数(启动日志一行写全;测试按它断言,不靠日志文本)。 */
 export interface OneTimeMigrationReport {
@@ -200,13 +205,31 @@ export interface MigrationLogSink {
 /**
  * 跳版升级的库的拒启:退役 schema(快照索引表 / 单座列)任一仍在。**具名类型**:锚类型不锚文案(日志消费端与测试按 `code` / 类型分派);
  * 码取列册探针同一个 `config.schema_mismatch`,运维面一个拒启码一个读法。拒句点名在场的坐标、说明第三条(旧拼法改写)同样没跑过、给出路。
+ * 继承 {@link StoreBootRefusalError}:这是一句**确定**的拒启表态(再等也等不来另一个答案)—— `ensureSchema()` 里它不被 SQL 开库的等待窗重试、不被改写成「库打不开」的拒句。
  */
-export declare class RetiredSchemaPresentError extends Error {
+export declare class RetiredSchemaPresentError extends StoreBootRefusalError {
     readonly found: readonly string[];
     /** 机读码(与列册探针的拒启同一个)。 */
     readonly code = "config.schema_mismatch";
     constructor(found: readonly string[]);
 }
+/** 探针口的池参数:方言与它的池一起走(判别联合 ⇒ 不靠调用方断言「这个池是哪种」)。 */
+export type RetiredSchemaProbeTarget = {
+    readonly dialect: "tidb";
+    readonly pool: MysqlPool;
+} | {
+    readonly dialect: "pg";
+    readonly pool: PgPool;
+};
+/**
+ * **探针口**(退役 schema 唯一的读处):库一连上、**任何 DDL 之前**探一遍,在场 ⇒ 抛 {@link RetiredSchemaPresentError}。本仓唯一调用点 =
+ * `store-backend.ts` 的 `withRetiredSchemaProbe`(SQL 两后端的 `ensureSchema()` 自身:探针先于建表的先后只写在那一处,不在两方言各写一遍)。**不在包根上**:
+ * 嵌入方经公开序列的 `ensureSchema()` 得到这一问,不需要自己排序列。
+ *
+ * 不取 `ensureSchema` 那把 advisory 锁:本口纯读(两条目录探针),不改任何东西,与别的副本正在跑的建表 / 迁移互不相干 —— 它们之间的先后不影响本口的判据
+ * (退役 schema 只会被 7.125.x 的迁移删去、不会被谁凭空建回)。用完即还连接,拒启时连接也已归还。
+ */
+export declare function assertRetiredSchemaAbsentOnPool(target: RetiredSchemaProbeTarget): Promise<void>;
 /**
  * SQL 两后端的一次性迁移。**调用点只有一个**(boot/stores.ts,在 `ensureSchema` 之后、任何路由装配
  * 之前)—— 拒启在那一刻仍然是拒启(还没开始服务),而 `ensureSchema` 那条通道的契约是「只发 CREATE」
@@ -223,7 +246,8 @@ export declare class RetiredSchemaPresentError extends Error {
  * 非破坏改写(M4–M9:改值不丢信息 / 加法 DDL / 复制 + 换名)在前,破坏性步骤(M11 的删行)排在最后;
  * M11 自己半途失败时,拒因自带已删的行(`purgeUndurableScopeRows`)—— 否则重试看不见已删的行,证据永久消失。
  *
- * @throws {RetiredSchemaPresentError} 退役 schema 仍在(跳版升级的库;唯一的拒启臂,先于一切改写)。
+ * 本函数**不问**退役 schema:带着它的库在更早处就被 `ensureSchema()` 自身拒掉了({@link assertRetiredSchemaAbsentOnPool},先于建表);走公开序列
+ * `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()` 的嵌入方与本服务的起服序列一样,有这一问、零动作。
  */
 export declare function runSqlOneTimeMigrations(dialect: "tidb" | "pg", pool: MysqlPool | PgPool): Promise<OneTimeMigrationReport>;
 /** M8 一行改写的结论:改写后的文本 / 这一行不用动 / 读不懂(解析错误原样交出,调用方计数进读数)。 */

package/dist/plugins/one-time-migrations.js

@@ -4,7 +4,7 @@ import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { decodeJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, readNonNullJsonValueColumn } from "./sql-json-column.js";
 import { SESSION_META_INCARNATION_COLUMN, mintSessionIncarnation } from "../session-incarnation.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError } from "./store-contracts.js";
 import { PERMISSION_RULE_TABLE, purgeUndurableScopeRows } from "./permission-rule-store-sql.js";
 import { SCHEMA_MISMATCH_ERROR_CODE } from "./schema-consistency.js";
 export const ONE_TIME_MIGRATIONS = [
@@ -198,7 +198,7 @@ const AUDIT_TABLE = "device_audit";
 const AUDIT_DETAIL_COLUMN = "detail";
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT_COLUMN = "pending_steer";
-export class RetiredSchemaPresentError extends Error {
+export class RetiredSchemaPresentError extends StoreBootRefusalError {
     found;
     code = SCHEMA_MISMATCH_ERROR_CODE;
     constructor(found) {
@@ -209,7 +209,7 @@ export class RetiredSchemaPresentError extends Error {
             `This build carries none of the three and will not guess. ` +
             `Way out: start a server 7.125.x build once against this database and let its one-time migrations finish (it drops the table and the column and rewrites the spelling; ` +
             `while the column still holds a steering instruction that can be delivered it refuses and names the rows and its own ways out), then upgrade to this build. ` +
-            `The check behind this refusal is read-only and runs before any rewrite: it changed nothing in the database.`);
+            `The check behind this refusal is read-only and runs before this build creates any table or rewrites anything: it changed nothing in the database.`);
         this.found = found;
         this.name = "RetiredSchemaPresentError";
     }
@@ -267,6 +267,25 @@ async function assertRetiredSchemaAbsent(db, dialect) {
     if (found.length > 0)
         throw new RetiredSchemaPresentError(found);
 }
+export async function assertRetiredSchemaAbsentOnPool(target) {
+    if (target.dialect === "tidb") {
+        const conn = await target.pool.getConnection();
+        try {
+            await assertRetiredSchemaAbsent(mysqlDb(conn), "tidb");
+        }
+        finally {
+            conn.release();
+        }
+        return;
+    }
+    const client = await target.pool.connect();
+    try {
+        await assertRetiredSchemaAbsent(pgDb(client), "pg");
+    }
+    finally {
+        client.release();
+    }
+}
 export async function runSqlOneTimeMigrations(dialect, pool) {
     return dialect === "tidb" ? withMysqlLock(pool, (db) => migrateOn(db, "tidb")) : withPgLock(pool, (db) => migrateOn(db, "pg"));
 }
@@ -299,7 +318,6 @@ async function withPgLock(pool, run) {
     }
 }
 async function migrateOn(db, dialect) {
-    await assertRetiredSchemaAbsent(db, dialect);
     const auditTablePresent = await tableExists(db, dialect, AUDIT_TABLE);
     const auditDetailJsonNullRows = !auditTablePresent
         ? 0

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

@@ -1,4 +1,4 @@
-import { FileError, 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 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, 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";
 /** 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` 梯子用它排升级定时器;会话级收敛
@@ -96,8 +96,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     readonly homeDir?: string | undefined;
     /**
      * core 7.49.0 #1554:shell 子进程**真拿到的** `CDPATH` 条目(`[]` = 没有)—— 删除守卫按它解裸 `cd <dir>`。本车道的命令就是本机子进程,
-     * env 是本类自己组合的(继承姿态 + `cfg.env`),所以说得出:读同一只组合({@link childEnv},不披露),切法与 core `NodeExecutionEnv` 同
-     * (缺席 / 空串 ⇒ `[]`,否则按 `:` 切)。逐命令的 `options.env` 由引擎自己交,它知道。
+     * env 是本类自己组合的(继承姿态 + `cfg.env`),所以说得出:读同一只组合({@link childEnv} 的**读面**,不披露、不钉 shell),切法与 core
+     * `NodeExecutionEnv` 同(缺席 / 空串 ⇒ `[]`,否则按 `:` 切)。逐命令的 `options.env` 由引擎自己交,它知道。
+     * 🔴 读面**不依赖 shell 落定**:core 判 Bash 的策略链在任何 exec 之前就读它(shell 解析在 exec 路径上才发生),所以这里不能碰
+     * {@link hostShell}(win32 上未落定同步抛 —— 修前每条 Bash 的策略链都因此被拒)。
      */
     get cdPath(): readonly string[];
     private readonly workspaceDir;
@@ -290,6 +292,16 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         maxLines?: number;
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
+    /** core `NodeExecutionEnv` 的绑定读器 —— 首次 {@link openBound} 时建(构造无副作用,只记 cwd)。 */
+    private boundReader;
+    /**
+     * core 7.50.0 `FileSystem.openBound`:开着并**持有**一只对象(叶链接不跟,开后身份对拍),调用方判的与读的是同一只对象 ——
+     * LSP 会话的读口与路径附件只经它读,不实现 ⇒ 两者在本车道一律拒。
+     * 🔴 **不重写**:委托 core `NodeExecutionEnv.openBound`(O_NOFOLLOW 开句柄 + fstat / 路径身份对拍的唯一属主;本车道的命令就跑在
+     * 这台机器、这个用户下,与它判的是同一个文件系统)。本适配器只给它两道与其余读口同一的入口纪律:销毁后拒(`fsReady`)与
+     * 工作区相对解析(`resolve`)。持有的对象由调用方关;本适配器的 destroy 不追它(只读句柄,活到被关)。
+     */
+    openBound(p: string, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
     /** S-539:整只方法体(**含** `fsReady` 那道门)走 `withInflightFs` —— 登记必须与调用方同一同步段,
      *  否则 destroy 的快照可能刚好在 `await this.fsReady(...)` 的让出点上取完。见那处头注。 */
@@ -412,11 +424,16 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  source of the shape rule) minus the config catalog's `secret`-typed names (`scrubServerSecrets`, 7.99.0 F7). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
      *  maps `true`→`"all"` / `false`→`[]`. */
     private inheritMode;
-    /** 每次 spawn 交给子进程的 env(组合 + 剥除披露)。 */
+    /** 每次 spawn 交给子进程的 env(组合 + 剥除披露 + win32 的 SHELL 钉)。`sh` = 调用点刚从 {@link hostShell} 读到的那只(spawn 路径
+     *  都在 `shellReady()` 之后):没有已落定的 shell 就到不了这条腿 —— 类型即次序守卫。 */
     private mergeEnv;
     /**
-     * 子进程 env 的**唯一组合**。`disclose` = 这一次是不是真要交给子进程(是 ⇒ scrub 腿经 `hostSubprocessEnv` 记剥除;否 ⇒ 只读组合,
-     * 不计数 —— {@link cdPath} 这类「子进程会拿到什么」的读者走这一臂,一次没发生的 spawn 不进剥除账)。
+     * 子进程 env 的**唯一组合**,分两层(一条律:**env 组合是纯函数,shell 只属于 spawn**):
+     *  · **组合层**(恒有)—— 继承姿态 + `cfg.env` + perCommand + win32 大小写折叠。**不碰 shell**,所以读面(如 {@link cdPath})任何时候
+     *    都能读,不依赖 shell 是否已落定。
+     *  · **spawn 层**(`spawnShell` 在场)—— 这一次是真要交给子进程:scrub 腿经 `hostSubprocessEnv` 记剥除(`spawnShell` 缺席 ⇒ 只读组合,
+     *    不计数:一次没发生的 spawn 不进剥除账),win32 上把 `SHELL` 钉到已解析的 Git Bash({@link pinHostShell},在大小写折叠**之前**)。
+     * 披露与钉同一个开关(`spawnShell`)—— 「真 spawn」只有一种说法,不再有 `disclose` 与钉各自一个布尔。
      */
     private childEnv;
     private fileError;

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

@@ -7,9 +7,9 @@ import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdi
 import { StringDecoder } from "node:string_decoder";
 import { armPipeDestroyGrace, numEnvOr, SYMLINK_CHAIN_MAX_HOPS } from "./remote-shell.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
-import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
+import { 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, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
+import { FileError, NodeExecutionEnv, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
 import { allowlistedEnv, composeHostSubprocessEnv, hostSubprocessEnv } from "../server-secret-env.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
@@ -58,7 +58,7 @@ export class RemoteHostExecutionEnv {
     cwd;
     homeDir;
     get cdPath() {
-        const value = this.childEnv(undefined, false).CDPATH;
+        const value = this.childEnv(undefined, undefined).CDPATH;
         return value === undefined || value === "" ? [] : value.split(":");
     }
     workspaceDir;
@@ -233,7 +233,7 @@ export class RemoteHostExecutionEnv {
                         const sh = hostShell();
                         child = spawn(sh.shell, [...sh.args, command], {
                             cwd: self.resolve(options?.cwd ?? self.cwd),
-                            env: self.mergeEnv(options?.env),
+                            env: self.mergeEnv(options?.env, sh),
                             ...spawnGroupOptions(),
                             stdio: ["ignore", outFh.fd, errFh.fd],
                         });
@@ -412,7 +412,7 @@ export class RemoteHostExecutionEnv {
             const sh = hostShell();
             const child = spawn(sh.shell, [...sh.args, command], {
                 cwd,
-                env: this.mergeEnv(options?.env),
+                env: this.mergeEnv(options?.env, sh),
                 ...spawnGroupOptions(),
             });
             const ticket = adoptHostForegroundChild(child);
@@ -672,7 +672,7 @@ export class RemoteHostExecutionEnv {
             try {
                 child = spawn(sh.shell, [...sh.args, command], {
                     cwd,
-                    env: this.mergeEnv(options?.env),
+                    env: this.mergeEnv(options?.env, sh),
                     ...spawnGroupOptions(),
                     stdio: ["ignore", spool.fds[0], spool.fds[1]],
                 });
@@ -814,7 +814,7 @@ export class RemoteHostExecutionEnv {
         let wake;
         const signalReady = () => { const w = wake; wake = undefined; w?.(); };
         const sh = hostShell();
-        const child = spawn(sh.shell, [...sh.args, command], { cwd, env: this.mergeEnv(options?.env), ...spawnGroupOptions() });
+        const child = spawn(sh.shell, [...sh.args, command], { cwd, env: this.mergeEnv(options?.env, sh), ...spawnGroupOptions() });
         const ticket = adoptHostForegroundChild(child);
         let pipeDestroyTimer;
         const kill = () => {
@@ -958,6 +958,14 @@ export class RemoteHostExecutionEnv {
             lines = lines.slice(0, options.maxLines);
         return ok(lines);
     }
+    boundReader;
+    async openBound(p, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        this.boundReader ??= new NodeExecutionEnv({ cwd: this.workspaceDir });
+        return this.boundReader.openBound(this.resolve(p), abortSignal);
+    }
     async readBinaryFile(p, abortSignal) {
         const ready = await this.fsReady(p);
         if (!ready.ok)
@@ -1311,10 +1319,11 @@ export class RemoteHostExecutionEnv {
             return "all";
         return "scrub";
     }
-    mergeEnv(perCommand) {
-        return this.childEnv(perCommand, true);
+    mergeEnv(perCommand, sh) {
+        return this.childEnv(perCommand, sh);
     }
-    childEnv(perCommand, disclose) {
+    childEnv(perCommand, spawnShell) {
+        const disclose = spawnShell !== undefined;
         const mode = this.inheritMode();
         let base;
         if (mode === "all")
@@ -1332,8 +1341,8 @@ export class RemoteHostExecutionEnv {
             Object.assign(base, this.cfg.env);
         if (perCommand)
             Object.assign(base, perCommand);
-        if (process.platform === "win32")
-            base.SHELL = hostShell().shell;
+        if (spawnShell)
+            pinHostShell(base, spawnShell);
         return collapseWin32EnvKeys(base);
     }
     fileError(e, p, abortSignal) {

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

@@ -1,6 +1,7 @@
 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];
@@ -50,6 +51,9 @@ export interface K8sEnvConfig {
     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;
@@ -209,6 +213,8 @@ export { execSocketTlsOptions } from "./k8s-exec-protocol.js";
  *  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`
@@ -237,6 +243,10 @@ 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,
@@ -282,6 +292,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 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>;
     /** This env holds a workspace its `destroy()` will commit ⇒ arm its seat on the space's commit fence (from here the
@@ -320,7 +332,9 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * 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;
     /**
@@ -348,6 +362,12 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     } | ({
         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. */
@@ -473,12 +493,21 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *    by the bucket's lifecycle rule or a hand): the data is gone by an operator rule ⇒ loud and continuable —
      *    {@link dropDanglingLatest} (one `workspace_latest_dangling` line, the pointer deleted); the run's own run-end
      *    snapshot then becomes the new `latest`.
-     * A restore that does not complete releases the pod it provisioned: no tool and no run-end snapshot may ever see a
-     * torn workspace. On the space lane that failure is the archive `latest` names being THERE but not coming back
-     * ({@link RestoreFailureClass}): the run is refused all the same — never an empty workspace (the user's changes are still in
-     * the bucket) — with exactly one `workspace_restore_failed` line and a refusal naming the two ways out.
+     * 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
@@ -645,6 +674,12 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
  * 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