@sema-agent/server 7.131.0 → 7.133.0

package/dist/plugins/remote-env-local-docker.d.ts

@@ -1,24 +1,16 @@
 import { spawn } from "node:child_process";
+import { type LaneHomeConfig } from "../lane-home-probe.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 } 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];
 /** Construction config for {@link RemoteLocalDockerExecutionEnv}. */
-export interface LocalDockerEnvConfig {
+export interface LocalDockerEnvConfig extends LaneHomeConfig {
     /**
      * Base container image to run the task in. **REQUIRED — no default** (domestic-images iron rule: the registry
      * is the operator's choice, never a hardcoded `docker.io` origin). e.g. the docker.io/claybobby pool or an
      * in-network `node:20` mirror (SWR deprecated).
      */
     image: string;
-    /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
-     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
-     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
-     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
-     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
-     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
-     */
-    homeDir?: string;
     /** Workspace root INSIDE the container; relative paths resolve against it. Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
     /** Path to the docker binary (or a docker-compatible CLI). Default "docker" (must be on PATH in the worker). */
@@ -77,8 +69,8 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     };
     /** Working directory inside the container; relative paths resolve against it (ExecutionEnv contract). */
     cwd: string;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):本容器里执行用户的 home —— 声明胜,否则开容器那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    get homeDir(): string | undefined;
     /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在容器里(镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -93,6 +85,10 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     private destroyed;
     /** In-flight connect, memoized so concurrent lazy first-use starts exactly one container (no double-run). */
     private connecting?;
+    /** 家目录:环境答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。 */
+    private homeRefusal?;
+    /** 家目录的座(声明胜 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    private readonly homeSeat;
     constructor(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps);
     private resolve;
     workspaceHandle(): WorkspaceHandle;
@@ -104,6 +100,13 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         error: RemoteExecutionError;
     }>;
     private doConnect;
+    /**
+     * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 实测)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、同一份 `-e` env),读数交座。
+     * 声明在场:环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,
+     * 但不记(与任何一次起容器失败同:下一次连接重问)。没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,环境照开(没声明就没有声明可拒)。
+     * 调用方中止 ⇒ `aborted`、不记、不交座。容器由调用方收。
+     */
+    private homeVerdict;
     suspendVM(_options?: VmLifecycleOptions): Promise<{
         ok: true;
         value: SnapshotId;
@@ -183,6 +186,12 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
+    /**
+     * 交给宿主 `docker` CLI 的 env —— 宿主子进程 env 的唯一组合(`server-secret-env.ts` `hostSubprocessEnv`),继承词 `"all"`:本服务自有凭据(起服声明的名与值)
+     * 任何词都不交,CLI 与它拉起的凭据助手 / CLI 插件要读的变量(`DOCKER_*` / `AWS_*` …)照交 —— 形状剥会剥 `AWS_SECRET_ACCESS_KEY` 一类,ECR / GCR 凭据助手因此断。
+     * 命令本身跑在容器里,容器的 env 只由 `execArgv` 的 `-e K=V` 显式给,本 env 到不了容器。每次起进程现算一次(与 host shell 同)。
+     */
+    private cliEnv;
     /** Prepend `-H <dockerHost>` to a docker argv when configured (per-invocation, not the process env). */
     private withHostFlag;
     /** Build the `docker exec` argv for a command, applying cwd (`-w`) and per-command env (`-e K=V`).
@@ -198,8 +207,13 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
      *  ⇒ 保 sh(修前字节形,诚实降级);探测自身失败同。容器**创建**引导命令(mkdir && tail)不走
      *  本 shell——无 bash 语法且探测尚不可能。 */
     private containerShell;
-    private containerShellProbed;
+    /** shell 探测的**一只在飞承诺**:并发的调用方(首用 exec / fs、connect、reconnect)都 join 它 —— 修前是先置真的布尔,第二个调用方在探测落定之前就拿 /bin/sh 往下走,
+     *  探测随后才把命令切到 bash(家目录对证因此可能问的是另一只 shell)。 */
+    private containerShellReady?;
+    /** 等一只共享的承诺,调用方的取消只退**它自己的**等待(承诺照常落定、照常服务其余等待者)。`false` = 取消了。 */
+    private untilOrAborted;
     private probeContainerShell;
+    private detectContainerShell;
     private ensureConnectedExec;
     /** Lazy connect for a FileSystem path → FileError on failure (fail closed, never throws). */
     private fsReady;

package/dist/plugins/remote-env-local-docker.js

@@ -2,10 +2,12 @@ import path from "node:path";
 import os from "node:os";
 import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
+import { hostSubprocessEnv } from "../server-secret-env.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { randomBytes } from "node:crypto";
 import { shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
-import { commandBoundsOf, livenessCutMessage } from "../exec-bounds.js";
+import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -21,7 +23,9 @@ const unsupported = (op) => ({
 export class RemoteLocalDockerExecutionEnv {
     capabilities = { isolation: true, suspendable: false, canonicalPathAuthoritative: true };
     cwd;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
     cdPath = "unknown";
     cfg;
     spawnFn;
@@ -30,6 +34,8 @@ export class RemoteLocalDockerExecutionEnv {
     handle;
     destroyed = false;
     connecting;
+    homeRefusal;
+    homeSeat;
     constructor(config, deps = {}) {
         if (!config.image || !config.image.trim()) {
             config = { ...config, image: config.image ?? "" };
@@ -43,7 +49,7 @@ export class RemoteLocalDockerExecutionEnv {
             controlTimeoutMs: config.controlTimeoutMs ?? DEFAULT_CONTROL_TIMEOUT_MS,
         };
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
         this.spawnFn = deps.spawn ?? spawn;
         const id = config.id ?? randomBytes(6).toString("hex");
         const suffix = randomBytes(4).toString("hex");
@@ -62,6 +68,8 @@ export class RemoteLocalDockerExecutionEnv {
             return unsupported("connect(snapshotId)");
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        if (this.homeRefusal)
+            return { ok: false, error: this.homeRefusal };
         if (config?.abortSignal?.aborted)
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
         if (this.containerId)
@@ -112,12 +120,39 @@ export class RemoteLocalDockerExecutionEnv {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         }
+        if (this.homeSeat.asks && !(await this.untilOrAborted(this.probeContainerShell(), config?.abortSignal))) {
+            await this.forceRemove().catch(() => { });
+            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while detecting the container's shell") };
+        }
+        const home = await this.homeVerdict(config?.abortSignal);
+        if (home !== undefined) {
+            await this.forceRemove().catch(() => { });
+            return { ok: false, error: home };
+        }
+        if (this.destroyed) {
+            await this.forceRemove().catch(() => { });
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
+        }
         this.containerId = run.value.stdout.trim() || this.containerName;
         this.handle = { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
         if (config?.secrets?.length) {
         }
         return ok(this.handle);
     }
+    async homeVerdict(signal) {
+        if (!this.homeSeat.asks)
+            return undefined;
+        const probe = await this.docker(this.execRaw(LANE_HOME_PROBE_COMMAND), { signal, timeoutMs: this.cfg.controlTimeoutMs });
+        if (!probe.ok && probe.error.code === "aborted")
+            return new RemoteExecutionError("aborted", "connect aborted while reading the environment's home");
+        const verdict = this.homeSeat.settle(probe.ok && probe.value.exitCode === 0 ? { ok: true, stdout: probe.value.stdout } : { ok: false, reason: probe.ok ? `exit ${probe.value.exitCode}` : probe.error.message });
+        if (verdict === undefined)
+            return undefined;
+        const error = new RemoteExecutionError("connect_failed", verdict.refusal);
+        if (verdict.answered)
+            this.homeRefusal = error;
+        return error;
+    }
     async suspendVM(_options) {
         return unsupported("suspendVM");
     }
@@ -130,11 +165,25 @@ export class RemoteLocalDockerExecutionEnv {
     async reconnect(sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        if (this.homeRefusal)
+            return { ok: false, error: this.homeRefusal };
         if (sessionToken && sessionToken !== this.containerName) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `reconnect token '${String(sessionToken)}' does not match this env's container '${this.containerName}'`) };
         }
+        if (this.connecting !== undefined && this.containerId === undefined) {
+            const joined = await this.connecting;
+            if (!joined.ok || this.containerId !== undefined)
+                return joined;
+        }
         const insp = await this.docker(["inspect", "-f", "{{.State.Running}}", this.containerName], { timeoutMs: this.cfg.controlTimeoutMs });
         if (insp.ok && insp.value.exitCode === 0 && insp.value.stdout.trim() === "true") {
+            if (this.containerId === undefined && this.homeSeat.asks)
+                await this.probeContainerShell();
+            const home = this.containerId === undefined ? await this.homeVerdict() : undefined;
+            if (home !== undefined)
+                return { ok: false, error: home };
+            if (this.destroyed || this.homeRefusal)
+                return { ok: false, error: this.homeRefusal ?? new RemoteExecutionError("connect_failed", "execution env destroyed during reconnect") };
             this.containerId = this.containerName;
             this.handle ??= { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
             return ok(this.handle);
@@ -179,7 +228,7 @@ export class RemoteLocalDockerExecutionEnv {
         if (!ready.ok)
             throw new RemoteExecutionError("connect_failed", ready.error.message, ready.error);
         const execArgs = this.execArgv(command, options?.cwd, options?.env);
-        const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(execArgs), { stdio: ["ignore", "pipe", "pipe"] });
+        const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(execArgs), { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
         const queue = [];
         let finished = false;
         let failure;
@@ -286,7 +335,8 @@ export class RemoteLocalDockerExecutionEnv {
                         child.kill("SIGKILL");
                     }
                     catch { }
-                    throw new RemoteExecutionError("timeout", livenessCutMessage(liveness));
+                    const cut = buildLivenessCut(liveness);
+                    throw new RemoteExecutionError(cut.code, cut.message);
                 }
             }
             while (queue.length)
@@ -427,6 +477,9 @@ export class RemoteLocalDockerExecutionEnv {
     async createTempFile(options) {
         return this.posixFs.createTempFile(options);
     }
+    cliEnv() {
+        return hostSubprocessEnv({ site: "server.remote-env-local-docker.spawn-env", policy: "all", allow: [] });
+    }
     withHostFlag(args) {
         return this.cfg.dockerHost ? ["-H", this.cfg.dockerHost, ...args] : args;
     }
@@ -447,7 +500,7 @@ export class RemoteLocalDockerExecutionEnv {
         return new Promise((resolve) => {
             let settled = false;
             let forceSettleTimer;
-            const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: ["ignore", "pipe", "pipe"] });
+            const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
             const killGrace = () => {
                 try {
                     child.kill("SIGKILL");
@@ -505,11 +558,29 @@ export class RemoteLocalDockerExecutionEnv {
         });
     }
     containerShell = "/bin/sh";
-    containerShellProbed = false;
-    async probeContainerShell() {
-        if (this.containerShellProbed)
-            return;
-        this.containerShellProbed = true;
+    containerShellReady;
+    async untilOrAborted(shared, signal) {
+        if (!signal) {
+            await shared;
+            return true;
+        }
+        if (signal.aborted)
+            return false;
+        let onAbort;
+        const aborted = new Promise((res) => {
+            onAbort = () => res(false);
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+        const won = await Promise.race([shared.then(() => true), aborted]);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+        return won;
+    }
+    probeContainerShell() {
+        this.containerShellReady ??= this.detectContainerShell();
+        return this.containerShellReady;
+    }
+    async detectContainerShell() {
         try {
             const r = await this.docker(["exec", this.containerName, "/bin/sh", "-c", "command -v bash"], { timeoutMs: this.cfg.controlTimeoutMs });
             if (r.ok && r.value.exitCode === 0 && r.value.stdout.trim().length > 0)

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

@@ -1,22 +1,14 @@
 import { type SshHostKeyPolicy } from "../ssh-host-key.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 } from "@sema-agent/core";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
-export interface SshEnvConfig {
+export interface SshEnvConfig extends LaneHomeConfig {
     host: string;
     port?: number;
     username: string;
     /** PEM private key — from the adapter-held secret env (NEVER the workspace). [ref] §5 #2. */
     privateKey: string;
     passphrase?: string;
-    /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
-     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
-     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
-     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
-     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
-     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
-     */
-    homeDir?: string;
     /** Workspace root; relative paths resolve against it. Default "." (the login dir). */
     mountPath?: string;
     /** Connect handshake bound (ms). */
@@ -92,8 +84,14 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
      *  =重连风暴);②共享尝试**不携带任何 caller 信号**(首创者的 pre-abort 不得毒化 joiner;单 caller
      *  取消只退它自己的等待,底层握手余命 ≤ readyTimeout 有界,彻底取消归 destroy 代际闸)。 */
     private inFlight?;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):目标机上登录用户的 home —— 声明胜,否则连上之后实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    get homeDir(): string | undefined;
+    /** 家目录的座(声明胜 · 否则连上之后实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    private readonly homeSeat;
+    /** 家目录声明 × 实测的判定,按连接记(同一条连接只问一次;重连换了连接再问 —— 登录用户不变时答案相同,代价一次往返;没声明且已量到绝对路径之后不再问)。 */
+    private homeChecked?;
+    /** 目标机答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每个面原样回它(同一目标机同一登录用户同一答案:不再问、不再发命令)。 */
+    private homeRefusal?;
     /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在远端登录 shell 里(目标机的 profile / env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -119,6 +117,17 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
      *  caller 的 signal 只中止**它自己的等待**(共享在飞尝试继续伺服其他等待者;彻底取消归 destroy 的代际
      *  闸管,handshake 余命 ≤ readyTimeout 有界)。 */
     private ensureConnected;
+    /** 家目录判定的 per-caller 可中止等待(共享的判定承诺不动,只退本 caller)。 */
+    private raceVerdictAbort;
+    /**
+     * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 量到绝对路径为止)⇒ 在这条连接上问一次 `$HOME`(登录用户的 shell 答的,与命令同一个用户、同一份登录 env),读数交座。
+     * 声明在场:答了而不一致 / 不是绝对路径 ⇒ 拒记在环境上(每个面原样回它),命令一条都不发;没答上(通道开不出 / 非零退出 / 超时)⇒ 这一次同样不开、不记,下一次调用重问。
+     * 没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,命令照跑(没声明就没有声明可拒)—— 判定对这条连接记下,换了连接再问。
+     * 问的是裸命令(不经工作目录守卫:工作目录进不去不影响家目录的答案)。上界 = 握手的 `readyTimeoutMs`(问一个环境变量,不是跑用户命令)。
+     */
+    private homeVerdict;
+    /** 连接本身(不含家目录判定):{@link ensureConnected} 的第一半。 */
+    private ensureTransport;
     private connectOnce;
     suspendVM(_options?: VmLifecycleOptions): Promise<{
         ok: true;

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

@@ -3,10 +3,11 @@ import { Client } from "ssh2";
 import { createSshHostKeyVerifier } from "../ssh-host-key.js";
 import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, kindFromMode } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
-import { commandBoundsOf, livenessCutMessage } from "../exec-bounds.js";
+import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 const PROVIDER = "ssh";
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
@@ -24,7 +25,12 @@ export class RemoteSshExecutionEnv {
     destroyed = false;
     connEpoch = 0;
     inFlight;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
+    homeChecked;
+    homeRefusal;
     cdPath = "unknown";
     cfg;
     injectedConnectOnce;
@@ -44,7 +50,7 @@ export class RemoteSshExecutionEnv {
             hostKey: config.hostKey,
         };
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
     }
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
@@ -103,6 +109,110 @@ export class RemoteSshExecutionEnv {
         return record.promise;
     }
     async ensureConnected(signal) {
+        for (let round = 0; round < 3; round++) {
+            if (this.homeRefusal)
+                return { ok: false, error: this.homeRefusal };
+            const transport = await this.ensureTransport(signal);
+            if (!transport.ok || !this.homeSeat.asks)
+                return transport;
+            const conn = this.conn;
+            if (!conn)
+                return { ok: false, error: new ExecutionError("shell_unavailable", "SSH connection dropped right after connect") };
+            if (this.homeChecked?.conn !== conn) {
+                const checked = { conn, verdict: this.homeVerdict(conn) };
+                this.homeChecked = checked;
+                void checked.verdict.then((r) => {
+                    if (!r.ok && this.homeRefusal === undefined && this.homeChecked === checked)
+                        this.homeChecked = undefined;
+                });
+            }
+            const verdict = await this.raceVerdictAbort(this.homeChecked.verdict, signal);
+            if (signal?.aborted)
+                return { ok: false, error: new ExecutionError("aborted", "aborted while checking the environment's home") };
+            if (!verdict.ok)
+                return verdict;
+            if (this.conn === conn)
+                return verdict;
+        }
+        return { ok: false, error: new ExecutionError("shell_unavailable", "SSH connection kept being replaced while the environment's home was being checked") };
+    }
+    async raceVerdictAbort(shared, signal) {
+        if (!signal)
+            return shared;
+        if (signal.aborted)
+            return { ok: false, error: new ExecutionError("aborted", "aborted while checking the environment's home") };
+        let onAbort;
+        const aborted = new Promise((res) => {
+            onAbort = () => res({ ok: false, error: new ExecutionError("aborted", "aborted while checking the environment's home") });
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+        const raced = await Promise.race([shared, aborted]);
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+        return raced;
+    }
+    homeVerdict(conn) {
+        return new Promise((resolve) => {
+            const chunks = [];
+            let outBytes = 0;
+            let settled = false;
+            let channel;
+            let channelClosed = false;
+            const closeChannel = (ch) => {
+                if (ch === undefined || channelClosed)
+                    return undefined;
+                try {
+                    ch.close();
+                    return undefined;
+                }
+                catch (e) {
+                    return `the probe channel could not be closed: ${e instanceof Error ? e.message : String(e)}`;
+                }
+            };
+            const settle = (probe) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                const closeTrouble = closeChannel(channel);
+                if (closeTrouble !== undefined && !probe.ok)
+                    probe = { ok: false, reason: `${probe.reason}; ${closeTrouble}` };
+                const verdict = this.homeSeat.settle(probe);
+                if (verdict === undefined)
+                    return resolve(ok(undefined));
+                const error = new ExecutionError("shell_unavailable", verdict.refusal);
+                if (verdict.answered)
+                    this.homeRefusal = error;
+                resolve({ ok: false, error });
+            };
+            const timer = setTimeout(() => settle({ ok: false, reason: `no answer within ${this.cfg.readyTimeoutMs}ms` }), this.cfg.readyTimeoutMs);
+            try {
+                conn.exec(LANE_HOME_PROBE_COMMAND, (err, stream) => {
+                    if (err)
+                        return settle({ ok: false, reason: err.message });
+                    if (settled)
+                        return void closeChannel(stream);
+                    channel = stream;
+                    stream
+                        .on("data", (d) => {
+                        if (outBytes < 4096) {
+                            chunks.push(d);
+                            outBytes += d.length;
+                        }
+                    })
+                        .on("close", (code) => {
+                        channelClosed = true;
+                        settle(code === 0 ? { ok: true, stdout: Buffer.concat(chunks).toString("utf8") } : { ok: false, reason: code == null ? "the channel closed without an exit status" : `exit ${code}` });
+                    });
+                    stream.stderr.on("data", () => { });
+                });
+            }
+            catch (e) {
+                settle({ ok: false, reason: e instanceof Error ? e.message : String(e) });
+            }
+        });
+    }
+    async ensureTransport(signal) {
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "SSH env destroyed — no lazy reconnect after teardown") };
         if (signal?.aborted)
@@ -435,8 +545,10 @@ export class RemoteSshExecutionEnv {
                     if (waitTimer !== undefined)
                         clearTimeout(waitTimer);
                 }
-                if (liveness !== undefined && !finished && Date.now() - lastChunk >= liveness.ms)
-                    throw new RemoteExecutionError("timeout", livenessCutMessage(liveness));
+                if (liveness !== undefined && !finished && Date.now() - lastChunk >= liveness.ms) {
+                    const cut = buildLivenessCut(liveness);
+                    throw new RemoteExecutionError(cut.code, cut.message);
+                }
             }
             while (queue.length)
                 yield queue.shift();

package/dist/plugins/remote-shell.d.ts

@@ -134,7 +134,6 @@ export declare function drainNumEnvWarnings(): Array<{
     raw: string;
 }>;
 export declare function numEnvOr(name: string, def: number, min: number): number;
-export declare const SYMLINK_CHAIN_MAX_HOPS = 64;
 /**
  * 一次往返走完叶 symlink 链的 POSIX sh 脚本(**纯数据**:返回一个命令串 ⇒ `build*`,CLAUDE.md 工厂律)。
  *

package/dist/plugins/remote-shell.js

@@ -1,4 +1,4 @@
-import { ExecutionError } from "@sema-agent/core";
+import { ExecutionError, SYMLINK_CHAIN_MAX_HOPS } from "@sema-agent/core";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { randomBytes } from "node:crypto";
 export const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
@@ -120,7 +120,6 @@ export function numEnvOr(name, def, min) {
     }
     return Math.max(min, (Number.isFinite(n) ? n : 0) || def);
 }
-export const SYMLINK_CHAIN_MAX_HOPS = 64;
 export function buildSymlinkChainCommand(absPath) {
     return (`{ if ! command -v readlink >/dev/null 2>&1; then printf 'readlink: not found\\n' >&2; exit 127; fi; ` +
         `c=${shellQuote(absPath)}; n=0; ` +

package/dist/plugins/retention-store-sql.js

@@ -2,6 +2,7 @@ import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
 import { USER_INPUT_ACCEPTANCE_TABLE } from "./user-input-ledger-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { incarnationFromCell } from "../session-incarnation.js";
 export const MANAGED_RETENTION = "managed";
 export const UNMANAGED_RETENTION = "none";
 export const RETENTION_AUDIT_TABLE = "retention_audit";
@@ -302,7 +303,10 @@ export class SqlRetentionStore {
         const { rows } = await exec.query(this.q(`SELECT sm.session_id, sm.incarnation FROM session_meta sm WHERE ${w.sql} AND sm.updated_at < ? AND NOT ${this.liveReferenceExists()} ` +
             `ORDER BY sm.updated_at ASC LIMIT ?${suffix}`, `SELECT sm.session_id, sm.incarnation FROM session_meta sm WHERE ${w.sql} AND sm.updated_at < $2 AND NOT ${this.liveReferenceExists()} ` +
             `ORDER BY sm.updated_at ASC LIMIT $3${suffix}`), [...w.params, new Date(input.cutoffMs), RETENTION_SESSION_BATCH]);
-        return rows.map((r) => ({ id: String(r.session_id), incarnation: typeof r.incarnation === "string" ? r.incarnation : "" }));
+        return rows.map((r) => {
+            const id = String(r.session_id);
+            return { id, incarnation: incarnationFromCell(id, r.incarnation, "absent") };
+        });
     }
     async countOrphanToolResultCandidates(exec, input) {
         return (await this.orphanToolResultCandidates(exec, input)).length;
@@ -337,7 +341,7 @@ export class SqlRetentionStore {
                     tombstones = await this.writeTombstones(conn, input.domain, "session", ids);
                 }
                 await this.writeAuditRow(conn, { domain: input.domain, action: "deleted_sessions", audit, deleted, skipped, tombstones });
-                const endedSpaces = doomed.filter((d) => d.incarnation !== "").map((d) => ({ sessionId: d.id, spaceKey: d.incarnation }));
+                const endedSpaces = doomed.flatMap((d) => (d.incarnation === undefined ? [] : [{ sessionId: d.id, spaceKey: d.incarnation }]));
                 return { domain: input.domain, deleted, skipped, tombstones, ...(endedSpaces.length > 0 ? { endedSpaces } : {}) };
             });
         }

package/dist/plugins/run-store-sql.d.ts

@@ -2,13 +2,14 @@ import type { TaskStatus } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
-import { type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
-import { type SqlDriver } from "./sql-driver.js";
+import { type ClaimFenced, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
 export type { RunRecord, SessionSummary, RunEvent, LatestRunRef } from "./store-contracts.js";
 export declare class SqlRunStore {
-    protected readonly db: SqlDriver;
+    readonly db: SqlDriver;
+    /** `db` 公开只读:会话认领住在这只池背后的库里,写在认领栅栏里的店(workflow 子代决定行)读写都走它 —— 那只店的池只有这一处来源。 */
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
@@ -159,6 +160,17 @@ export declare class SqlRunStore {
      * (一个输掉的认领不许覆盖赢家的持有记录——同一条条件 UPDATE 天然保证)。
      */
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
+    /**
+     * 认领当写栅栏用(进程内两孪生的契约 = `store-contracts.ts` 的 `InProcessClaimFence`;本孪生是它的事务形):一个事务 ——
+     *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
+     *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑;提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
+     * 🔴 **取锁序 = task_run → task_active**,与 `setTerminal` / `reapStale` / `reapSuspended` 同序(它们先改 run 行、再删认领行):两行用两条语句按序锁,
+     *    不用连表锁读(那一形的先后由计划器定,与终局 / 收割相反时两只事务各攥一行成环)。`createRun` 只插认领行、`deleteBySession` 见认领行在就中止,
+     *    都不与本序成环。锁住之后:收割的改行 / 终局与收割的删认领 / 别人的建行都排在本事务之后,收割器提交后重判 `updated_at` 看到的是刚刷的。
+     *    锁读没命中时 InnoDB 可能取一把间隙锁;本事务此后不往这两张表插任何行(见 space-commit 那条锁形注)。
+     * 担保止于提交:判出「持有」的是这只事务;提交确认在路上迟到、这一跑随后失去认领,不在本栅栏的射程里(调用方的已知边界)。
+     */
+    whileHoldingClaim<T>(sessionId: string, taskId: string, write: (tx: SqlTxConn) => Promise<T>): Promise<ClaimFenced<T>>;
     /** The active run's taskId for a session (the `task_active` claim) — lets resume find the suspended run row. */
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     /** Shared row→record mapper — byte-identical between dialects (both drivers hand back the same column
@@ -194,17 +206,7 @@ export declare class SqlRunStore {
      *  built with plain string pushes in call order. PG's `$n` needs a NUMBERED placeholder per param, so that arm
      *  keeps its own positional-counter closure (`p()`) — collapsing the two into one shared counter would hide
      *  the very placeholder-numbering divergence this file exists to keep visible. */
-    listRuns(opts: {
-        status?: string;
-        jobId?: string;
-        source?: string;
-        owner?: string;
-        cursor?: {
-            createdAt: string;
-            taskId: string;
-        };
-        limit: number;
-    }): Promise<RunRecord[]>;
+    listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
      * S-297 —— 这个会话**最近一条腿**的窄指针(`/mcp` 面板的 `lastLegMcp` 与任何「上一条 run 是谁」的读面共用)。
      *