@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/pg-pool.js

@@ -1,9 +1,11 @@
+import { createLogger } from "../observability/logger.js";
 import pg from "pg";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
+import { acquireAdvisoryLock, releaseAdvisoryLock } from "./ensure-schema-lock-policy.js";
 import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
 import { ensureSchema as ensureSessionSchema } from "../stores-sql/pg-session-storage.js";
 import { sessionExtDdl } from "./session-ext-table.js";
+import { CHECKPOINT_HOST_SESSION_COLUMN } from "./checkpoint-index-columns.js";
 import { ensureSchema as ensureToolResultSchema } from "../stores-sql/tool-result-store-sql.js";
 import { ensureSchema as ensureCostQuotaSchema } from "./pg-cost-quota.js";
 import { ensureSchema as ensureRateLimitSchema } from "./pg-rate-limiter.js";
@@ -23,7 +25,8 @@ import { ensureIndexes } from "./ensure-index.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { INBOX_PAYLOAD_COLUMN } from "./inbox-payload-column.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
-import { PRINCIPAL_MAX_LENGTH } from "../security.js";
+import { PRINCIPAL_MAX_BYTES } from "../principal-shape.js";
+import { SKILL_EXEMPTION_CUTOFF_ID, markIfAbsentSql, migrationMarkerDdl } from "./one-time-migration-marker.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -34,6 +37,8 @@ export const PG_SCHEMA_STATEMENTS = [
      error       TEXT COLLATE "C",
      error_code  VARCHAR(64) COLLATE "C",
      instance_id VARCHAR(64) COLLATE "C",
+     -- leg_id: the HOLDING LEG minted at every claim (semantics in the MySQL twin, tidb-pool.ts task_run).
+     leg_id      VARCHAR(36) COLLATE "C",
      job_id      VARCHAR(64) COLLATE "C",
      source      VARCHAR(64) COLLATE "C",
      -- identity_*: the run's identity tuple (semantics in the MySQL twin, tidb-pool.ts task_run; column definitions' single owner =
