@sema-agent/server 7.146.0 → 7.147.0

package/dist/plugins/owner-only-file-mode.d.ts

@@ -0,0 +1,29 @@
+export declare const OWNER_ONLY_FILE_MODE = 384;
+/**
+ * 调用方声明的持久化要求(闭集;两个出口同一参数、必填 —— 没有缺省,每只调用点自己说):
+ *  · `required` —— 这次写是一道围栏的持久化事实(例:local 数据根的引擎版本高水位):目录项没证落盘就不算写成,目录 fsync 失败 ⇒ 抛;
+ *  · `best-effort` —— 一般留痕 / 缓存 / 账本:目录 fsync 失败 ⇒ 写算成功(新内容已可见),F 类留痕 `server.atomic-write.dir-fsync-failed`。
+ */
+export type AtomicWriteDurability = "required" | "best-effort";
+/** 原子写的选项(两个出口同形)。 */
+export interface AtomicWriteOptions {
+    readonly durability: AtomicWriteDurability;
+}
+/**
+ * 异步原子写:同目录 tmp 以 `open(tmp, "wx", {@link OWNER_ONLY_FILE_MODE})` 显式独占新建 —— **拿到句柄那一刻起 tmp 归我**(不从错误形推断);
+ * 写好、fsync、关句柄、`rename` 到 `target`,再 fsync 目录(失败的去向按 `opts.durability`)—— 读者只见整份旧文件或整份新文件(撞名与清理律见头注)。
+ * I/O 经 `node:fs/promises`(与会话店的读口同一只模块):测试对那只模块装的拦点(打开 / 改名)看得见每一次写。
+ */
+export declare function atomicWriteFileAsync(target: string, data: string | Uint8Array, opts: AtomicWriteOptions): Promise<void>;
+/**
+ * 一只**已在位**的文件的持久化屏障(原子写以它收尾的那两步:fsync 文件、fsync 它的目录;win32 不 fsync 目录)—— 给「相等不写」的调用方:
+ * 读到的那一份可能是上一次写落了 `rename` 而目录项没证到的,不重写也要证它在盘上。失败即抛(它只服务 `required` 的事实;不是写口,不改字节、inode、mtime)。
+ */
+export declare function proveDurableSync(target: string): void;
+/**
+ * 同步原子写:与异步形同一只命名与清理律,外加 core `atomicWriteFile` 的其余语义(先 `ensureDir` 父目录;tmp 写好 `fsync`,`rename` 之后 fsync 目录)。
+ * 目录 fsync 失败不回滚(新内容已经可见,也回滚不了);抛不抛按 `opts.durability`(`best-effort` 不抛、留痕;`required` 抛 —— 头注那一座)。
+ * win32 不 fsync 目录(打不开目录 fd;NTFS 的目录项由文件系统日志落盘)。
+ */
+export declare function atomicWriteFileSync(target: string, data: string | Uint8Array, opts: AtomicWriteOptions): void;
+//# sourceMappingURL=owner-only-file-mode.d.ts.map

package/dist/plugins/owner-only-file-mode.js

