@sema-agent/server 7.145.0 → 7.147.0

package/dist/{plugins → stores-sql}/tidb-session-store.d.ts

@@ -12,19 +12,15 @@
  */
 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 { SessionWorkspace } from "../session-workspace.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import type { SessionSummary } from "./store-contracts.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 { SessionWriteHooks } from "./session-write-hooks.js";
+import { type PlacementAcquireOpts } from "../plugins/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";
+import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "../plugins/session-fork.js";
 export declare class TiDBSessionStore implements SessionStore {
     private readonly pool;
     /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法逐字见
-     *  `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+     *  `retention-declaration.ts` 的 {@link MANAGED_RETENTION}。 */
     readonly retention: RetentionDeclaration;
     /** [ref] C18(core 5.48.0 [ref]):placement **声明**。六条义务的实装点逐条见
      *  {@link SESSION_PLACEMENTS} 顶注与本类的 acquire / listSessions / release / listPlaced /
@@ -39,15 +35,11 @@ export declare class TiDBSessionStore implements SessionStore {
     readonly durability: "durable";
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
-    /**
-     * 执行席 —— 根会话行上这一位住客的那一格的唯一读口与 place / markMirror 两只写口(规则在 `src/execution-placement.ts`;
-     * 实现与语句的唯一属主 = `execution-placement-sql.ts`,两孪生同一只实现,本店只交自己的池)。
-     */
-    readonly executionPlacement: ExecutionPlacementSeat;
-    /** 本店的池包成的 SqlDriver:执行席与会话行格写原语的事务都经它借连接(连接初始化钉住事务读语义,`sql-driver.ts`)。 */
-    private readonly db;
-    constructor(pool: Pool, opts?: {
+    /** 部署的事务内钩(组合座交入;导入 / 删除 / fork 的写事务锁住根行之后、写之前调,`session-write-hooks.ts`)。 */
+    private readonly hooks;
+    constructor(pool: Pool, opts: {
         readonly retention?: RetentionDeclaration;
+        readonly hooks: SessionWriteHooks;
     });
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
@@ -111,77 +103,6 @@ export declare class TiDBSessionStore implements SessionStore {
     /** 真删除一只 placed 会话的两张表(条件删门在 `placement_kind IS NOT NULL`;事务内 meta 先删=提交点,
      *  与 {@link deleteSession} 同序)。任何 I/O 失败上浮成 `SessionError("storage")`,绝不吞。 */
     private deletePlacedSession;
-    /**
-     * E16 — list the caller's sessions (CC /resume picker), keyset-paginated newest-first by last activity.
-     * Session IDENTITY/enumeration comes from `session_meta` (owner-filtered on the service's OWN owner column);
-     * a LEFT JOIN onto the `task_run` runs ledger supplies run-level PREVIEW (latest run's objective/status,
-     * run count) but never gates which sessions exist — a session with zero runs still lists (preview null/0).
-     * Keyset on `(updated_at, session_id)`; `updated_at` is the session's last-activity marker (touch on every
-     * run/append). The shipped {@link SessionSummary} shape is preserved (additive): `lastActivityAt` =
-     * `session_meta.updated_at`, `firstActivityAt` = `session_meta.created_at`.
-     */
-    listSessions(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<SessionSummary[]>;
-    /** ONE session's list row — {@link listSessions}' projection (same SELECT, same mapper) scoped to one id; `undefined` = not a
-     *  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>;
-    /** {@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 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">;
-    /** The auto-titler's write: lands ONLY when title IS NULL (a concurrent/prior title — the user's included — wins;
-     *  writer order: `src/session-row.ts`). Returns whether this call set it. */
-    setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
-    /**
-     * [ref] —— 换源通告的基线读(一行 PK SELECT;列的三态读法见 `tidb-pool.ts` 的列注)。行不在 ⇒ 读作「没记过」
-     * (loader 跑在 acquire 之后,行恒在;不在 = 被带外删了,没有下一 run 可比)。
-     */
-    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
-    /**
-     * [ref] —— CAS 覆写基线(期望值 = 调用方读到的那一份;不符 ⇒ 0 行、不抛 —— 契约见 `InstructionSourceStore`)。
-     * **不**碰 `updated_at`(那是会话活动时刻,留存腿按它判龄;记基线不是一次会话活动)。
-     * 两条基线查询都带每查询超时(`BASELINE_IO_DEADLINE_MS`,mysql2 的 `{sql, timeout}` 形):被行锁卡住的写由查询自己
-     * 在期限内拒。⚠️ 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
@@ -194,14 +115,17 @@ export declare class TiDBSessionStore implements SessionStore {
      * We instead SELECT the entire `session_event` log ordered by seq — every durable entry, compaction floor
      * 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(sourceId: string, owner?: string | null, opts?: {
+        placement?: ForkPlacement;
+    }): Promise<string | null>;
     /**
      * **fork 续写的店契约**(三店同一只私有体;core `fork` 是它的投影):把源会话的整份历史拷进调用方给的目标 id。
-     *  1. **原子目标创建**:事务首句 `INSERT INTO session_meta (…, fork_key) VALUES (:target, …)`,主键即排他(meta 先,随后拷事件、COMMIT);
-     *  2. **赢家分类**:撞上已在的目标 ⇒ 输方整笔回滚,在新视图里读目标、按属主与 fork 键分类({@link classifyForkTarget});读不到(赢方在分类前回滚或被删)
+     *  1. **原子目标创建**:事务首句 `INSERT INTO session_meta (…) VALUES (:target, …)`,主键即排他(meta 先,随后事务内钩 `fork` —— 部署在同一事务里记下 fork 键
+     *     (部署格,旁表)—— 再拷事件、COMMIT);
+     *  2. **赢家分类**:撞上已在的目标 ⇒ 输方整笔回滚,经钩读目标那一行的属主与 fork 键(一次读)、分类({@link classifyForkTarget});读不到(赢方在分类前回滚或被删)
      *     ⇒ 整笔重跑一次,再撞而仍读不到 ⇒ {@link ForkTargetUnsettledError}(不猜);
-     *  3. 单事务 ⇒ 无中间态;`fork_key` 只由这里写(此后每个写携带:UPDATE 只碰点名列,整段换装经 `carriedRowCells` 带回)。
-     * 源不在 ⇒ `null`(先于目标判:源被删之后的同键重试答「源不在」)。新行 = 新住客(化身新铸),执行格 absent(INSERT 列名显式)。
+     *  3. 单事务 ⇒ 无中间态;fork 键只由这一钩写。
+     * 源不在 ⇒ `null`(先于目标判:源被删之后的同键重试答「源不在」)。新行 = 新住客(化身新铸),部署格全缺省(执行格 absent)。
      */
     forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
     /** {@link forkTo} 的一次尝试:`"unsettled"` = 撞上目标而回滚之后读不到它(交给外层重跑一次)。 */
@@ -253,33 +177,32 @@ export declare class TiDBSessionStore implements SessionStore {
      *       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: 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.
+     * **lock-or-create, meta first**:the `session_meta` row is occupied first (an existing row ⇒ refused before anything else about it is read), locked,
+     * then the deployment's transaction hook `import` runs on THIS connection (its run claim on the root ⇒ refused, nothing written; its cells for an
+     * imported row), 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} (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 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.
+     * 2c session-sync (§7/§8) — IDEMPOTENT REPLACE: rewrite the conversation log of `sessionId` with `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 the row: an absent id is created (a fresh occupant, like {@link importEntries}); an existing row is rewritten IN PLACE only when it is the
+     * importer's (`owner <=> ?`, defense-in-depth — a wrong-owner caller can never replace another tenant's session: nothing is written) and not a
+     * delegation transcript — the same occupant keeps its incarnation and its deployment cells (the side table row is not touched by the store), its
+     * created time is the replace's (the log is new). Then the SAME shared write body importEntries uses (the hook, then the events swapped) —
+     * ONE source of the write logic. 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 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.
+     * order (根 `session_meta` 先于 `task_*`、部署格与 `session_event`):
+     *  ① session_meta FIRST — `create` occupies the row (`ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq`: an existing row is left as it is) and then
+     *     locks it and judges it is the one this call occupied (化身 = 本次铸的;a row that existed before ⇒ refused before anything else about it is
+     *     read — no hook on someone else's row); `replace` rewrites the locked row in place (owner-guarded, not placed — 0 rows = another owner's row,
+     *     refused, nothing written). owner = the RE-STAMPED authenticated principal (never the bundle's);
+     *  ② the deployment's transaction hook `import` on THIS connection after the row lock (`session-write-hooks.ts`):its run claim on the root ⇒
+     *     refused; its cells for an imported row (a writer here ⇒ refused; otherwise the row is a mirror —「写者在别处」);
+     *  ③ 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).
      */

