@sema-agent/server 7.138.0 → 7.140.0

package/dist/plugins/pg-session-storage.js

@@ -1,6 +1,7 @@
 import { emitLeafAdvance } from "../session-leaf-bus.js";
 import { BaseSessionStorage, StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, admitSessionPlacement, } from "@sema-agent/core";
-import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
+import { SESSION_TITLE_MAX_CHARS, sessionRowTagKey } from "../session-row.js";
+import { writeSessionRowCellsSql } from "./session-row-sql.js";
 import { escapeLike } from "./sql-escape.js";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
 import { scanEpochAnchor } from "./session-epoch-anchor.js";
@@ -16,11 +17,15 @@ import { isPgUniqueViolation } from "./sql-errors.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
 import { SESSION_META_WORKSPACE_COLUMN, decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
-import { SESSION_META_INCARNATION_COLUMN, carriedIncarnation, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { SESSION_META_INCARNATION_COLUMN, carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue } from "./session-ownership.js";
 import { selectForkRows } from "@sema-agent/core";
-import { FORK_LOG_ROW_SHAPE, forkPointOf } from "./session-fork.js";
+import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf } from "./session-fork.js";
+import { pgDriver } from "./sql-driver.js";
+import { MIRROR_ON_COMMIT_GUARD, MIRROR_ON_COMMIT_SET, SESSION_META_PLACEMENT_READ_COLUMNS, createSqlExecutionPlacementSeat, importedRowCells, lockRootAndReadClaim, placementCellFromRow, readPlacementRowStatement, sessionMetaPlacementColumnsDdl } from "./execution-placement-sql.js";
+import { SessionActiveRunError, SessionWriterPresentError } from "../execution-placement.js";
+const rowsOnClient = (conn) => async (sql, values) => (await conn.query(sql, [...values])).rows;
 const isDupKey = isPgUniqueViolation;
 function baselineQuery(text, values) {
     return { text, values, query_timeout: BASELINE_IO_DEADLINE_MS };
@@ -34,7 +39,7 @@ export const PG_SESSION_SCHEMA = [
      leaf_id     VARCHAR(64) COLLATE "C",
      leaf_seq    BIGINT       NOT NULL DEFAULT 0,
      -- title: one column, two writers (TiDB twin, same name / width; law in src/session-row.ts): the user's write
-     -- (patchSessionMeta, unconditional; null = cleared back to automatic) and the auto-titler (setTitleIfNull / probeTitle
+     -- (writeSessionRowCells, unconditional unless the PATCH carries expectedRowTag; null = cleared back to automatic) and the auto-titler (setTitleIfNull / probeTitle
      -- — fills NULL only; NULL = "untitled", the three-state probe distinguishes it from "no such session").
      title       VARCHAR(${SESSION_TITLE_MAX_CHARS}) COLLATE "C",
      -- pinned: the user's pin (TiDB twin); every list row carries it, false by default.
@@ -56,6 +61,8 @@ export const PG_SESSION_SCHEMA = [
      placed_at                   TIMESTAMPTZ(3),
      -- S-790 / S-506:会话化身(TiDB 孪生同名同义;列定义唯一属主 = src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN)。
      ${SESSION_META_INCARNATION_COLUMN.pg},
+     -- 执行放置(根会话行上这一位住客的一格:execution_* 七列)+ fork 键(fork_key)—— TiDB 孪生同名同义;列定义与语句的唯一属主 = src/plugins/execution-placement-sql.ts。
+     ${sessionMetaPlacementColumnsDdl("pg")},
      PRIMARY KEY (session_id)
    )`,
     `CREATE TABLE IF NOT EXISTS session_event (
@@ -184,10 +191,14 @@ export class PgSessionStore {
     placements = SQL_SESSION_PLACEMENTS;
     pending = new Map();
     log;
+    executionPlacement;
+    db;
     constructor(pool, opts = {}) {
         this.pool = pool;
         this.log = opts.log ?? createLogger();
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
+        this.db = pgDriver(pool);
+        this.executionPlacement = createSqlExecutionPlacementSeat(this.db);
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
@@ -341,38 +352,25 @@ export class PgSessionStore {
             const sid = ph(opts.cursor.sessionId);
             where.push(`(sm.updated_at < ${a} OR (sm.updated_at = ${b} AND sm.session_id < ${sid}))`);
         }
-        return this.selectSummaries({ where, params, limit: opts.limit });
+        return (await this.selectListRows({ where, params, limit: opts.limit })).map((a) => a.row);
     }
     async sessionSummaryOf(sessionId) {
-        const rows = await this.selectSummaries({ where: ["sm.placement_kind IS NULL", "sm.session_id = $1"], params: [sessionId], limit: 1, runSessionId: sessionId });
-        return rows[0];
+        return (await this.listRowOf(sessionId))?.row;
     }
-    async patchSessionMeta(sessionId, patch, face) {
-        const sets = [];
-        const params = [];
-        if (patch.title !== undefined) {
-            params.push(patch.title);
-            sets.push(`title = $${params.length}`);
-        }
-        if (patch.pinned !== undefined) {
-            params.push(patch.pinned);
-            sets.push(`pinned = $${params.length}`);
-        }
-        if (sets.length > 0) {
-            params.push(sessionId, face.incarnation);
-            await this.pool.query(`UPDATE session_meta SET ${sets.join(", ")} WHERE session_id = $${params.length - 1} AND incarnation = $${params.length} AND placement_kind IS NULL`, params);
-        }
-        const rows = await this.selectSummaries({ where: ["sm.placement_kind IS NULL", "sm.session_id = $1", "sm.incarnation = $2"], params: [sessionId, face.incarnation], limit: 1, runSessionId: sessionId });
-        return rows[0];
+    async listRowOf(sessionId) {
+        return (await this.selectListRows({ where: ["sm.placement_kind IS NULL", "sm.session_id = $1"], params: [sessionId], limit: 1, runSessionId: sessionId }))[0];
     }
-    async selectSummaries(q) {
+    async writeSessionRowCells(sessionId, cells, how) {
+        return writeSessionRowCellsSql(this.db, sessionId, cells, how, (id) => this.listRowOf(id));
+    }
+    async selectListRows(q) {
         const params = [...q.params];
         const ph = (v) => {
             params.push(v);
             return `$${params.length}`;
         };
         const runWhere = q.runSessionId !== undefined ? ` WHERE session_id = ${ph(q.runSessionId)}` : "";
-        const sql = "SELECT sm.session_id, sm.owner, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, sm.pinned, " +
+        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, sm.pinned, " +
             "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
             "FROM session_meta sm " +
             "LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run" + runWhere + " GROUP BY session_id) r ON r.session_id = sm.session_id " +
@@ -383,9 +381,14 @@ export class PgSessionStore {
         const res = await this.pool.query(sql, params);
         return res.rows.map((r) => {
             const runId = r.last_task_run_id;
-            return {
-                sessionId: String(r.session_id),
-                owner: r.owner ?? null,
+            const sessionId = String(r.session_id);
+            const owner = r.owner ?? null;
+            const incarnation = incarnationFromCell(sessionId, r.incarnation, "absent");
+            const title = r.title ?? null;
+            const pinned = r.pinned === true;
+            const row = {
+                sessionId,
+                owner,
                 lastActivityAt: r.last_activity instanceof Date ? r.last_activity.toISOString() : String(r.last_activity),
                 firstActivityAt: r.first_activity instanceof Date ? r.first_activity.toISOString() : String(r.first_activity),
                 runCount: Number(r.run_count),
@@ -393,9 +396,11 @@ export class PgSessionStore {
                 lastStatus: r.status == null ? "" : String(r.status),
                 lastRunId: r.last_run_id ?? null,
                 ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
-                title: r.title ?? null,
-                pinned: r.pinned === true,
+                title,
+                pinned,
+                ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
             };
+            return { row, occupant: { owner, incarnation } };
         });
     }
     async probeTitle(sessionId) {
@@ -431,6 +436,17 @@ export class PgSessionStore {
         await this.pool.query("UPDATE session_meta SET workspace = $1::jsonb WHERE session_id = $2 AND incarnation = $3", [encodeSessionWorkspaceCell(workspace, pgSafeJsonStringify, sessionId), sessionId, incarnation]);
     }
     async fork(sourceId, owner) {
+        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner);
+    }
+    async forkTo(sourceId, owner, target) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const out = await this.forkToOnce(sourceId, owner, target);
+            if (out !== "unsettled")
+                return out;
+        }
+        throw new ForkTargetUnsettledError(target.id);
+    }
+    async forkToOnce(sourceId, owner, target) {
         const metaRes = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = $1", [sourceId]);
         if (!metaRes.rows[0])
             return null;
@@ -442,19 +458,29 @@ export class PgSessionStore {
         const point = await forkPointOf(storage);
         const eventRes = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("pg", "payload")}, ts FROM session_event WHERE session_id = $1 ORDER BY seq ASC`, [sourceId]);
         const { rows, leafId: forkLeafId } = selectForkRows(eventRes.rows, leafId, point, FORK_LOG_ROW_SHAPE);
-        const newId = uuidv7();
         const now = new Date();
         const conn = await this.pool.connect();
+        let collided = false;
         try {
             await conn.query("BEGIN");
-            for (let seq = 0; seq < rows.length; seq++) {
-                const r = rows[seq];
-                const payload = String(r.payload);
-                await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
+            try {
+                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, fork_key) VALUES ($1,$2,$3,$4,$5,$6,$7,$8)", [target.id, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation(), target.key ?? null]);
             }
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7)", [newId, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation()]);
-            await conn.query("COMMIT");
-            return newId;
+            catch (err) {
+                if (!isDupKey(err))
+                    throw err;
+                collided = true;
+            }
+            if (!collided) {
+                for (let seq = 0; seq < rows.length; seq++) {
+                    const r = rows[seq];
+                    const payload = String(r.payload);
+                    await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [target.id, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
+                }
+                await conn.query("COMMIT");
+                return { outcome: "created", id: target.id };
+            }
+            await conn.query("ROLLBACK");
         }
         catch (err) {
             try {
@@ -467,6 +493,9 @@ export class PgSessionStore {
         finally {
             conn.release();
         }
+        const existing = await this.pool.query("SELECT owner, fork_key FROM session_meta WHERE session_id = $1", [target.id]);
+        const row = existing.rows[0];
+        return row === undefined ? "unsettled" : classifyForkTarget(target, { owner: row.owner ?? null, forkKey: row.fork_key ?? null }, forkOwner);
     }
     async exportEntries(sessionId) {
         const metaRes = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = $1", [sessionId]);
@@ -506,7 +535,7 @@ export class PgSessionStore {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            await this.insertValidatedLog(conn, sessionId, owner, validated, mintSessionIncarnation());
+            await this.writeImportedLog(conn, sessionId, owner, validated, { incarnation: mintSessionIncarnation(), forkKey: null }, "create");
             await conn.query("COMMIT");
         }
         catch (err) {
@@ -515,7 +544,7 @@ export class PgSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError)
+            if (err instanceof SessionError || err instanceof SessionActiveRunError)
                 throw err;
             throw new SessionError("storage", `import of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -529,14 +558,21 @@ export class PgSessionStore {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            const placedRes = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
-            if (placedRes.rows[0]?.placement_kind != null) {
+            const placedRes = await conn.query(`SELECT ${SESSION_META_PLACEMENT_READ_COLUMNS}, fork_key FROM session_meta WHERE session_id = $1 FOR UPDATE`, [sessionId]);
+            const prior = placedRes.rows[0];
+            if (prior?.placement_kind != null) {
                 await conn.query("ROLLBACK");
-                throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placedRes.rows[0].placement_kind} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
+                throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${String(prior.placement_kind)} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
             }
-            await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
-            await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 AND placement_kind IS NULL", [sessionId, owner]);
-            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(sessionId, placedRes.rows[0]));
+            const purged = await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 AND placement_kind IS NULL", [sessionId, owner]);
+            const swapped = (purged.rowCount ?? 0) === 1 ? prior : undefined;
+            const cells = carriedRowCells(sessionId, swapped === undefined ? undefined : { incarnation: swapped.incarnation, forkKey: swapped.fork_key });
+            const priorCell = swapped === undefined ? undefined : placementCellFromRow(sessionId, swapped);
+            if (priorCell?.role === "writer") {
+                await conn.query("ROLLBACK");
+                throw new SessionWriterPresentError(sessionId, priorCell.lane);
+            }
+            await this.writeImportedLog(conn, sessionId, owner, validated, cells, "replace");
             await conn.query("COMMIT");
         }
         catch (err) {
@@ -545,7 +581,7 @@ export class PgSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError)
+            if (err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
                 throw err;
             throw new SessionError("storage", `replace of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -553,16 +589,29 @@ export class PgSessionStore {
             conn.release();
         }
     }
-    async insertValidatedLog(conn, sessionId, owner, validated, incarnation) {
+    async writeImportedLog(conn, sessionId, owner, validated, cells, mode) {
         let leafId = null;
         for (const e of validated)
             leafId = leafIdAfterEntry(e);
         const now = new Date();
+        const imported = importedRowCells(cells.forkKey);
+        await conn.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${imported.columns}) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)` +
+            (mode === "create" ? " ON CONFLICT (session_id) DO NOTHING" : ""), [sessionId, owner, now, now, leafId, validated.length, cells.incarnation, ...imported.values]);
+        if (mode === "create") {
+            const held = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
+            if (String(held.rows[0]?.incarnation) !== cells.incarnation) {
+                throw new SessionError("storage", `import of session ${sessionId} failed`, new Error(`session ${sessionId} already exists — importEntries only creates a session (replaceEntries rewrites one); nothing was written`));
+            }
+        }
+        const claim = await lockRootAndReadClaim(rowsOnClient(conn), "pg", sessionId);
+        if (claim.activeTaskId !== null)
+            throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+        if (mode === "replace")
+            await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
         for (let seq = 0; seq < validated.length; seq++) {
             const e = validated[seq];
             await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [sessionId, seq, e.id, e.parentId ?? null, e.type, pgSafeJsonStringify(e), new Date(e.timestamp)]);
         }
-        await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7)", [sessionId, owner, now, now, leafId, validated.length, incarnation]);
     }
     beginImportStaging(realSessionId, token) {
         return new PgStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
@@ -587,6 +636,11 @@ export class PgSessionStore {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
+            const claim = await lockRootAndReadClaim(rowsOnClient(conn), "pg", sessionId);
+            if (claim.activeTaskId !== null) {
+                await conn.query("ROLLBACK");
+                throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+            }
             const metaRes = await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2", [sessionId, owner]);
             if ((metaRes.rowCount ?? 0) > 0)
                 await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
@@ -666,6 +720,11 @@ class PgStagingHandle {
                     throw new StagedCommitOwnerChangedError(this.realSessionId);
                 }
             }
+            const claim = await lockRootAndReadClaim(rowsOnClient(conn), "pg", this.realSessionId);
+            if (claim.activeTaskId !== null) {
+                await conn.query("ROLLBACK");
+                throw new SessionActiveRunError(this.realSessionId, claim.activeTaskId);
+            }
             const staged = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const dst = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
             const dstMeta = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1", [this.realSessionId]);
@@ -698,7 +757,16 @@ class PgStagingHandle {
             let leafId = null;
             if (lastRes.rows[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRes.rows[0].payload, this.realSessionId, "last staged row"));
-            await conn.query("UPDATE session_meta SET owner = $1, updated_at = $2, leaf_id = $3, leaf_seq = $4 WHERE session_id = $5", [owner, now, leafId, srcIds.length, this.realSessionId]);
+            const settle = await conn.query(`UPDATE session_meta SET owner = $1, updated_at = $2, leaf_id = $3, leaf_seq = $4, ${MIRROR_ON_COMMIT_SET} WHERE session_id = $5 AND ${MIRROR_ON_COMMIT_GUARD}`, [owner, now, leafId, srcIds.length, this.realSessionId]);
+            if ((settle.rowCount ?? 0) !== 1) {
+                const locked = readPlacementRowStatement("pg", this.realSessionId, { lock: true });
+                const lockedRow = (await conn.query(locked.text, [...locked.values])).rows[0];
+                const cell = lockedRow === undefined ? undefined : placementCellFromRow(this.realSessionId, lockedRow);
+                await conn.query("ROLLBACK");
+                if (cell?.role === "writer")
+                    throw new SessionWriterPresentError(this.realSessionId, cell.lane);
+                throw new SessionError("storage", `staged commit for ${this.realSessionId}: the commit point matched no row under a held row lock and the row is not a writer — refusing to guess`);
+            }
             const afterMeta = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = $1", [this.realSessionId]);
             if (afterMeta.rows[0]?.placement_kind != null) {
                 await conn.query("ROLLBACK");
@@ -713,7 +781,7 @@ class PgStagingHandle {
                 await conn.query("ROLLBACK");
             }
             catch { }
-            if (err instanceof SyncConflictError || err instanceof SessionError)
+            if (err instanceof SyncConflictError || err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
                 throw err;
             throw new SessionError("storage", `staged commit for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
         }

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

@@ -52,23 +52,8 @@ export interface AdbEnvDeps {
  *  **结构**信号;adb 的 shell v2 没有等价物,所以这里只能靠标记词,**这条臂就把话说在这里**。 */
 export declare function isAdbTransportLost(stderr: string): boolean;
 export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
-    /**
-     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
-     * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,在设备 shell 里解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
-     * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
-     * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
-     * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
-     * 布尔字面量零影响(四键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
-     * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
-     * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
-     */
-    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在设备上(adb shell),不在本进程所在的进程表。 */
-    readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
-        sharesProcessTable: boolean;
-    };
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
+    readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
     cwd: string;
     private connected;
     /** 🔴 拆除是**终态**(2026-07-25 补齐:此前本适配器是同族里唯一没有这个概念的一条腿)。
@@ -80,10 +65,13 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     private destroyed;
     /** 在飞的那一次懒连接(单飞记忆)——见 {@link ensureConnected}。settle 即清,**不缓存败诺**。 */
     private connectPromise?;
-    /** core `ExecutionEnv.homeDir`([ref]):设备 shell 里执行用户的 home —— 声明胜,否则首连时 `adb shell` 实测的 `$HOME`(Android 常为 `/` 或 `/data/local/tmp` 一类,读到什么填什么,绝对即可),见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    /** core `ExecutionEnv.homeDir`([ref]):设备 shell 里执行用户的 home —— 声明在场 ⇒ 声明(首连时与设备 shell 的 `$HOME` 对证过),否则首连时 `adb shell` 实测的 `$HOME`(Android 常为 `/` 或 `/data/local/tmp` 一类,读到什么填什么,绝对即可),见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
     get homeDir(): string | undefined;
-    /** 家目录的座(声明胜 · 否则首连时实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道**不对证**声明:Android 没有 POSIX 登录家目录,声明是运维的断言,照单全收。 */
+    /** 家目录的座(声明在场 ⇒ 首连时对证 · 否则首连时实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。设备 shell 答得出 `$HOME`,命令里的 `~` / `$HOME` 展开的就是它 ——
+     *  声明与它不一致时规则守的是声明那个目录,所以与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
+    /** 家目录:设备答了而与声明不一致(或答的不是绝对路径)⇒ 这只环境的拒,记一次、此后每次连接原样回它(同一台设备同一个答案:不重试、不再问)。 */
+    private homeRefusal?;
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 Android 设备的 shell 里(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -175,8 +163,19 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
         maxLines?: number;
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
+    /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;父目录与私有暂存目录由编排的准备那一步建):
+     *  上传 = `adb 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`,目标未碰)。
+     *  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 把它带到设备上,与修前同)。 */
+    private push;
     private posixFsInst?;
     private get posixFs();
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;