@sema-agent/server 7.137.0 → 7.139.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";
@@ -14,11 +15,17 @@ import { createLogger } from "../observability/logger.js";
 import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "./sql-errors.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
-import { MANAGED_RETENTION } from "./retention-store-sql.js";
-import { SESSION_META_INCARNATION_COLUMN, carriedIncarnation, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.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, carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue } from "./session-ownership.js";
-import { forkCopyOf, forkPointOf } from "./session-fork.js";
+import { selectForkRows } from "@sema-agent/core";
+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 };
@@ -32,13 +39,15 @@ 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.
      pinned      BOOLEAN      NOT NULL DEFAULT FALSE,
      -- instruction_source(S-690):换源通告的基线 —— TiDB 孪生同名同宽,三态读法(NULL / '' / 链成员相对路径)见那里的列注。
      instruction_source VARCHAR(64) COLLATE "C",
+     -- workspace:本会话上一条腿自己的最后一帧 workspace_changed —— TiDB 孪生同名同义(列注与唯一属主见那里:src/plugins/session-workspace-cell.ts)。
+     ${SESSION_META_WORKSPACE_COLUMN.pg},
      -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组(TiDB 孪生同名同宽,
      -- 语义与六条义务见 src/plugins/session-placement.ts 顶注):创建时一次落行、first-write 不可变;
      -- placement_kind 在场 ⇒ 住在 placement 分区(不上宿主枚举 / claim 形 acquire 恒拒 / release=真删除 /
@@ -52,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 (
@@ -176,13 +187,18 @@ export class PgSessionStorage extends BaseSessionStorage {
 }
 export class PgSessionStore {
     pool;
-    retention = MANAGED_RETENTION;
+    retention;
     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) {
@@ -336,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 " +
@@ -378,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),
@@ -388,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) {
@@ -417,7 +427,26 @@ export class PgSessionStore {
             await this.pool.query(baselineQuery("UPDATE session_meta SET instruction_source = $1 WHERE session_id = $2 AND instruction_source IS NULL", [next, sessionId]));
         }
     }
+    async readSessionWorkspace(sessionId) {
+        const res = await this.pool.query(`SELECT ${jsonColumnText("pg", "workspace")} FROM session_meta WHERE session_id = $1`, [sessionId]);
+        const row = res.rows[0];
+        return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
+    }
+    async recordSessionWorkspace(sessionId, incarnation, workspace) {
+        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;
@@ -428,20 +457,30 @@ export class PgSessionStore {
             return null;
         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 } = forkCopyOf(eventRes.rows, leafId, point);
-        const newId = uuidv7();
+        const { rows, leafId: forkLeafId } = selectForkRows(eventRes.rows, leafId, point, FORK_LOG_ROW_SHAPE);
         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 {
@@ -454,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]);
@@ -493,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) {
@@ -502,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);
         }
@@ -516,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], owner));
+            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) {
@@ -532,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);
         }
@@ -540,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));
@@ -574,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]);
@@ -653,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]);
@@ -685,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");
@@ -700,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

@@ -58,14 +58,21 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
      * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
      * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
