@sema-agent/server 7.148.0 → 7.150.0

package/dist/plugins/org-delivery-quota-store.d.ts

@@ -18,20 +18,43 @@ export interface OrgDeliveryQuotaPolicy {
     /** 一个收件人在一个窗里能收的封数上界(全部发件人合计)。 */
     readonly perRecipient: number;
 }
+/** 一次记账的判决:放行,或拒 + 到店钟当前窗结束的整秒数(头注「拒的判决带重试指引」)。 */
+export type OrgDeliveryQuotaVerdict = {
+    readonly granted: true;
+} | {
+    readonly granted: false;
+    readonly retryAfterSec: number;
+};
+/**
+ * 店读不出自己的状态(File 腿:快照坏了)⇒ **拒用**的那一只错。fail-closed:每一次记账都抛它,绝不当成「放行」。
+ * 两句话各有读者,所以分开存:`message` = 运维句(点名文件与坏处、出路 —— 只进运维日志);{@link ORG_DELIVERY_QUOTA_UNREADABLE_SENTENCE} = 上线的
+ * 固定句(不点名宿主路径、不带坏处原文 —— 调用方是组织里的任何成员,不是运维)。HTTP 兜底(`http/server.ts`)按本类映射成带因的 500
+ * (码字面量只写在那一处发送点,wire 码目录的扫描面看得见它)。
+ */
+export declare 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 \u2014 nothing was delivered, and retrying will not change the answer";
+export declare class OrgDeliveryQuotaUnreadableError extends Error {
+    constructor(operatorSentence: string);
+}
 export interface OrgDeliveryQuotaStore {
     /**
-     * 原子地把这位发件人的一次投递**尝试**算进店钟当前窗:未满 ⇒ +1、答 `true`;已满 ⇒ 什么都不记、答 `false`。
+     * 原子地把这位发件人的一次投递**尝试**算进店钟当前窗:未满 ⇒ +1、答放行;已满 ⇒ 什么都不记、答拒(带重试指引)。
      * 店读不出 / 写不进 ⇒ **抛**(调用方按失败处置,绝不当成「放行」)。
      */
-    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
     /**
-     * 原子地把一封 (fromScope → toScope) 的信算进**店钟当前窗**的两只计数器:两界都未满 ⇒ 两只各 +1、答 `true`;
-     * 任一界已满 ⇒ 什么都不记、答 `false`。店读不出 / 写不进 ⇒ **抛**。
+     * 原子地把一封 (fromScope → toScope) 的信算进**店钟当前窗**的两只计数器:两界都未满 ⇒ 两只各 +1、答放行;
+     * 任一界已满 ⇒ 什么都不记、答拒(带重试指引)。店读不出 / 写不进 ⇒ **抛**。
      */
-    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
 }
 /** 窗起点(一处算法,三条腿共用)。 */
 export declare function quotaWindowStart(nowMs: number, windowMs: number): number;
+/**
+ * 拒的判决的退避秒数(三条腿共用的**唯一**算式):店钟 `nowMs` 到当前窗结束,向上取整。≥ 1 是桶公式的推论、不另设下限:`nowMs` 严格早于窗末
+ * (`floor(now / w)` 之下 `(桶 + 1) × w − now ∈ (0, w]`),正数向上取整至少是 1 —— 窗末前最后 1 ms 也答 1,不叫客户端「立刻重试」。
+ * 桶与退避秒数的公式不在这里写第二份:都读 `observability/cost-quota.ts` 的 `alignedWindow` / `retryAfterSecUntil`(成本配额、速率限制器同锚)。
+ */
+export declare function quotaRetryAfterSec(nowMs: number, windowMs: number): number;
 /** 店里记着的那个窗(`heldStart`)的计数此刻还算不算数 —— 头注那条律的**唯一**写法:此刻的窗,或此刻的下一个窗。 */
 export declare function heldWindowCounts(heldStart: number, at: number, windowMs: number): boolean;
 /** 一位发件人的当前窗(`windowMs` = 开窗那一次的窗宽:窗何时结束是条目自己的事实,File 腿据它丢已过窗的条目)。 */
@@ -58,8 +81,8 @@ export declare class MemoryOrgDeliveryQuotaStore implements OrgDeliveryQuotaStor
     protected state: QuotaWindows;
     /** @param nowMs 店钟(单进程腿:店 = 这个进程,缺省本进程墙钟)。 */
     constructor(nowMs?: () => number);
