@sema-agent/server 7.150.0 → 7.152.0

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

@@ -22,7 +22,10 @@ const PRODUCT_COLUMNS = [
 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_KIND_COLUMN = { name: "session_kind", mysql: "session_kind VARCHAR(32) NULL", pg: `session_kind VARCHAR(32) COLLATE "C"` };
+export const SESSION_EXT_COLUMNS = [...PRODUCT_COLUMNS, ...EXECUTION_PLACEMENT_COLUMNS, CLIENT_WRITES_COLUMN, DELETING_TOKEN_COLUMN, SESSION_KIND_COLUMN];
+export const SESSION_EXT_KIND_INDEX = "idx_session_ext_kind";
+export const SESSION_EXT_INDEXES = [{ table: SESSION_EXT_TABLE, name: SESSION_EXT_KIND_INDEX, columns: [SESSION_KIND_COLUMN.name] }];
 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'";
@@ -43,6 +46,7 @@ export function sessionExtDdl(dialect, referenced) {
         `     ${key},\n` +
         SESSION_EXT_COLUMNS.map((c) => `     ${c[dialect]},\n`).join("") +
         "     PRIMARY KEY (session_id),\n" +
+        (dialect === "mysql" ? SESSION_EXT_INDEXES.map((i) => `     KEY ${i.name} (${i.columns.join(", ")}),\n`).join("") : "") +
         `     CONSTRAINT ${SESSION_EXT_FOREIGN_KEY} FOREIGN KEY (session_id) REFERENCES session_meta (session_id) ON DELETE CASCADE\n` +
         (dialect === "pg" ? "   )" : "   ) COLLATE utf8mb4_bin"));
 }

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

@@ -23,9 +23,56 @@
  *       之后这一行连同标题换了主 —— 是行的历史,不是越权写。
  * 应答不在事务内读(理由见上),所以③这一窗在;不取「事务内应答」。
  * 全局锁序:根 `session_meta` 一行 → 它的旁表行(→ 读日志 mark 时它的末条事件),不碰 `task_*`(与旁表的每个写者同序:根行先)。
+ *
+ * ## 「锁根行读住客」只有一句({@link lockSessionRootOn})
+ * 部署侧(本目录之外的 `src/stores-sql/**` 不在射程)每一个先锁根 `session_meta` 行再判 / 写的写事务都经它:行格写原语与落定段({@link lockSessionRowOn})、
+ * 执行席的写序律 ①(`execution-placement-sql.ts`)、旁表格写(`session-store-sql.ts` 的 `withLockedSessionExt`)。选择列是它们要的并集(属主 · 化身 · 委派判别位 · 叶序 · 最后活动 —— 最后一格是删除围栏的老化重判读的),
+ * 各读者按自己的读法解码同一行。
+ *
+ * ## 落定段({@link withLandedRow};律在 `landed-attendants.ts` 头注)
+ * 一只事务:{@link lockSessionRowOn}(锁根行 → 补旁表行 → 锁读格与在删令牌)→ 判官 `judgeLandedRow`(就是 `judgeSessionRowWrite` 的 `replay` 写者:行在 ∧ 非在删 ∧
+ * 非委派分区 ∧ 属主与化身整对同)→ 是 ⇒ 段体在**同一连接、同一事务**里跑各店的语句源 → 提交;不是 ⇒ 回滚、一个字节不写。死锁受害 / 仲裁输了
+ * (`SqlArbitrationLostError`:文件历史哨兵消失等)⇒ 从**段首**重来(含锁根行与判,经仓里唯一的 `retryOnDeadlock`)—— 段内不许有自己回滚重开事务的语句源。
+ */
+import type { SqlDialect, SqlDriver, SqlTxConn } from "./sql-driver.js";
+import type { SessionLogMark } from "@sema-agent/core";
+import { type SessionFace } from "../session-incarnation.js";
+import { type LockedSessionRow, type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type SessionRowWriteOutcome, type LandedOutcome } from "../session-row.js";
+/** 一条连接上的行读口(本事务的语句面:SQL 文本 + 参数 → 行)—— `SqlTxConn` / mysql2 连接 / node-pg 客户端各包一行即得。 */
+export type SessionRootRowsOn = (text: string, values: readonly unknown[]) => Promise<ReadonlyArray<Readonly<Record<string, unknown>>>>;
+/** `SqlTxConn` 的行读口。 */
+export declare function rootRowsOnTx(conn: Pick<SqlTxConn, "query">): SessionRootRowsOn;
+/**
+ * **锁根行读住客 —— 唯一一句**(头注):同一连接上 `SELECT owner, incarnation, placement_kind, leaf_seq, updated_at FROM session_meta WHERE session_id = ? FOR UPDATE`。
+ * 行不在 ⇒ `undefined`(InnoDB 可重复读下锁一只不在的键取间隙锁 —— 挡住同 id 的并发登记到本事务结束,调用方随即回滚)。读者各自解码五格。
+ */
+export declare function lockSessionRootOn(conn: SessionRootRowsOn, dialect: SqlDialect, sessionId: string): Promise<Readonly<Record<string, unknown>> | undefined>;
+/**
+ * 会话根行的部署格(SQL 会话规则店的构造参数,组合座 `store-backend.ts` 交入;店目录不认识根行与旁表,R8):`lockRoot` = 上面那一句(行在不在),
+ * `countClientWrite` = 客户端写计数的唯一一处(`session-withdraw-sql.ts`)。形由规则店的 `SessionRootSeat` 型在组合座上结构核对。
+ */
+export declare const SQL_SESSION_ROOT_SEAT: {
+    readonly lockRoot: (conn: Pick<SqlTxConn, "query">, dialect: SqlDialect, sessionId: string) => Promise<boolean>;
+    readonly countClientWrite: (conn: SqlTxConn, dialect: SqlDialect, sessionId: string) => Promise<void>;
+};
+/**
+ * 写原语与落定段的**同一前缀**(头注 ①):锁根行({@link lockSessionRootOn})→ 行在 ⇒ 写序律:先补旁表行、再锁定读它的格与在删令牌(锁定读永远落在一行在的记录上 ——
+ * InnoDB 间隙锁死锁,见 `execution-placement-sql.ts` 的 readCellOn;锁定读 = 最新已提交)→ 判官吃的形;`logMark` ⇒ 同锁下读日志的 mark。行不在 ⇒ `locked: undefined`。
+ */
+export declare function lockSessionRowOn(conn: SqlTxConn, dialect: SqlDialect, sessionId: string, opts: {
+    readonly logMark: boolean;
+}): Promise<{
+    readonly locked: LockedSessionRow | undefined;
+    readonly mark?: SessionLogMark;
+}>;
+/**
+ * **落定段**(头注「落定段」):一只事务里锁根行判住客(`landed` = 提交回执交回的那一位 / identical 臂门读的那一位 / 运行腿受理时见证的那一位 / 路由门读的那一位)→
+ * 是那一位 ⇒ `body(本事务连接)` → 提交 ⇒ `{ landed: true, value }`;不是 ⇒ 回滚 ⇒ `{ landed: false }`(一个字节没写)。`body` 抛 ⇒ 回滚、原样上抛(段体自己的拒,
+ * 例:规则收紧门)。死锁受害 / 仲裁输了 / `alsoRetry` 认的错 ⇒ 从段首整段重来(重来同样重锁、重判)。
  */
