@sema-agent/server 7.148.0 → 7.149.0

package/dist/plugins/org-delivery-quota-store.js

@@ -4,13 +4,25 @@ import { existsSync, readFileSync } from "node:fs";
 import { atomicWriteFile, ensureDir } from "@sema-agent/core";
 import { mysqlDriver, pgDriver, sqlDbNowMs } from "./sql-driver.js";
 import { retryOnDeadlock } from "./sql-errors.js";
-import { alignedWindow } from "../observability/cost-quota.js";
+import { alignedWindow, retryAfterSecUntil } from "../observability/cost-quota.js";
 export const ORG_DELIVERY_SENDER_QUOTA_TABLE = "org_delivery_sender_quota";
 export const ORG_DELIVERY_RECIPIENT_QUOTA_TABLE = "org_delivery_recipient_quota";
 export const ORG_DELIVERY_PAIR_QUOTA_TABLE = "org_delivery_pair_quota";
+export const ORG_DELIVERY_QUOTA_UNREADABLE_SENTENCE = "the cross-principal delivery quota state on this server cannot be read, so every delivery is refused until an operator repairs it — nothing was delivered, and retrying will not change the answer";
+export class OrgDeliveryQuotaUnreadableError extends Error {
+    constructor(operatorSentence) {
+        super(operatorSentence);
+        this.name = "OrgDeliveryQuotaUnreadableError";
+    }
+}
 export function quotaWindowStart(nowMs, windowMs) {
     return alignedWindow(nowMs, windowMs).bucket * windowMs;
 }
+const GRANTED = Object.freeze({ granted: true });
+export function quotaRetryAfterSec(nowMs, windowMs) {
+    return retryAfterSecUntil(alignedWindow(nowMs, windowMs));
+}
+const refused = (nowMs, windowMs) => ({ granted: false, retryAfterSec: quotaRetryAfterSec(nowMs, windowMs) });
 export function heldWindowCounts(heldStart, at, windowMs) {
     return heldStart === at || heldStart === at + windowMs;
 }