-    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
-    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
     /**
      * 落新的整份状态,只留窗还没结束的条目(按条目自己的窗宽判;已结束的发件人 / 收件人整个丢掉 —— 有界:量 = 本窗活跃的主体数)。
      * 丢掉的条目按头注那条律本来就不再算数(过去的窗),所以剪枝不改任何判决;剪枝写在**这里**而不是 File 腿里,Memory 与 File
@@ -89,16 +112,16 @@ export declare class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaSto
         nowMs?: () => number;
         warn?: (event: string, fields: Record<string, unknown>) => void;
     });
-    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
-    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
     protected persist(next: QuotaWindows): void;
 }
 export declare class SqlOrgDeliveryQuotaStore implements OrgDeliveryQuotaStore {
     private readonly db;
     constructor(db: SqlDriver);
     private q;
-    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
-    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
     /**
      * 一个记账事务:库钟先读(池上一条值语句,不在事务里留普通 SELECT),判过 ⇒ 提交,判拒 ⇒ 回滚(零残留)。
      * 🔴 **引擎判了死锁 ⇒ 整事务重来**(`retryOnDeadlock`:全仓唯一的重来写法、唯一的上界与判据):被挑中的一方已整事务回滚、锁全放,

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,9 @@ 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";
+import { replicaRegistrationDdl } from "./replica-registration.js";
+import { servingRequirementDdl } from "./serving-requirement.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -36,6 +39,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 +422,9 @@ export const PG_SCHEMA_STATEMENTS = [
      updated_at_ms  BIGINT       NOT NULL,
      PRIMARY KEY (store_id, path)
    )`,
+    migrationMarkerDdl("pg"),
+    replicaRegistrationDdl("pg"),
+    servingRequirementDdl("pg"),
 ];
 export function pgPoolOptions(pgCfg, dbQueryTimeoutMs) {
     return {
@@ -475,19 +483,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 +498,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/posix-shell-fs.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchorUnder } from "./exec-path-law.js";
 import { FileError, } from "@sema-agent/core";
 import { runSymlinkChain, shellQuote, kindFromMode } from "./remote-shell.js";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
@@ -60,11 +61,12 @@ export function createPosixShellFs(deps) {
             const names = r.value.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
             const out = [];
             for (const name of names) {
-                const info = await fs.statFileInfo(path.posix.join(abs, name), abortSignal);
+                const entry = anchorUnder(path.posix, abs, name);
+                const info = await fs.statFileInfo(entry, abortSignal);
                 if (info.ok)
                     out.push(info.value);
                 else
-                    out.push({ name, path: path.posix.join(abs, name), kind: "file", size: 0, mtimeMs: 0 });
+                    out.push({ name, path: entry, kind: "file", size: 0, mtimeMs: 0 });
             }
             return ok(out);
         },

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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, joinedPath } from "./exec-path-law.js";
 import os from "node:os";
 import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
@@ -65,7 +66,7 @@ export class RemoteAdbExecutionEnv {
         this.injectedConnectOnce = deps?.connectOnce;
     }
     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.serial, provider: PROVIDER, mountPath: this.cwd };
@@ -328,7 +329,7 @@ export class RemoteAdbExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async fsGate(p) {
         if (this.destroyed)

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-device.js

@@ -1,4 +1,5 @@
 import { posix } from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import { ExecutionError, FileError, RemoteExecutionError, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { DEVICE_ERROR_CODES, isDeviceAbsolutePath, } from "../device-store.js";
@@ -174,7 +175,7 @@ export class RemoteDeviceExecutionEnv {
             "performing a NON-atomic write here is exactly the silent downgrade guarded writes exist to prevent (#157). Refusing; the per-task factory mints a correctly-shaped env on the next task.", absPath);
     }
     resolve(p) {
-        return isDeviceAbsolutePath(p) ? posix.normalize(p) : posix.normalize(posix.join(this.cwd, p));
+        return anchoredPath(DEVICE_PATH_FAMILY, this.cwd, p);
     }
     instructionCwd(requested) {
         return requested === undefined ? this.cwd : this.resolve(requested);
@@ -183,7 +184,7 @@ export class RemoteDeviceExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(posix.join(...parts));
+        return ok(joinedPath(DEVICE_PATH_FAMILY, parts));
     }
     workspaceHandle() {
         return {
@@ -557,7 +558,7 @@ export class RemoteDeviceExecutionEnv {
                 return this.wrongOutcome("stat", o.kind, abs);
             if (!o.info)
                 return { ok: false, error: new FileError("unknown", "device returned a stat outcome without info — protocol violation", abs) };
-            return ok(toFileInfo(o.info));
+            return ok(toFileInfo(o.info, abs));
         });
     }
     async doReadLink(p, abortSignal) {
@@ -642,7 +643,7 @@ export class RemoteDeviceExecutionEnv {
                 return this.wrongOutcome("stat", o.kind, abs);
             if (!o.entries)
                 return { ok: false, error: new FileError("unknown", "device returned a stat outcome without entries — protocol violation", abs) };
-            return ok(o.entries.map(toFileInfo));
+            return ok(o.entries.map((w) => toFileInfo(w, anchorUnder(DEVICE_PATH_FAMILY, abs, posix.basename(w.path)))));
         });
     }
     async writeFile(p, content, abortSignal) {
@@ -738,8 +739,9 @@ function mergedEnv(taskEnv, commandEnv) {
 function markTruncated(text, truncated) {
     return truncated === true ? `${text}\n[output truncated by the device executor]` : text;
 }
-function toFileInfo(w) {
-    return { name: posix.basename(w.path), path: w.path, kind: w.kind === "dir" ? "directory" : w.kind === "symlink" ? "symlink" : "file", size: w.size, mtimeMs: w.mtimeMs };
+const DEVICE_PATH_FAMILY = { sep: posix.sep, isAbsolute: isDeviceAbsolutePath };
+function toFileInfo(w, at) {
+    return { name: posix.basename(at), path: at, kind: w.kind === "dir" ? "directory" : w.kind === "symlink" ? "symlink" : "file", size: w.size, mtimeMs: w.mtimeMs };
 }
 function toWireExpectation(e) {
     return {

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

@@ -45,7 +45,7 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers, LaneHomeCo
     template?: string;
     /** Sandbox lifetime in ms (E2B billing window). Default {@link DEFAULT_TIMEOUT_MS}. */
     timeoutMs?: number;