package/dist/{plugins → stores-sql}/tidb-session-store.js

@@ -1,38 +1,43 @@
 import { StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, admitSessionPlacement } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./tidb-session-storage.js";
 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 { 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 { jsonColumnText } from "../plugins/sql-json-column.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
+import { headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
-import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "./session-placement.js";
+import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "../plugins/session-placement.js";
 import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
-import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "./session-ownership.js";
+import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "../plugins/session-ownership.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];
+import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf } from "../plugins/session-fork.js";
+import { isMysqlDupKeyError } from "../plugins/sql-errors.js";
+const statementsOn = (conn) => ({
+    async query(sql, params) {
+        const [res] = await conn.query(sql, params ?? []);
+        return Array.isArray(res) ? { rows: res, affected: 0 } : { rows: [], affected: res.affectedRows };
+    },
+});
+class HookRefusal {
+    refuse;
+    constructor(refuse) {
+        this.refuse = refuse;
+    }
+}
+function settleHookVerdict(verdict) {
+    if (verdict !== "proceed")
+        throw new HookRefusal(verdict.refuse);
+}
 export class TiDBSessionStore {
     pool;
     retention;
     placements = SESSION_PLACEMENTS;
     durability = SESSION_DURABILITY;
     pending = new Map();
-    executionPlacement;
-    db;
-    constructor(pool, opts = {}) {
+    hooks;
+    constructor(pool, opts) {
         this.pool = pool;
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
-        this.db = mysqlDriver(pool);
-        this.executionPlacement = createSqlExecutionPlacementSeat(this.db);
+        this.hooks = opts.hooks;
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
@@ -83,7 +88,7 @@ export class TiDBSessionStore {
         const now = new Date();
         await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
             "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +
-            "VALUES (?,?,?,?,NULL,0,?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE session_id = session_id", [sessionId, owner, now, now, mintSessionIncarnation(), ...placementInsertValues(placement, now)]);
+            "VALUES (?,?,?,?,NULL,0,?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq", [sessionId, owner, now, now, mintSessionIncarnation(), ...placementInsertValues(placement, now)]);
     }
     async placementOf(sessionId) {
         const [rows] = await this.pool.query(`SELECT ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = ?`, [sessionId]);
@@ -151,103 +156,8 @@ export class TiDBSessionStore {
             conn.release();
         }
     }
-    async listSessions(opts) {
-        const params = [];
-        const where = ["sm.placement_kind IS NULL"];
-        if (opts.owner !== undefined) {
-            where.push(opts.includeUnowned ? "(sm.owner = ? OR sm.owner IS NULL)" : "sm.owner = ?");
-            params.push(opts.owner);
-        }
-        if (opts.q) {
-            where.push("EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id AND LOWER(tr.objective_preview) LIKE LOWER(?) ESCAPE '\\\\')");
-            params.push(`%${escapeLike(opts.q)}%`);
-        }
-        if (opts.cursor) {
-            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 (await this.selectListRows({ where, params, limit: opts.limit })).map((a) => a.row);
-    }
-    async sessionSummaryOf(sessionId) {
-        return (await this.listRowOf(sessionId))?.row;
-    }
-    async listRowOf(sessionId) {
-        return (await this.selectListRows({ where: ["sm.placement_kind IS NULL", "sm.session_id = ?"], params: [sessionId], limit: 1, runSessionId: sessionId }))[0];
-    }
-    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.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 " +
-            "LEFT JOIN (SELECT session_id, objective_preview, status, task_id, last_task_run_id FROM (" +
-            "    SELECT session_id, objective_preview, status, task_id, JSON_UNQUOTE(JSON_EXTRACT(result, '$.runId')) AS last_task_run_id, " +
-            "      ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn FROM task_run" + runWhere +
-            "  ) lr WHERE rn = 1) latest ON latest.session_id = sm.session_id " +
-            (q.where.length ? "WHERE " + q.where.join(" AND ") + " " : "") +
-            "ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ?";
-        const [rows] = await this.pool.query(sql, [...runParams, ...q.params, q.limit]);
-        return rows.map((r) => {
-            const runId = r.last_task_run_id;
-            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),
-                objectivePreview: r.objective_preview ?? null,
-                lastStatus: r.status == null ? "" : String(r.status),
-                lastRunId: r.last_run_id ?? null,
-                ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
-                title,
-                pinned,
-                ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
-            };
-            return { row, occupant: { owner, incarnation } };
-        });
-    }
-    async probeTitle(sessionId) {
-        const [rows] = await this.pool.query("SELECT title FROM session_meta WHERE session_id = ?", [sessionId]);
-        if (!rows[0])
-            return "none";
-        return rows[0].title == null ? "untitled" : "titled";
-    }
-    async setTitleIfNull(sessionId, title) {
-        const [r] = await this.pool.query("UPDATE session_meta SET title = ? WHERE session_id = ? AND title IS NULL", [title, sessionId]);
-        return r.affectedRows > 0;
-    }
-    async readInstructionSource(sessionId) {
-        const [rows] = await this.pool.query({ sql: "SELECT instruction_source FROM session_meta WHERE session_id = ?", timeout: BASELINE_IO_DEADLINE_MS }, [sessionId]);
-        return decodeInstructionSource(rows[0]?.instruction_source);
-    }
-    async recordInstructionSource(sessionId, expected, source) {
-        const next = encodeInstructionSource(source);
-        if (expected.recorded) {
-            await this.pool.query({ sql: "UPDATE session_meta SET instruction_source = ? WHERE session_id = ? AND instruction_source = ?", timeout: BASELINE_IO_DEADLINE_MS }, [next, sessionId, encodeInstructionSource(expected.source)]);
-        }
-        else {
-            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("mysql", "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 fork(sourceId, owner, opts) {
+        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner, opts);
     }
     async forkTo(sourceId, owner, target) {
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -275,7 +185,8 @@ export class TiDBSessionStore {
         try {
             await conn.beginTransaction();
             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, " +
+                    "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)", [target.id, forkOwner, now, now, forkLeafId, eventRows.length, mintSessionIncarnation(), ...placementInsertValues(target.placement, now)]);
             }
             catch (err) {
                 if (!isMysqlDupKeyError(err))
@@ -283,6 +194,8 @@ export class TiDBSessionStore {
                 collided = true;
             }
             if (!collided) {
+                if (target.key !== undefined)
+                    await this.hooks.keyedFork.record(statementsOn(conn), { rootSessionId: target.id, forkKey: target.key });
                 for (let seq = 0; seq < eventRows.length; seq++) {
                     const r = eventRows[seq];
                     const payload = String(r.payload);
@@ -299,14 +212,15 @@ export class TiDBSessionStore {
             }
             catch {
             }
+            if (err instanceof HookRefusal)
+                throw err.refuse;
             throw err instanceof SessionError ? err : new SessionError("storage", `fork of session ${sourceId} failed`, err instanceof Error ? err : undefined);
         }
         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);
+        const existing = await this.hooks.keyedFork.targetOf(target.id);
+        return existing === undefined ? "unsettled" : classifyForkTarget(target, existing, forkOwner);
     }
     async exportEntries(sessionId) {
         const [metaRows] = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = ?", [sessionId]);
@@ -346,7 +260,7 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            await this.writeImportedLog(conn, sessionId, owner, validated, { incarnation: mintSessionIncarnation(), forkKey: null }, "create");
+            await this.writeImportedLog(conn, sessionId, owner, validated, "create");
             await conn.commit();
         }
         catch (err) {
@@ -355,7 +269,9 @@ export class TiDBSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `import of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -369,21 +285,13 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            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];
+            const [lockedRows] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
+            const prior = lockedRows[0];
             if (prior?.placement_kind != null) {
                 await conn.rollback();
                 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`);
             }
-            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 this.writeImportedLog(conn, sessionId, owner, validated, prior === undefined ? "create" : "replace");
             await conn.commit();
         }
         catch (err) {
@@ -392,7 +300,9 @@ export class TiDBSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `replace of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -400,23 +310,26 @@ export class TiDBSessionStore {
             conn.release();
         }
     }
-    async writeImportedLog(conn, sessionId, owner, validated, cells, mode) {
+    async writeImportedLog(conn, sessionId, owner, validated, 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 minted = mintSessionIncarnation();
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq", [sessionId, owner, now, now, leafId, validated.length, minted]);
             const [held] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
-            if (String(held[0]?.incarnation) !== cells.incarnation) {
+            if (String(held[0]?.incarnation) !== minted) {
                 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), "mysql", sessionId);
-        if (claim.activeTaskId !== null)
-            throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+        else {
+            const [rewritten] = await conn.query("UPDATE session_meta SET owner = ?, created_at = ?, updated_at = ?, leaf_id = ?, leaf_seq = ? WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [owner, now, now, leafId, validated.length, sessionId, owner]);
+            if (rewritten.affectedRows !== 1) {
+                throw new SessionError("storage", `replace of session ${sessionId} failed`, new Error(`session ${sessionId} belongs to another owner — a replace rewrites only the importer's own session; nothing was written`));
+            }
+        }
+        settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: sessionId }));
         if (mode === "replace")
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
         for (let seq = 0; seq < validated.length; seq++) {
@@ -425,7 +338,7 @@ export class TiDBSessionStore {
         }
     }
     beginImportStaging(realSessionId, token) {
-        return new TiDBStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
+        return new TiDBStagingHandle(this.pool, this.hooks, realSessionId, stagingIdFor(realSessionId, token));
     }
     async assertNotPlaced(sessionId, what) {
         const placed = await this.placementOf(sessionId);
@@ -453,11 +366,9 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "mysql", sessionId);
-            if (claim.activeTaskId !== null) {
-                await conn.rollback();
-                throw new SessionActiveRunError(sessionId, claim.activeTaskId);
-            }
+            const [locked] = await conn.query("SELECT session_id FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
+            if (locked.length > 0)
+                settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "delete", rootSessionId: sessionId }));
             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]);