-     * 布尔字面量零影响(三键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
+     * 布尔字面量零影响(四键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
      * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
      * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
      */
+    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在设备上(adb shell),不在本进程所在的进程表。 */
+    /** 能力块(引擎 [ref],八键必填、各键只经引擎读器读):`hostLocalPaths` = 这条车道答出的路径是不是本进程所在机器上的文件;`externalContentTarget` = 产出是否来自部署信任边界之外;`io` = 文件与 shell 两面真到达目标;`keepsReadFloor` = 是否守住读拒表的字节地板(本车道不守 ⇒ 读拒表非空的 run 被告知,部署要求地板时准备期拒)。 */
     readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
+        isolation: false;
+        suspendable: false;
+        canonicalPathAuthoritative: true;
+        sharesProcessTable: false;
+        hostLocalPaths: false;
+        externalContentTarget: false;
+        io: true;
+        keepsReadFloor: false;
     };
     cwd: string;
     private connected;
@@ -173,8 +180,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>>;

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

@@ -4,9 +4,10 @@ import fs from "node:fs/promises";
 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 { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
+import { appendFileStaged, rewriteAppend, buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace, writeFileStaged } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
+import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -27,7 +28,7 @@ export function isAdbTransportLost(stderr) {
     return /device offline|device '.*' not found|no devices\/emulators found|connection reset|protocol fault|device disconnected/i.test(stderr);
 }
 export class RemoteAdbExecutionEnv {
-    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true };
+    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false, hostLocalPaths: false, externalContentTarget: false, io: true, keepsReadFloor: false };
     cwd;
     connected = false;
     destroyed = false;
@@ -341,57 +342,46 @@ export class RemoteAdbExecutionEnv {
             lines = lines.slice(0, options.maxLines);
         return ok(lines);
     }
+    stagedLane(content) {
+        return { upload: (dest, signal) => this.push(content, dest, signal), run: (cmd, signal) => this.fsExec(cmd, signal) };
+    }
     async writeFile(p, content, abortSignal) {
+        const gated = await this.fsGate(p);
+        if (gated)
+            return gated;
+        return writeFileStaged(this.stagedLane(content), this.resolve(p), abortSignal);
+    }
+    async appendFile(p, content, abortSignal) {
         const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
-        const dir = path.posix.dirname(abs);
-        if (dir && dir !== "." && dir !== "/") {
-            const mk = await this.fsExec(`mkdir -p ${shellQuote(dir)}`, abortSignal);
-            if (!mk.ok)
-                return { ok: false, error: fileErrorFromExec(mk.error, dir) };
-            if (mk.value.exitCode !== 0)
-                return { ok: false, error: new FileError("unknown", mk.value.stderr.trim() || `mkdir -p failed for ${dir}`, dir) };
-        }
-        let local;
+        return appendFileStaged(this.stagedLane(content), abs, abortSignal, (ctx) => rewriteAppend((signal) => this.readBinaryFile(abs, signal), (bytes, signal) => this.push(bytes, abs, signal), content, ctx));
+    }
+    async push(content, dest, abortSignal) {
+        let localDir;
         try {
-            local = path.join(os.tmpdir(), `adb-push-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+            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, abs], { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs });
+            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, abs) };
+                return { ok: false, error: fileErrorFromExec(r.error, dest) };
             const out = `${r.value.stdout} ${r.value.stderr}`;
             if (/permission denied/i.test(out))
-                return { ok: false, error: new FileError("permission_denied", out.trim(), abs) };
+                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 ${abs}`, abs) };
+                return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `adb push failed for ${dest}`, dest) };
             return ok(undefined);
         }
         catch (e) {
-            return { ok: false, error: new FileError("unknown", e instanceof Error ? e.message : String(e), abs) };
+            return { ok: false, error: new FileError("unknown", e instanceof Error ? e.message : String(e), dest) };
         }
         finally {
-            if (local)
-                await fs.rm(local, { force: true }).catch(() => { });
+            if (localDir)
+                await fs.rm(localDir, { recursive: true, force: true }).catch(() => { });
         }
     }
