@sema-agent/server 7.137.0 → 7.139.0

package/dist/plugins/tidb-session-store.d.ts

@@ -13,17 +13,20 @@
 import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
-import { type SessionFace } from "../session-incarnation.js";
+import type { SessionWorkspace } from "../session-workspace.js";
+import type { RetentionDeclaration } from "@sema-agent/core";
 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 OrphanOwnerLog } from "../delegated-session-owner.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
+import { type ForkTarget, type ForkToOutcome } from "./session-fork.js";
+import { type ExecutionPlacementSeat } from "../execution-placement.js";
 export declare class TiDBSessionStore implements SessionStore {
     private readonly pool;
-    /** [ref] 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而实现体在别处」逐字见
+    /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法逐字见
      *  `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
-    readonly retention: import("@sema-agent/core").RetentionDeclaration;
+    readonly retention: RetentionDeclaration;
     /** [ref] C18(core 5.48.0 [ref]):placement **声明**。六条义务的实装点逐条见
      *  {@link SQL_SESSION_PLACEMENTS} 顶注与本类的 acquire / listSessions / release / listPlaced /
      *  placementOf 各处的 `[ref]` 注。 */
@@ -36,8 +39,16 @@ export declare class TiDBSessionStore implements SessionStore {
     private readonly pending;
     /** 委派子代孤行那一行 warn 的去处(`delegated-session-owner.ts`;装配给部署的 logger,缺席 ⇒ 缺省 logger,不静默)。 */
     private readonly log;
+    /**
+     * 执行席 —— 根会话行上这一位住客的那一格的唯一读口与 place / markMirror 两只写口(规则在 `src/execution-placement.ts`;
+     * 实现与语句的唯一属主 = `execution-placement-sql.ts`,两孪生同一只实现,本店只交自己的池)。
+     */
+    readonly executionPlacement: ExecutionPlacementSeat;
+    /** 本店的池包成的 SqlDriver:执行席与会话行格写原语的事务都经它借连接(连接初始化钉住事务读语义,`sql-driver.ts`)。 */
+    private readonly db;
     constructor(pool: Pool, opts?: {
         readonly log?: OrphanOwnerLog;
+        readonly retention?: RetentionDeclaration;
     });
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
@@ -80,7 +91,7 @@ export declare class TiDBSessionStore implements SessionStore {
     }): Promise<PlacedSessionRow[]>;
     /**
      * core `SessionStore.headOf` —— 这一行的属主、住客、叶子,**一条 PK SELECT、一行**(两次独立读在删除 / 重登记的缝里能拼出混世代组合;
-     * 单行单读天然一致)。`undefined` = 无此会话。本店按 id 问这一行的**唯一**读口:授权口的属主、parked 两读的住客、SSE 探针的叶子、
+     * 单行单读天然一致)。`undefined` = 无此会话。本店按 id 问这一行的**唯一**读口:授权口的属主、k8s 工作区空间的住客、SSE 探针的叶子、
      * resume-at 的叶子都是它的投影(此前的 `ownerOf` / `sessionFaceOf` / `incarnationOf` / `getLeafId` / `getHead` 五只读全部并进来;规则见
      * `session-incarnation.ts` 头注)。化身那一格经 `headFromRow` 的 `absent` 读法(空 ⇒ 住客未知);要一位活住客的读者经 `sessionFaceOfHead` 响亮拒空。
      * 只读、不取会话、不上锁、绕过暖缓存 —— 跑到一半读也安全(写的安全是追加时的 CAS)。
@@ -132,21 +143,24 @@ export declare class TiDBSessionStore implements SessionStore {
      *  row of the list face (no such session / placed). The run-preview subqueries are scoped to the same id (an index read on
      *  `task_run.session_id`, not the whole-ledger aggregate the list pays). */
     sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
-    /** The session row's writable bits — the ONLY writer of a user-set title / pin (writer order: `src/session-row.ts`):
-     *  `title` unconditional (a string = the user's title — the auto-titler's {@link setTitleIfNull} fills NULL only, so it always
-     *  wins; `null` = cleared back to the automatic title, which the auto-titler fills again on a later submit), `pinned` as given.
-     *  Only a row of the list face takes it (`placement_kind IS NULL`), and only the occupant the caller verified (`incarnation = ?`
-     *  from `face` — a session deleted and re-registered by anyone after the caller's gate is another occupant: zero rows updated).
-     *  The read-back carries the same condition, so the answer is that occupant's list row or `undefined` (the decision does not
-     *  read `affectedRows`: an UPDATE that wrote identical values and one that matched nothing differ there by driver flags, the
-     *  conditioned read-back does not). `updated_at` is NOT touched (a rename is not activity — the list's newest-first order stays put). */
-    patchSessionMeta(sessionId: string, patch: SessionRowPatch, face: SessionFace): Promise<SessionSummary | undefined>;
+    /** {@link sessionSummaryOf} 那一读 + 读到它时行上的住客(写原语的应答行要复核住客,`settleSessionRowWrite`)。 */
+    private listRowOf;
+    /**
+     * 会话行格写原语 —— 用户标题 / 置顶的唯一写口(规则与判序:`src/session-row.ts` 头注「写原语」;事务与语句:`session-row-sql.ts`,PG 孪生同一只实现)。
+     * 一只经 `SqlDriver.connect()` 的事务锁住根行、交 core 判官判行期望(属主 + 化身)→ 写者身份(客户端写在镜像上 ⇒ `mirror`)→ 标签 → 写;
+     * 应答行在提交 / 回滚之后另读(列表行同一只投影,含新 `rowTag`)、复核仍是判过的那一位住客。只写列表面上的行(委派分区行 ⇒ `absent`);
+     * `updated_at` 不动(改名不是活动)。重载按入口分:`replay` 的结局只有 `written` / `absent`。
+     */
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
     /**
      * The list projection's ONE SELECT + row mapper ({@link listSessions} and {@link sessionSummaryOf} both read through it).
      * `runSessionId` scopes the two run-preview subqueries to one session (the single-row read); the list leaves them whole.
      * Placeholder order follows the text: subquery params, then `where` params, then the LIMIT.
+     * `sm.incarnation` is read for the row tag only (`rowTag`, `sessionRowTagKey` — present-iff the row has a token) and the answer row's occupant
+     * check; it never enters the list row itself.
      */
-    private selectSummaries;
+    private selectListRows;
     /** Cheap pre-LLM probe: "none" = session_meta row not yet REGISTERED (createRun fires
      *  before the Runner's session acquire — the titler retries), "untitled" / "titled" as read. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
@@ -165,6 +179,18 @@ export declare class TiDBSessionStore implements SessionStore {
      * 在期限内拒。⚠️ mysql2 的超时是客户端侧的 —— 拒之后那条连接仍被挂着的命令占到服务端结束(S-9 同形,如实披露)。
      */
     recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
+    /**
+     * 会话行的位置与项目那一格(`session_meta.workspace`;域律 `src/session-workspace.ts`,列属主 `session-workspace-cell.ts`)。
+     * 一行 PK 读,按文本投影、恰好解一次;行不在 / 格为 NULL ⇒ `undefined`;格读不出 ⇒ 读作没有记录并计一次(F 类,见列属主头注)。
+     */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜;唯一调用方 = 腿的记录座,它在腿的流循环里一笔一笔等写完)。**住客围栏**:只写化身仍是 `incarnation` 的那一行 ——
+     * 行不在、或同 id 已换了住客 ⇒ 0 行、不抛(那一行不是这条腿的)。**不**碰 `updated_at`(那是会话活动时刻,留存腿按它判龄;记下站在哪里不是一次会话活动)。
+     * 走店的一般查询面(与腿循环里的账本追加同一形,不另设每查询的客户端超时):mysql2 的客户端超时只是不再等,服务端照把那条 UPDATE 跑完 ——
+     * 一笔「放弃等待却仍会落地」的写正是这条腿离开之后还能盖掉下一条腿的那一形。卡住的上界归服务端(锁等待超时)与部署的池策略。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
     /**
      * E17 — fork a session: copy its WHOLE durable history to a NEW uuidv7 session owned by `owner`, mirroring
      * core's `PgSessionRepo.fork`. Entry ids / parent links are per-session and copy VERBATIM; only `seq` is
@@ -178,6 +204,17 @@ export declare class TiDBSessionStore implements SessionStore {
      * bypassed — and re-seq it dense from 0 into the new session, ids/parents/payload byte-verbatim.
      */
     fork(sourceId: string, owner?: string | null): Promise<string | null>;