-    /** Workspace root inside the VM; remote paths normalize against it. Default {@link DEFAULT_MOUNT_PATH}. */
+    /** Workspace root inside the VM; a relative path is anchored at it (`exec-path-law.ts`: anchored, never folded). Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
     /** Outbound network for the sandbox (clay: service needs external-network capability). Default `true`. */
     allowInternetAccess?: boolean;
@@ -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;
@@ -371,6 +365,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private ensureConnected;
     private fsReady;
     private tempResult;
+    /** 提供方的条目 → `FileInfo`。`path` 取本环境的拼法(`at`:被问的那只路径 / 列目录时锚在它之下的条目),不取提供方回报的那一份
+     *  —— 提供方可能已把 `..` 折掉,而执行缝路径律(`exec-path-law.ts`)要求条目名在交来的路径之下、能原样再交回来。 */
     private toFileInfo;
     private fileError;
     /** A thrown provider error → this exec's error. The two cuts (aborted, the provider's own command deadline) are a command that RAN: they carry what it had

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

@@ -1,7 +1,9 @@
 import path from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 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 +57,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 +774,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));
@@ -859,7 +863,7 @@ export class RemoteContainerExecutionEnv {
         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 sbx = await this.fsReady(p);
@@ -931,8 +935,9 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         try {
-            const info = await this.rpc("files.getInfo", (signal) => sbx.value.files.getInfo(this.resolve(p), { signal }), abortSignal);
-            return ok(this.toFileInfo(info));
+            const abs = this.resolve(p);
+            const info = await this.rpc("files.getInfo", (signal) => sbx.value.files.getInfo(abs, { signal }), abortSignal);
+            return ok(this.toFileInfo(info, abs));
         }
         catch (e) {
             return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
@@ -943,8 +948,9 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         try {
-            const entries = await this.rpc("files.list", (signal) => sbx.value.files.list(this.resolve(p), { signal }), abortSignal);
-            return ok(entries.map((e) => this.toFileInfo(e)));
+            const abs = this.resolve(p);
+            const entries = await this.rpc("files.list", (signal) => sbx.value.files.list(abs, { signal }), abortSignal);
+            return ok(entries.map((e) => this.toFileInfo(e, anchorUnder(path.posix, abs, e.name))));
         }
         catch (e) {
             return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
@@ -1041,7 +1047,7 @@ export class RemoteContainerExecutionEnv {
         return this.tempResult(r, "mktemp");
     }
     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);
     }
     async rpc(label, op, userSignal, timeoutMs = this.cfg.rpcTimeoutMs) {
         const deadline = new AbortController();
@@ -1160,11 +1166,11 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `${op} failed`) };
         return ok(r.value.stdout.trim());
     }
-    toFileInfo(e) {
+    toFileInfo(e, at) {
         const kind = e.symlinkTarget ? "symlink" : e.type === FileType.DIR ? "directory" : "file";
         return {
             name: e.name,
-            path: e.path,
+            path: at,
             kind,
             size: e.size ?? 0,
             mtimeMs: e.modifiedTime ? e.modifiedTime.getTime() : 0,