@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/session-ext-table.js

@@ -0,0 +1,134 @@
+import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
+import { SESSION_WORKSPACE_COLUMN } from "./session-workspace-cell.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
+import { databaseAnswerCodesOf, isDeploymentFaultError } from "./sql-errors.js";
+export const SESSION_EXT_TABLE = "session_ext";
+export const EXECUTION_PLACEMENT_COLUMNS = [
+    { name: "execution_role", mysql: "execution_role VARCHAR(16) NULL", pg: `execution_role VARCHAR(16) COLLATE "C"` },
+    { name: "execution_lane", mysql: "execution_lane VARCHAR(32) NULL", pg: `execution_lane VARCHAR(32) COLLATE "C"` },
+    { name: "execution_device_id", mysql: "execution_device_id VARCHAR(64) NULL", pg: `execution_device_id VARCHAR(64) COLLATE "C"` },
+    { name: "execution_device_owner_tenant", mysql: "execution_device_owner_tenant VARCHAR(190) NULL", pg: `execution_device_owner_tenant VARCHAR(190) COLLATE "C"` },
+    { name: "execution_device_owner_subject", mysql: "execution_device_owner_subject VARCHAR(190) NULL", pg: `execution_device_owner_subject VARCHAR(190) COLLATE "C"` },
+    { name: "execution_placed_at", mysql: "execution_placed_at DATETIME(3) NULL", pg: "execution_placed_at TIMESTAMPTZ(3)" },
+    { name: "execution_rev", mysql: "execution_rev BIGINT NULL", pg: "execution_rev BIGINT" },
+    { name: "fork_key", mysql: "fork_key VARCHAR(255) NULL", pg: `fork_key VARCHAR(255) COLLATE "C"` },
+];
+const PRODUCT_COLUMNS = [
+    { name: "title", mysql: `title VARCHAR(${SESSION_TITLE_MAX_CHARS}) NULL`, pg: `title VARCHAR(${SESSION_TITLE_MAX_CHARS}) COLLATE "C"` },
+    { name: "pinned", mysql: "pinned BOOLEAN NOT NULL DEFAULT FALSE", pg: "pinned BOOLEAN NOT NULL DEFAULT FALSE" },
+    { name: "instruction_source", mysql: "instruction_source VARCHAR(64) NULL", pg: `instruction_source VARCHAR(64) COLLATE "C"` },
+    SESSION_WORKSPACE_COLUMN,
+];
+export const CLIENT_WRITES_COLUMN = { name: "client_writes", mysql: "client_writes BIGINT NOT NULL DEFAULT 0", pg: "client_writes BIGINT NOT NULL DEFAULT 0" };
+export const BUMP_CLIENT_WRITES = "client_writes = client_writes + 1";
+export const DELETING_TOKEN_COLUMN = { name: "deleting_token", mysql: "deleting_token VARCHAR(36) NULL", pg: `deleting_token VARCHAR(36) COLLATE "C"` };
+export const SESSION_EXT_COLUMNS = [...PRODUCT_COLUMNS, ...EXECUTION_PLACEMENT_COLUMNS, CLIENT_WRITES_COLUMN, DELETING_TOKEN_COLUMN];
+export const SESSION_EXT_MOVED_COLUMNS = [...PRODUCT_COLUMNS, ...EXECUTION_PLACEMENT_COLUMNS];
+export const SESSION_EXT_FOREIGN_KEY = "fk_session_ext_session";
+export const SESSION_META_KEY_COLLATION_PROBE = "SELECT CHARACTER_SET_NAME AS cs, COLLATION_NAME AS coll FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'session_meta' AND COLUMN_NAME = 'session_id'";
+const COLLATION_NAME_RE = /^[A-Za-z0-9_]{1,64}$/;
+export function readReferencedKeyCollation(rows) {
+    if (rows.length !== 1)
+        return undefined;
+    const row = rows[0];
+    const cs = row?.cs;
+    const coll = row?.coll;
+    return typeof cs === "string" && typeof coll === "string" && COLLATION_NAME_RE.test(cs) && COLLATION_NAME_RE.test(coll) ? { characterSet: cs, collation: coll } : undefined;
+}
+export function sessionExtDdl(dialect, referenced) {
+    if (dialect === "mysql" && referenced === undefined)
+        throw new Error("sessionExtDdl(mysql): the referenced column's character set and collation are required (the foreign key column copies them)");
+    const key = dialect === "pg" ? `session_id  VARCHAR(64) COLLATE "C" NOT NULL` : `session_id  VARCHAR(64) CHARACTER SET ${referenced.characterSet} COLLATE ${referenced.collation} NOT NULL`;
+    return (`CREATE TABLE IF NOT EXISTS ${SESSION_EXT_TABLE} (\n` +
+        `     ${key},\n` +
+        SESSION_EXT_COLUMNS.map((c) => `     ${c[dialect]},\n`).join("") +
+        "     PRIMARY KEY (session_id),\n" +
+        `     CONSTRAINT ${SESSION_EXT_FOREIGN_KEY} FOREIGN KEY (session_id) REFERENCES session_meta (session_id) ON DELETE CASCADE\n` +
+        (dialect === "pg" ? "   )" : "   ) COLLATE utf8mb4_bin"));
+}
+export class SessionExtTableRefusedError extends StoreBootRefusalError {
+    code = SCHEMA_MISMATCH_ERROR_CODE;
+    constructor(detail) {
+        super(`${SCHEMA_MISMATCH_ERROR_CODE}: this MySQL-protocol database cannot create table ${SESSION_EXT_TABLE} — refusing to start. ${detail} ` +
+            `The table's foreign key ${SESSION_EXT_FOREIGN_KEY} references session_meta (session_id) with ON DELETE CASCADE; its key column copies the character set and collation of session_meta.session_id. ` +
+            "Next: fix session_meta so that foreign key can be formed — on MySQL it must be an InnoDB table (foreign keys need InnoDB on both sides), and session_id must be a character column " +
+            "and its PRIMARY KEY or a UNIQUE key (MySQL 9.x refuses a foreign key to a non-unique column with errno 6125); on TiDB foreign keys need v6.6.0 or later; the account needs the CREATE grant. " +
+            "This is the database's definite answer, so waiting or changing the MYSQL_* coordinates will not change it. This check changed nothing in the database.");
+        this.name = "SessionExtTableRefusedError";
+    }
+}
+export async function ensureSessionExtTableMysql(query) {
+    const rows = await query(SESSION_META_KEY_COLLATION_PROBE);
+    const referenced = readReferencedKeyCollation(rows);
+    if (referenced === undefined) {
+        throw new SessionExtTableRefusedError(`Reading the character set and collation of session_meta.session_id from information_schema.COLUMNS gave ${rows.length} row(s) without two readable names, so the foreign key column cannot be declared to match it.`);
+    }
+    try {
+        await query(sessionExtDdl("mysql", referenced));
+    }
+    catch (err) {
+        if (!isDeploymentFaultError(err))
+            throw err;
+        const { sqlMessage: said } = err;
+        const sentence = typeof said === "string" ? said : err instanceof Error ? err.message : String(err);
+        const codes = databaseAnswerCodesOf("mysql", err);
+        throw new SessionExtTableRefusedError(`The foreign key column was declared CHARACTER SET ${referenced.characterSet} COLLATE ${referenced.collation} (read from session_meta.session_id); the database answered: ${sentence.split(/\r?\n/, 1)[0] ?? ""}${codes !== undefined ? ` (${codes})` : ""}.`);
+    }
+}
+export function ensureSessionExtRowStatement(dialect, sessionId) {
+    return { text: `INSERT INTO ${SESSION_EXT_TABLE} (session_id) VALUES (${dialect === "pg" ? "$1" : "?"}) ${ensureConflictClause(dialect)}`, values: [sessionId] };
+}
+export function ensureSessionExtRowsStatement(dialect, selectSessionIds) {
+    return { text: `INSERT INTO ${SESSION_EXT_TABLE} (session_id) SELECT picked.session_id FROM (${selectSessionIds}) picked ${ensureConflictClause(dialect)}`, values: [] };
+}
+function ensureConflictClause(dialect) {
+    return dialect === "pg" ? "ON CONFLICT (session_id) DO NOTHING" : "ON DUPLICATE KEY UPDATE pinned = pinned";
+}
+export const SESSION_EXT_CASCADE_REFUSED_CODE = "config.session_ext_cascade_absent";
+export class SessionExtCascadeAbsentError extends StoreBootRefusalError {
+    dialect;
+    code = SESSION_EXT_CASCADE_REFUSED_CODE;
+    constructor(dialect) {
+        super(`${SESSION_EXT_CASCADE_REFUSED_CODE}: on this ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database, deleting a session row did not delete its ${SESSION_EXT_TABLE} row ` +
+            `(the foreign key ${SESSION_EXT_FOREIGN_KEY} … ON DELETE CASCADE is not enforced) — refusing to start: a session id registered again would inherit the previous occupant's ` +
+            "title, pin, instruction baseline and execution placement. " +
+            (dialect === "pg"
+                ? "Check that the constraint exists on the table (it is created with the table) and that no session_replication_role / trigger setting disables it."
+                : "On TiDB, foreign keys are enforced from v6.6.0 with the session variable foreign_key_checks=ON (the default; a DSN or global setting may turn it OFF); " +
+                    `on MySQL, the table must be InnoDB. If the table was created while foreign keys were not enforced, drop the (empty) ${SESSION_EXT_TABLE} table and start again.`));
+        this.dialect = dialect;
+        this.name = "SessionExtCascadeAbsentError";
+    }
+}
+const CASCADE_PROBE_ID = "~session-ext-cascade-probe";
+export async function assertSessionExtCascadeOn(db) {
+    const conn = await db.connect();
+    try {
+        await conn.begin();
+        const p = db.dialect === "pg" ? (n) => `$${n}` : () => "?";
+        const now = new Date();
+        await conn.query(`INSERT INTO session_meta (session_id, created_at, updated_at) VALUES (${p(1)}, ${p(2)}, ${p(3)})`, [CASCADE_PROBE_ID, now, now]);
+        const ensure = ensureSessionExtRowStatement(db.dialect, CASCADE_PROBE_ID);
+        await conn.query(ensure.text, [...ensure.values]);
+        await conn.query(`DELETE FROM session_meta WHERE session_id = ${p(1)}`, [CASCADE_PROBE_ID]);
+        const left = await conn.query(`SELECT session_id FROM ${SESSION_EXT_TABLE} WHERE session_id = ${p(1)}`, [CASCADE_PROBE_ID]);
+        await conn.rollback();
+        if (left.rows.length !== 0)
+            throw new SessionExtCascadeAbsentError(db.dialect);
+    }
+    catch (err) {
+        await conn.rollback().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        conn.release();
+    }
+}
+export async function readDeletingTokenOn(conn, dialect, sessionId) {
+    const ensure = ensureSessionExtRowStatement(dialect, sessionId);
+    await conn(ensure.text, ensure.values);
+    const row = (await conn(`SELECT ${DELETING_TOKEN_COLUMN.name} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${dialect === "pg" ? "$1" : "?"} FOR UPDATE`, [sessionId]))[0];
+    const token = row?.[DELETING_TOKEN_COLUMN.name];
+    return token === null || token === undefined ? null : String(token);
+}
+//# sourceMappingURL=session-ext-table.js.map

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