+    /**
+     * **fork 续写的店契约**(三店同一只私有体;core `fork` 是它的投影):把源会话的整份历史拷进调用方给的目标 id。
+     *  1. **原子目标创建**:事务首句 `INSERT INTO session_meta (…, fork_key) VALUES (:target, …)`,主键即排他(meta 先,随后拷事件、COMMIT);
+     *  2. **赢家分类**:撞上已在的目标 ⇒ 输方整笔回滚,在新视图里读目标、按属主与 fork 键分类({@link classifyForkTarget});读不到(赢方在分类前回滚或被删)
+     *     ⇒ 整笔重跑一次,再撞而仍读不到 ⇒ {@link ForkTargetUnsettledError}(不猜);
+     *  3. 单事务 ⇒ 无中间态;`fork_key` 只由这里写(此后每个写携带:UPDATE 只碰点名列,整段换装经 `carriedRowCells` 带回)。
+     * 源不在 ⇒ `null`(先于目标判:源被删之后的同键重试答「源不在」)。新行 = 新住客(化身新铸),执行格 absent(INSERT 列名显式)。
+     */
+    forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
+    /** {@link forkTo} 的一次尝试:`"unsettled"` = 撞上目标而回滚之后读不到它(交给外层重跑一次)。 */
+    private forkToOnce;
     /**
      * 2c session-sync — EXPORT a session's full durable entry log for cross-backend migration. This is the
      * READ half of {@link fork}, surfaced as the core `SessionRepo.exportEntries` seam: the WHOLE `session_event` log,
@@ -224,29 +261,38 @@ export declare class TiDBSessionStore implements SessionStore {
      *       exactly-one-root / leaf-resolvable / structural refs present) — we persist its VERBATIM output and do NOT
      *       re-implement any of those checks in SQL ([[core-service-boundary]]; the same discipline fork's hand-SQL
      *       was warned about). A violation throws `SessionError("invalid_session")` and NOTHING is written.
-     * The write itself mirrors fork: re-seq dense from 0, entry_id/parent_id/payload/ts verbatim, in ONE txn with
-     * `session_meta` LAST as the commit point (a mid-import crash leaves orphan events with no meta = invisible to
-     * wake, never a half-session). The leaf is the replayed leaf (core's `leafIdAfterEntry`), matching core's import.
+     * The write: re-seq dense from 0, entry_id/parent_id/payload/ts verbatim, in ONE txn (COMMIT is the sole commit point), written
+     * **lock-or-create, meta first** (读写序律,`execution-placement-sql.ts` 头注):the `session_meta` row is occupied first (an existing row ⇒
+     * refused before anything else about it is read), locked, the run claim on the root is read on THIS connection (a claim ⇒
+     * `SessionActiveRunError`, nothing written), then the entries. The leaf is the replayed leaf (core's `leafIdAfterEntry`), matching core's import.
      */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
     /**
      * 2c session-sync (§7/§8) — IDEMPOTENT REPLACE: purge any existing conversation log for `sessionId` then re-import
-     * `entries` verbatim under `owner`, ALL in ONE txn. Unlike {@link importEntries} (a plain INSERT that crashes on a
-     * duplicate PK when the session already exists at the destination), replace is safe to run OVER an existing session
+     * `entries` verbatim under `owner`, ALL in ONE txn. Unlike {@link importEntries} (fresh-only: an existing session at the
+     * destination is refused), replace is safe to run OVER an existing session
      * — the §7 fast-forward path and a §8 retry-to-completion both land on it. The validate gate runs FIRST (fail-closed,
-     * before any write), then DELETE events + the OWNER-GUARDED meta delete (defense-in-depth, mirrors {@link deleteSession}
-     * — a wrong-owner caller can never replace another tenant's session), then the SAME shared insert body importEntries
-     * uses (so there is ONE source of the insert logic, no copy-paste drift). session_meta is still written LAST = commit
-     * point, so a mid-replace crash (post-delete, pre-insert) leaves orphan-free state (no meta = invisible to wake).
+     * before any write), then the OWNER-GUARDED meta delete (defense-in-depth, mirrors {@link deleteSession}
+     * — a wrong-owner caller can never replace another tenant's session: its delete matches nothing and the re-insert collides on the PK),
+     * then the SAME shared write body importEntries uses (session_meta first, the in-txn claim read, then the events swapped) — ONE source of
+     * the write logic, no copy-paste drift. COMMIT is the sole commit point: a mid-replace crash rolls the whole swap back.
      */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
     /**
-     * Shared insert half of {@link importEntries} / {@link replaceEntries} (ONE source of the insert logic, no drift):
-     * write the validated entries re-seq dense from 0 (entry_id/parent_id/type/ts verbatim), THEN session_meta LAST as
-     * the commit point. Runs inside the caller's open transaction (`conn`) so the caller owns begin/commit/rollback.
+     * Shared write half of {@link importEntries} / {@link replaceEntries} (ONE source of the write logic, no drift), in the global lock
+     * order (根 `session_meta` 先于 `task_*` 与 `session_event`):
+     *  ① session_meta FIRST — `create` occupies the row (`ON DUPLICATE KEY UPDATE session_id = session_id`: an existing row is left as it is),
+     *     `replace` is a plain INSERT after the caller's owner-guarded delete (a foreign row collides on the PK — the existing refusal);
+     *     owner = the RE-STAMPED authenticated principal (never the bundle's); 化身与 fork 键按 `carriedRowCells`(或新铸),执行格 = mirror
+     *     —— 导入落下的行是「写者在别处」(列名与值同出 `importedRowCells`);
+     *  ② `create`: lock the row and judge it is the one this call occupied (化身 = 本次铸的)— a row that existed before ⇒ refused before
+     *     anything else about it is read (no claim read on someone else's row);
+     *  ③ 读写序律:the run claim on the root, read on THIS connection after the row lock (`lockRootAndReadClaim`) — a claim ⇒ `SessionActiveRunError`;
+     *  ④ the validated entries re-seq dense from 0 (entry_id/parent_id/type/ts verbatim); `replace` drops the old log first.
+     * Runs inside the caller's open transaction (`conn`) so the caller owns begin/commit/rollback (COMMIT is the sole commit point).
      * `validated` is the OUTPUT of {@link validateEntriesForImport} (the caller runs the gate before opening the txn).
      */