-import type { SqlDriver } from "./sql-driver.js";
-import { type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type SessionRowWriteOutcome } from "../session-row.js";
+export declare function withLandedRow<T>(db: Pick<SqlDriver, "dialect" | "connect">, sessionId: string, landed: SessionFace, body: (tx: SqlTxConn) => Promise<T>, opts?: {
+    readonly alsoRetry?: (err: unknown) => boolean;
+}): Promise<LandedOutcome<T>>;
 /**
  * 写原语(头注):一只事务里锁根行 → 判官 → 写 / 不写;提交 / 回滚之后经 `readAnswer`(调用方店的列表行读 + 行上的住客)另读应答行。
  * `db` = 店自己的池包成的 SqlDriver(连接经它的初始化);`readAnswer` 只在判官答 `write` / `changed` 时被调。

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

@@ -1,6 +1,8 @@
-import { BUMP_CLIENT_WRITES, SESSION_EXT_TABLE, ensureSessionExtRowStatement } from "./session-ext-table.js";
+import { BUMP_CLIENT_WRITES, DELETING_TOKEN_COLUMN, SESSION_EXT_TABLE, ensureSessionExtRowStatement } from "./session-ext-table.js";
 import { incarnationFromCell } from "../session-incarnation.js";
-import { judgeSessionRowWrite, settleSessionRowWrite, } from "../session-row.js";
+import { retryOnDeadlock } from "./sql-errors.js";
+import { countClientWriteOn } from "./session-withdraw-sql.js";
+import { judgeLandedRow, judgeSessionRowWrite, settleSessionRowWrite, } from "../session-row.js";
 function binder(dialect) {
     const values = [];
     return {
@@ -11,11 +13,27 @@ function binder(dialect) {
         },
     };
 }
+export function rootRowsOnTx(conn) {
+    return async (text, values) => (await conn.query(text, [...values])).rows;
+}
+export async function lockSessionRootOn(conn, dialect, sessionId) {
+    return (await conn(`SELECT owner, incarnation, placement_kind, leaf_seq, updated_at FROM session_meta WHERE session_id = ${dialect === "pg" ? "$1" : "?"} FOR UPDATE`, [sessionId]))[0];
+}
+export const SQL_SESSION_ROOT_SEAT = {
+    async lockRoot(conn, dialect, sessionId) {
+        return (await lockSessionRootOn(rootRowsOnTx(conn), dialect, sessionId)) !== undefined;
+    },
+    async countClientWrite(conn, dialect, sessionId) {
+        await countClientWriteOn(conn, dialect, sessionId);
+    },
+};
 function lockedRowFrom(dialect, sessionId, row, ext) {
+    const token = ext?.[DELETING_TOKEN_COLUMN.name];
     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,
+        deleting: token !== null && token !== undefined,
         mirror: ext?.execution_role === "mirror",
         cells: {
             title: ext?.title === null || ext?.title === undefined ? null : String(ext.title),
@@ -23,6 +41,40 @@ function lockedRowFrom(dialect, sessionId, row, ext) {
         },
     };
 }
+export async function lockSessionRowOn(conn, dialect, sessionId, opts) {
+    const root = await lockSessionRootOn(rootRowsOnTx(conn), dialect, sessionId);
+    if (root === undefined)
+        return { locked: undefined };
+    const ensure = ensureSessionExtRowStatement(dialect, sessionId);
+    await conn.query(ensure.text, [...ensure.values]);
+    const extRead = binder(dialect);
+    const ext = (await conn.query(`SELECT execution_role, title, pinned, ${DELETING_TOKEN_COLUMN.name} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${extRead.p(sessionId)} FOR UPDATE`, extRead.values)).rows[0];
+    const locked = lockedRowFrom(dialect, sessionId, root, ext);
+    return opts.logMark ? { locked, mark: await lockedLogMark(conn, dialect, sessionId, root.leaf_seq) } : { locked };
+}
+export async function withLandedRow(db, sessionId, landed, body, opts) {
+    return retryOnDeadlock(db.dialect, async () => {
+        const conn = await db.connect();
+        try {
+            await conn.begin();
+            const { locked } = await lockSessionRowOn(conn, db.dialect, sessionId, { logMark: false });
+            if (!judgeLandedRow(sessionId, landed, locked)) {
+                await conn.rollback();
+                return { landed: false };
+            }
+            const value = await body(conn);
+            await conn.commit();
+            return { landed: true, value };
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }, opts?.alsoRetry);
+}
 async function lockedLogMark(conn, dialect, sessionId, leafSeq) {
     const b = binder(dialect);
     const last = await conn.query(`SELECT entry_id FROM session_event WHERE session_id = ${b.p(sessionId)} ORDER BY seq DESC LIMIT 1 FOR UPDATE`, b.values);
@@ -35,17 +87,8 @@ export async function writeSessionRowCellsSql(db, sessionId, cells, how, readAns
     const conn = await db.connect();
     try {
         await conn.begin();
-        const read = binder(dialect);
-        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, ext), () => {
+        const { locked, mark } = await lockSessionRowOn(conn, dialect, sessionId, { logMark: how.row.log !== undefined });
+        verdict = judgeSessionRowWrite(sessionId, how, locked, () => {
             if (mark === undefined)
                 throw new Error(`writeSessionRowCellsSql: the judge asked session ${sessionId}'s log mark, but the expectation carries none`);
             return mark;

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

@@ -21,26 +21,18 @@ import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type Ses
 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 IdleSession, type IdleSessionCursor, type SessionKind, type SessionKindReading } from "../session-kind.js";
 import { type ExecutionPlacementSeat } from "../execution-placement.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
-import { type RegisterReceipt, type SessionBirth, type WithdrawOutcome } from "../session-incarnation.js";
+import { type RegisterReceipt, type SessionBirth, type SessionFace, type WithdrawOutcome } from "../session-incarnation.js";
 import { type SessionDeletionFace } from "../session-deletion.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 { SessionListQuery, SessionSummary } from "./store-contracts.js";
 import type { SessionWorkspace } from "../session-workspace.js";
 /** 座的面:座的公开成员(两方言同形 —— PG 孪生按结构赋给它,组合座里 tsc 判)。 */
 export type SessionSeat = Pick<TiDBSessionStore, "retention" | "placements" | "durability" | "acquire" | "register" | "registerWithReceipt" | "deleteSessionIf" | "placementOf" | "listPlaced" | "headOf" | "touch" | "release" | "forget" | "fork" | "forkTo" | "exportEntries" | "listEntryIds" | "exportEntriesStream" | "importEntries" | "replaceEntries" | "beginImportStaging" | "readStagedEntries" | "sweepStagingSessions" | "size" | "dispose">;
