@sema-agent/server 7.148.0 → 7.150.0

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

@@ -1,5 +1,6 @@
-import { FileError, type InheritEnvPolicy, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions, type SecretEnvFinding } from "@sema-agent/core";
+import { FileError, type InheritEnvPolicy, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type ExecutionEnvFactoryContext, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions, type SecretEnvFinding } from "@sema-agent/core";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
+import { type CustodyMember } from "./workspace-custody.js";
 /** 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` 梯子用它排升级定时器;会话级收敛
@@ -10,7 +11,7 @@ export declare const HOST_BG_KILL_GRACE_MS: number;
 export interface HostEnvConfig extends LaneHomeConfig {
     /**
      * Base directory under which this adapter creates its per-task working directory. Default {@link os.tmpdir}.
-     * The actual workspace is `<workspaceBase>/sema-host-<id>` and is `rm -rf`'d on {@link destroy}.
+     * The actual workspace is `<workspaceBase>/sema-host-<id>-<rand>`; its last holder `rm -rf`s it on {@link destroy} (see {@link custody}).
      */
     workspaceBase?: string;
     /**
@@ -44,14 +45,21 @@ export interface HostEnvConfig extends LaneHomeConfig {
      * user's OWN directory (e.g. the cwd `run-local` was invoked in), not an adapter-created ephemeral sandbox,
      * so the agent's file edits PERSIST and are user-visible (like a local coding agent working in your repo).
      * Takes precedence over `workspaceBase`/`id` (those are ignored). Default unset = ephemeral random + cleanup.
+     * 唯一的例外由托管表说:它落在一只本服务铸的临时根里({@link custody} 的 `sharedRoot`)⇒ 本环境共持那只根,不是调用方自有目录。
      */
     workspaceDir?: string;
+    /**
+     * 工厂的工作区托管表交给它铸的每一只环境的那一面({@link hostExecutionEnvFactory} 装配;嵌入方直接构造的环境不带 ⇒ 不在任何表里,没有别的持有者)。
+     */
+    custody?: HostWorkspaceCustodySeat;
     /** R7 self-wake: the injected `SchedulerCapability` backend (the TOC self-wake scheduler write side).
      *  When set, `hasScheduler(env)` is true and core mounts CronCreate/CronDelete/CronList(旧名 CronCancel;Sleep 已 [ref] 撤除;挂载在 prepare-task 非 createHandsToolkit——L8 订正); when absent the env
      *  reports `supported:false` → INERT (no scheduler tools). Injected at boot only on the single-user host lane. */
     scheduler?: SchedulerCapability;
-    /** [ref] background shell: `false` → INERT (multi-tenant host lane gate). Default (undefined) = on for the
-     *  single-user TOC host lane. `HOST_BG_ENABLED=false` is an additional global kill switch(🪦 旧名
+    /** [ref] background shell: the assembly hands the deployment-shape row's answer here
+     *  (`DEPLOYMENT_SHAPE_PREDICATES.backgroundShell.holds(config)`); `false` → INERT (multi-tenant host lane gate).
+     *  Default (undefined) = the SAME row's answer for an undeclared principal (the single-user TOC host lane), never a literal.
+     *  `HOST_BG_ENABLED=false` is an additional global kill switch(🪦 旧名
      *  `HOST_BG_DISABLED` 自 server 3.0.0 起是 fail-loud 墓碑:设了即拒启并指路新名,不再被读取)。 */
     backgroundShell?: boolean;
     /**
@@ -61,7 +69,14 @@ export interface HostEnvConfig extends LaneHomeConfig {
      */
     gitBase?: true;
 }