@@ -14,14 +14,28 @@
  *
  * ## fork 续写的店契约(本文件下半)
  * 三店同一只私有体 `forkTo(sourceId, owner, target)`:目标行原子新建(唯一创建点)· 撞已在按属主与 fork 键分类({@link classifyForkTarget})·
- * local 崩溃中间态 `forking` 只许同键重试补齐 · fork 键此后每个写携带(整段换装经 `carriedRowCells`)。core 契约 `fork(sourceId, owner?, opts?)` = {@link forkByFreshId}。
+ * local 崩溃中间态 `forking` 只许同键重试补齐 · fork 键此后每个写携带(整段换装:local 经 `carriedRowCells`,SQL 就地改写、旁表行不动)。core 契约 `fork(sourceId, owner?, opts?)` = {@link forkByFreshId}。
  *
  * ## fork 进委派分区(core `SessionStore.fork` 的 `opts.placement`)
  * fork 的创建那一笔就是一次建行:带元组的 fork 与带 placement 的 acquire 落**同一组**元组(六列 / 存档行头,first-write 不可变,`placedAt` 由店铸),
  * 此后这一行欠 placed 行的每一条义务(不上宿主列表 · claim 形 acquire 拒 · 进分区枚举 · release = 真删除)。元组不带属主:行的属主仍是 fork 的属主参数
  * 按 `forkOwnerOf` 的那一读(core 句:元组没有属主)。没声明分区的店照常 fork、不落元组(core 句:忽略合法,拒 fork 不合法)。