-/** 列表面的查询(`OwnerAwareSessionStore.listSessions` 的入参形)。 */
-export interface SessionListOptions {
-    owner?: string;
-    includeUnowned?: boolean;
-    cursor?: {
-        lastActivityAt: string;
-        sessionId: string;
-    };
-    limit: number;
-    q?: string;
-}
+/** 列表面的查询(`OwnerAwareSessionStore.listSessions` 的入参形;三店同一形)。 */
+export type SessionListOptions = SessionListQuery;
 /**
  * 会话店的事务内钩(座锁住根行之后、写之前调;同一事务、同一连接):
  *  · 四个词同一只判官 {@link judgeSessionWrite}(local 店的写锁内同调这一只):`erase` 只判这一行的在删令牌(不是 ⇒ 拒 `SessionDeletionSupersededError`);其余认领在 ⇒ 拒 `SessionActiveRunError`;
@@ -49,6 +41,11 @@ export interface SessionListOptions {
  *  · 键控 fork(服务扩展)—— `record`:新行的 fork 键落旁表(新行是本事务刚插下的,本事务持着它的锁);`targetOf`:撞上已在的目标时的一次池读(属主 + fork 键)。
  */
 export declare function createSqlSessionWriteHooks(db: Pick<SqlDriver, "dialect" | "query">): SessionWriteHooks;