-    private insertValidatedLog;
+    private writeImportedLog;
     /**
      * 2c session-sync P1d-β (PUSH streaming, §15) — begin a STAGED import into `realSessionId` under the shadow id
      * `${realSessionId}#stg-${token}`. The route mints the uuidv7 `token` (the store never calls uuidv7/Date.now itself

package/dist/plugins/tidb-session-store.js

@@ -4,24 +4,38 @@ import { decodeSessionEventPayload } from "./session-event-payload.js";
 import { jsonColumnText } from "./sql-json-column.js";
 import { escapeLike } from "./sql-escape.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
-import { MANAGED_RETENTION } from "./retention-store-sql.js";
-import { carriedIncarnation, headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
+import { carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { sessionRowTagKey } from "../session-row.js";
+import { writeSessionRowCellsSql } from "./session-row-sql.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
 import { createLogger } from "../observability/logger.js";
 import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.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 { isMysqlDupKeyError } from "./sql-errors.js";
+import { mysqlDriver } from "./sql-driver.js";
+import { MIRROR_ON_COMMIT_GUARD, MIRROR_ON_COMMIT_SET, SESSION_META_PLACEMENT_READ_COLUMNS, createSqlExecutionPlacementSeat, importedRowCells, lockRootAndReadClaim, placementCellFromRow, readPlacementRowStatement } from "./execution-placement-sql.js";
+import { SessionActiveRunError, SessionWriterPresentError } from "../execution-placement.js";
+const rowsOnConnection = (conn) => async (sql, values) => (await conn.query(sql, [...values]))[0];
 export class TiDBSessionStore {
     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 = mysqlDriver(pool);
+        this.executionPlacement = createSqlExecutionPlacementSeat(this.db);
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
@@ -169,34 +183,21 @@ export class TiDBSessionStore {
             where.push("(sm.updated_at < ? OR (sm.updated_at = ? AND sm.session_id < ?))");
             params.push(new Date(opts.cursor.lastActivityAt), new Date(opts.cursor.lastActivityAt), opts.cursor.sessionId);
         }
-        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 = ?"], 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) {
-            sets.push("title = ?");
-            params.push(patch.title);
-        }
-        if (patch.pinned !== undefined) {
-            sets.push("pinned = ?");
-            params.push(patch.pinned);
-        }
-        if (sets.length > 0) {
-            params.push(sessionId, face.incarnation);
-            await this.pool.query(`UPDATE session_meta SET ${sets.join(", ")} WHERE session_id = ? AND incarnation = ? AND placement_kind IS NULL`, params);
-        }
-        const rows = await this.selectSummaries({ where: ["sm.placement_kind IS NULL", "sm.session_id = ?", "sm.incarnation = ?"], 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 = ?"], 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 runWhere = q.runSessionId !== undefined ? " WHERE session_id = ?" : "";
         const runParams = q.runSessionId !== undefined ? [q.runSessionId, 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 " +
@@ -209,9 +210,14 @@ export class TiDBSessionStore {
         const [rows] = await this.pool.query(sql, [...runParams, ...q.params, q.limit]);
         return 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 = Number(r.pinned) === 1;
+            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),
@@ -219,9 +225,11 @@ export class TiDBSessionStore {
                 lastStatus: r.status == null ? "" : String(r.status),
                 lastRunId: r.last_run_id ?? null,
                 ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
-                title: r.title ?? null,
-                pinned: Number(r.pinned) === 1,
+                title,
+                pinned,
+                ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
             };
+            return { row, occupant: { owner, incarnation } };
         });
     }
     async probeTitle(sessionId) {
@@ -247,7 +255,26 @@ export class TiDBSessionStore {
             await this.pool.query({ sql: "UPDATE session_meta SET instruction_source = ? WHERE session_id = ? AND instruction_source IS NULL", timeout: BASELINE_IO_DEADLINE_MS }, [next, sessionId]);
         }
     }
+    async readSessionWorkspace(sessionId) {
+        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("tidb", "workspace")} FROM session_meta WHERE session_id = ?`, [sessionId]);
+        const row = rows[0];
+        return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
+    }
+    async recordSessionWorkspace(sessionId, incarnation, workspace) {
+        await this.pool.query("UPDATE session_meta SET workspace = ? WHERE session_id = ? AND incarnation = ?", [encodeSessionWorkspaceCell(workspace, JSON.stringify, 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 [metaRows] = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = ?", [sourceId]);
         if (!metaRows[0])
             return null;
@@ -258,20 +285,30 @@ export class TiDBSessionStore {
             return null;
         const point = await forkPointOf(storage);
         const [allRows] = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("tidb", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sourceId]);
-        const { rows: eventRows, leafId: forkLeafId } = forkCopyOf(allRows, leafId, point);
-        const newId = uuidv7();
+        const { rows: eventRows, leafId: forkLeafId } = selectForkRows(allRows, leafId, point, FORK_LOG_ROW_SHAPE);
         const now = new Date();
         const conn = await this.pool.getConnection();
+        let collided = false;
         try {
             await conn.beginTransaction();
-            for (let seq = 0; seq < eventRows.length; seq++) {
-                const r = eventRows[seq];
-                const payload = String(r.payload);
-                await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [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 (?,?,?,?,?,?,?,?)", [target.id, forkOwner, now, now, forkLeafId, eventRows.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 (?,?,?,?,?,?,?)", [newId, forkOwner, now, now, forkLeafId, eventRows.length, mintSessionIncarnation()]);
-            await conn.commit();
-            return newId;
+            catch (err) {
+                if (!isMysqlDupKeyError(err))
+                    throw err;
+                collided = true;
+            }
+            if (!collided) {
+                for (let seq = 0; seq < eventRows.length; seq++) {
+                    const r = eventRows[seq];
+                    const payload = String(r.payload);
+                    await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [target.id, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
+                }
+                await conn.commit();
+                return { outcome: "created", id: target.id };
+            }
+            await conn.rollback();
         }
         catch (err) {
             try {
@@ -284,6 +321,9 @@ export class TiDBSessionStore {
         finally {
             conn.release();
         }
+        const [existing] = await this.pool.query("SELECT owner, fork_key FROM session_meta WHERE session_id = ?", [target.id]);
+        const row = existing[0];
+        return row === undefined ? "unsettled" : classifyForkTarget(target, { owner: row.owner ?? null, forkKey: row.fork_key ?? null }, forkOwner);
     }
     async exportEntries(sessionId) {
         const [metaRows] = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = ?", [sessionId]);
@@ -323,7 +363,7 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            await this.insertValidatedLog(conn, sessionId, owner, validated, mintSessionIncarnation());
+            await this.writeImportedLog(conn, sessionId, owner, validated, { incarnation: mintSessionIncarnation(), forkKey: null }, "create");
             await conn.commit();
         }
         catch (err) {
@@ -332,7 +372,7 @@ export class TiDBSessionStore {
             }
             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);
         }
@@ -346,14 +386,21 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            const [placedRows] = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
-            if (placedRows[0]?.placement_kind != null) {
+            const [placedRows] = await conn.query(`SELECT ${SESSION_META_PLACEMENT_READ_COLUMNS}, fork_key FROM session_meta WHERE session_id = ? FOR UPDATE`, [sessionId]);
+            const prior = placedRows[0];
+            if (prior?.placement_kind != null) {
                 await conn.rollback();
-                throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${String(placedRows[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 = ?", [sessionId]);
-            await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [sessionId, owner]);
-            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(sessionId, placedRows[0] === undefined ? undefined : { owner: placedRows[0].owner, incarnation: placedRows[0].incarnation }, owner));
+            const [purged] = await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [sessionId, owner]);
+            const swapped = purged.affectedRows === 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.rollback();
+                throw new SessionWriterPresentError(sessionId, priorCell.lane);
+            }
+            await this.writeImportedLog(conn, sessionId, owner, validated, cells, "replace");
             await conn.commit();
         }
         catch (err) {
@@ -362,7 +409,7 @@ export class TiDBSessionStore {
             }
             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);
         }
@@ -370,16 +417,29 @@ export class TiDBSessionStore {
             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 (?,?,?,?,?,?,?,?,?)` +
+            (mode === "create" ? " ON DUPLICATE KEY UPDATE session_id = session_id" : ""), [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 = ? FOR UPDATE", [sessionId]);
+            if (String(held[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(rowsOnConnection(conn), "tidb", sessionId);
+        if (claim.activeTaskId !== null)
+            throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+        if (mode === "replace")
+            await conn.query("DELETE FROM session_event WHERE session_id = ?", [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 (?,?,?,?,?,?,?)", [sessionId, seq, e.id, e.parentId ?? null, e.type, JSON.stringify(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 (?,?,?,?,?,?,?)", [sessionId, owner, now, now, leafId, validated.length, incarnation]);
     }
     beginImportStaging(realSessionId, token) {
         return new TiDBStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
@@ -410,6 +470,11 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
+            const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "tidb", sessionId);
+            if (claim.activeTaskId !== null) {
+                await conn.rollback();
+                throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+            }
             const [metaRes] = await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ?", [sessionId, owner]);
             if (metaRes.affectedRows > 0)
                 await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
@@ -488,6 +553,11 @@ class TiDBStagingHandle {
                     throw new StagedCommitOwnerChangedError(this.realSessionId);
                 }
             }
+            const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "tidb", this.realSessionId);
+            if (claim.activeTaskId !== null) {
+                await conn.rollback();
+                throw new SessionActiveRunError(this.realSessionId, claim.activeTaskId);
+            }
             const [stagedRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const [dstRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
             const [dstMeta] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ?", [this.realSessionId]);
@@ -522,7 +592,16 @@ class TiDBStagingHandle {
             let leafId = null;
             if (lastRow[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRow[0].payload, this.realSessionId, "last staged row"));
-            await conn.query("UPDATE session_meta SET owner = ?, updated_at = ?, leaf_id = ?, leaf_seq = ? WHERE session_id = ?", [owner, now, leafId, srcIds.length, this.realSessionId]);
+            const [settle] = await conn.query(`UPDATE session_meta SET owner = ?, updated_at = ?, leaf_id = ?, leaf_seq = ?, ${MIRROR_ON_COMMIT_SET} WHERE session_id = ? AND ${MIRROR_ON_COMMIT_GUARD}`, [owner, now, leafId, srcIds.length, this.realSessionId]);
+            if (settle.affectedRows !== 1) {
+                const locked = readPlacementRowStatement("tidb", this.realSessionId, { lock: true });
+                const [lockedRows] = await conn.query(locked.text, [...locked.values]);
+                const cell = lockedRows[0] === undefined ? undefined : placementCellFromRow(this.realSessionId, lockedRows[0]);
+                await conn.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 = ?", [this.realSessionId]);
             if (afterMeta[0]?.placement_kind != null) {
                 await conn.rollback();
@@ -537,7 +616,7 @@ class TiDBStagingHandle {
                 await conn.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/tool-result-store-sql.d.ts

@@ -2,6 +2,7 @@ import type { ToolResultProvenance, ToolResultStore, ToolResultSlice, ToolResult
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+import type { RetentionDeclaration } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 /** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
  *  (LONGTEXT→TEXT, DATETIME(3)→TIMESTAMPTZ(3), inline KEY→separate CREATE INDEX). Disjoint from other stores'
@@ -14,14 +15,15 @@ export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>
 /**
  * [ref] 升级前置断言 —— **拒启**,不是 warn(codex 复审 [high],已核真)。
  *
- * 病:本仓不发 `ALTER TABLE` 迁移(标准裁定:改列就改 CREATE + 删库重建)。于是一台**没删表**就升上来的
+ * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:代码是唯一真源,存量库缺列由部署者按拒启句打印的 ALTER 自己执行)。于是一台**没跟上**就升上来的
  * 部署,`CREATE TABLE IF NOT EXISTS` 对它是空操作,旧表既没有出处两列也只有 `VARCHAR(190)` 的 ref 列。
  * 那样跑起来的后果不是「少个功能」:每一次 offload 写都会撞 unknown column 报错,而 core 的 offload
  * 失败臂会把错误吞成一条内联占位("[offload LOST at write time…]")—— 服务照跑,工具产物全丢,日志里只有
  * 一句看不出根因的话。这正是「响亮或 fail-closed,禁静默降级」那条要挡的形态。
  *
  * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
- * 探不通即拒启,错误文案直接给出两条方言的动作(删表重建),不让运维去猜。
+ * 探针读抛且是**可证**的缺列 ⇒ 拒启(其余错误原样上抛,与兄弟探针同一条规则)。拒因的出路是**闭集三条**(与整库对账同一份,{@link describeProbedTableDrift} / {@link schemaWaysOut}),没有销毁性的一条:
+ * 缺的出处两列由对账同一套件逐条打印 `ALTER TABLE tool_result ADD COLUMN …`;键宽不够则第 (2) 条是部署者自己把 `ref` 加宽到本构建的定义。
  */
 export declare function assertToolResultProvenanceSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