@@ -470,6 +381,8 @@ export class TiDBSessionStore {
             }
             catch {
             }
+            if (err instanceof HookRefusal)
+                throw err.refuse;
             throw err;
         }
         finally {
@@ -485,12 +398,14 @@ export class TiDBSessionStore {
 }
 class TiDBStagingHandle {
     pool;
+    hooks;
     realSessionId;
     stagingId;
     nextSeq = 0;
     seen = new Set();
-    constructor(pool, realSessionId, stagingId) {
+    constructor(pool, hooks, realSessionId, stagingId) {
         this.pool = pool;
+        this.hooks = hooks;
         this.realSessionId = realSessionId;
         this.stagingId = stagingId;
     }
@@ -529,18 +444,14 @@ class TiDBStagingHandle {
                 }
             }
             else {
-                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,NULL,0,?) ON DUPLICATE KEY UPDATE session_id = session_id", [this.realSessionId, owner, now, now, minted]);
+                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,NULL,0,?) ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq", [this.realSessionId, owner, now, now, minted]);
                 const [claimed] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [this.realSessionId]);
                 if (String(claimed[0]?.incarnation) !== minted) {
                     await conn.rollback();
                     throw new StagedCommitOwnerChangedError(this.realSessionId);
                 }
             }
-            const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "mysql", this.realSessionId);
-            if (claim.activeTaskId !== null) {
-                await conn.rollback();
-                throw new SessionActiveRunError(this.realSessionId, claim.activeTaskId);
-            }
+            settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: this.realSessionId }));
             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]);
@@ -575,16 +486,7 @@ class TiDBStagingHandle {
             let leafId = null;
             if (lastRow[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRow[0].payload, this.realSessionId, "last staged row"));
-            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("mysql", 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`);
-            }
+            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 [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();
@@ -599,7 +501,9 @@ class TiDBStagingHandle {
                 await conn.rollback();
             }
             catch { }
-            if (err instanceof SyncConflictError || err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SyncConflictError || err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `staged commit for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
         }