+ *
+ * ## fork 谱系(三店同一读法)
+ * fork 行的谱系两格 = core `forkRowCells` 从**源行**(fork 那一刻,建行之前那一读)铸出的 `forkedFrom`(源 id)与 `forkedFromIncarnation`(源行那一刻的住客令牌;
+ * 源行没有令牌 ⇒ 缺)—— 三店的建行都读 `forkRowCells`,本仓不写第二份谱系读法。两格落在**行上**(SQL:`session_meta` 的两列,列定义属主 `session-incarnation.ts` 的 `SESSION_META_LINEAGE_COLUMNS`;
+ * local:会话元数据边档那一格的两位),同一笔写;交出的会话元数据与列表行(`forkedFrom`)从行上读回(`session-incarnation.ts` 的 `forkLineageOfRow`)。
+ * 缺 = 不是 fork 建的行,或谱系落地之前建的 fork(源已不可知,不回填)。属主不读 `forkRowCells` 那一格:本仓的 fork 属主律是 `forkOwnerOf`(差异见 `test/session-incarnation.test.ts` 的对拍格)。
+ * **一只 fork 拷一代源**:谱系的住客那一半说的就是拷贝所读的那一代。源在这一次 fork 的几次读之间换了代(删掉后同 id 重建 —— 令牌永不复现)⇒ 这一次 fork 读到的不是一代源,
+ * 与「源不在」同答(`null`,零写):SQL 两孪生在叶 / 属主那一读、唤醒、整日志读之后各问一次住客({@link sameSourceGeneration});local 店的首次拷贝在源的写锁里读(一代),
+ * 崩在格与拷贝之间的同键补拷照这一律比格上记下的来源住客与此刻的源。
  */
 import { type ForkPoint, type ForkRowShape, type SessionStorage, type SessionStore } from "@sema-agent/core";
