@sema-agent/server 7.145.0 → 7.147.0

package/dist/plugins/session-placement.d.ts

@@ -34,6 +34,7 @@
  *    店上,带 placement 的 acquire 必须回读到**已持久化**且同一元组身份的行,回读缺失/异组=响亮拒。
  */
 import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord, type SessionStore } from "@sema-agent/core";
+import type { ForkPlacement } from "./session-fork.js";
 /**
  * 三只持久会话店(SQL 两孪生 + local 后端)的**会话耐久声明**(core `SessionStore.durability`:未 placed 的会话活不活过进程重启)——
  * **单源**:三处声明(两孪生类上的顶层 `durability`、`LocalBackend` 交给店的顶层 `durability`)与委派分区的 {@link SESSION_PLACEMENTS}
@@ -93,8 +94,9 @@ export declare function placementFromRow(row: PlacementColumns | undefined): Ses
  * 消费方对它 fail-closed(永不按年龄收割)。一个「无行」与「另一个租户有行」分不清的 join 不许删东西。
  */
 export declare function placedRowFromRow(sessionId: string, row: PlacementColumns, lastActivityMs?: number): PlacedSessionRow;
-/** 创建时一次落行的六个绑定值(顺序 = {@link PLACEMENT_SELECT_COLUMNS});无 placement ⇒ 六个 NULL。 */
-export declare function placementInsertValues(placement: SessionPlacement | undefined, placedAt: Date): [string | null, string | null, string | null, string | null, string | null, Date | null];
+/** 创建时一次落行的六个绑定值(顺序 = {@link PLACEMENT_SELECT_COLUMNS});无 placement ⇒ 六个 NULL。读的只是元组(属主不在元组里 —— 它是行的属主格,建行那一笔另记):
+ *  带 placement 的 acquire 与带元组的 fork 两个建行点同调。 */
+export declare function placementInsertValues(placement: ForkPlacement | undefined, placedAt: Date): [string | null, string | null, string | null, string | null, string | null, Date | null];
 /** `acquire` 的 opts 面(core `SessionStore.acquire` 的第二参,窄成本模块要判的两键)。 */
 export interface PlacementAcquireOpts {
     requireExisting?: boolean;

package/dist/plugins/session-row-sql.d.ts

@@ -1,16 +1,17 @@
 /**
- * **会话行格写原语的 SQL 半** —— 两孪生(`tidb-session-store.ts` / `pg-session-storage.ts`)同一只实现,方言只在语句文本里。规则在 `src/session-row.ts`
- * 头注「写原语」;判序只在那里的判官 `judgeSessionRowWrite`,本模块只说事务与语句。
+ * **会话行格写原语的 SQL 半** —— 两方言同一只实现,方言只在语句文本里。规则在 `src/session-row.ts` 头注「写原语」;判序只在那里的判官
+ * `judgeSessionRowWrite`,本模块只说事务与语句。格住部署的旁表 `session_ext`(属主 `session-ext-table.ts`);住客住引擎座表 `session_meta`(只读)。
  *
  * ## 一只事务(经 `SqlDriver.connect()`)
- *  ① `SELECT … FROM session_meta WHERE session_id = ? FOR UPDATE` —— 判定读 = 锁读(当前读;连接初始化钉住读语义:TiDB 悲观、设不上拒启,
- *     `sql-driver.ts` 的 `@contract txn.read-semantics`);行期望带 `log` 时,同锁下读日志的 mark:长度 = 锁住的行上的 `leaf_seq`(每次追加与
- *     `leaf_id` 同句 +1,导入 / 换装 / fork 写成条目数),末条 = `session_event` 按 `seq` 倒序第一行(锁读)。追加者先锁这一行再插事件,所以持锁期间 mark 不动。
+ *  ① `SELECT … FROM session_meta WHERE session_id = ? FOR UPDATE` —— 锁根行读住客(当前读;连接初始化钉住读语义:TiDB 悲观、设不上拒启,
+ *     `sql-driver.ts` 的 `@contract txn.read-semantics`);行在 ⇒ 同锁下锁读它的旁表行(格:执行角色、标题、置顶;行不在 = 全缺省)。
+ *     行期望带 `log` 时,同锁下读日志的 mark:长度 = 锁住的行上的 `leaf_seq`(每次追加与 `leaf_id` 同句 +1,导入 / 换装 / fork 写成条目数),
+ *     末条 = `session_event` 按 `seq` 倒序第一行(锁读)。追加者先锁这一行再插事件,所以持锁期间 mark 不动。
  *  ② 判官(行期望 → 写者身份 → 标签);不是 `write` ⇒ 回滚、一个字节不写。
- *  ③ `write` ⇒ 按 `session_id` 写(行已被本事务锁住)→ 提交。`updated_at` 不动(改名不是活动 —— 列表的新近序不变)。
+ *  ③ `write` ⇒ 补旁表行(行在不动)、按 `session_id` 写格(根行已被本事务锁住)→ 提交。`updated_at` 不动(改名不是活动 —— 列表的新近序不变)。
  * 应答行在**提交 / 回滚之后**由调用方的列表行读另读(新语句、新快照 —— 不在事务内用普通 `SELECT` 读:TiDB 悲观事务的普通读钉 `start_ts`,
  * 等锁之后会读回判定之前的旧值),再交 `settleSessionRowWrite` 复核住客。
- * 全局锁序:只锁根 `session_meta` 一行(读日志 mark 时再锁它的末条事件),不碰 `task_*`,不进放置写者「根 meta → `task_*`」锁序的后段。
+ * 全局锁序:根 `session_meta` 一行 → 它的旁表行(→ 读日志 mark 时它的末条事件),不碰 `task_*`(与旁表的每个写者同序:根行先)。
  */
 import type { SqlDriver } from "./sql-driver.js";
 import { type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type SessionRowWriteOutcome } from "../session-row.js";

package/dist/plugins/session-row-sql.js

@@ -1,3 +1,4 @@
+import { SESSION_EXT_TABLE, ensureSessionExtRowStatement } from "./session-ext-table.js";
 import { incarnationFromCell } from "../session-incarnation.js";
 import { judgeSessionRowWrite, settleSessionRowWrite, } from "../session-row.js";
 function binder(dialect) {
@@ -10,15 +11,15 @@ function binder(dialect) {
         },
     };
 }