@@ -0,0 +1,141 @@
+import { closeSync, fsyncSync, openSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { open, rename, rm } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { ensureDir } from "@sema-agent/core";
+import { IS_WIN32 } from "./host-platform.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+export const OWNER_ONLY_FILE_MODE = 0o600;
+const TMP_RANDOM_BYTES = 6;
+const TMP_ATTEMPTS = 8;
+const tmpPathFor = (target) => `${target}.${process.pid}.${randomBytes(TMP_RANDOM_BYTES).toString("hex")}.tmp`;
+const collided = (err) => typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST";
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+const cleanupFailed = (target, tmp, err, cleanup) => new Error(`atomic write of ${target} failed (${messageOf(err)}) and its temporary file ${tmp} could not be removed (${messageOf(cleanup)})`, { cause: err });
+const useAndCloseFailed = (use, close) => Object.assign(new AggregateError([use, close], messageOf(use)), { code: typeof use === "object" && use !== null && "code" in use ? use.code : undefined });
+async function usingHandle(handle, use) {
+    try {
+        await use(handle);
+    }
+    catch (err) {
+        await handle.close().catch((close) => {
+            throw useAndCloseFailed(err, close);
+        });
+        throw err;
+    }
+    await handle.close();
+}
+function usingFd(fd, use) {
+    try {
+        use(fd);
+    }
+    catch (err) {
+        try {
+            closeSync(fd);
+        }
+        catch (close) {
+            throw useAndCloseFailed(err, close);
+        }
+        throw err;
+    }
+    closeSync(fd);
+}
+function dirFsyncFailed(target, err, durability) {
+    switch (durability) {
+        case "required":
+            throw new Error(`atomic write of ${target} landed but its directory entry could not be made durable (${messageOf(err)}) — the write is visible but not proven on disk`, { cause: err });
+        case "best-effort":
+            recordFailOpen("server.atomic-write.dir-fsync-failed", `path=${target} err=${messageOf(err)}`);
+            return;
+        default: {
+            const unhandled = durability;
+            throw new Error(`atomic write of ${target}: unknown durability ${String(unhandled)}`);
+        }
+    }
+}
+export async function atomicWriteFileAsync(target, data, opts) {
+    const { tmp, handle } = await openOwnTmpAsync(target);
+    try {
+        await usingHandle(handle, async (h) => {
+            await h.writeFile(data);
+            await h.sync();
+        });
+        await rename(tmp, target);
+    }
+    catch (err) {
+        try {
+            await rm(tmp, { force: true });
+        }
+        catch (cleanup) {
+            throw cleanupFailed(target, tmp, err, cleanup);
+        }
+        throw err;
+    }
+    if (IS_WIN32)
+        return;
+    try {
+        await usingHandle(await open(dirname(target), "r"), (dir) => dir.sync());
+    }
+    catch (err) {
+        dirFsyncFailed(target, err, opts.durability);
+    }
+}
+async function openOwnTmpAsync(target) {
+    for (let attempt = 1;; attempt += 1) {
+        const tmp = tmpPathFor(target);
+        try {
+            return { tmp, handle: await open(tmp, "wx", OWNER_ONLY_FILE_MODE) };
+        }
+        catch (err) {
+            if (!collided(err) || attempt >= TMP_ATTEMPTS)
+                throw err;
+        }
+    }
+}
+function openOwnTmpSync(target) {
+    for (let attempt = 1;; attempt += 1) {
+        const tmp = tmpPathFor(target);
+        try {
+            return { tmp, fd: openSync(tmp, "wx", OWNER_ONLY_FILE_MODE) };
+        }
+        catch (err) {
+            if (!collided(err) || attempt >= TMP_ATTEMPTS)
+                throw err;
+        }
+    }
+}
+export function proveDurableSync(target) {
+    usingFd(openSync(target, "r"), fsyncSync);
+    if (IS_WIN32)
+        return;
+    usingFd(openSync(dirname(target), "r"), fsyncSync);
+}
+export function atomicWriteFileSync(target, data, opts) {
+    ensureDir(dirname(target));
+    const { tmp, fd } = openOwnTmpSync(target);
+    try {
+        usingFd(fd, (f) => {
+            writeFileSync(f, data);
+            fsyncSync(f);
+        });
+        renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch (cleanup) {
+            throw cleanupFailed(target, tmp, err, cleanup);
+        }
+        throw err;
+    }
+    if (IS_WIN32)
+        return;
+    try {
+        usingFd(openSync(dirname(target), "r"), fsyncSync);
+    }
+    catch (err) {
+        dirFsyncFailed(target, err, opts.durability);
+    }
+}
+//# sourceMappingURL=owner-only-file-mode.js.map

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

@@ -1,4 +1,5 @@
 import { FileDurableRulePartitionProvider, type RuleApprovalRecord, type RuleApprovalRecordStore, type StaleRuleApprovalRecord } from "@sema-agent/core";
+import type { RuleBucketCensus } from "./imported-layer-root-retirement.js";
 import { type RuleImportTicket, type RuleTicketPurpose, type RuleTicketReclaimResult, type RuleTicketRedeemResult, type RuleTicketSnapshot } from "./permission-rule-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 import type { Logger } from "../observability/logger.js";
@@ -27,10 +28,9 @@ export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordSt
     create(record: RuleApprovalRecord): Promise<void>;
     cas(id: string, expectRev: number, next: RuleApprovalRecord): Promise<boolean>;
     /**
-     * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)在 File 店的桶来源之一:本店**导入记录**点名过的每一个属主(逐条记录取、**这里不去重**:
-     * 多条记录点名同一属主就重复出现,按桶键去重在退役步)。引擎 File 分区的桶文件按属主名的单向摘要命名,桶的属主不写在文件里;File 腿读的桶集是
-     * {@link fileRuleBucketOwners} 取的并集 = 本店导入记录点名的属主 ∪ 引擎 `listBucketOwners().owners`(自 core 7.64.0 起的列桶口:本机属主那只桶与收编标记点名的身份),
-     * 所以记录不是 File 腿叫得出桶属主的唯一来源(SQL 店不经记录,直接列规则表)。引擎 `unnamedBuckets` 为什么本步不报、File 侧还剩的缺口,见 `imported-layer-root-retirement.ts` 头注「读哪些桶」。
+     * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)在 File 店交给引擎列桶口的那一半:本店**导入记录**点名过的每一个属主(逐条记录取、**这里不去重**:
+     * 多条记录点名同一属主就重复出现,引擎按名去重)。引擎 File 分区的桶文件按属主名的单向摘要命名,桶的属主不写在文件里;{@link fileRuleBucketOwners} 把这里的身份名
+     * 作 `knownOwners` 交给引擎 `listBucketOwners`,由引擎一次答出桶在场的属主与叫不出名字的桶数(SQL 店不经记录,直接列规则表),见 `imported-layer-root-retirement.ts` 头注「读哪些桶」。
      * 上一形的记录(Stale 信封)读不出种类 ⇒ 属主读得出就算上(多读一只桶零写,少读一只会漏)。
      * 损坏闸合着 ⇒ 抛(读不全记录就叫不全桶;与本面其余口同一条 fail-closed)。
      */
@@ -99,11 +99,11 @@ export declare class FileRuleImportTicketStore {
 /** 三面束在数据根下的目录名(唯一一处;束在第一次装配时建它 —— 没开过规则店的数据根下没有它)。 */
 export declare const FILE_PERMISSION_RULE_DIR = "permission-rules";
 /**
- * M36 File 腿读哪些桶(窗口见 `plugins/one-time-migrations.ts` 登记表;读法见 `imported-layer-root-retirement.ts` 头注「读哪些桶」):
- * 导入记录点名过的属主 ∪ 引擎 File 分区后端列得出名字的属主(本机属主那只桶、收编标记点名的身份)。两源有重 ⇒ 退役步按桶键去重。
- * 引擎列桶口的拒(目录用不了 `bucket_damaged`、列不出 `bucket_unreadable`、坏收编标记)原样抛 ⇒ 起服拒(叫不全桶就不判)。
+ * M36 File 腿的桶普查(窗口见 `plugins/one-time-migrations.ts` 登记表;读法见 `imported-layer-root-retirement.ts` 头注「读哪些桶」):引擎 File 分区后端的列桶口一次答 ——
+ * 目录自己叫得出名字的属主(本机属主那只桶、收编标记点名的身份)+ 导入记录点名过的身份里桶文件在场的那些(`knownOwners`),与两者都叫不出属主的桶数。
+ * 引擎列桶口的拒(目录用不了 `bucket_damaged`、列不出 `bucket_unreadable`、坏收编标记、`knownOwners` 里有不是身份名的串 `config.invalid_argument`)原样抛 ⇒ 起服拒(叫不全桶就不判)。
  */
-export declare function fileRuleBucketOwners(stores: Pick<FilePermissionRuleStores, "approvals" | "durable">): Promise<readonly RuleOwner[]>;
+export declare function fileRuleBucketOwners(stores: Pick<FilePermissionRuleStores, "approvals" | "durable">): Promise<RuleBucketCensus>;
 /**
  * 这只读桶抛出物是不是引擎 File 分区的**确定性整桶拒**(拒码 `permission_rules.bucket_damaged`:同一份字节每次读都同样拒,读侧零规则、什么都不放行)。
  * 别的都不是:`permission_rules.bucket_unreadable`(一次读失败,带 `errno`;证明不了以后也读不出)、`permission_rules.later_grammar`(更新的引擎写的桶)、

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

@@ -333,8 +333,20 @@ export class FileRuleImportTicketStore {
 }
 export const FILE_PERMISSION_RULE_DIR = "permission-rules";
 export async function fileRuleBucketOwners(stores) {
-    const listed = stores.durable.listBucketOwners();
-    return [...(await stores.approvals.importRecordOwners()), ...listed.owners];
+    const knownOwners = (await stores.approvals.importRecordOwners()).flatMap(principalNameOfOwner);
+    return stores.durable.listBucketOwners({ knownOwners });
+}
+function principalNameOfOwner(owner) {
+    switch (owner.kind) {
+        case "principal":
+            return [owner.principal];
+        case "local-owner":
+            return [];
+        default: {
+            const unknown = owner;
+            throw new Error(`M36: an owner of a kind this pass does not know: ${JSON.stringify(unknown)}`);
+        }
+    }
 }
 export function isFileBucketDamaged(e) {
     return typeof e === "object" && e !== null && e.code === PERMISSION_RULES_DAMAGED_BUCKET_CODE;

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

@@ -99,7 +99,8 @@ export declare function acquirePgEnsureSchemaLock(client: pg.PoolClient, tag: st
 /** {@link acquirePgEnsureSchemaLock} 的释放(尽力而为 —— 锁随连接归还自动释放)。 */
 export declare function releasePgEnsureSchemaLock(client: pg.PoolClient, tag: string): Promise<void>;
 /** Idempotent central schema apply (the PG twin of tidb-pool.ts ensureSchema): the run/checkpoint tables here +
- *  every PG store's own (disjoint) tables. Order is irrelevant (CREATE IF NOT EXISTS, no cross-table FKs).
+ *  every PG store's own (disjoint) tables. Order is irrelevant (CREATE IF NOT EXISTS) except for the one cross-table FK: the session
+ *  side table `session_ext` references `session_meta`, so it is created right after the session store's tables.
  *
  *  Concurrency: callers run this concurrently — tests fan ALL integration suites out in parallel (each beforeAll
  *  calls ensurePgSchema), and in production every replica calls it at boot. Concurrent DDL on the SAME table makes

package/dist/plugins/pg-pool.js

@@ -2,7 +2,8 @@ import pg from "pg";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
 import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
-import { ensureSchema as ensureSessionSchema } from "./pg-session-storage.js";
+import { ensureSchema as ensureSessionSchema } from "../stores-sql/pg-session-storage.js";
+import { sessionExtDdl } from "./session-ext-table.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";
@@ -16,9 +17,11 @@ import { ensurePgSessionCaptureOptOutSchema } from "./session-capture-record-sto
 import { ensurePgAdoptionLogSchema } from "./adoption-log-sql.js";
 import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
 import { ensurePgLeaderRunSchema } from "./leader-run-store-sql.js";
-import { ensurePgRetentionSchema } from "./retention-store-sql.js";
+import { PG_RETENTION_TOMBSTONE_SCHEMA, RETENTION_TOMBSTONE_INDEXES } from "../stores-sql/retention-store-sql.js";
+import { PG_RETENTION_LANE_SCHEMA, RETENTION_LANE_INDEXES } from "./retention-lane-store-sql.js";
 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";
 export const PG_SCHEMA_STATEMENTS = [
@@ -351,7 +354,8 @@ export const PG_SCHEMA_STATEMENTS = [
      -- (the engine's own correlation id, verbatim; the engine's diagnostic teaching text, redacted + bounded at enqueue;
      -- each key absent when the engine minted none, NULL when neither).
      kind           VARCHAR(24) COLLATE "C",
-     payload        TEXT COLLATE "C",
+     -- Column definition owner = inbox-payload-column.ts (INBOX_PAYLOAD_COLUMN; TiDB twin same note).
+     ${INBOX_PAYLOAD_COLUMN.pg},
      PRIMARY KEY (session_id, run_id),
      -- Twin-alignment with TiDB's \`UNIQUE KEY uq_wfinbox_seq (seq)\` (same constraint name on purpose, so the two
      -- schemas can be diffed by name). This is NOT a correctness fix: seq is BIGSERIAL, so it is already unique in
@@ -485,6 +489,7 @@ export async function ensurePgSchema(pool) {
         for (const stmt of PG_SCHEMA_STATEMENTS)
             await client.query(stmt);
         await ensureSessionSchema(client);
+        await client.query(sessionExtDdl("pg"));
         await ensureToolResultSchema(client);
         await ensureCostQuotaSchema(client);
         await ensureRateLimitSchema(client);
@@ -498,7 +503,9 @@ export async function ensurePgSchema(pool) {
         await ensurePgAdoptionLogSchema((text, params) => client.query(text, params));
         await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
         await ensurePgLeaderRunSchema((text, params) => client.query(text, params));
-        await ensurePgRetentionSchema((text, params) => client.query(text, params));
+        for (const stmt of [...PG_RETENTION_LANE_SCHEMA, ...PG_RETENTION_TOMBSTONE_SCHEMA])
+            await client.query(stmt);
+        await ensureIndexes((text, params) => client.query(text, params), "pg", [...RETENTION_LANE_INDEXES, ...RETENTION_TOMBSTONE_INDEXES]);
         await ensureIndexes((text, params) => client.query(text, params), "pg", CENTRAL_SCHEMA_INDEXES);
     }
     finally {

package/dist/plugins/release-version.d.ts

@@ -0,0 +1,20 @@
+/**
+ * **版本串的两种读法**(唯一一处;两问不同,两个读者各管一问,三段的文法只有一只正则):
+ *  · {@link releaseTriple} 读 **marker 里的串**(公开契约):纯 `x.y.z` —— 整串三段十进制、无前导零、无 `v` 前缀、无预发布 / 构建后缀、无空白,每段是安全整数;
+ *    别的一律读不出(`undefined`),不剥前后缀、不猜;入参先验型(不是字符串 ⇒ 读不出)。与壳侧判官(client-core `compareReleaseVersions` 的 `releaseTriple`)同一读法:
+ *    同一对 marker 串两边答案不分叉。
+ *  · {@link buildReleaseTriple} 读 **本构建 `package.json` 的版本** —— 它属于哪一条发布线:semver 文法的 `x.y.z`,可带 `-<预发布>` 与 / 或 `+<构建>` 后缀;
+ *    后缀**只剥不比**(`7.147.0-rc.1` 属于 `7.147.0` 那条线),三段交给 {@link releaseTriple} 同一只正则;不是字符串 / 不合文法 ⇒ 读不出。
+ * (钉 `test/local-engine-high-water.test.ts` 的两张读法表逐格对它们。)读者:引擎版本高水位的判与抬(`local-engine-high-water.ts`)。
+ */
+/** 一只发布版本的三段(大 · 次 · 补丁)。 */
+export type ReleaseTriple = readonly [number, number, number];
+/** 纯 `x.y.z` → 三段;不是(含不是字符串 —— 先验型、再匹配,正则不强转)⇒ `undefined`。 */
+export declare function releaseTriple(v: unknown): ReleaseTriple | undefined;
+/** 本构建版本 → 它所属发布线的三段(后缀只剥不比);不是字符串 / 不合 semver 文法 / 三段不是纯 `x.y.z` ⇒ `undefined`。 */
+export declare function buildReleaseTriple(v: unknown): ReleaseTriple | undefined;
+/** 三段的纯 `x.y.z` 串(marker 里写的形;{@link releaseTriple} 读回的就是它)。 */
+export declare function releaseText(t: ReleaseTriple): string;
+/** 两只三段按数比(先大版本,再次版本,再补丁):`-1` / `0` / `1`。 */
+export declare function compareReleaseTriples(a: ReleaseTriple, b: ReleaseTriple): -1 | 0 | 1;
+//# sourceMappingURL=release-version.d.ts.map

package/dist/plugins/release-version.js

@@ -0,0 +1,28 @@
+export function releaseTriple(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const m = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(v);
+    if (m === null)
+        return undefined;
+    const t = [Number(m[1]), Number(m[2]), Number(m[3])];
+    return t.every((n) => Number.isSafeInteger(n)) ? t : undefined;
+}
+const PRERELEASE_IDENTIFIER = String.raw `(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)`;
+const BUILD_IDENTIFIER = String.raw `[0-9A-Za-z-]+`;
+const BUILD_VERSION = new RegExp(String.raw `^([^-+]*)(?:-${PRERELEASE_IDENTIFIER}(?:\.${PRERELEASE_IDENTIFIER})*)?(?:\+${BUILD_IDENTIFIER}(?:\.${BUILD_IDENTIFIER})*)?$`);
+export function buildReleaseTriple(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const m = BUILD_VERSION.exec(v);
+    return m === null ? undefined : releaseTriple(m[1]);
+}
+export function releaseText(t) {
+    return `${t[0]}.${t[1]}.${t[2]}`;
+}
+export function compareReleaseTriples(a, b) {
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    return 0;
+}
+//# sourceMappingURL=release-version.js.map

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

@@ -15,6 +15,12 @@ export interface AdbEnvConfig extends LaneHomeConfig {
         maxAttempts?: number;
         backoffMs?: number;
     };
+    /** 运维日志座(起服装配递本服务的 logger;缺席 ⇒ 本模块自建一只 JSON 行 logger —— 设模式失败那一行不因没人递座而消失)。 */
+    logger?: AdbEnvLogger;
+}
+/** 本适配器说话用的那一面(与 k8s / device 车道的 logger 座同形)。 */
+export interface AdbEnvLogger {
+    warn(event: string, fields?: Record<string, unknown>): void;
 }
 type ConnectResult = {
     ok: true;
@@ -79,6 +85,7 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      *  这条显式授予),没有一条是从本进程继承的 ⇒ `[]`(core 契约:「`[]` when its shell environment is built rather than inherited」)。 */
     readonly withheldEnv: readonly [];
     private readonly cfg;
+    private readonly logger;
     private readonly spawnFn;
     private readonly injectedConnectOnce?;
     constructor(config: AdbEnvConfig, deps?: AdbEnvDeps);
@@ -164,17 +171,26 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;父目录与私有暂存目录由编排的准备那一步建):
-     *  上传 = `adb push` 到私有目录里的暂存件;提交 = 文件面探针 exec。两者同一身份(push 与 `adb shell` 都由设备上的 adbd 以它的身份落盘 / 起进程)。 */
+     *  上传 = `adb push` 到私有目录里的暂存件(阶段一 = 本机落临时件,见 {@link prepareUpload};阶段二 = push);提交 = 文件面探针 exec。两者同一身份(push 与 `adb shell` 都由设备上的 adbd 以它的身份落盘 / 起进程)。 */
     private stagedLane;
     /** 整旧或整新(暂存 → 一次 `mv -f`)。修前 push 直落目标:传输中途断 / 取消时目标剩什么取决于设备侧 adbd 的落地实现,本适配器不依赖它。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     /** 追加(暂存要加的字节 → 一次 `cat >>`;inode 不换、已有字节不重写)。修前 = 读旧 + 拼 + 整份 push(O(文件);中途断 ⇒ 目标没了或半份)。
      *  目录不收新名字 / 私有目录收不成私有时的退路 = 修前那一形(push 没有追加写,只能把整份文件落到一个路径上):读旧(不在 ⇒ 按空;别的读错照实答、不 push)
-     *  + 拼 + 整份 push 直落目标(与 e2b 共用 `rewriteAppend`)—— 非原子,push 中途断 / 取消 ⇒ 目标可能没了或只剩半份(只有 push 那一步经 `ctx.inPlace`:读旧时取消照答 `aborted`,目标未碰)。
+     *  + 拼 + 本机落临时件 + 整份 push 直落目标(与 e2b 共用 `rewriteAppend`)—— 非原子,push 中途断 / 取消 ⇒ 目标可能没了或只剩半份;读旧与落临时件是备件阶段:
+     *  取消落在这里 ⇒ `aborted`、目标未碰、一次 push 都没发,只有 push 那一步被取消打断才答 `unknown`。
      *  Android 共享存储(权限位由挂载派生)上收紧那一步按 sdcardfs / MediaProvider FUSE 的权限语义**推断**不过(未上真机,真机读数候 test),追加每次走这里。 */
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
-    /** 把整份内容 `adb push` 到设备上的 `dest`(建或覆盖)。本机这一侧先落一只本地临时件再 push(二进制安全,不经 shell 转义载荷)——
-     *  临时件同样只在私有目录里出现(`mkdtemp` 建的目录生来 0700),本机别的用户读不到;文件自己的权限位照缺省(push 把它带到设备上,与修前同)。 */
+    /** 阶段一(备件):把整份内容在本机落一只临时件(二进制安全,不经 shell 转义载荷)—— 临时件同样只在私有目录里出现(`mkdtemp` 建的目录生来 0700,本机别的用户读不到);
+     *  文件自己带 {@link OWNER_ONLY_FILE_MODE}(0600,不靠上层私有目录兜:内容是要上设备的文件,可能含凭据)。设备侧的模式**不随它走**:`adb push` 会把本机文件的模式位带到设备上
+     *  〔推断,未上真机;adbd 还会先把属主位扩到组 / 他人位、再交文件系统策略〕,所以阶段二在 push 之后把目的地显式设回 {@link DEVICE_PUSHED_FILE_MODE}(尽力而为)。这一段只碰本机,没有一个字节发往设备:编排在它之后复核取消、再起阶段二;`release` 删临时件。
+     *  阶段二({@link push})把临时件 `adb push` 到设备上的 `dest`。 */
+    private prepareUpload;
+    /** 阶段二:把本机临时件 `adb push` 到设备上的 `dest`(建或覆盖),**同一步内**紧跟一次 `chmod -- 0644 <dest>`:设备目标的模式是显式的 {@link DEVICE_PUSHED_FILE_MODE},
+     *  不依赖临时件的模式传播(升级前它来自本机 umask 的缺省 0644)。push 的结局就是这一步的结局:push 失败 ⇒ 既有错误形;取消落在 push 里 ⇒ `aborted`(编排按阶段二读)。
+     *  设模式是**尽力而为**(「传完之后设模式」全树一种失败策略,与 `remote-shell.ts` 的 `carryMode` 同):字节已经落地,设不上(文件系统不认改模式 / 设备掉线 / 取消落在 chmod 上)
+     *  ⇒ 这一步照样成功,只多一行运维 warn `remote_env_file_mode_failed`(目的地经出口座、设备回话只取首行;不记 fail-open:模式是显式加固,目标文件系统不支持时无从加固,
+     *  不是放宽 —— 升级前同一只文件落成的位也由文件系统定)。答失败会让调用方以为没写成,而目标已是新字节。 */
     private push;
     private posixFsInst?;
     private get posixFs();

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