+/**
+ * 🔴 **视图谓词的 SQL 一句**(两方言同一函数;列表 lister 与老化候选面同调 —— local 店的同一判是 `session-kind.ts` 的 `sessionKindListed`):
+ * 缺省视图(`view` 缺席)⇒ 只有无种类的行;`view` 在场 ⇒ 恰那一种。`se` = 旁表 `session_ext` 的别名(LEFT JOIN:旁表行不在 = 无种类)。
+ */
+export declare function sessionKindSql(view: SessionKind | undefined, p: (v: unknown) => string): string;
 export declare class SqlSessionStore implements SessionStore {
     private readonly db;
     /** 座(引擎座表的唯一写者)。 */
@@ -63,8 +60,10 @@ export declare class SqlSessionStore implements SessionStore {
     constructor(db: SqlDriver, seatOn: (hooks: SessionWriteHooks) => SessionSeat);
     acquire(...a: Parameters<SessionSeat["acquire"]>): Promise<AcquiredSession>;
     register(sessionId: string, owner: string | null): Promise<void>;
-    /** 出生回执面(座逐字转发;`plugins/session-birth.ts`)。 */
-    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    /** 出生回执面(座逐字转发,种类一并转 —— 漏一层 = 种类在 SQL 上静默丢;`plugins/session-birth.ts`)。 */
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: SessionKind): Promise<RegisterReceipt>;
+    /** 按 id 的种类读(`session-kind.ts` 的 `SessionKindFace`):一条 PK SELECT —— 根行的化身 + 旁表的种类(同一次读;旁表行不在 = 无种类)。不在 ⇒ `undefined`。 */
+    sessionKindOf(sessionId: string): Promise<SessionKindReading | undefined>;
     /** 条件撤回面:座的条件删除 + 本部署的判据(启用标记 / 客户端写计数 / 别的 run / 本次 run 的部署行;同一事务)。 */
     withdrawBirth(birth: SessionBirth, ownTaskId: string | undefined): Promise<WithdrawOutcome>;
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
@@ -99,6 +98,22 @@ export declare class SqlSessionStore implements SessionStore {
      * 写序与旁表的其余格写者同一条(根行 → 旁表;根行先 ⇒ 与认领事务、座的删除 / 导入同一锁序)。
      */
     private fenceDeletion;
+    /**
+     * 老化条件的锁内判({@link SessionAgeOutExpectation};调用方持根行锁、旁表行已补并锁定 —— `readDeletingTokenOn` 之后):住客仍是候选那一位 ∧ 最后活动仍早于视界
+     * ∧ 种类仍是它 ∧ 当下无活引用(与托管留存同一只谓词;认领那一腿随后由围栏自己的判官再判一次,结局 `active`)。
+     * **全部是当前读**:住客与最后活动来自根行的锁定读;种类与活引用两读也带 `FOR UPDATE` —— MySQL 协议的可重复读下普通 SELECT 读的是一份快照(TiDB:事务起点的快照),
+     * 等根行锁期间别的事务提交的待决检查点 / 子代 / workflow 行会被它漏掉;锁定读读最新提交(与托管留存执行器的候选锁读同一形)。
+     */
+    private ageOutHoldsOn;
+    /**
+     * 老化候选面(`OwnerAwareSessionStore.listIdleOfKind`;律 `src/session-kind.ts`):`session_meta` JOIN 旁表 —— 视图谓词同一只片段({@link sessionKindSql})∧ 最后活动早于视界
+     * ∧ 当下无活引用(与托管留存同一只谓词),**在删的行也交**(一次失败的自动删除撂下的在删行,两只 lister 都读不到它 —— 交给围栏:持有者已死 ⇒ 接管收完)。
+     * 最老先出,`(updated_at, session_id)` 升序 keyset 续页;走 `idx_session_ext_kind`。每读带语句期限(过期 ⇒ 这一句自己拒,调用方本拍停、下拍再来)。
+     */
+    listIdleOfKind(kind: SessionKind, idleBefore: Date, page: {
+        readonly after?: IdleSessionCursor;
+        readonly limit: number;
+    }): Promise<IdleSession[]>;
     get size(): number;
     dispose(): void;
     /**
@@ -135,9 +150,10 @@ export declare class SqlSessionStore implements SessionStore {
     /** 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>;
+    /** 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`)
+     *  AND the session row is still `landed` (the occupant the titler read at acceptance) — judged in the landed section (`withLandedRow`: lock the root row,
+     *  the row-write judge). Returns whether this call set it. No session row / another occupant / being deleted ⇒ `false`, zero bytes. */
+    setTitleIfNull(sessionId: string, title: string, landed: SessionFace): Promise<boolean>;
     /** 换源通告的基线读(一行 PK 读;列的三态读法见 `instruction-source-notice.ts`)。旁表行不在 ⇒ 读作「没记过」。语句期限 {@link BASELINE_IO_DEADLINE_MS}(过期 ⇒ 查询自己拒、连接销毁)。 */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**

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

@@ -2,7 +2,10 @@ import { uuidv7 } from "@sema-agent/core";
 import { escapeLike } from "./sql-escape.js";
 import { jsonColumnText } from "./sql-json-column.js";
 import { pgSafeJsonStringify } from "./pg-safe-json.js";
-import { DELETING_TOKEN_COLUMN, SESSION_EXT_TABLE, ensureSessionExtRowStatement, readDeletingTokenOn } from "./session-ext-table.js";
+import { DELETING_TOKEN_COLUMN, SESSION_EXT_TABLE, SESSION_KIND_COLUMN, ensureSessionExtRowStatement, readDeletingTokenOn } from "./session-ext-table.js";
+import { sessionKindFromCell } from "../session-kind.js";
+import { sessionLiveReferenceSql } from "./retention-sql.js";
+import { lockHoldSentinel } from "./retention-lane-store-sql.js";
 import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
 import { createSqlExecutionPlacementSeat, markMirrorStatement, readCellOn, readClaimOn, writeCellOn } from "./execution-placement-sql.js";
 import { judgeSessionWrite, sessionWriteTouchesCell } from "../execution-placement.js";
@@ -10,9 +13,10 @@ import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSour
 import { forkLineageOfRow, headFromRow, incarnationFromCell } from "../session-incarnation.js";
 import { CROSS_PROCESS_TAKEOVER_AFTER_MS, deletionTokenMintedAt } from "../session-deletion.js";
 import { sessionRowTagKey } from "../session-row.js";
-import { writeSessionRowCellsSql } from "./session-row-sql.js";
+import { lockSessionRootOn, withLandedRow, writeSessionRowCellsSql } from "./session-row-sql.js";
 import { bumpClientWritesOn, createSqlWithdrawJudge } from "./session-withdraw-sql.js";
 import { WITHDRAWABLE_ENTRY_TYPES } from "./session-birth.js";
+import { sealStoreClass, sealStoreObject } from "./store-boundary.js";
 const RUN_PREVIEW_PRESENT = "CHAR_LENGTH(objective_preview) > 0";
 function binder(dialect) {
     const values = [];
@@ -57,17 +61,30 @@ export function createSqlSessionWriteHooks(db) {
                 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) };
             },
         },