@@ -121,6 +126,8 @@ export const PG_SCHEMA_STATEMENTS = [
      -- JSON ⇒ 与同表 outcome 列同取 JSONB(协议信封无损,IS NULL 谓词两方言同义)。
      execution_outcome JSONB,
      execution_at_ms   BIGINT,
+     -- host_session_id:这张卡归在哪只会话上(MySQL 孪生同名同义;语义、写口与 M49 回填见 tidb-pool.ts 同名列的行内注)。
+     ${CHECKPOINT_HOST_SESSION_COLUMN.pg},
      PRIMARY KEY (token)
    )`,
     `CREATE TABLE IF NOT EXISTS checkpoint_ctx (
@@ -150,22 +157,27 @@ export const PG_SCHEMA_STATEMENTS = [
      consumed_at_ms BIGINT         NOT NULL,
      expires_at_ms  BIGINT         NOT NULL,
      PRIMARY KEY (session_id, nonce)
+   )`,
+    `CREATE TABLE IF NOT EXISTS approval_nonce_floor (
+     singleton CHAR(1) COLLATE "C" NOT NULL DEFAULT 'x',
+     floor_ms  BIGINT  NOT NULL,
+     PRIMARY KEY (singleton)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_sender_quota (
-     from_scope      VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     from_scope      VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      attempts        INT          NOT NULL,
      PRIMARY KEY (from_scope)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_recipient_quota (
-     to_scope        VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     to_scope        VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      delivered       INT          NOT NULL,
      PRIMARY KEY (to_scope)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_pair_quota (
-     to_scope        VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
-     from_scope      VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     to_scope        VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+     from_scope      VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      delivered       INT          NOT NULL,
      PRIMARY KEY (to_scope, from_scope)
@@ -408,6 +420,7 @@ export const PG_SCHEMA_STATEMENTS = [
      updated_at_ms  BIGINT       NOT NULL,
      PRIMARY KEY (store_id, path)
    )`,
+    migrationMarkerDdl("pg"),
 ];
 export function pgPoolOptions(pgCfg, dbQueryTimeoutMs) {
     return {
@@ -430,7 +443,7 @@ export function pgPoolClientErrorMeta(err) {
 }
 export function createPgPool(opts, onIdleClientError) {
     const pool = typeof opts === "string" ? new pg.Pool({ connectionString: opts }) : new pg.Pool(opts);
-    const warn = onIdleClientError ?? ((msg, meta) => console.warn(`[pg-pool] ${msg}`, meta));
+    const warn = onIdleClientError ?? createLogger().warn;
     const report = (msgName, state, err, count) => {
         const meta = pgPoolClientErrorMeta(err);
         try {
@@ -466,19 +479,12 @@ export function createPgPool(opts, onIdleClientError) {
     return pool;
 }
 export const ENSURE_SCHEMA_LOCK_KEY = 4906;
+const ENSURE_SCHEMA_LOCK_ID = { dialect: "pg", keys: [ENSURE_SCHEMA_LOCK_KEY] };
 export async function acquirePgEnsureSchemaLock(client, tag) {
-    await pollUntilLocked(async () => {
-        const res = await client.query("SELECT pg_try_advisory_lock($1) AS got", [ENSURE_SCHEMA_LOCK_KEY]);
-        return res.rows[0]?.got === true;
-    }, { tag, label: `pg advisory lock ${ENSURE_SCHEMA_LOCK_KEY}` });
+    await acquireAdvisoryLock(client, ENSURE_SCHEMA_LOCK_ID, tag);
 }
 export async function releasePgEnsureSchemaLock(client, tag) {
-    try {
-        await client.query("SELECT pg_advisory_unlock($1)", [ENSURE_SCHEMA_LOCK_KEY]);
-    }
-    catch (err) {
-        console.warn(`[${tag}] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (lock auto-frees on connection close):`, err);
-    }
+    await releaseAdvisoryLock(client, ENSURE_SCHEMA_LOCK_ID, tag);
 }
 export async function ensurePgSchema(pool) {
     const client = await pool.connect();
@@ -488,6 +494,7 @@ export async function ensurePgSchema(pool) {
         locked = true;
         for (const stmt of PG_SCHEMA_STATEMENTS)
             await client.query(stmt);
+        await client.query(markIfAbsentSql("pg"), [SKILL_EXEMPTION_CUTOFF_ID, Date.now()]);
         await ensureSessionSchema(client);
         await client.query(sessionExtDdl("pg"));
         await ensureToolResultSchema(client);

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

@@ -331,14 +331,15 @@ export declare function deviceExecutionEnvFactory(deps: DeviceEnvFactoryDeps): E
 /**
  * §4.3.3 的 cwd 优先序 —— 与 host 腿的 `effectiveHostWorkspace` **同源**:
  *   ① 本 session 显式注册的 cwd(部署形表行 `callerCwd` 闸下由 resolve-spec 写);
- *   ② `ctx.parentCwd`(委派子代:自己没注册过 cwd,继承父的工作目录 —— 少了它子代会丢工作目录);
+ *   ② `ctx.parentCwd`(交活方的工作目录:委派子代继承父的;组合腿 —— 梯子的级、验证器腿,跑在引擎现铸的会话里 —— 由组合入口交提交登记的 cwd;
+ *      少了它这些腿会丢工作目录);
  *   ③ 设备入籍时登记并落库的 `workspaceRoot`(缺 cwd 时的解析基准,有明确 wire 契约,不是「executor
  *      默认根」这种空话)。
  *
  * 🔴 **这一只解析源同时守它的后置条件:结果必是 POSIX 绝对路径,否则响亮抛 typed 拒(`.code` = `config.device_cwd_invalid`)。** 协议文档对 executor 的承诺是
  * 「exec / execStream 的指令帧恒带绝对 `cwd`」—— 不带或带相对的,都会把「用哪个目录」这件事留给 executor
  * 自己猜(同一个事实两种读法)。判据是入籍口那**同一只**谓词 `isDeviceAbsolutePath`(`device-store.ts`):入籍口用它拒相对的
- * `workspaceRoot`;这里的判留作存量行守卫(入籍口收紧之前落库的相对根)并守另两个来源 —— 委派链的父 cwd 来自引擎,不经入籍口。
+ * `workspaceRoot`;这里的判留作存量行守卫(入籍口收紧之前落库的相对根)并守另两个来源 —— 第 ② 臂的交活方工作目录不经入籍口。
  */
 export declare function effectiveDeviceCwd(sessionCwd: string | undefined, parentCwd: string | undefined, row: Pick<DeviceRow, "workspaceRoot">): string;
 export {};

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

@@ -20,7 +20,7 @@
  * iterator MAY throw `RemoteExecutionError` mid-stream before an `exit` chunk (seam contract, OutputChunk).
  */
 import { Sandbox, type SandboxOpts, type SandboxConnectOpts } from "e2b";
-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 ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
@@ -159,18 +159,6 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     /** 收据句柄。还没连上(懒环境:续跑腿的引擎在 `resumeVM` **之前**先取它比车道)⇒ 未连接形 `{ sandboxId: "(unconnected)", provider, mountPath }`(与 k8s 车道同形),
      *  不抛 —— 抛了,续跑腿在恢复之前就失败。 */
     workspaceHandle(): WorkspaceHandle;
-    /**
-     * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
-     * ([ref] §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
-     * provisions the VM (like exec/fs); `undefined` if it can't connect → the LSP manager degrades.
-     */
-    getHost(port: number): Promise<string | undefined>;
-    /**
-     * Launch a long-running process as a TRUE E2B background command (resolves once launched, E2B keeps it alive)
-     * — for the LSP bridge ([ref] §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
-     * command's process group on completion, which would kill an in-shell `&`/nohup child. Fire-and-forget.
-     */
-    startBackground(command: string): Promise<void>;
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -251,25 +239,12 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private stopKeepAlive;
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
-    exec(command: string, options?: ExecOpts): Promise<Result<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-        detached?: {
-            shellId: string;
-        };
-    }, ExecutionError>>;
+    exec(command: string, options?: ExecOpts): Promise<Result<ExecResult, ExecutionError>>;
     /** 适配器自己的固定命令(文件面助手:readlink / realpath / rm / mktemp / 暂存写的提交)—— 与 {@link exec} 同一条路,起动形 `adapter`。 */
     private execInternal;
     private execAs;
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
-    readonly backgroundCapabilities: {
-        readonly supported: true;
-        readonly maxConcurrent: number;
-        readonly defaultBgTimeoutSec: number;
-        readonly maxBgTimeoutSec: number;
-        readonly supportsDetach: true;
-    };
+    readonly backgroundCapabilities: BackgroundShellCapability["backgroundCapabilities"];
     private _bgManager?;
     private get bgManager();
     private makeBgDriver;
@@ -355,10 +330,11 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      * confirmations: a refused `kill()` (logged; the exit is still awaited), a `wait()` that ends without an exit (the
      * connection deadline, a lost stream — the process may still run). With neither the count stays held and `suspendVM`
      * keeps refusing `command_in_flight` — the same arm as a start that never settles. No start promise (the op never ran)
-     * ⇒ released now. A failed start is released at once too, as in 7.129.0 — and that one is NOT a confirmation: there is
-     * no handle to kill or wait on, and a start whose reply was lost (the SDK's own 60 s handshake) may have spawned the
-     * process. Closing it means classifying the start failure (provider refused ⇒ not started; lost reply ⇒ held) — open,
-     * not done here.
+     * ⇒ released now. A start that FAILED is read by the same rule ({@link providerRefusedStart}): the provider answered a
+     * refusal of the request itself ⇒ no process was ever spawned — a confirmation, released; any other failure (the SDK's
+     * own handshake deadline, a dropped stream, an unreachable sandbox, anything else) has no answer in it — the provider may
+     * have spawned the process and the reply was lost ⇒ not a confirmation, held, and said once
+     * (`e2b_start_outcome_unknown`: the sandbox and the error's class, never the command).
      */
     private settleAbandonedStart;
     /**

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

@@ -2,6 +2,7 @@ import path from "node:path";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, 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, createSandboxReadFloor, e2bFloorCommand, engineStart, } from "./sandbox-read-floor.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
@@ -55,6 +56,14 @@ export class RemoteContainerExecutionEnv {
         this.sandboxApi = deps.sandboxApi ?? Sandbox;
         this.floor = deps.readFloor ?? createSandboxReadFloor({ lane: PROVIDER, knob: config.sandboxReadFloor, ...(config.logger !== undefined ? { logger: config.logger } : {}) });
         this.capabilities = capabilitiesFor({ remoteExec: { provider: PROVIDER }, sandboxReadFloor: config.sandboxReadFloor });
+        const backgroundShellOn = DEPLOYMENT_SHAPE_PREDICATES.backgroundShell.holds({ remoteExec: { provider: PROVIDER } });
+        this.backgroundCapabilities = {
+            supported: backgroundShellOn,
+            maxConcurrent: E2B_BG_MAX_CONCURRENT,
+            defaultBgTimeoutSec: E2B_BG_DEFAULT_TIMEOUT_SEC,
+            maxBgTimeoutSec: E2B_BG_MAX_TIMEOUT_SEC,
+            supportsDetach: backgroundShellOn,
+        };
     }
     capabilities;
     floor;
@@ -140,19 +149,6 @@ export class RemoteContainerExecutionEnv {
     workspaceHandle() {
         return this.handle ?? { sandboxId: "(unconnected)", provider: PROVIDER, mountPath: this.cwd };
     }
-    async getHost(port) {
-        const conn = await this.ensureConnected();
-        return conn.ok ? conn.value.getHost(port) : undefined;
-    }
-    async startBackground(command) {
-        const conn = await this.ensureConnected();
-        if (!conn.ok)
-            return;
-        const s = this.startIn(engineStart(undefined), command, undefined);
-        if (!s.ok)
-            return void this.cfg.logger?.warn?.("remote_env_background_refused", { error: s.error.message });
-        await this.runIn(conn.value, s.value, { background: true });
-    }
     async connect(config) {
         if (config?.snapshotId) {
             return this.resumeVM(config.snapshotId, config.abortSignal ? { abortSignal: config.abortSignal } : undefined);
@@ -507,7 +503,7 @@ export class RemoteContainerExecutionEnv {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
                 timeoutMs: tee
-                    ? Math.max(this.commandTimeoutMs(options?.timeout), (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000)
+                    ? this.commandTimeoutMs(options?.timeout) + (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000
                     : this.commandTimeoutMs(options?.timeout),
                 onStdout: (d) => {
                     if (startCut)
@@ -554,12 +550,14 @@ export class RemoteContainerExecutionEnv {
         waitP.then(markResolved, markResolved);
         let fgSettled = false;
         let adoptedShellId;
+        let adoptedCause;
         let onDetach;
+        let onDetachSignal;
         const detachedP = detachSignal && tee
             ? new Promise((res) => {
-                onDetach = () => {
+                const adoptRunning = (cause) => {
                     if (detached || fgSettled || fgResolved || options?.abortSignal?.aborted)
-                        return;
+                        return false;
                     const adopted = this.bgManager.adoptSync((ctx) => {
                         waitP
                             .then((r) => ctx.onTerminal(false, r.exitCode))
@@ -572,22 +570,28 @@ export class RemoteContainerExecutionEnv {
                         return { handle, stdout: tee.stdout, stderr: tee.stderr };
                     });
                     if (!adopted)
-                        return;
+                        return false;
                     adoptedShellId = adopted.shellId;
+                    adoptedCause = cause;
                     detached = true;
                     res("detached");
+                    return true;
                 };
+                onDetach = adoptRunning;
+                const signalled = () => void adoptRunning();
+                onDetachSignal = signalled;
                 if (detachSignal.aborted)
-                    onDetach();
+                    signalled();
                 else
-                    detachSignal.addEventListener("abort", onDetach, { once: true });
+                    detachSignal.addEventListener("abort", signalled, { once: true });
             })
             : undefined;
+        const onWall = options?.autoBackgroundOnTimeout === true && detachedP !== undefined ? () => onDetach?.("timeout") === true : undefined;
         try {
             const fg = this.waitWithLiveness(handle, () => lastProgress, {
                 waitP,
                 disarmed: () => detached,
-                ...(tee ? { wall: { totalMs: this.commandTimeoutMs(options?.timeout), leftMs: Math.max(0, this.commandTimeoutMs(options?.timeout) - (Date.now() - startedAt)) } } : {}),
+                ...(tee ? { wall: { totalMs: this.commandTimeoutMs(options?.timeout), leftMs: Math.max(0, this.commandTimeoutMs(options?.timeout) - (Date.now() - startedAt)), ...(onWall !== undefined ? { onWall } : {}) } } : {}),
                 liveness: bounds.liveness,
                 captured,
             });
@@ -599,7 +603,7 @@ export class RemoteContainerExecutionEnv {
                     stdout: markTruncated(o.text, o.droppedBytes),
                     stderr: markTruncated(e.text, e.droppedBytes),
                     exitCode: 0,
-                    detached: { shellId: adoptedShellId },
+                    detached: { shellId: adoptedShellId, ...(adoptedCause !== undefined ? { cause: adoptedCause } : {}) },
                 });
             }
             if (options?.abortSignal?.aborted && !detached) {
@@ -618,8 +622,8 @@ export class RemoteContainerExecutionEnv {
         }
         finally {
             fgSettled = true;
-            if (onDetach && detachSignal)
-                detachSignal.removeEventListener("abort", onDetach);
+            if (onDetachSignal && detachSignal)
+                detachSignal.removeEventListener("abort", onDetachSignal);
             this.activeCommands--;
             options?.abortSignal?.removeEventListener("abort", onAbort);
         }
@@ -673,7 +677,7 @@ export class RemoteContainerExecutionEnv {
                 const bc = boundCut(first);
                 throw new RemoteExecutionError(bc.code, bc.message, e);
             }
-            throw this.remoteError(e, "connect_failed");
+            throw this.remoteError(e, providerTimedOut(e) ? "timeout" : "connect_failed");
         }
         handle
             .wait()
@@ -769,13 +773,7 @@ export class RemoteContainerExecutionEnv {
             options?.signal?.removeEventListener("abort", onAbort);
         }
     }
-    backgroundCapabilities = {
-        supported: true,
-        maxConcurrent: E2B_BG_MAX_CONCURRENT,
-        defaultBgTimeoutSec: E2B_BG_DEFAULT_TIMEOUT_SEC,
-        maxBgTimeoutSec: E2B_BG_MAX_TIMEOUT_SEC,
-        supportsDetach: true,
-    };
+    backgroundCapabilities;
     _bgManager;
     get bgManager() {
         return (this._bgManager ??= new BackgroundShellManager(this.makeBgDriver(), this.backgroundCapabilities));
@@ -1083,7 +1081,15 @@ export class RemoteContainerExecutionEnv {
             late.kill().then(release, (e) => {
                 this.cfg.logger?.warn?.("e2b_abandoned_start_kill_failed", { sandboxId: this.sbx?.sandboxId, pid: late.pid, error: e instanceof Error ? e.name : typeof e });
             });
-        }, release);
+        }, (e) => {
+            if (providerRefusedStart(e))
+                return release();
+            this.cfg.logger?.warn?.("e2b_start_outcome_unknown", {
+                sandboxId: this.sbx?.sandboxId,
+                error: e instanceof Error ? e.name : typeof e,
+                effect: "the command start failed without the provider refusing it — the command may be running, so this sandbox is not suspended (command_in_flight) for the rest of its life",
+            });
+        });
     }
     commandTimeoutMs(timeoutSec) {
         return timeoutSec != null ? timeoutSec * 1000 : this.cfg.timeoutMs;
@@ -1115,6 +1121,8 @@ export class RemoteContainerExecutionEnv {
                 wallTimer = setTimeout(() => {
                     if (opts.disarmed?.())
                         return;
+                    if (wall.onWall?.() === true)
+                        return;
                     reject(createCutError({ code: "timeout", message: wallCutMessage(wall.totalMs) }, opts.captured()));
                     void handle.kill().catch(() => { });
                 }, wall.leftMs);
@@ -1232,6 +1240,10 @@ function boundCut(first) {
 function providerTimedOut(e) {
     return e?.name === "TimeoutError" || /timeout|timed out/i.test(errMsg(e));
 }
+const E2B_START_REFUSALS = new Set(["InvalidArgumentError", "AuthenticationError", "NotFoundError", "RateLimitError"]);
+function providerRefusedStart(e) {
+    return e instanceof Error && E2B_START_REFUSALS.has(e.name);
+}
 function anySignal(signals) {
     const ctor = AbortSignal;
     if (typeof ctor.any === "function")

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 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
@@ -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 契约)。 */
@@ -264,14 +293,7 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     disposeBackgroundShells(opts?: {
         except?: readonly BackgroundShellId[];
     }): Promise<void>;
-    exec(command: string, options?: ExecOpts): Promise<Result<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-        detached?: {
-            shellId: string;
-        };
-    }, ExecutionError>>;
+    exec(command: string, options?: ExecOpts): Promise<Result<ExecResult, ExecutionError>>;
     /** 管道旧形(win32 / spool 打开失败的回退;行为=1.225 及以前的 exec 原样)。 */
     private execViaPipes;
     /** [ref] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"
@@ -380,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 权限判据无从谈起。
@@ -460,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