@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/pg-pool.js

@@ -1,8 +1,11 @@
+import { createLogger, writeLogText } from "../observability/logger.js";
 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 { CHECKPOINT_HOST_SESSION_COLUMN } from "./checkpoint-index-columns.js";
 import { ensureSchema as ensureToolResultSchema } from "../stores-sql/tool-result-store-sql.js";
 import { ensureSchema as ensureCostQuotaSchema } from "./pg-cost-quota.js";
 import { ensureSchema as ensureRateLimitSchema } from "./pg-rate-limiter.js";
@@ -16,11 +19,13 @@ 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";
+import { PRINCIPAL_MAX_BYTES } from "../principal-shape.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -118,6 +123,8 @@ export const PG_SCHEMA_STATEMENTS = [
      -- JSON ⇒ 与同表 outcome 列同取 JSONB(协议信封无损,IS NULL 谓词两方言同义)。
      execution_outcome JSONB,
      execution_at_ms   BIGINT,
+     -- host_session_id:这张卡归在哪只会话上(MySQL 孪生同名同义;语义、写口与 M49 回填见 tidb-pool.ts 同名列的行内注)。
+     ${CHECKPOINT_HOST_SESSION_COLUMN.pg},
      PRIMARY KEY (token)
    )`,
     `CREATE TABLE IF NOT EXISTS checkpoint_ctx (
@@ -147,22 +154,27 @@ export const PG_SCHEMA_STATEMENTS = [
      consumed_at_ms BIGINT         NOT NULL,
      expires_at_ms  BIGINT         NOT NULL,
      PRIMARY KEY (session_id, nonce)
+   )`,
+    `CREATE TABLE IF NOT EXISTS approval_nonce_floor (
+     singleton CHAR(1) COLLATE "C" NOT NULL DEFAULT 'x',
+     floor_ms  BIGINT  NOT NULL,
+     PRIMARY KEY (singleton)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_sender_quota (
-     from_scope      VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     from_scope      VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      attempts        INT          NOT NULL,
      PRIMARY KEY (from_scope)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_recipient_quota (
-     to_scope        VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     to_scope        VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      delivered       INT          NOT NULL,
      PRIMARY KEY (to_scope)
    )`,
     `CREATE TABLE IF NOT EXISTS org_delivery_pair_quota (
-     to_scope        VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
-     from_scope      VARCHAR(${PRINCIPAL_MAX_LENGTH}) COLLATE "C" NOT NULL,
+     to_scope        VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+     from_scope      VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
      window_start_ms BIGINT       NOT NULL,
      delivered       INT          NOT NULL,
      PRIMARY KEY (to_scope, from_scope)
@@ -351,7 +363,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
@@ -426,7 +439,7 @@ export function pgPoolClientErrorMeta(err) {
 }
 export function createPgPool(opts, onIdleClientError) {
     const pool = typeof opts === "string" ? new pg.Pool({ connectionString: opts }) : new pg.Pool(opts);
-    const warn = onIdleClientError ?? ((msg, meta) => console.warn(`[pg-pool] ${msg}`, meta));
+    const warn = onIdleClientError ?? createLogger().warn;
     const report = (msgName, state, err, count) => {
         const meta = pgPoolClientErrorMeta(err);
         try {
@@ -473,7 +486,7 @@ export async function releasePgEnsureSchemaLock(client, tag) {
         await client.query("SELECT pg_advisory_unlock($1)", [ENSURE_SCHEMA_LOCK_KEY]);
     }
     catch (err) {
-        console.warn(`[${tag}] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (lock auto-frees on connection close):`, err);
+        writeLogText("stderr", `[${tag}] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (lock auto-frees on connection close):`, err);
     }
 }
 export async function ensurePgSchema(pool) {
@@ -485,6 +498,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 +512,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

@@ -20,7 +20,7 @@
  * iterator MAY throw `RemoteExecutionError` mid-stream before an `exit` chunk (seam contract, OutputChunk).
  */
 import { Sandbox, type SandboxOpts, type SandboxConnectOpts } from "e2b";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
@@ -159,18 +159,6 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     /** 收据句柄。还没连上(懒环境:续跑腿的引擎在 `resumeVM` **之前**先取它比车道)⇒ 未连接形 `{ sandboxId: "(unconnected)", provider, mountPath }`(与 k8s 车道同形),
      *  不抛 —— 抛了,续跑腿在恢复之前就失败。 */
     workspaceHandle(): WorkspaceHandle;
-    /**
-     * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
-     * ([ref] §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
-     * provisions the VM (like exec/fs); `undefined` if it can't connect → the LSP manager degrades.
-     */
-    getHost(port: number): Promise<string | undefined>;
-    /**
-     * Launch a long-running process as a TRUE E2B background command (resolves once launched, E2B keeps it alive)
-     * — for the LSP bridge ([ref] §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
-     * command's process group on completion, which would kill an in-shell `&`/nohup child. Fire-and-forget.
-     */
-    startBackground(command: string): Promise<void>;
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -251,14 +239,7 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private stopKeepAlive;
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
-    exec(command: string, options?: ExecOpts): Promise<Result<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-        detached?: {
-            shellId: string;
-        };
-    }, ExecutionError>>;
+    exec(command: string, options?: ExecOpts): Promise<Result<ExecResult, ExecutionError>>;
     /** 适配器自己的固定命令(文件面助手:readlink / realpath / rm / mktemp / 暂存写的提交)—— 与 {@link exec} 同一条路,起动形 `adapter`。 */
     private execInternal;
     private execAs;
@@ -291,12 +272,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>>;
@@ -346,10 +336,11 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      * confirmations: a refused `kill()` (logged; the exit is still awaited), a `wait()` that ends without an exit (the
      * connection deadline, a lost stream — the process may still run). With neither the count stays held and `suspendVM`
      * keeps refusing `command_in_flight` — the same arm as a start that never settles. No start promise (the op never ran)
-     * ⇒ released now. A failed start is released at once too, as in 7.129.0 — and that one is NOT a confirmation: there is
-     * no handle to kill or wait on, and a start whose reply was lost (the SDK's own 60 s handshake) may have spawned the
-     * process. Closing it means classifying the start failure (provider refused ⇒ not started; lost reply ⇒ held) — open,
-     * not done here.
+     * ⇒ released now. A start that FAILED is read by the same rule ({@link providerRefusedStart}): the provider answered a
+     * refusal of the request itself ⇒ no process was ever spawned — a confirmation, released; any other failure (the SDK's
+     * own handshake deadline, a dropped stream, an unreachable sandbox, anything else) has no answer in it — the provider may
+     * have spawned the process and the reply was lost ⇒ not a confirmation, held, and said once
+     * (`e2b_start_outcome_unknown`: the sandbox and the error's class, never the command).
      */
     private settleAbandonedStart;
     /**
@@ -390,7 +381,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";
@@ -140,19 +140,6 @@ export class RemoteContainerExecutionEnv {
     workspaceHandle() {
         return this.handle ?? { sandboxId: "(unconnected)", provider: PROVIDER, mountPath: this.cwd };
     }
-    async getHost(port) {
-        const conn = await this.ensureConnected();
-        return conn.ok ? conn.value.getHost(port) : undefined;
-    }
-    async startBackground(command) {
-        const conn = await this.ensureConnected();
-        if (!conn.ok)
-            return;
-        const s = this.startIn(engineStart(undefined), command, undefined);
-        if (!s.ok)
-            return void this.cfg.logger?.warn?.("remote_env_background_refused", { error: s.error.message });
-        await this.runIn(conn.value, s.value, { background: true });
-    }
     async connect(config) {
         if (config?.snapshotId) {
             return this.resumeVM(config.snapshotId, config.abortSignal ? { abortSignal: config.abortSignal } : undefined);
@@ -507,7 +494,7 @@ export class RemoteContainerExecutionEnv {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
                 timeoutMs: tee
-                    ? Math.max(this.commandTimeoutMs(options?.timeout), (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000)
+                    ? this.commandTimeoutMs(options?.timeout) + (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000
                     : this.commandTimeoutMs(options?.timeout),
                 onStdout: (d) => {
                     if (startCut)
@@ -554,12 +541,14 @@ export class RemoteContainerExecutionEnv {
         waitP.then(markResolved, markResolved);
         let fgSettled = false;
         let adoptedShellId;
+        let adoptedCause;
         let onDetach;
+        let onDetachSignal;
         const detachedP = detachSignal && tee
             ? new Promise((res) => {
-                onDetach = () => {
+                const adoptRunning = (cause) => {
                     if (detached || fgSettled || fgResolved || options?.abortSignal?.aborted)
-                        return;
+                        return false;
                     const adopted = this.bgManager.adoptSync((ctx) => {
                         waitP
                             .then((r) => ctx.onTerminal(false, r.exitCode))
@@ -572,22 +561,28 @@ export class RemoteContainerExecutionEnv {
                         return { handle, stdout: tee.stdout, stderr: tee.stderr };
                     });
                     if (!adopted)
-                        return;
+                        return false;
                     adoptedShellId = adopted.shellId;
+                    adoptedCause = cause;
                     detached = true;
                     res("detached");
+                    return true;
                 };
+                onDetach = adoptRunning;
+                const signalled = () => void adoptRunning();
+                onDetachSignal = signalled;
                 if (detachSignal.aborted)
-                    onDetach();
+                    signalled();
                 else
-                    detachSignal.addEventListener("abort", onDetach, { once: true });
+                    detachSignal.addEventListener("abort", signalled, { once: true });
             })
             : undefined;
+        const onWall = options?.autoBackgroundOnTimeout === true && detachedP !== undefined ? () => onDetach?.("timeout") === true : undefined;
         try {
             const fg = this.waitWithLiveness(handle, () => lastProgress, {
                 waitP,
                 disarmed: () => detached,
-                ...(tee ? { wall: { totalMs: this.commandTimeoutMs(options?.timeout), leftMs: Math.max(0, this.commandTimeoutMs(options?.timeout) - (Date.now() - startedAt)) } } : {}),
+                ...(tee ? { wall: { totalMs: this.commandTimeoutMs(options?.timeout), leftMs: Math.max(0, this.commandTimeoutMs(options?.timeout) - (Date.now() - startedAt)), ...(onWall !== undefined ? { onWall } : {}) } } : {}),
                 liveness: bounds.liveness,
                 captured,
             });
@@ -599,7 +594,7 @@ export class RemoteContainerExecutionEnv {
                     stdout: markTruncated(o.text, o.droppedBytes),
                     stderr: markTruncated(e.text, e.droppedBytes),
                     exitCode: 0,
-                    detached: { shellId: adoptedShellId },
+                    detached: { shellId: adoptedShellId, ...(adoptedCause !== undefined ? { cause: adoptedCause } : {}) },
                 });
             }
             if (options?.abortSignal?.aborted && !detached) {
@@ -618,8 +613,8 @@ export class RemoteContainerExecutionEnv {
         }
         finally {
             fgSettled = true;
-            if (onDetach && detachSignal)
-                detachSignal.removeEventListener("abort", onDetach);
+            if (onDetachSignal && detachSignal)
+                detachSignal.removeEventListener("abort", onDetachSignal);
             this.activeCommands--;
             options?.abortSignal?.removeEventListener("abort", onAbort);
         }
@@ -673,7 +668,7 @@ export class RemoteContainerExecutionEnv {
                 const bc = boundCut(first);
                 throw new RemoteExecutionError(bc.code, bc.message, e);
             }
-            throw this.remoteError(e, "connect_failed");
+            throw this.remoteError(e, providerTimedOut(e) ? "timeout" : "connect_failed");
         }
         handle
             .wait()
@@ -904,7 +899,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 +907,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 +924,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);
@@ -1081,7 +1078,15 @@ export class RemoteContainerExecutionEnv {
             late.kill().then(release, (e) => {
                 this.cfg.logger?.warn?.("e2b_abandoned_start_kill_failed", { sandboxId: this.sbx?.sandboxId, pid: late.pid, error: e instanceof Error ? e.name : typeof e });
             });
-        }, release);
+        }, (e) => {
+            if (providerRefusedStart(e))
+                return release();
+            this.cfg.logger?.warn?.("e2b_start_outcome_unknown", {
+                sandboxId: this.sbx?.sandboxId,
+                error: e instanceof Error ? e.name : typeof e,
+                effect: "the command start failed without the provider refusing it — the command may be running, so this sandbox is not suspended (command_in_flight) for the rest of its life",
+            });
+        });
     }
     commandTimeoutMs(timeoutSec) {
         return timeoutSec != null ? timeoutSec * 1000 : this.cfg.timeoutMs;
@@ -1113,6 +1118,8 @@ export class RemoteContainerExecutionEnv {
                 wallTimer = setTimeout(() => {
                     if (opts.disarmed?.())
                         return;
+                    if (wall.onWall?.() === true)
+                        return;
                     reject(createCutError({ code: "timeout", message: wallCutMessage(wall.totalMs) }, opts.captured()));
                     void handle.kill().catch(() => { });
                 }, wall.leftMs);
@@ -1230,6 +1237,10 @@ function boundCut(first) {
 function providerTimedOut(e) {
     return e?.name === "TimeoutError" || /timeout|timed out/i.test(errMsg(e));
 }
+const E2B_START_REFUSALS = new Set(["InvalidArgumentError", "AuthenticationError", "NotFoundError", "RateLimitError"]);
+function providerRefusedStart(e) {
+    return e instanceof Error && E2B_START_REFUSALS.has(e.name);
+}
 function anySignal(signals) {
     const ctor = AbortSignal;
     if (typeof ctor.any === "function")