-function lockedRowFrom(dialect, sessionId, row) {
+function lockedRowFrom(dialect, sessionId, row, ext) {
     return {
         owner: row.owner === null || row.owner === undefined ? null : String(row.owner),
         incarnation: incarnationFromCell(sessionId, row.incarnation, "absent"),
         placed: row.placement_kind !== null && row.placement_kind !== undefined,
-        mirror: row.execution_role === "mirror",
+        mirror: ext?.execution_role === "mirror",
         cells: {
-            title: row.title === null || row.title === undefined ? null : String(row.title),
-            pinned: dialect === "pg" ? row.pinned === true : Number(row.pinned) === 1,
+            title: ext?.title === null || ext?.title === undefined ? null : String(ext.title),
+            pinned: ext === undefined ? false : dialect === "pg" ? ext.pinned === true : Number(ext.pinned) === 1,
         },
     };
 }
@@ -35,9 +36,16 @@ export async function writeSessionRowCellsSql(db, sessionId, cells, how, readAns
     try {
         await conn.begin();
         const read = binder(dialect);
-        const locked = (await conn.query(`SELECT owner, incarnation, placement_kind, execution_role, title, pinned, leaf_seq FROM session_meta WHERE session_id = ${read.p(sessionId)} FOR UPDATE`, read.values)).rows[0];
+        const locked = (await conn.query(`SELECT owner, incarnation, placement_kind, leaf_seq FROM session_meta WHERE session_id = ${read.p(sessionId)} FOR UPDATE`, read.values)).rows[0];
+        const extRead = binder(dialect);
+        let ext;
+        if (locked !== undefined) {
+            const ensure = ensureSessionExtRowStatement(dialect, sessionId);
+            await conn.query(ensure.text, [...ensure.values]);
+            ext = (await conn.query(`SELECT execution_role, title, pinned FROM ${SESSION_EXT_TABLE} WHERE session_id = ${extRead.p(sessionId)} FOR UPDATE`, extRead.values)).rows[0];
+        }
         const mark = how.row.log === undefined || locked === undefined ? undefined : await lockedLogMark(conn, dialect, sessionId, locked.leaf_seq);
-        verdict = judgeSessionRowWrite(sessionId, how, locked === undefined ? undefined : lockedRowFrom(dialect, sessionId, locked), () => {
+        verdict = judgeSessionRowWrite(sessionId, how, locked === undefined ? undefined : lockedRowFrom(dialect, sessionId, locked, ext), () => {
             if (mark === undefined)
                 throw new Error(`writeSessionRowCellsSql: the judge asked session ${sessionId}'s log mark, but the expectation carries none`);
             return mark;
@@ -53,7 +61,7 @@ export async function writeSessionRowCellsSql(db, sessionId, cells, how, readAns
             if (cells.pinned !== undefined)
                 sets.push(`pinned = ${w.p(cells.pinned)}`);
             if (sets.length > 0)
-                await conn.query(`UPDATE session_meta SET ${sets.join(", ")} WHERE session_id = ${w.p(sessionId)}`, w.values);
+                await conn.query(`UPDATE ${SESSION_EXT_TABLE} SET ${sets.join(", ")} WHERE session_id = ${w.p(sessionId)}`, w.values);
             await conn.commit();
         }
     }

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

@@ -0,0 +1,131 @@
+/**
+ * **SQL 会话店 = 引擎座店 + 部署的会话格**(两方言同一只类;组合座 `store-backend.ts` 装配)。
+ *
+ * ## 两半,一只店
+ *  · **座**(`src/stores-sql/` 的方言店):引擎座表 `session_meta` / `session_event` 的唯一写者 —— 唤醒、追加、fork、导入、暂存、删除。
+ *  · **部署格**(本模块):本服务记在一只会话上的格,全部住旁表 `session_ext`(属主 `session-ext-table.ts`)—— 列表投影的标题 / 置顶 / 行标签、
+ *    换源通告的基线、位置与项目、执行放置那一格与 fork 键。读引擎座表只经它的公布列(身份、属主、化身、时刻、委派判别位);写只写旁表。
+ * 座在它的写事务里锁住根行之后调部署的**事务内钩**({@link createSqlSessionWriteHooks},契约在 `stores-sql/session-write-hooks.ts`)——
+ * 认领、本处写者、导入落 mirror、fork 键都在座的同一事务里由钩判 / 写(同事务两句:锁根行一句、钩的读写各一句)。
+ *
+ * ## 一条列表读口
+ * 列表面(`listSessions` / `listSessionRows` / `sessionSummaryOf`)是一条 SELECT、一只行映射({@link SqlSessionStore.selectListRows}):
+ * `session_meta` LEFT JOIN 旁表(标题 / 置顶;行不在 = 未命名、未置顶)LEFT JOIN run 账本的预览。两方言只差语句文本(窗函数 / `DISTINCT ON`、JSON 标量提取、
+ * LIKE 的转义字面量、布尔的读法)。
+ *
+ * ## 旁表的写序(一条,与执行放置的写序律同一条)
+ * 每个格写者在一只事务里:锁根 `session_meta` 行(行不在 ⇒ 不写)→ 补旁表行(行在不动)→ 要判格的再锁定读那一行 → 一句按 `session_id` 定址的格写。根行先 ⇒ 与座的删除 /
+ * 导入 / 换装同一锁序,外键的补行不会与删除的级联互等;补行先于锁定读 ⇒ 锁定读永远落在一行在的记录上(不拿 InnoDB 间隙锁)。
+ */
+import type { AcquiredSession, PlacedSessionRow, SessionHead, SessionPlacementRecord, SessionStore, SessionTreeEntry } from "@sema-agent/core";
+import type { TiDBSessionStore } from "../stores-sql/tidb-session-store.js";
+import type { SessionWriteHooks } from "../stores-sql/session-write-hooks.js";
+import type { SqlDriver } from "./sql-driver.js";
+import { type ExecutionPlacementSeat } from "../execution-placement.js";
+import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
+import type { SessionSummary } from "./store-contracts.js";
+import type { SessionWorkspace } from "../session-workspace.js";
+/** 座的面:座的公开成员(两方言同形 —— PG 孪生按结构赋给它,组合座里 tsc 判)。 */
+export type SessionSeat = Pick<TiDBSessionStore, "retention" | "placements" | "durability" | "acquire" | "register" | "placementOf" | "listPlaced" | "headOf" | "touch" | "release" | "forget" | "fork" | "forkTo" | "exportEntries" | "listEntryIds" | "exportEntriesStream" | "importEntries" | "replaceEntries" | "beginImportStaging" | "readStagedEntries" | "sweepStagingSessions" | "deleteSession" | "size" | "dispose">;
+/** 列表面的查询(`OwnerAwareSessionStore.listSessions` 的入参形)。 */
+export interface SessionListOptions {
+    owner?: string;
+    includeUnowned?: boolean;
+    cursor?: {
+        lastActivityAt: string;
+        sessionId: string;
+    };
+    limit: number;
+    q?: string;
+}
+/**
+ * 会话店的事务内钩(座锁住根行之后、写之前调;同一事务、同一连接):
+ *  · `import` —— 判官 {@link judgeImportWrite}(local 店的写锁内同调这一只):认领在 ⇒ 拒 `SessionActiveRunError`;这一处是写者 ⇒ 拒 `SessionWriterPresentError`;放行 ⇒ 这一格落 mirror(写者在别处);
+ *  · `delete` / `retention-delete` —— 认领在 ⇒ 拒 `SessionActiveRunError`(级联随根行带走旁表行,钩不另删);
+ *  · 键控 fork(服务扩展)—— `record`:新行的 fork 键落旁表(新行是本事务刚插下的,本事务持着它的锁);`targetOf`:撞上已在的目标时的一次池读(属主 + fork 键)。
+ */
+export declare function createSqlSessionWriteHooks(db: Pick<SqlDriver, "dialect" | "query">): SessionWriteHooks;
+export declare class SqlSessionStore implements SessionStore {
+    private readonly db;
+    /** 座(引擎座表的唯一写者)。 */
+    private readonly seat;
+    /** 托管留存声明 / placement 声明 / 耐久声明:座的声明逐字转发。 */
+    readonly retention: SessionSeat["retention"];
+    readonly placements: SessionSeat["placements"];
+    readonly durability: SessionSeat["durability"];
+    /** 执行席(规则在 `src/execution-placement.ts`;实现与语句的唯一属主 = `execution-placement-sql.ts`)。 */
+    readonly executionPlacement: ExecutionPlacementSeat;
+    /** `db` = 座的池包成的 SqlDriver(同一只池);`seatOn` 拿部署的事务内钩建座。 */
+    constructor(db: SqlDriver, seatOn: (hooks: SessionWriteHooks) => SessionSeat);
+    acquire(...a: Parameters<SessionSeat["acquire"]>): Promise<AcquiredSession>;
+    register(sessionId: string, owner: string | null): Promise<void>;
+    placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
+    listPlaced(...a: Parameters<SessionSeat["listPlaced"]>): Promise<PlacedSessionRow[]>;
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
+    touch(sessionId: string): Promise<void>;
+    release(sessionId: string): Promise<void>;
+    forget(sessionId: string): void;
+    fork(...a: Parameters<SessionSeat["fork"]>): ReturnType<SessionSeat["fork"]>;
+    forkTo(...a: Parameters<SessionSeat["forkTo"]>): ReturnType<SessionSeat["forkTo"]>;
+    exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
+    listEntryIds(sessionId: string): Promise<string[] | null>;
+    exportEntriesStream(...a: Parameters<SessionSeat["exportEntriesStream"]>): ReturnType<SessionSeat["exportEntriesStream"]>;
+    importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    beginImportStaging(...a: Parameters<SessionSeat["beginImportStaging"]>): ReturnType<SessionSeat["beginImportStaging"]>;
+    readStagedEntries(stagingId: string): Promise<SessionTreeEntry[]>;
+    sweepStagingSessions(): Promise<number>;
+    deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
+    get size(): number;
+    dispose(): void;
+    /**
+     * 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 its owner column); the side table supplies the title / pin; 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. Keyset on `(updated_at, session_id)`.
+     */
+    listSessions(opts: SessionListOptions): Promise<SessionSummary[]>;
+    /** {@link listSessions} with each row's occupant (owner + incarnation) from the same SELECT — `OwnerAwareSessionStore.listSessionRows`; the incarnation never enters the row. */
+    listSessionRows(opts: SessionListOptions): Promise<Array<SessionRowAnswer<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. */
+    sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
+    /** {@link sessionSummaryOf} 那一读 + 读到它时行上的住客(写原语的应答行要复核住客,`settleSessionRowWrite`)。 */
+    private listRowOf;
+    /**
+     * 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. Placeholders are minted in text order (run scope,
+     * then `where`, then the LIMIT), so one builder serves both dialects. `sm.incarnation` is read for the row tag and the answer row's occupant only.
+     * The run-preview JOIN: the LATEST run per session (ties broken by task_id so EXACTLY one row joins) + a count rollup; LEFT JOINs keep sessions with
+     * no runs (preview NULL, run_count 0) and sessions with no side-table row (title NULL, not pinned).
+     */
+    private selectListRows;
+    /**
+     * 会话行格写原语 —— 用户标题 / 置顶的唯一写口(规则与判序:`src/session-row.ts` 头注「写原语」;事务与语句:`session-row-sql.ts`)。应答行在提交 / 回滚之后
+     * 由列表行读另读(含新 `rowTag`)、复核仍是判过的那一位住客。只写列表面上的行(委派分区行 ⇒ `absent`);`updated_at` 不动(改名不是活动)。
+     */
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
+    /** 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 (no side-table row = untitled). */
+    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. No session row ⇒ `false`. */
+    setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /** 换源通告的基线读(一行 PK 读;列的三态读法见 `instruction-source-notice.ts`)。旁表行不在 ⇒ 读作「没记过」。语句期限 {@link BASELINE_IO_DEADLINE_MS}(过期 ⇒ 查询自己拒、连接销毁)。 */
+    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
+    /**
+     * CAS 覆写基线(期望值 = 调用方读到的那一份;不符 ⇒ 0 行、不抛 —— 契约见 `InstructionSourceStore`)。会话行不在 ⇒ 不写。**不**碰 `updated_at`。
+     * 期限:事务里每一句带语句期限 {@link BASELINE_IO_DEADLINE_MS} —— 被行锁卡住的写由查询自己在期限内拒、连接销毁(事务随连接关闭回滚,池里不留卡住的连接);
+     * 调用方的 `withinIoDeadline` 同一只数,是它那一侧的放手。
+     */
+    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
+    /** 会话行的位置与项目那一格(域律 `src/session-workspace.ts`,列属主 `session-workspace-cell.ts`)。一行 PK 读,按文本投影、恰好解一次;行不在 / 格为 NULL ⇒ `undefined`。 */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜;唯一调用方 = 腿的记录座)。**住客围栏**:只写化身仍是 `incarnation` 的那一行(锁根行时按化身收窄)—— 行不在、或同 id 已换了住客 ⇒
+     * 不写、不抛。**不**碰 `updated_at`。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
+}
+//# sourceMappingURL=session-store-sql.d.ts.map

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

@@ -0,0 +1,298 @@
+import { escapeLike } from "./sql-escape.js";
+import { jsonColumnText } from "./sql-json-column.js";
+import { pgSafeJsonStringify } from "./pg-safe-json.js";
+import { SESSION_EXT_TABLE, ensureSessionExtRowStatement } from "./session-ext-table.js";
+import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
+import { createSqlExecutionPlacementSeat, markMirrorStatement, readCellOn, readClaimOn, writeCellOn } from "./execution-placement-sql.js";
+import { SessionActiveRunError, judgeImportWrite } from "../execution-placement.js";
+import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
+import { incarnationFromCell } from "../session-incarnation.js";
+import { sessionRowTagKey } from "../session-row.js";
+import { writeSessionRowCellsSql } from "./session-row-sql.js";
+function binder(dialect) {
+    const values = [];
+    return {
+        values,
+        p: (v) => {
+            values.push(v);
+            return dialect === "pg" ? `$${values.length}` : "?";
+        },
+    };
+}
+const rowsOnTxn = (txn) => async (sql, values) => (await txn.query(sql, [...values])).rows;
+export function createSqlSessionWriteHooks(db) {
+    const dialect = db.dialect;
+    return {
+        async beforeCommit(txn, write) {
+            const rows = rowsOnTxn(txn);
+            const root = write.rootSessionId;
+            switch (write.op) {
+                case "import": {
+                    const verdict = await judgeImportWrite(root, { claim: () => readClaimOn(rows, dialect, root), cell: () => readCellOn(rows, dialect, root) });
+                    if (verdict !== "proceed")
+                        return verdict;
+                    await writeCellOn(txn, dialect, root, markMirrorStatement(dialect, root));
+                    return "proceed";
+                }
+                case "delete":
+                case "retention-delete": {
+                    const claim = await readClaimOn(rows, dialect, root);
+                    return claim === null ? "proceed" : { refuse: new SessionActiveRunError(root, claim) };
+                }
+                default: {
+                    const unknownOp = write.op;
+                    throw new Error(`session write hooks: no write ${JSON.stringify(unknownOp)}`);
+                }
+            }
+        },
+        keyedFork: {
+            async record(txn, fork) {
+                const ensure = ensureSessionExtRowStatement(dialect, fork.rootSessionId);
+                await txn.query(ensure.text, [...ensure.values]);
+                const b = binder(dialect);
+                const res = await txn.query(`UPDATE ${SESSION_EXT_TABLE} SET fork_key = ${b.p(fork.forkKey)} WHERE session_id = ${b.p(fork.rootSessionId)}`, b.values);
+                if (res.affected !== 1)
+                    throw new Error(`fork of session ${fork.rootSessionId}: the fork key write matched no row of a row this transaction just created — engine/driver anomaly, refusing to guess`);
+            },
+            async targetOf(sessionId) {
+                const b = binder(dialect);
+                const row = (await db.query(`SELECT sm.owner, se.fork_key FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE sm.session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+                if (row === undefined)
+                    return undefined;
+                return { owner: row.owner === null || row.owner === undefined ? null : String(row.owner), forkKey: row.fork_key === null || row.fork_key === undefined ? null : String(row.fork_key) };
+            },
+        },
+    };
+}
+const BASELINE_STATEMENT = { deadlineMs: BASELINE_IO_DEADLINE_MS };
+async function withLockedSessionExt(db, sessionId, lock, write) {
+    const conn = await db.connect();
+    const query = (sql, params) => conn.query(sql, params, lock.statement);
+    try {
+        await conn.begin();
+        const b = binder(db.dialect);
+        const locked = await query(`SELECT session_id FROM session_meta WHERE session_id = ${b.p(sessionId)}${lock.where === undefined ? "" : ` AND ${lock.where(b.p)}`} FOR UPDATE`, b.values);
+        if (locked.rows.length === 0) {
+            await conn.rollback();
+            return false;
+        }
+        const ensure = ensureSessionExtRowStatement(db.dialect, sessionId);
+        await query(ensure.text, [...ensure.values]);
+        const wrote = await write(query);
+        await conn.commit();
+        return wrote;
+    }
+    catch (err) {
+        await conn.rollback().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        conn.release();
+    }
+}
+const pinnedOf = (dialect, v) => (dialect === "pg" ? v === true : Number(v) === 1);
+export class SqlSessionStore {
+    db;
+    seat;
+    retention;
+    placements;
+    durability;
+    executionPlacement;
+    constructor(db, seatOn) {
+        this.db = db;
+        this.seat = seatOn(createSqlSessionWriteHooks(db));
+        this.retention = this.seat.retention;
+        this.placements = this.seat.placements;
+        this.durability = this.seat.durability;
+        this.executionPlacement = createSqlExecutionPlacementSeat(db);
+    }
+    acquire(...a) {
+        return this.seat.acquire(...a);
+    }
+    register(sessionId, owner) {
+        return this.seat.register(sessionId, owner);
+    }
+    placementOf(sessionId) {
+        return this.seat.placementOf(sessionId);
+    }
+    listPlaced(...a) {
+        return this.seat.listPlaced(...a);
+    }
+    headOf(sessionId) {
+        return this.seat.headOf(sessionId);
+    }
+    touch(sessionId) {
+        return this.seat.touch(sessionId);
+    }
+    release(sessionId) {
+        return this.seat.release(sessionId);
+    }
+    forget(sessionId) {
+        this.seat.forget(sessionId);
+    }
+    fork(...a) {
+        return this.seat.fork(...a);
+    }
+    forkTo(...a) {
+        return this.seat.forkTo(...a);
+    }
+    exportEntries(sessionId) {
+        return this.seat.exportEntries(sessionId);
+    }
+    listEntryIds(sessionId) {
+        return this.seat.listEntryIds(sessionId);
+    }
+    exportEntriesStream(...a) {
+        return this.seat.exportEntriesStream(...a);
+    }
+    importEntries(sessionId, owner, entries) {
+        return this.seat.importEntries(sessionId, owner, entries);
+    }
+    replaceEntries(sessionId, owner, entries) {
+        return this.seat.replaceEntries(sessionId, owner, entries);
+    }
+    beginImportStaging(...a) {
+        return this.seat.beginImportStaging(...a);
+    }
+    readStagedEntries(stagingId) {
+        return this.seat.readStagedEntries(stagingId);
+    }
+    sweepStagingSessions() {
+        return this.seat.sweepStagingSessions();
+    }
+    deleteSession(sessionId, owner) {
+        return this.seat.deleteSession(sessionId, owner);
+    }
+    get size() {
+        return this.seat.size;
+    }
+    dispose() {
+        this.seat.dispose();
+    }
+    async listSessions(opts) {
+        return (await this.listSessionRows(opts)).map((a) => a.row);
+    }
+    async listSessionRows(opts) {
+        const dialect = this.db.dialect;
+        return this.selectListRows({
+            limit: opts.limit,
+            where: (p) => {
+                const where = ["sm.placement_kind IS NULL"];
+                if (opts.owner !== undefined)
+                    where.push(opts.includeUnowned ? `(sm.owner = ${p(opts.owner)} OR sm.owner IS NULL)` : `sm.owner = ${p(opts.owner)}`);
+                if (opts.q) {
+                    const escape = dialect === "pg" ? "'\\'" : "'\\\\'";
+                    where.push(`EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id AND LOWER(tr.objective_preview) LIKE LOWER(${p(`%${escapeLike(opts.q)}%`)}) ESCAPE ${escape})`);
+                }
+                if (opts.cursor) {
+                    const at = new Date(opts.cursor.lastActivityAt);
+                    where.push(`(sm.updated_at < ${p(at)} OR (sm.updated_at = ${p(at)} AND sm.session_id < ${p(opts.cursor.sessionId)}))`);
+                }
+                return where;
+            },
+        });
+    }
+    async sessionSummaryOf(sessionId) {
+        return (await this.listRowOf(sessionId))?.row;
+    }
+    async listRowOf(sessionId) {
+        return (await this.selectListRows({ limit: 1, runSessionId: sessionId, where: (p) => ["sm.placement_kind IS NULL", `sm.session_id = ${p(sessionId)}`] }))[0];
+    }
+    async selectListRows(q) {
+        const dialect = this.db.dialect;
+        const b = binder(dialect);
+        const runWhere = () => (q.runSessionId !== undefined ? ` WHERE session_id = ${b.p(q.runSessionId)}` : "");
+        const runCount = `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 `;
+        const latest = dialect === "pg"
+            ? "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview, status, task_id, result ->> 'runId' AS last_task_run_id FROM task_run" +
+                runWhere() +
+                "  ORDER BY session_id, created_at DESC, task_id DESC) latest ON latest.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 ";
+        const where = q.where(b.p);
+        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, se.title, se.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 ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id ` +
+            runCount +
+            latest +
+            (where.length ? "WHERE " + where.join(" AND ") + " " : "") +
+            `ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ${b.p(q.limit)}`;
+        const rows = (await this.db.query(sql, b.values)).rows;
+        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 = pinnedOf(dialect, r.pinned);
+            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 writeSessionRowCells(sessionId, cells, how) {
+        return writeSessionRowCellsSql(this.db, sessionId, cells, how, (id) => this.listRowOf(id));
+    }
+    async probeTitle(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT se.title FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE sm.session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+        if (row === undefined)
+            return "none";
+        return row.title === null || row.title === undefined ? "untitled" : "titled";
+    }
+    async setTitleIfNull(sessionId, title) {
+        return withLockedSessionExt(this.db, sessionId, {}, async (query) => {
+            const b = binder(this.db.dialect);
+            return (await query(`UPDATE ${SESSION_EXT_TABLE} SET title = ${b.p(title)} WHERE session_id = ${b.p(sessionId)} AND title IS NULL`, b.values)).affected > 0;
+        });
+    }
+    async readInstructionSource(sessionId) {
+        const b = binder(this.db.dialect);
+        const conn = await this.db.connect();
+        try {
+            const row = (await conn.query(`SELECT instruction_source FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)}`, b.values, BASELINE_STATEMENT)).rows[0];
+            return decodeInstructionSource(row?.instruction_source);
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async recordInstructionSource(sessionId, expected, source) {
+        const next = encodeInstructionSource(source);
+        await withLockedSessionExt(this.db, sessionId, { statement: BASELINE_STATEMENT }, async (query) => {
+            const b = binder(this.db.dialect);
+            const text = `UPDATE ${SESSION_EXT_TABLE} SET instruction_source = ${b.p(next)} WHERE session_id = ${b.p(sessionId)} AND ${expected.recorded ? `instruction_source = ${b.p(encodeInstructionSource(expected.source))}` : "instruction_source IS NULL"}`;
+            return (await query(text, b.values)).affected > 0;
+        });
+    }
+    async readSessionWorkspace(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT ${jsonColumnText(this.db.dialect, "workspace")} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+        return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
+    }
+    async recordSessionWorkspace(sessionId, incarnation, workspace) {
+        const dialect = this.db.dialect;
+        const cell = encodeSessionWorkspaceCell(workspace, dialect === "pg" ? pgSafeJsonStringify : JSON.stringify, sessionId);
+        await withLockedSessionExt(this.db, sessionId, { where: (p) => `incarnation = ${p(incarnation)}` }, async (query) => {
+            const b = binder(dialect);
+            return (await query(`UPDATE ${SESSION_EXT_TABLE} SET workspace = ${b.p(cell)}${dialect === "pg" ? "::jsonb" : ""} WHERE session_id = ${b.p(sessionId)}`, b.values)).affected > 0;
+        });
+    }
+}
+//# sourceMappingURL=session-store-sql.js.map

package/dist/plugins/session-workspace-cell.d.ts

@@ -1,7 +1,7 @@
 import type { SessionWorkspace } from "../session-workspace.js";
 import { type JsonColumnReader } from "./sql-json-column.js";
-/** 列定义的唯一属主(两方言 DDL 内插它;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由建表语句生成)。 */
-export declare const SESSION_META_WORKSPACE_COLUMN: {
+/** 列定义的唯一属主(旁表建表句内插它,`session-ext-table.ts`)。 */
+export declare const SESSION_WORKSPACE_COLUMN: {
     readonly name: "workspace";
     readonly mysql: "workspace JSON NULL";
     readonly pg: "workspace JSONB";

package/dist/plugins/session-workspace-cell.js

@@ -2,7 +2,7 @@ import { PROJECT_ID_REGEX } from "@sema-agent/core";
 import { z } from "zod";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { assertJsonColumnWritable, createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem } from "./sql-json-column.js";
-export const SESSION_META_WORKSPACE_COLUMN = {
+export const SESSION_WORKSPACE_COLUMN = {
     name: "workspace",
     mysql: "workspace JSON NULL",
     pg: "workspace JSONB",
@@ -16,7 +16,7 @@ const SESSION_WORKSPACE_SHAPE = z.object({
 });
 export const readSessionWorkspaceCell = createZodColumnReader(SESSION_WORKSPACE_SHAPE);
 export const SESSION_WORKSPACE_DEGRADED = "server.session-workspace.record-degraded";
-const where = (sessionId) => `session_meta.workspace for session ${sessionId}`;
+const where = (sessionId) => `session_ext.workspace for session ${sessionId}`;
 export function encodeSessionWorkspaceCell(workspace, encode, sessionId) {
     const text = encode(workspace);
     assertJsonColumnWritable(text, readSessionWorkspaceCell, where(sessionId));

package/dist/plugins/shared-memory-store-sql.d.ts

@@ -131,6 +131,16 @@ export interface SqlSharedMemoryStoreOptions {
  * This module keeps no copy of the pattern (nor of the `__` ban): the protocol table's namespace separator is core's to spell.
  */
 export declare function assertStoreId(storeId: string): void;
+/**
+ * MINT-side org scope key admission. The rule is core's own judge ({@link isOrgScopeKey}): `org:` plus one segment spelled by core's
+ * `formatOrgScope`. This module keeps no copy of the grammar, and no width bound of its own — core's segment bound is far inside the
+ * `scope_key` column.
+ *
+ * Called only where a key ENTERS a durable row: {@link SqlSharedMemoryStore.putScopeState} and {@link SqlSharedMemoryStore.putStore}.
+ * The other write methods take the key as a FENCE against the owner already registered for the store id ({@link ownedExactly}: a byte-for-byte
+ * match, loud on a miss), so they never judge its shape: a row stored under a key this judge now refuses stays addressable — it can still be
+ * written to and deleted, which is the way out for an operator who must re-home it under a key core accepts.
+ */
 export declare function assertScopeKey(scopeKey: string): void;
 /**
  * WRITE-side document-path admission: core's own judge ({@link isSharedMemoryDocumentPath} — the SAME predicate core's listing