+/**
+ * SQL 两孪生 fork 的「一代源」判(见头注「一只 fork 拷一代源」):唤醒交出的源住客(`woke`)与整日志读之前、之后两次读到的那一格(`before` / `after`,行上原值;行不在 ⇒ `undefined`)
+ * 三者相同才是一代 —— 令牌永不复现,首尾两读与唤醒同 ⇒ 夹在中间的整日志读读的也是这一代。不是一代 ⇒ 调用方按「源不在」答。
+ */
+export declare function sameSourceGeneration(woke: string | undefined, before: unknown, after: unknown): boolean;
 /** 问引擎:这只(已唤醒的)源会话从哪里拷。SQL 孪生用它;local 店手里就是引擎的 `Session`,直接调 `settledForkOptions`。 */
 export declare function forkPointOf(storage: SessionStorage): Promise<ForkPoint>;
 /** 两只 SQL 孪生整份日志里的一行(两孪生选同一组列):父链两键交引擎挑行,其余三列原样搬进新会话、不读内容。 */
@@ -40,7 +54,7 @@ export declare const FORK_LOG_ROW_SHAPE: ForkRowShape<ForkLogRow>;
 /**
  * fork 进委派分区时落的元组 —— core `SessionStore.fork` 第三参 `opts.placement` 的那一形,**直接取 core 的型、不复述**(core 当前写作 `SessionPlacement` 去掉属主:行的属主是
  * fork 的属主参数的那一读)。本仓里这个元组型只有这一处定义:三店(local · pg · tidb)、路由店、`forkByFreshId`、引擎面声明的 fork 形参,以及建行绑定值
- * `placementInsertValues`(`session-placement.ts`)都读它 —— core 再改 `fork` 的第三参,型面在这里一处跟着动(`SessionStore.fork` 是可选成员,所以取参数前先 `NonNullable`)。
+ * `placementInsertCells`(`session-placement.ts`)都读它 —— core 再改 `fork` 的第三参,型面在这里一处跟着动(`SessionStore.fork` 是可选成员,所以取参数前先 `NonNullable`)。
  */
 export type ForkPlacement = NonNullable<NonNullable<Parameters<NonNullable<SessionStore["fork"]>>[2]>["placement"]>;
 /**

package/dist/plugins/session-fork.js

@@ -1,5 +1,8 @@
 import { SessionError, StoredSession, settledForkOptions, uuidv7 } from "@sema-agent/core";
 import { createHash } from "node:crypto";
+export function sameSourceGeneration(woke, before, after) {
+    return woke !== undefined && before === woke && after === woke;
+}
 export async function forkPointOf(storage) {
     return settledForkOptions(new StoredSession(storage));
 }

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

@@ -7,7 +7,7 @@ export declare const NOT_A_PRINCIPAL_NAME = "a string that names nobody (empty,
  * 「这个值能不能作一只会话行的属主格」—— core 7.56.0 [ref] 起只有一只判官 `principalNameOf`:主体名(有可见内容、不含控制 / 分隔 / 非连接符格式字符,
  * 原样保存不规整)或 `null`(匿名)。空串、空白串、带不可见字符的串与一切非串都不是属主(它们谁也不指 —— 读成匿名会放行每一位主体)。
  *
- * 边界同判官:HTTP 请求带来的主体在鉴权边界已经过同一只 `principalNameOf`(`security.ts` `principalShapeProblem` 的 `not_a_name`,7.137.0)⇒
+ * 边界同判官:HTTP 请求带来的主体在鉴权边界已经过同一只 `principalNameOf`(`principal-shape.ts` `principalShapeProblem` 的 `not_a_name`,7.137.0)⇒
  * 经过边界的请求到不了这里的拒臂;这里是纵深(嵌入方直调店、别的写者),规则只有引擎那一只,不在本仓另写。
  */
 export declare function isSessionOwnerValue(owner: unknown): owner is string | null;

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

