@sema-agent/server 7.132.0 → 7.133.0

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

@@ -4,9 +4,10 @@ import { type CacheMissMemory, type WorkspaceCacheCapability } from "../workspac
 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";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, buildKillAllScript, parseBgPollOutput, type ParsedBgPoll, } from "./k8s-bg-scripts.js";
-export interface K8sEnvConfig {
+export interface K8sEnvConfig extends LaneHomeConfig {
     /** API server URL. Default: in-cluster (`https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT`). */
     apiUrl?: string;
     /** Bearer token. Default: in-cluster service-account token file. */
@@ -20,15 +21,6 @@ export interface K8sEnvConfig {
     image: string;
     /** RuntimeClass for the VM boundary. Default "kata-qemu" (set "" to run plain runc — tests/dev only). */
     runtimeClass?: 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 pod; created on connect. Default "/workspace". */
     mountPath?: string;
     /** Pod lifetime (`activeDeadlineSeconds`; env `K8S_TIMEOUT_MS`) — the whole-pod leak guard, and the ceiling background-shell
@@ -275,8 +267,10 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      *  the space restore (`latest` names an archive that is there and did not come back — {@link restoreSnapshot}) and the pod's admission (the cluster created
      *  the pod and it ended `Failed` before it ran — {@link createPod}). Neither goes away by asking again: the same request answers the same. */
     private connectRefusal?;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):pod 里执行用户的 home —— 声明胜,否则 pod 就绪那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时 pod 起来之前缺席)。 */
+    get homeDir(): string | undefined;
+    /** 家目录的座(声明胜 · 否则 pod 就绪那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证(与 local-docker / ssh 同一只判官、同一句拒)。 */
+    private readonly homeSeat;
     /** core 7.49.0 #1554:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 pod 里(镜像与 pod spec 的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -616,6 +610,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * `latest` is not published, loud) → move `latest` → keep N → the row is deleted (always, saved or failed).
      * A lost fence, an upload or a pointer failure ⇒ one `workspace_snapshot_failed` line + the `failed` outcome; `latest`
      * keeps naming the previous snapshot, so the next run restores THAT — never an empty workspace dressed up as a restore.
+     * `latest` is moved only onto an object the upload wrote: a pod that is gone when the tar is due (it vanished while the fence was
+     * being claimed) uploads nothing, and is that same upload failure.
      */
     private persistWorkspace;
     private execUrl;

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

@@ -18,6 +18,7 @@ import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js"
 import { createPosixShellFs } from "./posix-shell-fs.js";
 import { randomUUID } from "node:crypto";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 const PROVIDER = "k8s";
 const K8S_BG_DIR_ROOT = "/tmp/.sema-bg";
 const K8S_BG_MAX_CONCURRENT = numEnvOr("K8S_BG_MAX_CONCURRENT", 8, 1);
@@ -177,7 +178,10 @@ export class RemoteK8sExecutionEnv {
     idleWaiters = [];
     connectInFlight;
     connectRefusal;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
     cdPath = "unknown";
     cfg;
     deps;
@@ -217,7 +221,7 @@ export class RemoteK8sExecutionEnv {
             ...(config.snapshotExclude && config.snapshotExclude.length > 0 ? { snapshotExclude: config.snapshotExclude } : {}),
         };
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
         this.deps = deps ?? {};
         this.laneLiveness = laneLivenessOf(this.cfg.livenessMs, "K8S_LIVENESS_MS");
         const occupant = occupantKeyOf(config.spaceOccupant);
@@ -675,13 +679,24 @@ export class RemoteK8sExecutionEnv {
         }
         this.podName = name;
         this.podIP = podIP;
-        const mk = await this.runExec(`mkdir -p ${shellQuote(this.cfg.mountPath)}`);
+        const askHome = this.homeSeat.asks;
+        const mk = await this.runExec(`mkdir -p ${shellQuote(this.cfg.mountPath)}${askHome ? ` && { ${LANE_HOME_PROBE_COMMAND} || true; }` : ""}`);
         if (!mk.ok || mk.value.exitCode !== 0) {
             await this.deletePod(name).catch(() => { });
             this.podName = undefined;
             this.podIP = undefined;
             return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace mkdir failed: ${mk.ok ? mk.value.stderr : mk.error.message}`) };
         }
+        if (askHome) {
+            const verdict = this.homeSeat.settle({ ok: true, stdout: mk.value.stdout });
+            if (verdict !== undefined) {
+                await this.deletePod(name).catch(() => { });
+                this.podName = undefined;
+                this.podIP = undefined;
+                const error = new RemoteExecutionError("connect_failed", verdict.refusal);
+                return verdict.answered ? this.holdRefusal(error) : { ok: false, error };
+            }
+        }
         if (cache?.fresh)
             this.logger?.warn("workspace_cache_fresh", { space: incarnationLogPrefix(cache.spaceKey), claim: cache.claim.name, size: cache.size });
         return ok(this.workspaceHandle());
@@ -927,8 +942,11 @@ export class RemoteK8sExecutionEnv {
         if (target.lane === "park" && this.inFlight.size > 0)
             return { ok: false, error: new RemoteExecutionError("command_in_flight", "cannot suspend while a command is in flight (would snapshot a torn workspace)") };
         const snapshotId = mintSnapshotId(this.occupantIncarnation);
-        if (!this.podName)
-            return ok(snapshotId);
+        if (!this.podName) {
+            return target.lane === "space"
+                ? { ok: false, error: new RemoteExecutionError("connect_failed", "the sandbox pod was gone when the run-end snapshot reached the upload — nothing was saved (the workspace could not be read), and `latest` keeps naming the previous snapshot") }
+                : ok(snapshotId);
+        }
         const presigned = this.presignSnapshot({ ...target, method: "PUT", snapshotId });
         if (!presigned.ok)
             return presigned;

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";
@@ -95,6 +87,8 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     private connecting?;
     /** 家目录:环境答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。 */
     private homeRefusal?;
+    /** 家目录的座(声明胜 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    private readonly homeSeat;
     constructor(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps);
     private resolve;
     workspaceHandle(): WorkspaceHandle;
@@ -107,9 +101,10 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     }>;
     private doConnect;
     /**
-     * 家目录:声明在场(`homeDir`,只来自 `REMOTE_EXEC_HOME_DIR` —— 本车道没有自己的缺省)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、
-     * 同一份 `-e` env),交唯一判官 `judgeLaneHome`。环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);
-     * 没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,但不记(与任何一次起容器失败同:下一次连接重问);调用方中止 ⇒ `aborted`、不记。没声明 ⇒ 不问(`undefined`)。容器由调用方收。
+     * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 实测)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、同一份 `-e` env),读数交座。
+     * 声明在场:环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,
+     * 但不记(与任何一次起容器失败同:下一次连接重问)。没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,环境照开(没声明就没有声明可拒)。
+     * 调用方中止 ⇒ `aborted`、不记、不交座。容器由调用方收。
      */
     private homeVerdict;
     suspendVM(_options?: VmLifecycleOptions): Promise<{

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

@@ -3,7 +3,7 @@ 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, judgeLaneHome } from "../lane-home-probe.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";
@@ -23,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;
@@ -33,6 +35,7 @@ export class RemoteLocalDockerExecutionEnv {
     destroyed = false;
     connecting;
     homeRefusal;
+    homeSeat;
     constructor(config, deps = {}) {
         if (!config.image || !config.image.trim()) {
             config = { ...config, image: config.image ?? "" };
@@ -46,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");
@@ -117,7 +120,7 @@ export class RemoteLocalDockerExecutionEnv {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         }
-        if (this.homeDir !== undefined && !(await this.untilOrAborted(this.probeContainerShell(), config?.abortSignal))) {
+        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") };
         }
@@ -137,14 +140,14 @@ export class RemoteLocalDockerExecutionEnv {
         return ok(this.handle);
     }
     async homeVerdict(signal) {
-        if (this.homeDir === undefined)
+        if (!this.homeSeat.asks)
             return undefined;
         const probe = await this.docker(this.execRaw(LANE_HOME_PROBE_COMMAND), { signal, timeoutMs: this.cfg.controlTimeoutMs });
-        const verdict = judgeLaneHome(PROVIDER, this.homeDir, 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;
         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;
@@ -174,7 +177,7 @@ export class RemoteLocalDockerExecutionEnv {
         }
         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.homeDir !== undefined)
+            if (this.containerId === undefined && this.homeSeat.asks)
                 await this.probeContainerShell();
             const home = this.containerId === undefined ? await this.homeVerdict() : undefined;
             if (home !== undefined)

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,9 +84,11 @@ 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?;
@@ -126,9 +120,9 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     /** 家目录判定的 per-caller 可中止等待(共享的判定承诺不动,只退本 caller)。 */
     private raceVerdictAbort;
     /**
-     * 家目录:声明在场(`homeDir`,只来自 `REMOTE_EXEC_HOME_DIR` —— 本车道没有自己的缺省)⇒ 在这条连接上问一次 `$HOME`(登录用户的 shell 答的,
-     * 与命令同一个用户、同一份登录 env),交唯一判官 `judgeLaneHome`。答了而不一致 / 不是绝对路径 ⇒ 拒记在环境上(每个面原样回它),命令一条都不发;
-     * 没答上(通道开不出 / 非零退出 / 超时)⇒ 这一次同样不开、不记,下一次调用重问。
+     * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 量到绝对路径为止)⇒ 在这条连接上问一次 `$HOME`(登录用户的 shell 答的,与命令同一个用户、同一份登录 env),读数交座。
+     * 声明在场:答了而不一致 / 不是绝对路径 ⇒ 拒记在环境上(每个面原样回它),命令一条都不发;没答上(通道开不出 / 非零退出 / 超时)⇒ 这一次同样不开、不记,下一次调用重问。
+     * 没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,命令照跑(没声明就没有声明可拒)—— 判定对这条连接记下,换了连接再问。
      * 问的是裸命令(不经工作目录守卫:工作目录进不去不影响家目录的答案)。上界 = 握手的 `readyTimeoutMs`(问一个环境变量,不是跑用户命令)。
      */
     private homeVerdict;

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

@@ -7,7 +7,7 @@ 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, judgeLaneHome } from "../lane-home-probe.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 const PROVIDER = "ssh";
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
@@ -25,7 +25,10 @@ export class RemoteSshExecutionEnv {
     destroyed = false;
     connEpoch = 0;
     inFlight;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
     homeChecked;
     homeRefusal;
     cdPath = "unknown";
@@ -47,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));
@@ -110,13 +113,13 @@ export class RemoteSshExecutionEnv {
             if (this.homeRefusal)
                 return { ok: false, error: this.homeRefusal };
             const transport = await this.ensureTransport(signal);
-            if (!transport.ok || this.homeDir === undefined)
+            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.homeDir) };
+                const checked = { conn, verdict: this.homeVerdict(conn) };
                 this.homeChecked = checked;
                 void checked.verdict.then((r) => {
                     if (!r.ok && this.homeRefusal === undefined && this.homeChecked === checked)
@@ -148,9 +151,10 @@ export class RemoteSshExecutionEnv {
             signal.removeEventListener("abort", onAbort);
         return raced;
     }
-    homeVerdict(conn, declared) {
+    homeVerdict(conn) {
         return new Promise((resolve) => {
-            let out = "";
+            const chunks = [];
+            let outBytes = 0;
             let settled = false;
             let channel;
             let channelClosed = false;
@@ -173,7 +177,7 @@ export class RemoteSshExecutionEnv {
                 const closeTrouble = closeChannel(channel);
                 if (closeTrouble !== undefined && !probe.ok)
                     probe = { ok: false, reason: `${probe.reason}; ${closeTrouble}` };
-                const verdict = judgeLaneHome(PROVIDER, declared, probe);
+                const verdict = this.homeSeat.settle(probe);
                 if (verdict === undefined)
                     return resolve(ok(undefined));
                 const error = new ExecutionError("shell_unavailable", verdict.refusal);
@@ -191,12 +195,14 @@ export class RemoteSshExecutionEnv {
                     channel = stream;
                     stream
                         .on("data", (d) => {
-                        if (out.length < 4096)
-                            out += d.toString("utf8");
+                        if (outBytes < 4096) {
+                            chunks.push(d);
+                            outBytes += d.length;
+                        }
                     })
                         .on("close", (code) => {
                         channelClosed = true;
-                        settle(code === 0 ? { ok: true, stdout: out } : { ok: false, reason: code == null ? "the channel closed without an exit status" : `exit ${code}` });
+                        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", () => { });
                 });

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 是谁」的读面共用)。
      *

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

@@ -269,6 +269,21 @@ export class SqlRunStore {
         const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, instance_id = ?, updated_at = ? WHERE task_id = ? AND status IN ('suspended','needs_review')", "UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, instance_id = $1, updated_at = $2 WHERE task_id = $3 AND status IN ('suspended','needs_review')"), [instanceId, new Date(), taskId]);
         return affected === 1;
     }
+    async whileHoldingClaim(sessionId, taskId, write) {
+        let fenced = { held: false };
+        await this.tx(async (conn) => {
+            const run = await conn.query(this.q("SELECT task_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
+            if (run.rows.length === 0)
+                return;
+            const claim = await conn.query(this.q("SELECT task_id FROM task_active WHERE session_id = ? FOR UPDATE", "SELECT task_id FROM task_active WHERE session_id = $1 FOR UPDATE"), [sessionId]);
+            const holder = claim.rows[0];
+            if (holder === undefined || String(holder.task_id) !== taskId)
+                return;
+            await conn.query(this.q("UPDATE task_run SET updated_at = ? WHERE task_id = ?", "UPDATE task_run SET updated_at = $1 WHERE task_id = $2"), [new Date(), taskId]);
+            fenced = { held: true, value: await write(conn) };
+        });
+        return fenced;
+    }
     async getActiveTaskId(sessionId) {
         const { rows } = await this.db.query(this.q("SELECT task_id FROM task_active WHERE session_id = ?", "SELECT task_id FROM task_active WHERE session_id = $1"), [sessionId]);
         return rows[0] ? String(rows[0].task_id) : undefined;
@@ -335,7 +350,10 @@ export class SqlRunStore {
                 where.push("source = ?");
                 params.push(opts.source);
             }
-            if (opts.owner !== undefined) {
+            if (opts.owner === null) {
+                where.push("owner IS NULL");
+            }
+            else if (opts.owner !== undefined) {
                 where.push("owner = ?");
                 params.push(opts.owner);
             }
@@ -362,7 +380,9 @@ export class SqlRunStore {
             where.push(`job_id = ${p(opts.jobId)}`);
         if (opts.source !== undefined)
             where.push(`source = ${p(opts.source)}`);
-        if (opts.owner !== undefined)
+        if (opts.owner === null)
+            where.push("owner IS NULL");
+        else if (opts.owner !== undefined)
             where.push(`owner = ${p(opts.owner)}`);
         if (opts.cursor) {
             const a = p(new Date(opts.cursor.createdAt));

package/dist/plugins/schema-indexes.js

@@ -21,6 +21,8 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "workflow_run", name: "idx_wfrun_scope_created", columns: ["scope", "created_at_ms"] },
     { table: "workflow_run", name: "idx_wfrun_scope_status", columns: ["scope", "status"] },
     { table: "workflow_agent_session", name: "idx_wfagentsess_run", columns: ["run_id"] },
+    { table: "workflow_park_decision", name: "idx_wfparkdec_host", columns: ["host_session_id"] },
+    { table: "workflow_park_decision", name: "idx_wfparkdec_run", columns: ["run_id"] },
     { table: "workflow_completion_inbox", name: "idx_wfinbox_session_seq", columns: ["session_id", "seq"] },
     { table: "workflow_inbox_fence", name: "idx_wffence_until", columns: ["until_ms"] },
     { table: "workflow_notify_journal", name: "idx_wfnotify_acked", columns: ["acked"] },

package/dist/plugins/send-user-file.js

@@ -1,6 +1,6 @@
 import { createHmac } from "node:crypto";
 import { uuidv7 } from "@sema-agent/core";
-import { CONTROL_AND_BIDI_STRIP_RE } from "../text-bidi.js";
+import { stripControlAndBidi } from "@sema-agent/settings-schema";
 import { presignS3CopyUrl, presignS3Url } from "./s3-presign.js";
 import { OBJECT_STORE_IO_TIMEOUT_MS } from "./blob-backend.js";
 export const PRESIGN_MAX_TTL_SEC = 604_800;
@@ -11,7 +11,7 @@ export function scopeSegment(secretKey, scope) {
 }
 export function sanitizeSendFileName(name) {
     const base = (name ?? "").split(/[/\\]/).pop() ?? "";
-    let clean = base.replace(CONTROL_AND_BIDI_STRIP_RE, "").replace(/^\.+/, "").trim();
+    let clean = stripControlAndBidi(base).replace(/^\.+/, "").trim();
     if (clean.length > 128) {
         const dot = clean.lastIndexOf(".");
         const ext = dot > 0 && clean.length - dot <= 16 ? clean.slice(dot) : "";

package/dist/plugins/session-epoch-anchor.d.ts

@@ -1,13 +1,39 @@
-/** One row of the scan: its `seq` and the `payload` column projected as text (`jsonColumnText`). */
+/**
+ * The prompt-epoch anchor below a bounded window's floor — `SessionStorage.getEpochAnchor()` for every session storage that
+ * loads a window instead of the whole tree: the two SQL session backends (`tidb-session-storage.ts` / `pg-session-storage.ts`,
+ * the run's wake and the session view alike) and the local leg's session view (`local-session-window.ts`). One reading, three
+ * dialects: each storage hands in only its own page and reads its own rows.
+ *
+ * ## The rule: the store carries the record, the engine reads it
+ * A bounded wake loads `[floor .. leaf]`; when the loaded branch holds no epoch carrier (a rewind cut inside the kept
+ * tail, or compactions written before the engine restated the epoch), the engine's `Session.getPromptEpoch()` asks the
+ * storage for the nearest carrier BELOW the floor and reads it itself. The storage returns that record **as stored**:
+ *  · a `prompt_epoch` entry ⇒ the whole entry (the engine's branch walk reads the whole entry too);
+ *  · a compaction whose `details.promptEpoch` is present ⇒ that restatement;
+ *  · a compaction without a restatement carries nothing ⇒ the scan pages past it, to exhaustion (a session that lived
+ *    across the release that introduced epochs can hold any number of them between the floor and its pin).
+ * The storage never judges the record's shape. The engine answers a current-shape record as a pin and a retired-shape
+ * record by name (`legacy`, with whether it pinned a center artifact) — a storage that normalized the record first would
+ * turn a session pinned under a retired shape into one with no pin, and the engine would then skip the center source's
+ * handling of that pin. A record that is neither is the engine's to read as well (it reads as no record).
+ *
+ * `floorSeq <= 0` (a full load: the walk already reaches the root) or no carrier below the floor ⇒ `undefined`
+ * (a session that predates epochs).
+ *
+ * What "below the floor, newest first" walks is the storage's: the SQL twins page their `session_event` rows by `seq` (their
+ * window is cut by `seq` too); the local window pages the branch path it was cut from.
+ */
+import type { SessionTreeEntry } from "@sema-agent/core";
+/** One row of a scan: its position (`seq`, the keyset cursor). What else the row holds is the storage's — it reads the entry
+ *  out of the row itself ({@link scanEpochAnchor}'s `entryOf`), so a row is read only when the scan reaches it. */
 export interface EpochAnchorRow {
     readonly seq: string | number;
-    readonly payload: unknown;
 }
 /**
- * Page the rows `seq < beforeSeq` whose type is `prompt_epoch` or `compaction`, newest first (the backend's own SQL;
- * an empty page = no older row).
+ * Page the rows `seq < beforeSeq` that may carry an epoch record, newest first (an empty page = no older row). A page may hold
+ * other rows too — they carry nothing and the scan passes them.
  */
-export type EpochAnchorPage = (beforeSeq: number) => Promise<readonly EpochAnchorRow[]>;
+export type EpochAnchorPage<R extends EpochAnchorRow> = (beforeSeq: number) => Promise<readonly R[]>;
 /** The nearest epoch carrier below `floorSeq`, as stored; see the file header. */
-export declare function scanEpochAnchor(sessionId: string, floorSeq: number, page: EpochAnchorPage): Promise<unknown>;
+export declare function scanEpochAnchor<R extends EpochAnchorRow>(floorSeq: number, page: EpochAnchorPage<R>, entryOf: (row: R) => SessionTreeEntry): Promise<unknown>;
 //# sourceMappingURL=session-epoch-anchor.d.ts.map

package/dist/plugins/session-epoch-anchor.js

@@ -1,5 +1,4 @@
-import { decodeSessionEventPayload } from "./session-event-payload.js";
-export async function scanEpochAnchor(sessionId, floorSeq, page) {
+export async function scanEpochAnchor(floorSeq, page, entryOf) {
     if (floorSeq <= 0)
         return undefined;
     let cursor = floorSeq;
@@ -8,7 +7,7 @@ export async function scanEpochAnchor(sessionId, floorSeq, page) {
         if (rows.length === 0)
             return undefined;
         for (const row of rows) {
-            const entry = decodeSessionEventPayload(row.payload, sessionId, row.seq);
+            const entry = entryOf(row);
             if (entry.type === "prompt_epoch")
                 return entry;
             if (entry.type === "compaction") {