@@ -5,6 +5,7 @@ import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { appendFileStaged, rewriteAppend, buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace, writeFileStaged } from "./remote-shell.js";
+import { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
 import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { buildCapturedOutput, createCutError } from "../exec-cut.js";
@@ -12,7 +13,10 @@ import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTail
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
+import { createLogger } from "../observability/logger.js";
+import { seatText } from "../trace/exit-seat.js";
 const PROVIDER = "adb";
+const DEVICE_PUSHED_FILE_MODE = "0644";
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
     ok: false,
@@ -42,6 +46,7 @@ export class RemoteAdbExecutionEnv {
     cdPath = "unknown";
     withheldEnv = [];
     cfg;
+    logger;
     spawnFn;
     injectedConnectOnce;
     constructor(config, deps) {
@@ -54,6 +59,7 @@ export class RemoteAdbExecutionEnv {
             retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 800 },
         };
         this.cwd = this.cfg.mountPath;
+        this.logger = config.logger ?? createLogger();
         this.homeSeat = new LaneHomeSeat(PROVIDER, config);
         this.spawnFn = deps?.spawn ?? spawn;
         this.injectedConnectOnce = deps?.connectOnce;
@@ -360,7 +366,7 @@ export class RemoteAdbExecutionEnv {
         return ok(lines);
     }
     stagedLane(content) {
-        return { upload: (dest, signal) => this.push(content, dest, signal), run: (cmd, signal) => this.fsExec(cmd, signal) };
+        return { prepare: this.prepareUpload(content), run: (cmd, signal) => this.fsExec(cmd, signal), provider: PROVIDER, logger: this.logger };
     }
     async writeFile(p, content, abortSignal) {
         const gated = await this.fsGate(p);
@@ -373,14 +379,29 @@ export class RemoteAdbExecutionEnv {
         if (gated)
             return gated;
         const abs = this.resolve(p);
-        return appendFileStaged(this.stagedLane(content), abs, abortSignal, (ctx) => rewriteAppend((signal) => this.readBinaryFile(abs, signal), (bytes, signal) => this.push(bytes, abs, signal), content, ctx));
+        return appendFileStaged(this.stagedLane(content), abs, abortSignal, rewriteAppend((signal) => this.readBinaryFile(abs, signal), (merged) => this.prepareUpload(merged), content));
+    }
+    prepareUpload(content) {
+        return async () => {
+            let localDir;
+            const release = async () => {
+                if (localDir)
+                    await fs.rm(localDir, { recursive: true, force: true }).catch(() => { });
+            };
+            try {
+                localDir = await fs.mkdtemp(path.join(os.tmpdir(), "sema-adb-push-"));
+                const local = path.join(localDir, "data");
+                await fs.writeFile(local, typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content), { mode: OWNER_ONLY_FILE_MODE });
+                return ok({ upload: (dest, signal) => this.push(local, dest, signal), release });
+            }
+            catch (e) {
+                await release();
+                return { ok: false, error: new FileError("unknown", e instanceof Error ? e.message : String(e)) };
+            }
+        };
     }
-    async push(content, dest, abortSignal) {
-        let localDir;
+    async push(local, dest, abortSignal) {
         try {
-            localDir = await fs.mkdtemp(path.join(os.tmpdir(), "sema-adb-push-"));
-            const local = path.join(localDir, "data");
-            await fs.writeFile(local, typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content));
             const r = await this.adb(["-s", this.cfg.serial, "push", local, dest], { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs });
             if (!r.ok)
                 return { ok: false, error: fileErrorFromExec(r.error, dest) };
@@ -389,15 +410,22 @@ export class RemoteAdbExecutionEnv {
                 return { ok: false, error: new FileError("permission_denied", out.trim(), dest) };
             if (r.value.exitCode !== 0)
                 return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `adb push failed for ${dest}`, dest) };
+            const m = await this.fsExec(`chmod -- ${DEVICE_PUSHED_FILE_MODE} ${shellQuote(dest)}`, abortSignal);
+            const unset = !m.ok ? m.error.message : m.value.exitCode !== 0 ? m.value.stderr.trim() || `chmod exited ${m.value.exitCode}` : undefined;
+            if (unset !== undefined) {
+                this.logger.warn("remote_env_file_mode_failed", {
+                    provider: PROVIDER,
+                    path: seatText("operator-log-arg", dest),
+                    mode: DEVICE_PUSHED_FILE_MODE,
+                    error: seatText("operator-log-text", unset.split(/\r?\n/, 1)[0] ?? ""),
+                    effect: "the bytes landed; the file keeps the mode the device filesystem gave it (setting the mode is best effort, as adbd itself treats it)",
+                });
+            }
             return ok(undefined);
         }
         catch (e) {
             return { ok: false, error: new FileError("unknown", e instanceof Error ? e.message : String(e), dest) };
         }
-        finally {
-            if (localDir)
-                await fs.rm(localDir, { recursive: true, force: true }).catch(() => { });
-        }
     }
     posixFsInst;
     get posixFs() {

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

@@ -291,12 +291,21 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
     /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;本腿是原生 SDK 腿,与四条
      *  shell 腿共用的是这只编排,不是 `posix-shell-fs` 基座;父目录与私有暂存目录由编排的准备那一步建):上传 = `files.write` 整份写到私有目录里的
-     *  暂存件;提交 = 一次 `exec`。两者同一身份(`files.write` 与 `commands.run` 都不带 `user`,沙箱侧取同一个缺省用户)。 */
+     *  暂存件;提交 = 一次 `exec`。
+     *
+     *  **身份怎么读(出处:e2b 2.36.0 的 `dist/index.d.ts`,按符号名 + 文档原句引,不引行号 —— 上游 dist 的行号随提货漂)**:上传的 `files.write` 不带 `user`(下面 `upload`);
+     *  `FilesystemRequestOpts.user` 的文档说它影响「解析相对路径与 `ownership of the created filesystem objects`」(所建文件系统对象的**属主**),
+     *  文件接口 REST 参数 `username` 的文档句是 `Defaults to the sandbox's default user`(缺省 = 沙箱的缺省用户)⇒ 上传落下的东西**属主**是沙箱缺省用户。
+     *  提交 / 清理的 `commands.run`:`CommandStartOpts.user` 的缺省是 `default Sandbox user (as specified in the template)`(模板的缺省用户);本腿的起动经 {@link startIn} 的起动编码,身份只由那一处给
+     *  (读地板守着时外层以 root 起、监督者再降到工作区属主,见 `sandbox-read-floor.ts` 的 `laneLaunchPlan`)。
+     *  所以编排要的「提交方拿得走、清得掉上传落下的东西」靠的是**属主**(缺省用户 = 命令的缺省执行用户);SDK 类型**没有**说上传是以该用户的**权限**去写 ——
+     *  [I:读 SDK 类型,推断由沙箱守护进程代写再改属主;未上真沙箱]。这一差别的后果:准备脚本建的 0700 私有目录属提交方,上传能写进去是守护进程代写的结果、
+     *  不是「同一个用户自己写」;目录收不成私有而退到直接写目标时,`files.write` 整份写目标,落地后的属主 / 权限位由沙箱侧定(与 7.138.x 同权,无用户可见回归)。 */
     private stagedLane;
     /** 整旧或整新(暂存 → 一次 `mv -f`)。修前 `files.write` 直落目标:上传中途断 / 取消时目标剩什么取决于沙箱侧的落地实现,本适配器不依赖它。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     /** 追加(暂存要加的字节 → 一次 `cat >>`;inode 不换、已有字节不重写)。修前 = 读旧 + 拼 + 整份 `files.write`(O(文件);中途断 ⇒
-     *  半份)。目录不收新名字 / 私有目录收不成私有时的退路 = 旧形(`rewriteAppend`:读旧 + 拼 + 整份 `files.write` 到目标;只有写那一步经 `ctx.inPlace`)。 */
+     *  半份)。目录不收新名字 / 私有目录收不成私有时的退路 = 旧形(`rewriteAppend`:读旧 + 拼是备件阶段,取消落在那里 ⇒ `aborted`、目标未碰;整份 `files.write` 到目标是传输那一步,被取消打断 ⇒ `unknown`)。 */
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
@@ -390,7 +399,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
 /**
  * Build the deployment-level `RunnerDeps.executionEnvFactory` ([ref] v1b). Wiring this onto a
  * deployment makes it a "code-agent worker": every task's hand runs in a per-task E2B VM. Deployments that do
- * NOT set this (e.g. OA / review) keep the in-process stub env — routing is **deployment-level** (the factory
+ * declare another lane run that lane's factory (or none, for `REMOTE_EXEC=none`) — routing is **deployment-level** (the factory
  * ctx carries only sessionId/taskId, never a service scenario; that stays out of the generic core seam).
  *
  * The factory returns the env **unconnected** (lazy): the VM is provisioned on first FS/Shell/execStream use,

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

@@ -5,7 +5,7 @@ import { capabilitiesFor } from "../execution-lane-caps.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";
-import { appendFileStaged, rewriteAppend, numEnvOr, runSymlinkChain, shellQuote, writeFileStaged } from "./remote-shell.js";
+import { appendFileStaged, readyUpload, rewriteAppend, numEnvOr, runSymlinkChain, shellQuote, writeFileStaged } from "./remote-shell.js";
 import { buildLivenessCut, commandBoundsOf, firstBoundOf, laneLivenessOf, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
 import { createCutError } from "../exec-cut.js";
 import { BackgroundShellManager } from "./background-shell-support.js";
@@ -904,7 +904,7 @@ export class RemoteContainerExecutionEnv {
     stagedLane(sbx, content) {
         const data = typeof content === "string" ? content : toArrayBuffer(content);
         return {
-            upload: async (dest, signal) => {
+            prepare: readyUpload(async (dest, signal) => {
                 try {
                     await this.rpc("files.write", (s) => sbx.files.write(dest, data, { signal: s }), signal, this.cfg.dataTimeoutMs);
                     return ok(undefined);
@@ -912,8 +912,10 @@ export class RemoteContainerExecutionEnv {
                 catch (e) {
                     return { ok: false, error: this.fileError(e, dest, signal) };
                 }
-            },
+            }),
             run: (cmd, signal) => this.execInternal(cmd, { cwd: "/", ...(signal !== undefined ? { abortSignal: signal } : {}) }),
+            provider: PROVIDER,
+            logger: this.cfg.logger,
         };
     }
     async writeFile(p, content, abortSignal) {
@@ -927,7 +929,7 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         const abs = this.resolve(p);
-        return appendFileStaged(this.stagedLane(sbx.value, content), abs, abortSignal, (ctx) => rewriteAppend((signal) => this.readBinaryFile(abs, signal), (bytes, signal) => this.stagedLane(sbx.value, bytes).upload(abs, signal), content, ctx));
+        return appendFileStaged(this.stagedLane(sbx.value, content), abs, abortSignal, rewriteAppend((signal) => this.readBinaryFile(abs, signal), (merged) => this.stagedLane(sbx.value, merged).prepare, content));
     }
     async fileInfo(p, abortSignal) {
         const sbx = await this.fsReady(p);

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

@@ -54,6 +54,12 @@ export interface HostEnvConfig extends LaneHomeConfig {
      *  single-user TOC host lane. `HOST_BG_ENABLED=false` is an additional global kill switch(🪦 旧名
      *  `HOST_BG_DISABLED` 自 server 3.0.0 起是 fail-loud 墓碑:设了即拒启并指路新名,不再被读取)。 */
     backgroundShell?: boolean;