-    async appendFile(p, content, abortSignal) {
-        const abs = this.resolve(p);
-        const existing = await this.readBinaryFile(abs, abortSignal);
-        let base;
-        if (existing.ok)
-            base = existing.value;
-        else if (existing.error.code === "not_found")
-            base = new Uint8Array(0);
-        else
-            return existing;
-        const add = typeof content === "string" ? new TextEncoder().encode(content) : content;
-        const merged = new Uint8Array(base.length + add.length);
-        merged.set(base, 0);
-        merged.set(add, base.length);
-        return this.writeFile(abs, merged, abortSignal);
-    }
     posixFsInst;
     get posixFs() {
         return (this.posixFsInst ??= createPosixShellFs({
@@ -451,23 +441,44 @@ export class RemoteAdbExecutionEnv {
             const outBufs = [];
             const outTail = binary ? undefined : new RollingTailBuffer();
             const errBuf = new RollingTailBuffer();
-            const finish = (r) => {
+            const recordStderr = (bytes) => {
+                if (bytes.length > 0)
+                    errBuf.push(bytes);
+            };
+            const emitStderr = (bytes) => {
+                if (bytes.length > 0)
+                    opts?.onStderr?.(bytes.toString());
+            };
+            const takeStderr = (bytes) => {
+                recordStderr(bytes);
+                emitStderr(bytes);
+            };
+            const heldStderr = () => opts?.stderrFilter?.endStderr();
+            const captured = () => {
+                const held = heldStderr();
+                if (held)
+                    recordStderr(held);
+                return buildCapturedOutput(outTail, errBuf);
+            };
+            const finish = (outcome) => {
                 if (settled)
-                    return;
+                    return false;
                 settled = true;
+                const r = outcome();
                 clearTimeout(timer);
                 opts?.signal?.removeEventListener("abort", onAbort);
                 resolve(r);
+                return true;
             };
             const timeoutMs = opts?.timeoutMs ?? this.cfg.commandTimeoutMs;
-            const timer = setTimeout(() => {
-                killGrace();
-                finish({ ok: false, error: new ExecutionError("timeout", `adb ${args[0]} exceeded ${timeoutMs}ms`) });
-            }, timeoutMs);
-            const onAbort = () => {
-                killGrace();
-                finish({ ok: false, error: new ExecutionError("aborted", "adb command aborted") });
+            const cut = (c) => {
+                finish(() => {
+                    killGrace();
+                    return { ok: false, error: createCutError(c, captured()) };
+                });
             };
+            const timer = setTimeout(() => cut({ code: "timeout", message: `adb ${args[0]} exceeded ${timeoutMs}ms` }), timeoutMs);
+            const onAbort = () => cut({ code: "aborted", message: "adb command aborted" });
             if (opts?.signal) {
                 if (opts.signal.aborted)
                     return onAbort();
@@ -480,30 +491,27 @@ export class RemoteAdbExecutionEnv {
                     outTail.push(d);
                 opts?.onStdout?.(d.toString());
             });
-            const takeStderr = (bytes) => {
-                if (bytes.length === 0)
-                    return;
-                errBuf.push(bytes);
-                opts?.onStderr?.(bytes.toString());
-            };
             child.stderr.on("data", (d) => takeStderr(opts?.stderrFilter ? opts.stderrFilter.filterStderr(d) : d));
-            child.on("error", (e) => finish({ ok: false, error: new ExecutionError("spawn_error", `adb spawn failed (is '${this.cfg.adbPath}' installed?): ${e.message}`, e) }));
+            child.on("error", (e) => finish(() => ({ ok: false, error: new ExecutionError("spawn_error", `adb spawn failed (is '${this.cfg.adbPath}' installed?): ${e.message}`, e) })));
             child.on("close", (code, signal) => {
                 if (forceSettleTimer)
                     clearTimeout(forceSettleTimer);
-                if (opts?.stderrFilter)
-                    takeStderr(opts.stderrFilter.endStderr());
-                const err = errBuf.result();
-                const stderr = markTruncated(err.text, err.droppedBytes);
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0);
-                if (binary) {
-                    const stdoutBytes = Buffer.concat(outBufs);
-                    finish(ok({ stdout: stdoutBytes.toString("utf8"), stderr, exitCode, stdoutBytes: new Uint8Array(stdoutBytes) }));
-                }
-                else {
+                const held = heldStderr();
+                const won = finish(() => {
+                    if (held)
+                        recordStderr(held);
+                    const err = errBuf.result();
+                    const stderr = markTruncated(err.text, err.droppedBytes);
+                    if (binary) {
+                        const stdoutBytes = Buffer.concat(outBufs);
+                        return ok({ stdout: stdoutBytes.toString("utf8"), stderr, exitCode, stdoutBytes: new Uint8Array(stdoutBytes) });
+                    }
                     const out = outTail.result();
-                    finish(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr, exitCode }));
-                }
+                    return ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr, exitCode });
+                });
+                if (won && held)
+                    emitStderr(held);
             });
         });
     }