@sema-agent/server 7.138.0 → 7.139.0

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

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, isValidDurableScope, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, EMPTY_DURABLE_RULE_PARTITION, PERMISSION_RULES_LATER_GRAMMAR_CODE, SESSION_RULES_GRAMMAR, readRuleGrammarStamp, readRuleOwner, principalNameOf, readRuleOffer2, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
+import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { ensureIndexes } from "./ensure-index.js";
 import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, SqlJsonColumnError } from "./sql-json-column.js";
@@ -144,8 +145,8 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     -- version:**数据格式版本**(= core \`RuleApprovalRecord.schema\`,本形恒 4 —— core 7.9.0 #625 由 3 升,
     -- 代码里的单点是 RULE_APPROVAL_RECORD_SCHEMA;OCC 守卫另在 rev,两轴禁混,schema-naming 门③ 白名单
     -- 登记)。读侧对非 4 的行(含上一形的 3)交还 design/375 §4.5 的
-    -- StaleRuleApprovalRecord 信封(identity 键 only)—— 本仓 SCHEMA POLICY 是删表重建,重建后的表
-    -- 不该有这种行,这一臂是「未来再换形」的防御位,绝不静默 widen 成一条本形担保不了的记录。
+    -- StaleRuleApprovalRecord 信封(identity 键 only)—— 这一臂是「未来再换形」的防御位,
+    -- 绝不静默 widen 成一条本形担保不了的记录。
     version INT NOT NULL,
     -- offers_json:core \`RuleOffer2[]\`(design/375 §4.1)—— 按 index 引用 candidates 的 OPTION 结构,
     -- **绝不存规则文本副本**(显示三元组由 core \`ruleOffersOfRecord\` 从候选文本投影;存副本=造一个
@@ -240,13 +241,11 @@ export async function assertPermissionRuleApprovalSchema(query, dialect) {
             `#340 card-edit columns (command / edited_json) and the design/375 record-form columns ` +
             `(version / offers_json / selected_offer): the approval record now stores its OPTION structure and the ` +
             `chosen offer, and the store refuses to read rows whose record-form version it cannot vouch for. ` +
-            `This repository ships no ` +
-            `ALTER TABLE migrations, so the table must be recreated: run \`DROP TABLE ${PERMISSION_RULE_APPROVAL_TABLE};\` on the ` +
-            `${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart — the schema is recreated at boot. ` +
-            `The cost is bounded: this table holds pending/settled approval RECORDS (the audit trail of who said yes to which ` +
-            `rule), not the rules themselves — persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched. Dropping it ` +
-            `loses in-flight CC-import previews (re-runnable) and the historical record trail. ` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+            `This table holds pending/settled approval RECORDS (the audit trail of who said yes to which ` +
+            `rule), not the rules themselves — persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched; ` +
+            `an in-place ALTER keeps the record trail.\n` +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+            (await describeProbedTableDrift(query, dialect, [PERMISSION_RULE_APPROVAL_TABLE])));
     }
 }
 export async function assertPermissionRuleTicketSchema(query, dialect) {
@@ -260,12 +259,10 @@ export async function assertPermissionRuleTicketSchema(query, dialect) {
             `the #265 A7 three-state redemption columns (MINTED → CLAIMED → SETTLED, the claim generation that fences a superseded ` +
             `claimant, and the lane binding that keeps cc-import and local-import tickets from being interchangeable): without them a ` +
             `local-import ticket can be claimed but never settled, so a redemption that already wrote rules to the store answers its ` +
-            `owner with a retry-later it can never satisfy. This repository ships no ALTER TABLE migrations, so the table must be recreated: run ` +
-            `\`DROP TABLE ${PERMISSION_RULE_TICKET_TABLE};\` on the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and ` +
-            `restart — the schema is recreated at boot. The cost is bounded and small: this table holds minute-TTL single-use import ` +
-            `tickets (a governance transient that dies on expiry), so dropping it only makes anyone mid-preview re-run prepare; ` +
-            `persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched. ` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+            `owner with a retry-later it can never satisfy. This table holds minute-TTL single-use import ` +
+            `tickets (a governance transient that dies on expiry); persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched.\n` +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+            (await describeProbedTableDrift(query, dialect, [PERMISSION_RULE_TICKET_TABLE])));
     }
 }
 export const PERMISSION_RULE_INDEXES = [
@@ -537,7 +534,7 @@ class SqlDurableRulePartition {
         },
         apply: async (delta, opts) => {
             if (delta.kind === "sync-join") {
-                throw new Error("the SQL permission-rule backend does not implement the sync-join landing pipeline (core's applySyncJoin is not on the package's public export face); " +
+                throw new Error("the SQL permission-rule backend does not implement the sync-join landing arm; " +
                     "no sync client is wired in this deployment, so this arm has no caller — see permission-rule-store-sql.ts header");
             }
             assertWriteDeltaScopeDurable(delta);

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

@@ -10,9 +10,13 @@
  * (run-store + checkpoint); the remaining tidb-* tables are added as their PG stores land (tracked).
  *
  * ─────────────────────────────── SCHEMA POLICY (clay 裁 2026-07-26) ───────────────────────────────
- * THIS CODE IS THE SINGLE SOURCE OF TRUTH for the PG schema. The stack is not yet in production and runs
- * against a single local operator's database, so a schema change is DROP-AND-RECREATE (drop the database,
- * boot, `ensurePgSchema` rebuilds it) — NOT an in-place migration.
+ * THIS CODE IS THE SINGLE SOURCE OF TRUTH for the PG schema, and there is NO in-place migration seam in this statement array: a database that
+ * lags behind the code is refused at boot with the exact `ALTER TABLE … ADD COLUMN …` statements printed, and the
+ * deployer runs them themselves: the column-set check and its refusal never alter a database. The only DDL this
+ * process runs by itself on a table that already exists is idempotent index creation (`ensureIndex`: indexes only,
+ * never a column) and the registered one-time migrations (each has a window and a registry row in
+ * `one-time-migrations.ts`) — adding / changing / renaming a column or dropping a table is done by those migrations
+ * and by nothing else.
  *
  * Consequence, and it is a hard rule: **do NOT add new `ALTER TABLE` seams here.** Every column / default /
  * constraint change is folded into its own `CREATE TABLE`, and this array stays pure `CREATE TABLE` +

package/dist/plugins/pg-session-storage.d.ts

@@ -1,21 +1,22 @@
 import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
-import { type SessionRowPatch } from "../session-row.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type OrphanOwnerLog } from "../delegated-session-owner.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import type { SessionWorkspace } from "../session-workspace.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type SessionFace } from "../session-incarnation.js";
 import { type IndexSpec } from "./ensure-index.js";
+import { type ForkTarget, type ForkToOutcome } from "./session-fork.js";
+import { type ExecutionPlacementSeat } from "../execution-placement.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
  * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), inline `KEY`/`UNIQUE KEY`→separate CREATE INDEX (UNIQUE for uq_session_event_entry).
  *
- * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
- * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
+ * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, there is no in-place
+ * migration, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
  */
 export declare const PG_SESSION_SCHEMA: string[];
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
@@ -70,6 +71,10 @@ export declare class PgSessionStore implements SessionStore {
     private readonly pending;
     /** 委派子代孤行那一行 warn 的去处(TiDB 孪生同格)。 */
     private readonly log;
+    /** 执行席(TiDB 孪生同格;实现与语句的唯一属主 = `execution-placement-sql.ts`,本店只交自己的池)。 */
+    readonly executionPlacement: ExecutionPlacementSeat;
+    /** 本店的池包成的 SqlDriver(TiDB 孪生同格):执行席与会话行格写原语的事务都经它借连接。 */
+    private readonly db;
     constructor(pool: Pool, opts?: {
         readonly log?: OrphanOwnerLog;
         readonly retention?: RetentionDeclaration;
@@ -121,13 +126,14 @@ export declare class PgSessionStore implements SessionStore {
     }): Promise<SessionSummary[]>;
     /** @see TiDBSessionStore.sessionSummaryOf — the PG twin (same projection, run-preview subqueries scoped to the id). */
     sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
-    /** @see TiDBSessionStore.patchSessionMeta — the PG twin (the only writer of a user-set title / pin; the UPDATE and the read-back
-     *  both conditioned on the verified occupant's incarnation; `updated_at` untouched). The read-back is a second statement, not a
-     *  `RETURNING` CTE: the outer SELECT of a data-modifying CTE reads the pre-UPDATE snapshot of `session_meta`. */
-    patchSessionMeta(sessionId: string, patch: SessionRowPatch, face: SessionFace): Promise<SessionSummary | undefined>;
-    /** @see TiDBSessionStore.selectSummaries — the PG twin. `where` already carries `$n` placeholders numbered over `params`;
+    /** @see TiDBSessionStore.listRowOf — the PG twin. */
+    private listRowOf;
+    /** @see TiDBSessionStore.writeSessionRowCells — the PG twin (the same SQL half, `session-row-sql.ts`; only the statement text differs). */
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
+    /** @see TiDBSessionStore.selectListRows — the PG twin. `where` already carries `$n` placeholders numbered over `params`;
      *  the run scope and the LIMIT take the next numbers (PG binds by number, so text order does not matter). */
-    private selectSummaries;
+    private selectListRows;
     /** @see TiDBSessionStore.probeTitle — the PG twin. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
     /** @see TiDBSessionStore.setTitleIfNull — the PG twin (the auto-titler's NULL-only write). */
@@ -143,9 +149,13 @@ export declare class PgSessionStore implements SessionStore {
     /** @see TiDBSessionStore.recordSessionWorkspace — the PG twin (whole-cell overwrite fenced to the occupant; `pgSafeJsonStringify` + `::jsonb`, like every PG JSON write;
      *  the general query surface — the pool-wide `DB_QUERY_TIMEOUT_MS` server-side `statement_timeout` bounds it, no per-call client timer). */
     recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
-    /** @see TiDBSessionStore.fork — copy the WHOLE durable history (full session_event log, compaction floor bypassed,
-     *  NOT wake's bounded tail) to a NEW uuidv7 session, re-seq dense from 0, ids/parents verbatim, owner=caller. */
+    /** @see TiDBSessionStore.fork — core 契约 `fork(sourceId, owner?)` = {@link forkTo} 的投影(新铸 uuidv7 目标,`forkByFreshId`;三店同一只)。 */
     fork(sourceId: string, owner?: string | null): Promise<string | null>;
+    /** @see TiDBSessionStore.forkTo — fork 续写的店契约(PG 孪生逐字同义):目标行 meta 先、主键排他;撞已在 ⇒ 回滚后在新视图读目标按属主与 fork 键分类;
+     *  读不到 ⇒ 整笔重跑一次,再不行 ⇒ {@link ForkTargetUnsettledError}。 */
+    forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
+    /** @see TiDBSessionStore.forkToOnce — 一次尝试(PG 孪生):拷**整份**持久日志(压缩地板绕过,不是 wake 的有界尾),seq 从 0 重铸稠密,id / 父 / 载荷原样。 */
+    private forkToOnce;
     /** @see TiDBSessionStore.exportEntries — 2c session-sync EXPORT: the FULL durable session_event log (compaction floor
      *  bypassed, NOT wake's tail) as `SessionTreeEntry[]`, oldest-first, verbatim. null if the source is unknown. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
@@ -163,18 +173,19 @@ export declare class PgSessionStore implements SessionStore {
         batchSize?: number;
     }): Promise<AsyncIterable<SessionTreeEntry> | null>;
     /** @see TiDBSessionStore.importEntries — 2c session-sync IMPORT: core `validateEntriesForImport` gate FIRST (fail-closed),
-     *  then persist its verbatim output (re-seq dense from 0, ids/parents/payload/ts unchanged) in ONE txn with
-     *  session_meta LAST as the commit point; owner = the RE-STAMPED authenticated principal (never the bundle's). */
+     *  then persist its verbatim output (re-seq dense from 0, ids/parents/payload/ts unchanged) in ONE txn, **lock-or-create, meta first**
+     *  (读写序律:占行 → 锁行判是不是本次占下的 → 锁定读认领 → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
     /** @see TiDBSessionStore.replaceEntries — 2c (§7/§8) IDEMPOTENT REPLACE: core `validateEntriesForImport` gate FIRST
-     *  (fail-closed), then DELETE events + the owner-guarded meta delete (`owner IS NOT DISTINCT FROM $n` = the PG `<=>`,
-     *  defense-in-depth), then re-insert via the SHARED body (entries + session_meta LAST as the commit point), ALL in
+     *  (fail-closed), then the owner-guarded meta delete (`owner IS NOT DISTINCT FROM $n` = the PG `<=>`, defense-in-depth), then the
+     *  SHARED body (session_meta first, the in-txn claim read, then the old events out and the new ones in), ALL in
      *  ONE txn. Safe to run OVER an existing session (fast-forward / §8 retry) — unlike importEntries' fresh-only INSERT. */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** @see TiDBSessionStore.insertValidatedLog — shared insert half of importEntries / replaceEntries (ONE source, no
-     *  drift): entries re-seq dense from 0 (ids/parents/payload/ts verbatim), THEN session_meta LAST as the commit point.
+    /** @see TiDBSessionStore.writeImportedLog — the shared write half of importEntries / replaceEntries (ONE source, no drift):
+     *  session_meta FIRST (create = occupy the row, an existing one ⇒ refused; replace = plain INSERT after the caller's owner-guarded
+     *  delete), the in-txn claim read on THIS connection (读写序律), then the entries re-seq dense from 0 (ids/parents/payload/ts verbatim).
      *  Runs inside the caller's open txn (`conn` already in BEGIN); the caller owns COMMIT/ROLLBACK + the validate gate. */
-    private insertValidatedLog;
+    private writeImportedLog;
     /** @see TiDBSessionStore.beginImportStaging — 2c P1d-β PUSH staging: stream batches into the shadow id
      *  `${realSessionId}#stg-${token}` (route-minted token), then commit (atomic swap) / abort. */
     beginImportStaging(realSessionId: string, token: string): StagingHandle;
@@ -188,7 +199,7 @@ export declare class PgSessionStore implements SessionStore {
     sweepStagingSessions(): Promise<number>;
     /** @see TiDBSessionStore.deleteSession — purge session_meta + session_event; idempotent (false if absent).
      *  Owner-guarded on session_meta.owner (`IS NOT DISTINCT FROM` = the PG `<=>`); the event purge is gated on the
-     *  owner-matched meta delete (session_event has no owner column). */
+     *  owner-matched meta delete (session_event has no owner column). A live run claim read inside the txn ⇒ `SessionActiveRunError`. */
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     get size(): number;
     dispose(): void;

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

@@ -63,11 +63,16 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      * 谁该声明由闭集门看着(`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;
-        sharesProcessTable: boolean;
+        isolation: false;
+        suspendable: false;
+        canonicalPathAuthoritative: true;
+        sharesProcessTable: false;
+        hostLocalPaths: false;
+        externalContentTarget: false;
+        io: true;
+        keepsReadFloor: false;
     };
     cwd: string;
     private connected;
@@ -175,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>>;