@@ -22,7 +22,7 @@
  *
  * 本仓成文教训(`memory-origin-law.ts` 顶注同族、`key-resolver.ts` 顶注「链只有一条」):两支方言各
  * 抄一份准入判据,迟早在某一支上少一个分支——而少掉的那一支**没有任何报错面**,表现只是「这台机器上
- * 一个陌生人可以把自己接到别人子代的转录上」。所以准入判据(两个方向)、列名、行→元组的映射都在
+ * 一个陌生人可以把自己接到别人子代的转录上」。所以准入判据(两个方向)、列名(读侧投影与写侧建行同一张表)、行→元组的映射都在
  * 这一处;两支后端只负责在自己的 I/O 点上调用它。
  *
  * ## 判据的两个方向(缺一不可,core `TtlSessionStore.assertPlacementAdmission` 的镜像)
@@ -64,20 +64,19 @@ export declare const SESSION_PLACEMENTS: {
     };
 };
 /**
- * `session_meta` 上承载 placement 元组的六列,**两方言同名**(单点定义:列名手抄两份必漂,而漂掉的
- * 那一支只会表现为「这台机器上 placed 行读不出来」——静默,不报错)。
+ * `session_meta` 上承载 placement 元组的六列,**两方言同名** —— 列名只住这一张表:读侧投影 {@link PLACEMENT_SELECT_COLUMNS}、行形
+ * {@link PlacementColumns}、写侧建行的列段与绑定值 {@link placementInsertCells} 都从它派生,源码里没有第二份手写列表
+ * (列名手抄一份必漂,而漂掉的那一支只会表现为「这台机器上 placed 行读不出来」—— 静默,不报错)。
  * `placed_at` 是 GC 的年龄锚(core `PlacedSessionRow.placedAt`);其余五列是元组本身。
  */