-export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
+/** 工作区托管表交给它铸的环境的那一面(`workspace-custody.ts`;host 车道的读法)。 */
+export interface HostWorkspaceCustodySeat {
+    /** `workspaceDir` 落在这只本服务铸的临时根里(委派子代按父的工作目录落根)⇒ 本环境与它的铸者共持这只根:建成后登记、收场时放手、最后放手的持有者删它。 */
+    readonly sharedRoot?: string;
+    /** 表里除 `self` 之外还有没有成员持有 `root` —— 收场放手时问;有 ⇒ 删交给最后放手的那一只。 */
+    heldElsewhere(self: RemoteHostExecutionEnv, root: string): boolean;
+}
+export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability, CustodyMember<never> {
     /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
     readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
     /** R7 自唤醒: structural delegation to the injected scheduler backend. `hasScheduler(env)` checks BOTH the method
@@ -97,7 +112,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     /**
      * core 7.56.0 [ref]:shell 子进程继承的环境里**收不到**的条目(名 + 规则,从不带值)—— 与 {@link cdPath} 同一只组合的读面
      * (`server-secret-env.ts` 的 `withheldFromHostSubprocess`:继承组合扣下的发现,减去 `cfg.env` 这条显式授予重供的键)。逐命令的 `options.env`
-     * 是引擎自己交的显式授予,它知道(core KL-1963-b 同一残余)。只读:不披露、不计数、不碰 shell。
+     * 是引擎自己交的显式授予,它知道(core [ref] 同一残余)。只读:不披露、不计数、不碰 shell。
      */
     get withheldEnv(): readonly SecretEnvFinding[];
     private readonly workspaceDir;
@@ -106,6 +121,9 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private prepared;
     /** Terminal once {@link destroy} ran — guards fs/exec from running against a removed workspace. */
     private destroyed;
+    /** {@link destroy} 的那一次收场(第二次调用等同一只);托管表读它({@link releasing}):收场在飞时同一身份不铸新的。 */
+    private teardown?;
+    private teardownSettled;
     /** [ref] 五轮复审:fg/bg spool 根=tmpdir 私有目录(core bgSpoolDir 同形)。workspace 是命令可写区,
      *  `git clean -fdx` 类清理会 unlink 活跃 spool(子进程经继承 fd 对 unlinked inode 继续写,而父进程
      *  按路径 statSync/read 静默断=输出丢失+轮转帽失效);顺带不再弄脏 user-owned workspace(TOC/CC
@@ -172,12 +190,22 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     private drainInflightFs;
     private ensureSpoolRoot;
-    /** True when `workspaceDir` was given (user-owned persistent dir) → destroy() must NOT delete it. */
-    private readonly persistent;
+    /** 本环境对它工作区的租期({@link HostWorkspaceTenure}):借用的永不删;持有的收场放手、最后放手的持有者删。唯一写处 = 构造与 {@link removeOwnedTrees}。 */
+    private tenure;
     /** Memoized lazy `mkdir -p` so concurrent first-use prepares the workspace exactly once. */
     private preparing?;
     private readonly handle;
     constructor(config?: HostEnvConfig);
+    /** 收场的进度(托管表读):活着 ⇒ 缺席;{@link destroy} 开始 ⇒ 那一次收场。 */
+    get releasing(): Promise<void> | undefined;
+    /** 收场已落定。 */
+    get released(): boolean;
+    /** 本车道收场不欠同一身份下一只环境任何账(删不掉的根留在退出兜底簿上,不交接)。 */
+    readonly leftover: undefined;
+    /** 收场落定且已放手 ⇒ 出托管表(超时臂里放手挂在在飞写之后:落定了还持有 ⇒ 仍是持有者)。 */
+    get settled(): boolean;
+    /** 本环境此刻持有的、本服务铸的临时根(托管表的持有读法读它);借用 / 已放手 ⇒ 缺席。 */
+    get heldWorkspace(): string | undefined;
     workspaceHandle(): WorkspaceHandle;
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
@@ -223,6 +251,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  core 留活过的驻留 watcher 又杀了一遍(run 尾 dispose→destroy 顺序,destroy 是第二刀)。隔离 env(容器/VM)
      *  整体拆机自然带走进程,与本契约不冲突(k8s/e2b 各自 destroy 不走这条路径)。 */
     destroy(): Promise<void>;
+    private tearDown;
     /** `destroy()` 真正动手删的那一段(本 env **自有**的两棵树:spool 根 + ephemeral workspace)。
      *  抽成一只是因为它有两个调用时机 —— 在飞写按时清空时由 `destroy()` 直接 await,超时时挂在那批写后面异步跑
      *  (见 {@link drainInflightFs} 头注③)。永不抛(teardown 契约)。 */
@@ -373,7 +402,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      * 查不到根因;更糟的是每一个任务都复发一次同一条。⇒ 前判把它换成一句能直接照做的拒绝:哪个目录、
      * 哪个用户、改哪个旋钮。
      *
-     * 只对 **ephemeral** 形做(persistent 形是用户自己的目录,`mkdir -p` 一个已存在的只读 checkout 本来
+     * 只对**自铸**的那一只做(没给 `workspaceDir`;给了的是用户自己的目录或父那只已判过的根,`mkdir -p` 一个已存在的只读 checkout 本来
      * 就该成功 —— 在那儿加可写判据会把"只读仓库上跑只读任务"这个正当用法拒掉)。
      * root 与非 POSIX 平台跳过:root 的可写判据恒真(root-squash 的网络盘上反而会假拒),
      * 而 `process.getuid` 不存在时这条 POSIX 权限判据无从谈起。
@@ -453,6 +482,18 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
  * Mirrors `e2bExecutionEnvFactory`: returns the env **unconnected** (lazy) and folds the per-task
  * `ctx.sessionId` into the workspace dir id so two concurrent tasks never share a working directory.
  */
-export declare function hostExecutionEnvFactory(config?: HostEnvConfig): ExecutionEnvFactory;
+/** 一条腿的环境配置里随腿变的那几格({@link hostExecutionEnvFactory} 第二参:工厂上下文 → 值)。 */
+export interface HostLegConfig extends Pick<HostEnvConfig, "workspaceDir" | "env" | "inheritEnv"> {
+    /** 铸成那一拍对这只环境做的一次装饰(交回已有环境时不再做)。 */
+    readonly minted?: (env: RemoteHostExecutionEnv) => void;
+}
+/**
+ * host 车道的工厂。**一只身份一只工作区**:经工作区托管表(`workspace-custody.ts`,与 local-docker 车道同一只)铸环境 ——
+ * 同一身份(`ctx.taskId ?? ctx.sessionId`)还有一只没收场的环境 ⇒ 交回它(停驻腿的环境 = 续跑腿的环境:引擎 park-only 契约要的「重连到同一工作区」);
+ * 正在收场 ⇒ 等它落定再铸。铸的时候问同一张表「腿的目录落在哪只本服务铸的临时根里」:落在里面(委派子代按父的工作目录落根)⇒ 与铸者共持那只根,
+ * 父收场时子代还持有它就不删,最后放手的持有者删。`legOf` 先于交回 / 铸判(它可以拒)。
+ * 起服铸**一只**工厂(每次调用另铸一只工厂 = 没有表)。
+ */
+export declare function hostExecutionEnvFactory(config?: HostEnvConfig, legOf?: (ctx: ExecutionEnvFactoryContext) => HostLegConfig): ExecutionEnvFactory;
 export { localDockerExecutionEnvFactory, type LocalDockerEnvConfig, type LocalDockerEnvDeps, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
 //# sourceMappingURL=remote-env-host.d.ts.map

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

@@ -2,6 +2,7 @@ import { writeLogText } from "../observability/logger.js";
 import { spawn } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import fs from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync, accessSync, constants as FS_CONST } from "node:fs";
@@ -12,12 +13,14 @@ import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
-import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
+import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, physicalPathOf as kernelRealPathOf, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { LaneHomeSeat, laneHomeRefusal } from "../lane-home-probe.js";
 import { composeHostSubprocessEnv, hostSubprocessEnv, withheldFromHostSubprocess } from "../server-secret-env.js";
 import { nameTooLongCode } from "./remote-env-file-error.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
+import { createWorkspaceCustody } from "./workspace-custody.js";
 import { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
@@ -34,6 +37,8 @@ const unsupported = (op) => ({
     ok: false,
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a host target (the operator's own machine — no container boundary, not snapshotable; capabilities.suspendable=false)`),
 });
+const BORROWED = Object.freeze({ kind: "borrowed" });
+const RELEASED = Object.freeze({ kind: "released" });
 const UNSUPPORTED_SCHEDULER_CAPS = {
     supported: false,
     maxScheduledPerScope: 0,
@@ -80,6 +85,8 @@ export class RemoteHostExecutionEnv {
     cfg;
     prepared = false;
     destroyed = false;
+    teardown;
+    teardownSettled = false;
     spoolRootDir;
     liveFgSpools = new Set();
     inflightFs = new Set();
@@ -122,20 +129,21 @@ export class RemoteHostExecutionEnv {
             this.spoolRootDir = mkdtempSync(path.join(os.tmpdir(), "sema-host-spool-"));
         return this.spoolRootDir;
     }
-    persistent;
+    tenure;
     preparing;
     handle;
     constructor(config = {}) {
         if (config.workspaceDir) {
             this.workspaceDir = path.resolve(config.workspaceDir);
-            this.persistent = true;
+            const shared = config.custody?.sharedRoot;
+            this.tenure = shared !== undefined ? { kind: "held", root: path.resolve(shared) } : BORROWED;
         }
         else {
             const base = config.workspaceBase ?? os.tmpdir();
             const id = config.id ?? randomBytes(6).toString("hex");
             const suffix = randomBytes(4).toString("hex");
             this.workspaceDir = path.resolve(base, `sema-host-${sanitizeId(id)}-${suffix}`);
-            this.persistent = false;
+            this.tenure = { kind: "held", root: this.workspaceDir };
         }
         const inheritEnvProblem = inheritEnvPolicyProblem(config.inheritEnv);
         if (inheritEnvProblem !== undefined)
@@ -156,6 +164,19 @@ export class RemoteHostExecutionEnv {
         if (homeVerdict !== undefined)
             throw laneHomeRefusal(homeVerdict);
     }
+    get releasing() {
+        return this.teardown;
+    }
+    get released() {
+        return this.teardownSettled;
+    }
+    leftover = undefined;
+    get settled() {
+        return this.teardownSettled && this.tenure.kind !== "held";
+    }
+    get heldWorkspace() {
+        return this.tenure.kind === "held" ? this.tenure.root : undefined;
+    }
     workspaceHandle() {
         return this.handle;
     }
@@ -190,9 +211,13 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
         return ok(this.handle);
     }
-    async destroy() {
-        if (this.destroyed)
-            return;
+    destroy() {
+        this.teardown ??= this.tearDown().finally(() => {
+            this.teardownSettled = true;
+        });
+        return this.teardown;
+    }
+    async tearDown() {
         this.destroyed = true;
         const p = this.preparing;
         this.preparing = undefined;
@@ -215,11 +240,15 @@ export class RemoteHostExecutionEnv {
             catch { }
             this.spoolRootDir = undefined;
         }
-        if (this.persistent)
+        const tenure = this.tenure;
+        if (tenure.kind !== "held")
+            return;
+        this.tenure = RELEASED;
+        if (this.cfg.custody?.heldElsewhere(this, tenure.root) === true)
             return;
         try {
-            await fs.rm(this.workspaceDir, { recursive: true, force: true });
-            untrackEphemeralHostWorkspace(this.workspaceDir);
+            await fs.rm(tenure.root, { recursive: true, force: true });
+            untrackEphemeralHostWorkspace(tenure.root);
         }
         catch {
         }
@@ -228,12 +257,13 @@ export class RemoteHostExecutionEnv {
         return this.destroy();
     }
     get backgroundCapabilities() {
+        const backgroundShellOn = (this.cfg.backgroundShell ?? DEPLOYMENT_SHAPE_PREDICATES.backgroundShell.holds({ remoteExec: { provider: PROVIDER } })) && hostBackgroundShellEnabled();
         return {
-            supported: (this.cfg.backgroundShell ?? true) && hostBackgroundShellEnabled(),
+            supported: backgroundShellOn,
             maxConcurrent: HOST_BG_MAX_CONCURRENT,
             defaultBgTimeoutSec: HOST_BG_DEFAULT_TIMEOUT_SEC,
             maxBgTimeoutSec: HOST_BG_MAX_TIMEOUT_SEC,
-            supportsDetach: (this.cfg.backgroundShell ?? true) && hostBackgroundShellEnabled(),
+            supportsDetach: backgroundShellOn,
         };
     }
     _bgManager;
@@ -975,7 +1005,7 @@ export class RemoteHostExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.join(...parts));
+        return ok(joinedPath(path, parts));
     }
     async readTextFile(p, abortSignal) {
         const ready = await this.fsReady(p);
@@ -1077,7 +1107,7 @@ export class RemoteHostExecutionEnv {
             const entries = await fs.readdir(abs, { withFileTypes: true });
             const out = [];
             for (const e of entries) {
-                const child = path.join(abs, e.name);
+                const child = anchorUnder(path, abs, e.name);
                 let size = 0;
                 let mtimeMs = 0;
                 try {
@@ -1218,7 +1248,7 @@ export class RemoteHostExecutionEnv {
         });
     }
     resolve(p) {
-        return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
+        return anchoredPath(path, this.cwd, p);
     }
     assertWorkspaceParentWritable() {
         const uid = process.getuid?.();
@@ -1251,7 +1281,7 @@ export class RemoteHostExecutionEnv {
     ensurePrepared() {
         if (this.prepared)
             return Promise.resolve();
-        if (!this.persistent) {
+        if (this.cfg.workspaceDir === undefined) {
             try {
                 this.assertWorkspaceParentWritable();
             }
@@ -1264,8 +1294,8 @@ export class RemoteHostExecutionEnv {
                 .mkdir(this.workspaceDir, { recursive: true })
                 .then(() => {
                 this.prepared = true;
-                if (!this.persistent)
-                    trackEphemeralHostWorkspace(this.workspaceDir);
+                if (this.tenure.kind === "held")
+                    trackEphemeralHostWorkspace(this.tenure.root);
             })
                 .catch((e) => {
                 this.preparing = undefined;
@@ -1295,17 +1325,25 @@ export class RemoteHostExecutionEnv {
         const abs = this.resolve(p);
         if (!existsSync(abs))
             return false;
-        const real = (x) => { try {
-            return realpathSync(x);
-        }
-        catch {
-            return path.resolve(x);
-        } };
+        const real = (x) => {
+            try {
+                return kernelRealPathOf(x);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const target = real(abs);
+        if (target === undefined)
+            return false;
         const inside = (root) => {
-            const rel = path.relative(real(root), real(abs));
+            const r = real(root);
+            if (r === undefined)
+                return false;
+            const rel = path.relative(r, target);
             return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
         };
-        return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.persistent && inside(this.workspaceDir));
+        return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.tenure.kind === "borrowed" && inside(this.workspaceDir));
     }
     async fsReady(p, opts) {
         if (this.destroyed) {
@@ -1389,11 +1427,39 @@ function asError(e) {
 function signalNumber(signal) {
     return os.constants.signals[signal];
 }
-export function hostExecutionEnvFactory(config = {}) {
-    return (ctx) => new RemoteHostExecutionEnv({
-        ...config,
-        id: config.id ?? ctx.taskId ?? ctx.sessionId,
-    });
+export function hostExecutionEnvFactory(config = {}, legOf = () => ({})) {
+    const custody = createWorkspaceCustody();
+    const heldElsewhere = (self, root) => custody.holder((m) => m !== self && m.heldWorkspace === root) !== undefined;
+    return (ctx) => {
+        const { minted, ...leg } = legOf(ctx);
+        const identity = ctx.taskId ?? ctx.sessionId;
+        return custody.envOf(identity, () => {
+            const dir = leg.workspaceDir ?? config.workspaceDir;
+            const sharedRoot = dir === undefined ? undefined : custody.holder((m) => m.heldWorkspace !== undefined && dirWithin(dir, m.heldWorkspace))?.heldWorkspace;
+            const env = new RemoteHostExecutionEnv({ ...config, ...leg, id: config.id ?? identity, custody: { heldElsewhere, ...(sharedRoot !== undefined ? { sharedRoot } : {}) } });
+            minted?.(env);
+            return env;
+        });
+    };
+}
+function dirWithin(dir, root) {
+    const inside = (d, r) => {
+        const rel = path.relative(r, d);
+        return rel === "" || (rel.split(path.sep)[0] !== ".." && !path.isAbsolute(rel));
+    };
+    return inside(path.resolve(dir), path.resolve(root)) || inside(physicalPathOf(dir), physicalPathOf(root));
+}
+function physicalPathOf(p) {
+    let head = path.resolve(p);
+    const tail = [];
+    while (!existsSync(head)) {
+        const up = path.dirname(head);
+        if (up === head)
+            return path.resolve(p);
+        tail.unshift(path.basename(head));
+        head = up;
+    }
+    return path.join(realpathSync(head), ...tail);
 }
 export { localDockerExecutionEnvFactory, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
 //# sourceMappingURL=remote-env-host.js.map

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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, joinedPath } from "./exec-path-law.js";
 import { readFileSync } from "node:fs";
 import https from "node:https";
 import http from "node:http";
@@ -19,6 +20,7 @@ import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { SANDBOX_IPV6_DEFAULT, sandboxEgressGaps, sandboxPodSysctls } from "../sandbox-egress-policy.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { ADAPTER_START, BOOTSTRAP_START, buildFloorPodSeat, createSandboxReadFloor, FLOOR_K8S_CONFIGMAP_KEY, engineStart, floorArgv, } from "./sandbox-read-floor.js";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -283,12 +285,13 @@ export class RemoteK8sExecutionEnv {
         this.floor = this.deps.readFloor ?? createSandboxReadFloor({ lane: PROVIDER, knob: config.sandboxReadFloor, ...(config.logger !== undefined ? { logger: config.logger } : {}) });
         this.capabilities = capabilitiesFor({ remoteExec: { provider: PROVIDER, s3Snapshot: this.cfg.s3Snapshot }, sandboxReadFloor: config.sandboxReadFloor });
         const bgMax = Math.max(1, Math.min(K8S_BG_MAX_TIMEOUT_SEC, Math.floor(this.cfg.timeoutMs / 1000)));
+        const backgroundShellOn = DEPLOYMENT_SHAPE_PREDICATES.backgroundShell.holds({ remoteExec: { provider: PROVIDER } });
         this.backgroundCapabilities = {
-            supported: true,
+            supported: backgroundShellOn,
             maxConcurrent: K8S_BG_MAX_CONCURRENT,
             defaultBgTimeoutSec: Math.min(K8S_BG_DEFAULT_TIMEOUT_SEC, bgMax),
             maxBgTimeoutSec: bgMax,
-            supportsDetach: true,
+            supportsDetach: backgroundShellOn,
         };
     }
     get sandboxLeaseRef() {
@@ -298,7 +301,7 @@ export class RemoteK8sExecutionEnv {
         return this.cfg.timeoutMs;
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return { sandboxId: this.podName ?? "(unconnected)", provider: PROVIDER, mountPath: this.cwd, ...(this.handleSnapshotId ? { snapshotId: this.handleSnapshotId } : {}) };
@@ -2194,7 +2197,7 @@ export class RemoteK8sExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readBinaryFile(p, abortSignal) {
         const abs = this.resolve(p);

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

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { type LaneLogger } from "./remote-shell.js";
+import { type CustodyMember } from "./workspace-custody.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 ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
@@ -105,7 +106,7 @@ export interface LocalDockerEnvDeps {
     /** 这只环境手里的读地板模块(缺席 ⇒ `createSandboxReadFloor` 按旋钮选;钉注入守地板的模块)。能力块的 `keepsReadFloor` 读它的状态。 */
     readFloor?: SandboxReadFloor;
 }
-export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv {
+export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<LocalDockerLeftover>, RemoteExecutionEnv {
     /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。读地板旋钮是它的输入,{@link floor} 由同一只判据、同一个旋钮值选出。 */
     readonly capabilities: ExecutionEnvCapabilities;
     /** 读拒表字节地板模块:容器里每一次 `docker exec` 起动都先经它的 `wrap`({@link startArgv},唯一接缝)。 */
@@ -155,8 +156,10 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     get leftover(): LocalDockerLeftover | undefined;
     /** 收场的进度:活着 ⇒ 缺席;{@link destroy} 开始 ⇒ 那一次收场(容器删除证实或放弃之后落定)。工厂读它:活着就交回、收场中就等它落定。 */
     get releasing(): Promise<void> | undefined;
-    /** 收场已落定(工厂从同身份表里清掉它)。 */
+    /** 收场已落定。 */
     get released(): boolean;
+    /** 收场落定、不欠删除 ⇒ 出托管表(欠着的由同一身份的下一只拿走)。容器名由身份派生,一只身份同一时刻只有一只没收场的环境 ⇒ 它收场即删,不存在第二个持有者。 */
+    get settled(): boolean;
     private resolve;
     /** 收据句柄。还没连上(懒环境:续跑腿的引擎在恢复相**之前**先取它比车道)⇒ 未连接形 `{ sandboxId: "(unconnected)", provider, mountPath }`(与 k8s / e2b 车道同形),
      *  不抛 —— 抛了,续跑腿在恢复相就失败。 */
@@ -393,7 +396,7 @@ export declare function localDockerIdentityOfName(workerLabel: string, name: str
  * owns the lifetime and calls `destroy()` (= `docker rm -f`) on task end.
  *
  * 身份 = `ctx.taskId ?? ctx.sessionId`(与引擎交给工具的宿主任务号同一读法:顶层 run = run 号,委派子代 = 它自己的会话号 —— 子代从不带 `taskId`)。
- * 一只身份一只工作区:本工厂对同一身份交回**那一只**还没销毁的环境(停驻腿的环境引擎还拿着;续跑腿拿到的就是它 —— 引擎 park-only 契约要的「重连到同一工作区」,
+ * 一只身份一只工作区(工作区托管表 `workspace-custody.ts`,与 host 车道同一只):本工厂对同一身份交回**那一只**还没销毁的环境(停驻腿的环境引擎还拿着;续跑腿拿到的就是它 —— 引擎 park-only 契约要的「重连到同一工作区」,
  * 在同一进程里就是同一只环境,读地板的中继也只有一只);上一只正在收场 ⇒ 等它的删除落定再铸;没有 ⇒ 铸一只(它连接时在跑的同名容器就附着 —— 上一只进程起的)。
  * 收场落定的从表里清掉。
  * 无主容器:停驻中取消 / 停驻过期(本服务在店层结清,不经引擎的仲裁器,停驻腿的环境没有销毁者)与重起之后才结清的停驻,容器一直在跑 ——

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

@@ -1,9 +1,11 @@
 import path from "node:path";
+import { anchoredPath, joinedPath } from "./exec-path-law.js";
 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 { createHash, randomBytes } from "node:crypto";
 import { shellQuote, armPipeDestroyGrace, appendFileStaged, readyUpload, writeFileStaged } from "./remote-shell.js";
+import { createWorkspaceCustody } from "./workspace-custody.js";
 import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { buildCapturedOutput, createCutError } from "../exec-cut.js";
@@ -84,8 +86,11 @@ export class RemoteLocalDockerExecutionEnv {
     get released() {
         return this.teardownSettled;
     }
+    get settled() {
+        return this.teardownSettled && this.leftover === undefined;
+    }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return this.handle ?? { sandboxId: "(unconnected)", provider: PROVIDER, mountPath: this.cfg.mountPath };
@@ -614,7 +619,7 @@ export class RemoteLocalDockerExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readBinaryFile(p, abortSignal) {
         const ready = await this.fsReady(p, abortSignal);
@@ -974,30 +979,11 @@ function errMsg(e) {
 }
 export function localDockerExecutionEnvFactory(config, deps = {}) {
     const { workspaceFillOf, ...base } = config;
-    const live = new Map();
-    const envOf = async (identity, ctx) => {
-        sweep();
-        let leftover;
-        for (let held = live.get(identity); held !== undefined; held = live.get(identity)) {
-            const releasing = held.releasing;
-            if (releasing === undefined)
-                return held;
-            await releasing;
-            if (live.get(identity) === held) {
-                leftover = held.leftover;
-                live.delete(identity);
-            }
-        }
+    const custody = createWorkspaceCustody();
+    const envOf = (identity, ctx) => custody.envOf(identity, (leftover) => {
         const workspaceFill = ctx !== undefined ? workspaceFillOf?.(ctx) : undefined;
-        const env = new RemoteLocalDockerExecutionEnv({ ...base, id: identity, ...(workspaceFill !== undefined ? { workspaceFill } : {}), ...(leftover !== undefined ? { leftover } : {}) }, deps);
-        live.set(identity, env);
-        return env;
-    };
-    const sweep = () => {
-        for (const [identity, env] of live)
-            if (env.released && env.leftover === undefined)
-                live.delete(identity);
-    };
+        return new RemoteLocalDockerExecutionEnv({ ...base, id: identity, ...(workspaceFill !== undefined ? { workspaceFill } : {}), ...(leftover !== undefined ? { leftover } : {}) }, deps);
+    });
     let lister;
     const reapPort = {
         label: base.workerLabel,

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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import { Client } from "ssh2";
 import { createSshHostKeyVerifier } from "../ssh-host-key.js";
 import { appendFileStaged, buildCwdEnvCommand, createCwdGuardedCall, kindFromMode, writeFileStaged } from "./remote-shell.js";
@@ -57,7 +58,7 @@ export class RemoteSshExecutionEnv {
         this.homeSeat = new LaneHomeSeat(PROVIDER, config);
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return { sandboxId: `${this.cfg.host}:${this.cfg.port}`, provider: PROVIDER, mountPath: this.cwd };
@@ -595,7 +596,7 @@ export class RemoteSshExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readTextFile(p, abortSignal) {
         const r = await this.readBinaryFile(p, abortSignal);
@@ -674,7 +675,7 @@ export class RemoteSshExecutionEnv {
             const entries = await new Promise((resolve, reject) => sftp.readdir(abs, (err, list) => (err ? reject(err) : resolve(list))));
             return ok(entries.map((e) => {
                 const a = e.attrs;
-                return { name: e.filename, path: path.posix.join(abs, e.filename), kind: kindFromMode(a.mode), size: a.size ?? 0, mtimeMs: (a.mtime ?? 0) * 1000 };
+                return { name: e.filename, path: anchorUnder(path.posix, abs, e.filename), kind: kindFromMode(a.mode), size: a.size ?? 0, mtimeMs: (a.mtime ?? 0) * 1000 };
             }));
         }
         catch (e) {

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

@@ -60,7 +60,9 @@ export type CwdGuardFace = "settled" | "raw";
  * 🔴 [ref](7.103.1)—— 三条远端 shell 腿(ssh / k8s / adb)交给远端 `sh -c` 的那一串**唯一**的组装:进工作目录 →(settled 面)打 started 行 →
  * 导出任务 env → 跑命令。各腿只决定 `dir`(自己的缺省 cwd 规则 + 路径绝对化),串的形状只在这里。
  *
- * 形:`cd '<dir>' || { echo '<marker>: <dir> (cd failed; command not run)' >&2; exit 125; }; echo '<started>' >&2; export K='v'; … <command>`
+ * 形:`cd -P '<dir>' || { echo '<marker>: <dir> (cd failed; command not run)' >&2; exit 125; }; echo '<started>' >&2; export K='v'; … <command>`
+ *  · `-P`(物理):工作目录按内核解 —— 执行缝路径律下 `<dir>` 是未折的拼法(`<base>/bridge/../next`),文件面由内核解 `..`;缺省的逻辑 `cd` 会先词法折成 `<base>/next`,
+ *    命令与文件动作就各在一只目录。`-P` 是 POSIX `cd` 的选项(dash / bash / busybox ash / mksh 都认)。
  * (raw 面没有 `echo '<started>' >&2;` 那一段)
  *  · cd 失败(目录不存在 / 无权限 / 不是目录)⇒ 命令**不跑**,整条退 {@link CWD_UNAVAILABLE_EXIT};stderr 先是 shell 自己的 cd 报错,再是守卫行。
  *    修前形 `cd '<dir>' && export K='v'; <command>`:`&&` 只绑到第一只 `export`,`;` 之后的命令照样在**登录目录**里跑,还少了那只 env ——

package/dist/plugins/remote-shell.js

@@ -30,7 +30,7 @@ export function buildCwdEnvCommand(command, dir, env, face) {
         const nonce = randomBytes(8).toString("hex");
         cwdGuard = { dir, marker: `${CWD_UNAVAILABLE_LINE} [${nonce}]`, started: startedLineFor(face, nonce) };
         const line = `${cwdGuard.marker}: ${dir} (cd failed; command not run)`;
-        parts.push(`cd ${shellQuote(dir)} || { echo ${shellQuote(line)} >&2; exit ${CWD_UNAVAILABLE_EXIT}; };`);
+        parts.push(`cd -P ${shellQuote(dir)} || { echo ${shellQuote(line)} >&2; exit ${CWD_UNAVAILABLE_EXIT}; };`);
         if (cwdGuard.started !== undefined)
             parts.push(`echo ${shellQuote(cwdGuard.started)} >&2;`);
     }
@@ -184,11 +184,11 @@ function hardenPrivate(dir) {
     return `( chmod -- 700 ${dir} 2>/dev/null && ${readModeOwner(dir)} && case "$1" in drw[xs]--[-S]--[-T]*) [ "$3" = "$(id -u)" ];; *) false;; esac && ${aclCleared(dir)} )`;
 }
 function aclCleared(dir) {
-    const marker = `ls_out=$(cd ${dir} && ls -ld . 2>&1) && [ -z "$(printf '%s\\n' "$ls_out" | sed -n 2p)" ] && mode_word=\${ls_out%% *} && ` +
+    const marker = `ls_out=$(cd -P ${dir} && ls -ld . 2>&1) && [ -z "$(printf '%s\\n' "$ls_out" | sed -n 2p)" ] && mode_word=\${ls_out%% *} && ` +
         `case "$mode_word" in d?????????*+*) echo +;; d?????????*) ;; *) false;; esac`;
     return (`plat=$(uname -s 2>/dev/null) && case "$plat" in ` +
         `Linux) acl_read() { :; }; acl_strip() { false; };; ` +
-        `Darwin) acl_read() { ls_out=$(cd ${dir} && ls -led . 2>&1) && case "$ls_out" in d?????????*) ;; *) false;; esac && printf '%s\\n' "$ls_out" | sed 1d; }; acl_strip() { chmod -N ${dir}; };; ` +
+        `Darwin) acl_read() { ls_out=$(cd -P ${dir} && ls -led . 2>&1) && case "$ls_out" in d?????????*) ;; *) false;; esac && printf '%s\\n' "$ls_out" | sed 1d; }; acl_strip() { chmod -N ${dir}; };; ` +
         `FreeBSD) acl_read() { ${marker}; }; acl_strip() { setfacl -b ${dir}; };; ` +
         `SunOS) acl_read() { ${marker}; }; acl_strip() { chmod A- ${dir}; };; ` +
         `*) false;; esac && acl=$(acl_read 2>/dev/null) && { [ -z "$acl" ] || { acl_strip 2>/dev/null && acl=$(acl_read 2>/dev/null) && [ -z "$acl" ]; }; }`);