@@ -29,10 +31,12 @@ export declare function assertToolResultProvenanceSchema(query: (sql: string) =>
 /** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;
-    /** [ref] 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而三方法的实现体在 `retention-store-sql.ts`」
-     *  逐字见 {@link MANAGED_RETENTION}(本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
-    readonly retention: import("@sema-agent/core").RetentionDeclaration;
-    constructor(db: SqlDriver);
+    /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
+     *  `retention-store-sql.ts`」逐字见 {@link MANAGED_RETENTION}(扫车道开着时本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
+    readonly retention: RetentionDeclaration;
+    constructor(db: SqlDriver, opts?: {
+        readonly retention?: RetentionDeclaration;
+    });
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** D1(试剂盒揪出,[ref] 语义):ref 是主键,而 `deleteBySession` 只认**记录下来的出处**与单射的
@@ -97,10 +101,14 @@ export declare class SqlToolResultStore implements ToolResultStore {
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBToolResultStore extends SqlToolResultStore {
-    constructor(pool: MySqlPool);
+    constructor(pool: MySqlPool, opts?: {
+        readonly retention?: RetentionDeclaration;
+    });
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgToolResultStore extends SqlToolResultStore {
-    constructor(pool: PgPool);
+    constructor(pool: PgPool, opts?: {
+        readonly retention?: RetentionDeclaration;
+    });
 }
 //# sourceMappingURL=tool-result-store-sql.d.ts.map