-export declare const PLACEMENT_SELECT_COLUMNS = "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at";
-/** 一行 `session_meta` 的 placement 列(两方言的驱动都把列名原样带回,故一份形)。 */
-export interface PlacementColumns {
-    placement_kind?: unknown;
-    placement_scope?: unknown;
-    placement_parent_session_id?: unknown;
-    placement_root_session_id?: unknown;
-    placement_handle?: unknown;
-    placed_at?: unknown;
-}
+declare const PLACEMENT_COLUMN_NAMES: readonly ["placement_kind", "placement_scope", "placement_parent_session_id", "placement_root_session_id", "placement_handle", "placed_at"];
+type PlacementColumnName = (typeof PLACEMENT_COLUMN_NAMES)[number];
+/** 读侧投影:六列按表序逗号拼接(`SELECT …, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta …`)。 */
+export declare const PLACEMENT_SELECT_COLUMNS: string;
+/** 一行 `session_meta` 的 placement 列(两方言的驱动都把列名原样带回,故一份形;键集 = 那张表)。 */
+export type PlacementColumns = {
+    [K in PlacementColumnName]?: unknown;
+};
 /**
  * 行 → 持久化的 placement 元组(`undefined` = 这是一只普通会话)。
  *
@@ -94,9 +93,15 @@ 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。读的只是元组(属主不在元组里 —— 它是行的属主格,建行那一笔另记):
- *  带 placement 的 acquire 与带元组的 fork 两个建行点同调。 */
-export declare function placementInsertValues(placement: ForkPlacement | undefined, placedAt: Date): [string | null, string | null, string | null, string | null, string | null, Date | null];
+/** 建行 INSERT 的放置六列:列段与绑定值出自同一张表、同序(调用方把 `columns` 接在自己的列之后、`values` 接在自己的绑定值之后,占位符按方言自写)。 */
+export interface PlacementInsertCells {
+    /** 列段(= {@link PLACEMENT_SELECT_COLUMNS}:读写同一张表)。 */
+    readonly columns: string;
+    /** 与 `columns` 同序的六个绑定值;无 placement ⇒ 六个 NULL。 */
+    readonly values: readonly (string | Date | null)[];
+}
+/** 写侧唯一导出:创建时一次落行的放置列与绑定值。两店(PG / MySQL 协议)的两个建行点 —— 带 placement 的 acquire、带元组的 fork —— 同调这一只。 */
+export declare function placementInsertCells(placement: ForkPlacement | undefined, placedAt: Date): PlacementInsertCells;
 /** `acquire` 的 opts 面(core `SessionStore.acquire` 的第二参,窄成本模块要判的两键)。 */
 export interface PlacementAcquireOpts {
     requireExisting?: boolean;
@@ -123,4 +128,5 @@ export declare function placementCapabilityOf(store: {
  * 接着收」,而不是「有些行永远看不见」。判据消费方(core 的分区收割腿)本就是每 tick 重新枚举的。
  */
 export declare const LIST_PLACED_BATCH = 1000;
+export {};
 //# sourceMappingURL=session-placement.d.ts.map

package/dist/plugins/session-placement.js

@@ -1,7 +1,8 @@
 import { SessionError } from "@sema-agent/core";
 export const SESSION_DURABILITY = "durable";
 export const SESSION_PLACEMENTS = { subagent: { durability: SESSION_DURABILITY } };
-export const PLACEMENT_SELECT_COLUMNS = "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at";
+const PLACEMENT_COLUMN_NAMES = ["placement_kind", "placement_scope", "placement_parent_session_id", "placement_root_session_id", "placement_handle", "placed_at"];
+export const PLACEMENT_SELECT_COLUMNS = PLACEMENT_COLUMN_NAMES.join(", ");
 function toEpochMs(v) {
     if (v == null)
         return undefined;
@@ -34,17 +35,19 @@ export function placedRowFromRow(sessionId, row, lastActivityMs) {
         ? { sessionId, placedAt, scope, handle }
         : { sessionId, placedAt, tupleIncomplete: true };
 }
-export function placementInsertValues(placement, placedAt) {
-    if (placement === undefined)
-        return [null, null, null, null, null, null];
-    return [
-        placement.kind,
-        placement.scope ?? null,
-        placement.parentSessionId ?? null,
-        placement.rootSessionId ?? null,
-        placement.handle ?? null,
-        placedAt,
-    ];
+const PLACEMENT_CELL_OF = {
+    placement_kind: (p) => p.kind,
+    placement_scope: (p) => p.scope ?? null,
+    placement_parent_session_id: (p) => p.parentSessionId ?? null,
+    placement_root_session_id: (p) => p.rootSessionId ?? null,
+    placement_handle: (p) => p.handle ?? null,
+    placed_at: (_p, placedAt) => placedAt,
+};
+export function placementInsertCells(placement, placedAt) {
+    return {
+        columns: PLACEMENT_SELECT_COLUMNS,
+        values: PLACEMENT_COLUMN_NAMES.map((column) => (placement === undefined ? null : PLACEMENT_CELL_OF[column](placement, placedAt))),
+    };
 }
 export function placementCapabilityOf(store) {
     return { subagentPlacement: store.placements?.subagent !== undefined };

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

@@ -1,22 +1,35 @@
 /**
- * **会话行格写原语的 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_*`」锁序的后段。
+ *
+ * ## 结局 `absent` 的三种去向(一个词不说「写没写」)
+ * 调用方把 `absent` 答成「无此会话」(PATCH = 404),但**写落没落**按住客是在哪一刻对不上的分三种(契约「会话行可写位」一节 `PATCH` 一行同表):
+ *  ① 判官在锁下答 `absent`(行期望不中 / 没有行 / 委派分区行):回滚,一个字节没写;
+ *  ② 判官答 `changed`(行标签不中,回滚,一个字节没写),回滚之后另读应答行时那一行已换了住客、或读不到:仍是 `absent` 而不是 `changed`
+ *     (应答行属于另一位住客,不交给这位调用方),写同样一个字节没落;
+ *  ③ 判官答 `write`、事务**已提交**,提交之后另读应答行时那一行才换了住客:
+ *     · 会话被删(之后同一 id 被重新登记与否)⇒ 这一笔写随旧行的 `ON DELETE CASCADE` 一并删掉(级联是旁表的承重前提:`session-ext-table.ts` 头注、起服级联探针),重新登记的新住客的标题 / 置顶是缺省;
+ *     · 只换了属主、化身没变(同一化身被认领 / 同步重戳)⇒ 这一笔写**留在那一行上**:写落下那一刻判官判过的那位住客仍是行主(两笔都先锁根行、串行),
+ *       之后这一行连同标题换了主 —— 是行的历史,不是越权写。
+ * 应答不在事务内读(理由见上),所以③这一窗在;不取「事务内应答」。
+ * 全局锁序:根 `session_meta` 一行 → 它的旁表行(→ 读日志 mark 时它的末条事件),不碰 `task_*`(与旁表的每个写者同序:根行先)。
  */
 import type { SqlDriver } from "./sql-driver.js";
 import { type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type SessionRowWriteOutcome } from "../session-row.js";
 /**
  * 写原语(头注):一只事务里锁根行 → 判官 → 写 / 不写;提交 / 回滚之后经 `readAnswer`(调用方店的列表行读 + 行上的住客)另读应答行。
  * `db` = 店自己的池包成的 SqlDriver(连接经它的初始化);`readAnswer` 只在判官答 `write` / `changed` 时被调。
+ * 结局 `absent` 并不都是「一个字节没写」:判官在锁下答 `absent` / 答 `changed` 之后应答复核对不上,都是零写;答 `write` 且已提交之后应答复核对不上,写已落(去向见头注)。
  */
 export declare function writeSessionRowCellsSql<Row>(db: Pick<SqlDriver, "dialect" | "connect">, sessionId: string, cells: SessionRowPatch, how: SessionRowWrite, readAnswer: (sessionId: string) => Promise<SessionRowAnswer<Row> | undefined>): Promise<SessionRowWriteOutcome<Row>>;
 //# sourceMappingURL=session-row-sql.d.ts.map

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

@@ -1,3 +1,4 @@
+import { BUMP_CLIENT_WRITES, 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;
@@ -52,8 +60,8 @@ export async function writeSessionRowCellsSql(db, sessionId, cells, how, readAns
                 sets.push(`title = ${w.p(cells.title)}`);
             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);
+            sets.push(BUMP_CLIENT_WRITES);
+            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-run-rollup.d.ts

@@ -0,0 +1,29 @@
+/**
+ * run 账里「每会话的 run 投影」的**唯一 JS 规则**({@link SessionRunRollup} 的五位)—— 文件 / 内存两只 run 店的窄读面
+ * (`SessionRunRollupSource.sessionRunRollups`)都调这一只;SQL 侧是会话店列表投影里的子查询文本(`plugins/session-store-sql.ts` 的 `selectListRows`),
+ * 两侧由同一张用例表钉同读数(`test/helpers/session-preview-cases.ts`)。
+ *
+ * 律:
+ *  · 排序口径 `created_at DESC, task_id DESC`(与 SQL 的 rn=1 窗函数 / `DISTINCT ON` 逐字同一句);
+ *  · `runCount` = 全部行数;`lastStatus` / `lastRunId` / `lastTaskRunId` = 最新一条(rn=1)的状态 / task_id / `result.runId`(非空串才铸键);
+ *  · `objectivePreview` = 同一排序下第一条「预览列是串且 `length > 0`」的那一列,没有 ⇒ `null` —— 按字符长度判,不按与 `""` 比较
+ *    (只空格的老值 `" "` 算有;SQL 侧 `CHAR_LENGTH(…) > 0` 同读,`<> ''` 在 PAD SPACE 排序规则下会把它当空);
+ *  · `q`(非空)⇒ 只交「有一条行的预览列含 q」的会话(两边转小写后按字面包含;SQL 侧 `LOWER(…) LIKE LOWER(…)` + `ESCAPE`)。
+ *
+ * 单遍、不排序、不把一只会话的行展开成函数实参(一只会话的行数没有上界:展开约 12.5 万条就是 `RangeError`,而 local 列表读的是全账)。
+ */
+import type { SessionRunRollup } from "./store-contracts.js";
+/** 一条 run 行在本规则眼里的六格(两只店的行形结构上都满足它)。`objectivePreview` 可缺席(公开快照之前写下、没有这一键的 run.json)= 不是串 ⇒ 跳过。 */
+export interface SessionRunRollupRow {
+    readonly sessionId: string;
+    readonly taskId: string;
+    readonly createdAt: Date;
+    readonly status: string;
+    readonly objectivePreview?: string | null;
+    readonly result: unknown;
+}
+/** 一次读的结果:有 run 行的每只会话 → 五位;`q` 非空 ⇒ 只留命中的会话。 */
+export declare function buildSessionRunRollups(rows: Iterable<SessionRunRollupRow>, opts?: {
+    readonly q?: string;
+}): ReadonlyMap<string, SessionRunRollup>;
+//# sourceMappingURL=session-run-rollup.d.ts.map

package/dist/plugins/session-run-rollup.js

@@ -0,0 +1,40 @@
+const newer = (a, b) => {
+    const ta = a.createdAt.getTime();
+    const tb = b.createdAt.getTime();
+    return ta > tb || (ta === tb && a.taskId > b.taskId);
+};
+const hasPreview = (r) => typeof r.objectivePreview === "string" && r.objectivePreview.length > 0;
+export function buildSessionRunRollups(rows, opts = {}) {
+    const needle = opts.q ? opts.q.toLowerCase() : undefined;
+    const acc = new Map();
+    for (const r of rows) {
+        const hit = needle !== undefined && typeof r.objectivePreview === "string" && r.objectivePreview.toLowerCase().includes(needle);
+        const cur = acc.get(r.sessionId);
+        if (cur === undefined) {
+            acc.set(r.sessionId, { count: 1, latest: r, withPreview: hasPreview(r) ? r : undefined, hit });
+            continue;
+        }
+        cur.count += 1;
+        if (newer(r, cur.latest))
+            cur.latest = r;
+        if (hasPreview(r) && (cur.withPreview === undefined || newer(r, cur.withPreview)))
+            cur.withPreview = r;
+        if (hit)
+            cur.hit = true;
+    }
+    const out = new Map();
+    for (const [sessionId, a] of acc) {
+        if (needle !== undefined && !a.hit)
+            continue;
+        const runId = a.latest.result?.runId;
+        out.set(sessionId, {
+            runCount: a.count,
+            lastStatus: a.latest.status,
+            lastRunId: a.latest.taskId,
+            ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
+            objectivePreview: a.withPreview?.objectivePreview ?? null,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=session-run-rollup.js.map