+    /**
+     * `true` = 本服务自己的 git worktree 基环境(`git worktree add / remove / prune`;`boot/execution-env.ts` 铸一只):它**从不交给引擎**,引擎不读它的 {@link withheldEnv},
+     * 所以它扣了哪些名字没有引擎通告替它说 —— 它的 spawn 记在自己的现场 `server.remote-env-host.git-base`(披露行是唯一读法)。缺省(交给引擎的环境:工厂产物、
+     * worktree 子代环境、嵌入方交给 `Runner` 的环境)记在 `server.remote-env-host.spawn-env`:名字由引擎的 `inherit_env.names_withheld` 说,只记计数。
+     */
+    gitBase?: true;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
     /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
@@ -428,7 +434,9 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *    `inheritedHostEnv(policy)`:三个继承词(`"all"` / `"scrub"` / `[names]`)只在引擎一处判,本进程自有凭据名(起服声明)任何词都不交 ——
      *    本类不再有三臂字面(7.129.0 / core 7.51.1;修前 `all` 是 `{ ...process.env }` 零剥除)。**不碰 shell**,所以读面(如 {@link cdPath})任何时候
      *    都能读,不依赖 shell 是否已落定。
-     *  · **spawn 层**(`spawnShell` 在场)—— 这一次是真要交给子进程:经 `hostSubprocessEnv` 记剥除(`spawnShell` 缺席 ⇒ 只读组合 `composeHostSubprocessEnv`,
+     *  · **spawn 层**(`spawnShell` 在场)—— 这一次是真要交给子进程:经 `hostSubprocessEnv` 记剥除。交给引擎的环境(缺省)只记**计数**、不写名字:扣了哪些名字由引擎读
+     *    {@link withheldEnv} 说(`inherit_env.names_withheld`;现场 `server.remote-env-host.spawn-env`,表里 `told:"engine-notice"`);本服务自己的 git 基环境({@link HostEnvConfig.gitBase})
+     *    引擎读不到,记在 `server.remote-env-host.git-base`,披露行照写(`spawnShell` 缺席 ⇒ 只读组合 `composeHostSubprocessEnv`,
      *    不计数:一次没发生的 spawn 不进剥除账),win32 上把 `SHELL` 钉到已解析的 Git Bash({@link pinHostShell},在大小写折叠**之前**)。
      * 披露与钉同一个开关(`spawnShell`)—— 「真 spawn」只有一种说法,不再有 `disclose` 与钉各自一个布尔。
      * 引擎对点到自有凭据名的白名单在这里**抛**(spawn 时的拒;构造器已先问过同一只判)—— 子进程不起,拒句带名。