+        birth: {
+            async record(txn, born) {
+                const ensure = ensureSessionExtRowStatement(dialect, born.rootSessionId);
+                await txn.query(ensure.text, [...ensure.values]);
+                const b = binder(dialect);
+                const res = await txn.query(`UPDATE ${SESSION_EXT_TABLE} SET ${SESSION_KIND_COLUMN.name} = ${b.p(born.kind)} WHERE session_id = ${b.p(born.rootSessionId)}`, b.values);
+                if (res.affected !== 1)
+                    throw new Error(`registration of session ${born.rootSessionId}: the session kind write matched ${res.affected} row(s) of a row this transaction just created — engine/driver anomaly, refusing to guess`);
+            },
+        },
     };
 }
+export function sessionKindSql(view, p) {
+    return view === undefined ? `se.${SESSION_KIND_COLUMN.name} IS NULL` : `se.${SESSION_KIND_COLUMN.name} = ${p(view)}`;
+}
+const IDLE_SESSION_READ = { deadlineMs: 2_000 };
 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) {
+        const root = await lockSessionRootOn(async (text, values) => (await query(text, [...values])).rows, db.dialect, sessionId);
+        if (root === undefined || (lock.incarnation !== undefined && root.incarnation !== lock.incarnation)) {
             await conn.rollback();
             return false;
         }
@@ -90,6 +107,10 @@ const listedLineageOf = (sessionId, forkedFrom) => {
     const lineage = forkLineageOfRow(sessionId, forkedFrom, undefined);
     return lineage.forkedFrom !== undefined ? { forkedFrom: lineage.forkedFrom } : {};
 };
+const listedKindOf = (sessionId, cell) => {
+    const kind = sessionKindFromCell(sessionId, cell);
+    return kind !== undefined ? { sessionKind: kind } : {};
+};
 function holderMayBeAlive(holder, token) {
     switch (holder) {
         case "running":
@@ -123,8 +144,15 @@ export class SqlSessionStore {
     register(sessionId, owner) {
         return this.seat.register(sessionId, owner);
     }
-    registerWithReceipt(sessionId, owner) {
-        return this.seat.registerWithReceipt(sessionId, owner);
+    registerWithReceipt(sessionId, owner, kind) {
+        return this.seat.registerWithReceipt(sessionId, owner, kind);
+    }
+    async sessionKindOf(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT sm.incarnation, se.${SESSION_KIND_COLUMN.name} AS session_kind 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 { incarnation: incarnationFromCell(sessionId, row.incarnation, "absent"), kind: sessionKindFromCell(sessionId, row.session_kind) };
     }
     withdrawBirth(birth, ownTaskId) {
         const cond = {
@@ -190,7 +218,7 @@ export class SqlSessionStore {
     sweepStagingSessions() {
         return this.seat.sweepStagingSessions();
     }
-    sessionDeletion = {
+    sessionDeletion = sealStoreObject({
         fence: (sessionId, owner, opts) => this.fenceDeletion(sessionId, owner, opts),
         holds: async (sessionId, token) => {
             const b = binder(this.db.dialect);
@@ -201,21 +229,25 @@ export class SqlSessionStore {
             const rows = (await this.db.query(`SELECT sm.session_id, sm.owner, se.${DELETING_TOKEN_COLUMN.name} AS token FROM session_meta sm JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE se.${DELETING_TOKEN_COLUMN.name} IS NOT NULL ORDER BY sm.session_id`, [])).rows;
             return rows.map((r) => ({ sessionId: String(r.session_id), owner: r.owner ?? null, token: String(r.token) }));
         },
-    };
+    }, "sql-session-deletion", { fence: "exit", holds: "exit", pending: "exit" });
     async fenceDeletion(sessionId, owner, opts) {
         const dialect = this.db.dialect;
         const conn = await this.db.connect();
         try {
             await conn.begin();
             const rows = async (sql, values) => (await conn.query(sql, [...values])).rows;
-            const root = (await rows(`SELECT owner, incarnation FROM session_meta WHERE session_id = ${dialect === "pg" ? "$1" : "?"} FOR UPDATE`, [sessionId]))[0];
+            if (opts.ageOut !== undefined && (await lockHoldSentinel(conn, dialect, owner ?? ""))) {
+                await conn.rollback();
+                return undefined;
+            }
+            const root = await lockSessionRootOn(rows, dialect, sessionId);
             if (root === undefined || (root.owner ?? null) !== owner) {
                 await conn.rollback();
                 return undefined;
             }
             const held = await readDeletingTokenOn(rows, dialect, sessionId);
             if (held === null) {
-                if (opts.expect !== undefined) {
+                if (opts.expect !== undefined || (opts.ageOut !== undefined && !(await this.ageOutHoldsOn(rows, sessionId, root, opts.ageOut)))) {
                     await conn.rollback();
                     return undefined;
                 }
@@ -251,6 +283,45 @@ export class SqlSessionStore {
             conn.release();
         }
     }
+    async ageOutHoldsOn(rows, sessionId, root, ageOut) {
+        if (incarnationFromCell(sessionId, root.incarnation, "absent") !== ageOut.incarnation)
+            return false;
+        const lastActivity = root.updated_at instanceof Date ? root.updated_at : new Date(String(root.updated_at));
+        if (!(lastActivity.getTime() < ageOut.idleBefore.getTime()))
+            return false;
+        const b = binder(this.db.dialect);
+        const cell = (await rows(`SELECT ${SESSION_KIND_COLUMN.name} AS session_kind FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)} FOR UPDATE`, b.values))[0];
+        if (sessionKindFromCell(sessionId, cell?.session_kind) !== ageOut.kind)
+            return false;
+        const live = binder(this.db.dialect);
+        return (await rows(`SELECT 1 AS live FROM session_meta sm WHERE sm.session_id = ${live.p(sessionId)} AND ${sessionLiveReferenceSql(this.db.dialect)} FOR UPDATE`, live.values)).length === 0;
+    }
+    async listIdleOfKind(kind, idleBefore, page) {
+        const b = binder(this.db.dialect);
+        const where = [sessionKindSql(kind, b.p), `sm.updated_at < ${b.p(idleBefore)}`, `NOT ${sessionLiveReferenceSql(this.db.dialect)}`];
+        if (page.after !== undefined) {
+            const at = new Date(page.after.lastActivityAt);
+            where.push(`(sm.updated_at > ${b.p(at)} OR (sm.updated_at = ${b.p(at)} AND sm.session_id > ${b.p(page.after.sessionId)}))`);
+        }
+        const sql = `SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at FROM session_meta sm JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id ` +
+            `WHERE ${where.join(" AND ")} ORDER BY sm.updated_at ASC, sm.session_id ASC LIMIT ${b.p(page.limit)}`;
+        const conn = await this.db.connect();
+        try {
+            const rows = (await conn.query(sql, b.values, IDLE_SESSION_READ)).rows;
+            return rows.map((r) => {
+                const sessionId = String(r.session_id);
+                return {
+                    sessionId,
+                    owner: r.owner ?? null,
+                    incarnation: incarnationFromCell(sessionId, r.incarnation, "absent"),
+                    lastActivityAt: r.updated_at instanceof Date ? r.updated_at.toISOString() : new Date(String(r.updated_at)).toISOString(),
+                };
+            });
+        }
+        finally {
+            conn.release();
+        }
+    }
     get size() {
         return this.seat.size;
     }
@@ -265,7 +336,7 @@ export class SqlSessionStore {
         return this.selectListRows({
             limit: opts.limit,
             where: (p) => {
-                const where = ["sm.placement_kind IS NULL"];
+                const where = ["sm.placement_kind IS NULL", sessionKindSql(opts.sessionKind, p)];
                 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) {
@@ -311,7 +382,7 @@ export class SqlSessionStore {
                 runAnd() +
                 "  ) pr WHERE rn = 1) pv ON pv.session_id = sm.session_id ";
         const where = [...q.where(b.p), `se.${DELETING_TOKEN_COLUMN.name} IS NULL`];
-        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.forked_from, se.title, se.pinned, " +
+        const sql = `SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.forked_from, se.title, se.pinned, se.${SESSION_KIND_COLUMN.name} AS session_kind, ` +
             "  COALESCE(r.run_count, 0) AS run_count, pv.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 ` +
@@ -342,6 +413,7 @@ export class SqlSessionStore {
                 pinned,
                 ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
                 ...listedLineageOf(sessionId, r.forked_from),
+                ...listedKindOf(sessionId, r.session_kind),
             };
             return { row, occupant: { owner, incarnation } };
         });
@@ -356,11 +428,12 @@ export class SqlSessionStore {
             return "none";
         return row.title === null || row.title === undefined ? "untitled" : "titled";
     }
-    async setTitleIfNull(sessionId, title) {
-        return withLockedSessionExt(this.db, sessionId, {}, async (query) => {
+    async setTitleIfNull(sessionId, title, landed) {
+        const out = await withLandedRow(this.db, sessionId, landed, async (tx) => {
             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;
+            return (await tx.query(`UPDATE ${SESSION_EXT_TABLE} SET title = ${b.p(title)} WHERE session_id = ${b.p(sessionId)} AND title IS NULL`, b.values)).affected > 0;
         });
+        return out.landed && out.value;
     }
     async readInstructionSource(sessionId) {
         const b = binder(this.db.dialect);
@@ -389,10 +462,18 @@ export class SqlSessionStore {
     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) => {
+        await withLockedSessionExt(this.db, sessionId, { 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;
         });
     }
 }
+sealStoreClass(SqlSessionStore, "sql-session-store", {
+    acquire: "exit", register: "exit", registerWithReceipt: "exit", withdrawBirth: "exit", placementOf: "exit", listPlaced: "exit", headOf: "exit",
+    deletionHeadOf: "exit", touch: "exit", release: "exit", forget: "exit", fork: "exit", forkTo: "exit", exportEntries: "exit", listEntryIds: "exit",
+    exportEntriesStream: "exit", importEntries: "exit", replaceEntries: "exit", beginImportStaging: "exit", readStagedEntries: "exit",
+    sweepStagingSessions: "exit", dispose: "exit", listSessions: "exit", listSessionRows: "exit", sessionSummaryOf: "exit", writeSessionRowCells: "exit",
+    probeTitle: "exit", setTitleIfNull: "exit", readInstructionSource: "exit", recordInstructionSource: "exit", readSessionWorkspace: "exit",
+    recordSessionWorkspace: "exit", sessionKindOf: "exit", listIdleOfKind: "exit",
+});
 //# sourceMappingURL=session-store-sql.js.map

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

@@ -118,6 +118,7 @@ export declare class SqlSharedMemoryStore implements SharedMemoryStoreProvider {
      * 并发读被写者串起来,而这是会话附着的热路径)。规则少了一条:全店从此只有写方法开事务。
      */
     private readBinding;
+    /** 交给引擎的读器(快照兑现之后才拨库)—— 出店口,造对象处封(读器上的库错同样只带原码 + 稳定句)。 */
     private readerFor;
     /** One keyset window. Always the PAGED shape — a large library must never be materialized per call. */
     private listDocuments;

package/dist/plugins/shared-memory-store-sql.js

@@ -2,6 +2,7 @@ import { writeLogText } from "../observability/logger.js";
 import { isOrgScopeKey, isSharedMemoryDocumentPath, isSharedMemoryStoreId, SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
+import { sealStoreClass, sealStoreObject } from "./store-boundary.js";
 const isDupKey = isDupKeyError;
 export const SHARED_MEMORY_SCOPE_TABLE = "shared_memory_scope";
 export const SHARED_MEMORY_STORE_TABLE = "shared_memory_store";
@@ -159,10 +160,10 @@ export class SqlSharedMemoryStore {
         };
     }
     readerFor(storeId, scopeKey) {
-        return {
+        return sealStoreObject({
             list: (prefix, opts) => this.listDocuments(storeId, scopeKey, prefix, opts),
             read: (path, opts) => this.readDocument(storeId, scopeKey, path, opts),
-        };
+        }, "sql-shared-memory-reader", { list: "exit", read: "exit" });
     }
     async listDocuments(storeId, scopeKey, prefix, opts) {
         throwIfAborted(opts.signal);
@@ -363,6 +364,9 @@ export class SqlSharedMemoryStore {
         }
     }
 }
+sealStoreClass(SqlSharedMemoryStore, "sql-shared-memory-store", {
+    snapshot: "exit", putScopeState: "exit", putStore: "exit", putDocument: "exit", deleteDocument: "exit", deleteStore: "exit",
+});
 export class TiDBSharedMemoryStore extends SqlSharedMemoryStore {
     constructor(pool, authorizer, opts) {
         super(mysqlDriver(pool), authorizer, opts);

package/dist/plugins/snapshot-bucket-presence.d.ts

@@ -9,7 +9,9 @@
  * 被读成「这个空间头一回」,从空目录起;run 末的保存虽失败,报的却是一条不点名桶的 curl 404,没有一行说「桶没建」。
  *
  * ## 形(一条规则,不加特例)
- *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
+ *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`,列举前缀 = 角色行的 `probePrefix`:会话桶 = 退役快照纪元的根 `{legacyBlobRoot}`,
+ *    工作区桶 = 适配器写入的那只前缀 `<WORKSPACE_SNAPSHOT_PREFIX>/`,与适配器同一读 `workspaceSnapshotPrefixOf` —— 按前缀授列举的最小权限凭据对探针与对适配器同答;
+ *    两行各是对象存储动作表的一行 `boot-probe/*:LIST`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
  *    NoSuchBucket 的 404)⇒ **不拒**、照常起服,走登记过的 F 类兜底口 `recordFailOpen("server.snapshot-bucket.presence-unproven")`(计数 + 探针行 + 记录器的一次性 warn;
  *    三问写在该 tag 的 note 里)—— 拒启要有证据,没有证据只留痕;
  *  · 缺 = 配置好的店资源还没就绪,与「库连不上」同一类处境:在 `STORE_LOCK_WAIT_MS` 窗内重试({@link openWithinWait},同一只窗、同一只节拍、同一条窗尾规则 —— 编排里
@@ -36,6 +38,16 @@ export declare const SNAPSHOT_BUCKET_ROLES: {
         readonly defaultName: "session-snapshots";
         readonly consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)";
         readonly createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment";
+        readonly probeOp: "boot-probe/session:LIST";
+        readonly probePrefix: (store: {
+            endpoint: string;
+            bucket: string;
+            accessKey: string;
+            secretKey: string;
+            region?: string;
+            keyPrefix?: string;
+            presignTtlSec?: number;
+        }) => string;
     };
     readonly workspace: {
         readonly noun: "workspace snapshot bucket";
@@ -43,9 +55,20 @@ export declare const SNAPSHOT_BUCKET_ROLES: {
         readonly defaultName: "workspaces";
         readonly consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing";
         readonly createHint: "";
+        readonly probeOp: "boot-probe/workspace:LIST";
+        readonly probePrefix: (store: {
+            endpoint: string;
+            bucket: string;
+            accessKey: string;
+            secretKey: string;
+            region?: string;
+            keyPrefix?: string;
+            presignTtlSec?: number;
+        }) => string;
     };
 };
-/** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。 */
+/** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。
+ *  会话 blob 命名空间的认领请求(`session-blob-namespace.ts`,起服的那一次与每次删除前的重读)读同一只数:起服对快照桶的探针只有这一个上界。 */
 export declare const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10000;
 /** 缺桶的拒启句(唯一铸点)。 */
 /** @param endpoint `MINIO_ENDPOINT` 的**显示安全形**(调用方过 {@link buildDisplaySafeUrl};本函数不碰原串)。 */