@@ -21,25 +33,27 @@ export class MemoryOrgDeliveryQuotaStore {
         this.nowMs = nowMs;
     }
     async admitAttempt(fromScope, policy) {
-        const at = quotaWindowStart(this.nowMs(), policy.windowMs);
+        const now = this.nowMs();
+        const at = quotaWindowStart(now, policy.windowMs);
         const held = this.state.senders.get(fromScope);
         const current = held !== undefined && heldWindowCounts(held.windowStart, at, policy.windowMs) ? held : { windowStart: at, windowMs: policy.windowMs, attempts: 0 };
         if (current.attempts >= policy.attemptsPerSender)
-            return false;
+            return refused(now, policy.windowMs);
         const senders = new Map(this.state.senders).set(fromScope, { ...current, attempts: current.attempts + 1 });
         this.commit({ senders, recipients: this.state.recipients });
-        return true;
+        return GRANTED;
     }
     async take(fromScope, toScope, policy) {
-        const at = quotaWindowStart(this.nowMs(), policy.windowMs);
+        const now = this.nowMs();
+        const at = quotaWindowStart(now, policy.windowMs);
         const held = this.state.recipients.get(toScope);
         const current = held !== undefined && heldWindowCounts(held.windowStart, at, policy.windowMs) ? held : { windowStart: at, windowMs: policy.windowMs, total: 0, pairs: new Map() };
         const pair = current.pairs.get(fromScope) ?? 0;
         if (current.total >= policy.perRecipient || pair >= policy.perPair)
-            return false;
+            return refused(now, policy.windowMs);
         const next = { ...current, total: current.total + 1, pairs: new Map(current.pairs).set(fromScope, pair + 1) };
         this.commit({ senders: this.state.senders, recipients: new Map(this.state.recipients).set(toScope, next) });
-        return true;
+        return GRANTED;
     }
     commit(next) {
         const now = this.nowMs();
@@ -97,7 +111,7 @@ export class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaStore {
             parsed = { ok: false, problem: err instanceof Error ? err.message : String(err) };
         }
         if (!parsed.ok) {
-            this.unusable = `the cross-principal delivery quota file ${this.path} cannot be read (${parsed.problem}) — every delivery is refused until an operator moves it away (moving it resets the current window's counts)`;
+            this.unusable = `the cross-principal delivery quota file ${this.path} cannot be read (${parsed.problem}) — every delivery is refused until an operator repairs or moves it away and restarts this server — the file is read once at startup (moving it away resets the current window's counts)`;
             (opts?.warn ?? createLogger().warn)("org_delivery_quota_corrupt_read", { path: this.path, problem: parsed.problem });
             return;
         }
@@ -105,12 +119,12 @@ export class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaStore {
     }
     async admitAttempt(fromScope, policy) {
         if (this.unusable !== undefined)
-            throw new Error(this.unusable);
+            throw new OrgDeliveryQuotaUnreadableError(this.unusable);
         return super.admitAttempt(fromScope, policy);
     }
     async take(fromScope, toScope, policy) {
         if (this.unusable !== undefined)
-            throw new Error(this.unusable);
+            throw new OrgDeliveryQuotaUnreadableError(this.unusable);
         return super.take(fromScope, toScope, policy);
     }
     persist(next) {
@@ -141,16 +155,17 @@ export class SqlOrgDeliveryQuotaStore {
         return retryOnDeadlock(this.db.dialect, () => this.inTxOnce(table, policy, body));
     }
     async inTxOnce(table, policy, body) {
-        const at = quotaWindowStart(await sqlDbNowMs(this.db, table), policy.windowMs);
+        const now = await sqlDbNowMs(this.db, table);
+        const at = quotaWindowStart(now, policy.windowMs);
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const granted = await body(conn, at);
-            if (granted)
+            const ok = await body(conn, at);
+            if (ok)
                 await conn.commit();
             else
                 await conn.rollback();
-            return granted;
+            return ok ? GRANTED : refused(now, policy.windowMs);
         }
         catch (err) {
             await conn.rollback().catch((rollbackErr) => {

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -121,7 +121,7 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
  *
  * 判据同款:发一条恒空的 `WHERE 1=0` 读;**只有可证的缺列**才给「缺列」的拒因(其余错误原样 rethrow ——
  * 超时/连接重置/权限/表不在都会让这条读抛,把它们诊断成「缺列」是一条比缺陷更贵的诊断)。出路是**闭集三条**
- * (与整库对账同一份,{@link describeProbedTableDrift}),没有销毁性的一条。
+ * (与整库对账同一份,{@link probedMissingColumnRefusal}),没有销毁性的一条。
  *
  * 文案照实说本表的分量:票是分钟级 TTL 的治理瞬态(过期即死),持久规则在 `permission_rule` 里,一行都不动。
  */

package/dist/plugins/permission-rule-store-sql.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, EMPTY_DURABLE_RULE_PARTITION, PERMISSION_RULES_LATER_GRAMMAR_CODE, SESSION_RULES_GRAMMAR, readRuleGrammarStamp, readRuleOwner, principalNameOf, readRuleOffer2, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
-import { describeProbedTableDrift } from "./schema-drift-sentence.js";
+import { probedMissingColumnRefusal } from "./schema-drift-sentence.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { ensureIndexes } from "./ensure-index.js";
 import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, StoreCorruptError } from "./sql-json-column.js";
@@ -234,15 +234,13 @@ export async function assertPermissionRuleApprovalSchema(query, dialect) {
     catch (err) {
         if (!isMissingColumnError(err, dialect))
             throw err;
-        throw new Error(`${PERMISSION_RULE_APPROVAL_TABLE} is missing required columns — refusing to start. This build needs the ` +
+        throw await probedMissingColumnRefusal(query, dialect, [PERMISSION_RULE_APPROVAL_TABLE], `${PERMISSION_RULE_APPROVAL_TABLE} is missing required columns — refusing to start. This build needs the ` +
             `#340 card-edit columns (command / edited_json) and the design/375 record-form columns ` +
             `(version / offers_json / selected_offer): the approval record now stores its OPTION structure and the ` +
             `chosen offer, and the store refuses to read rows whose record-form version it cannot vouch for. ` +
             `This table holds pending/settled approval RECORDS (the audit trail of who said yes to which ` +
             `rule), not the rules themselves — persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched; ` +
-            `an in-place ALTER keeps the record trail.\n` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
-            (await describeProbedTableDrift(query, dialect, [PERMISSION_RULE_APPROVAL_TABLE])));
+            `an in-place ALTER keeps the record trail.`, err);
     }
 }
 export async function assertPermissionRuleTicketSchema(query, dialect) {
@@ -252,14 +250,12 @@ export async function assertPermissionRuleTicketSchema(query, dialect) {
     catch (err) {
         if (!isMissingColumnError(err, dialect))
             throw err;
-        throw new Error(`${PERMISSION_RULE_TICKET_TABLE} is missing required columns (redeemed_outcome / claim_id / purpose / settled_at_ms) — refusing to start. This build needs ` +
+        throw await probedMissingColumnRefusal(query, dialect, [PERMISSION_RULE_TICKET_TABLE], `${PERMISSION_RULE_TICKET_TABLE} is missing required columns (redeemed_outcome / claim_id / purpose / settled_at_ms) — refusing to start. This build needs ` +
             `the #265 A7 three-state redemption columns (MINTED → CLAIMED → SETTLED, the claim generation that fences a superseded ` +
             `claimant, and the lane binding that keeps cc-import and local-import tickets from being interchangeable): without them a ` +
             `local-import ticket can be claimed but never settled, so a redemption that already wrote rules to the store answers its ` +
             `owner with a retry-later it can never satisfy. This table holds minute-TTL single-use import ` +
-            `tickets (a governance transient that dies on expiry); persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched.\n` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
-            (await describeProbedTableDrift(query, dialect, [PERMISSION_RULE_TICKET_TABLE])));
+            `tickets (a governance transient that dies on expiry); persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched.`, err);
     }
 }
 export const PERMISSION_RULE_INDEXES = [

package/dist/plugins/pg-pool.d.ts

@@ -51,7 +51,7 @@ export declare function createPgPool(opts: string | pg.PoolConfig, onIdleClientE
 export declare const ENSURE_SCHEMA_LOCK_KEY = 4906;
 /**
  * {@link ENSURE_SCHEMA_LOCK_KEY} 的**非阻塞**获取(轮询 + 抖动退避)—— MySQL 孪生
- * `tidb-pool.ts acquireEnsureSchemaLock` 的逐条同形(循环共用 `ensure-schema-lock-policy.ts`)。轮到拿到为止;坏连接连续抛上抛
+ * `tidb-pool.ts acquireEnsureSchemaLock` 的逐条同形(两只都是 `ensure-schema-lock-policy.ts` 取锁器的薄壳:语句 / 读法 / 循环共用)。轮到拿到为止;坏连接连续抛上抛
  * (每条 DDL 本来就各自幂等),而不是把启动挂死。
  *
  * 🔴 **为什么不能再用阻塞的 `pg_advisory_lock()`**([ref] 复审 H1,对 7.82.1 的回归):本仓自 [ref] 起在

package/dist/plugins/pg-pool.js

@@ -1,7 +1,7 @@
-import { createLogger, writeLogText } from "../observability/logger.js";
+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";
@@ -26,6 +26,7 @@ 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_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,
@@ -36,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 =
@@ -417,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 {
@@ -475,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) {
-        writeLogText("stderr", `[${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();
@@ -497,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

@@ -244,13 +244,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     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;

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;
@@ -764,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));

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
@@ -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

@@ -14,10 +14,12 @@ import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions,
 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 { 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 +36,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 +84,8 @@ export class RemoteHostExecutionEnv {
     cfg;
     prepared = false;
     destroyed = false;
+    teardown;
+    teardownSettled = false;
     spoolRootDir;
     liveFgSpools = new Set();
     inflightFs = new Set();
@@ -122,20 +128,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 +163,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 +210,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 +239,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 +256,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;
@@ -1251,7 +1280,7 @@ export class RemoteHostExecutionEnv {
     ensurePrepared() {
         if (this.prepared)
             return Promise.resolve();
-        if (!this.persistent) {
+        if (this.cfg.workspaceDir === undefined) {
             try {
                 this.assertWorkspaceParentWritable();
             }
@@ -1264,8 +1293,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;
@@ -1305,7 +1334,7 @@ export class RemoteHostExecutionEnv {
             const rel = path.relative(real(root), real(abs));
             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 +1418,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