@sema-agent/server 7.147.0 → 7.148.0

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

@@ -4,7 +4,7 @@
  * ## 两半,一只店
  *  · **座**(`src/stores-sql/` 的方言店):引擎座表 `session_meta` / `session_event` 的唯一写者 —— 唤醒、追加、fork、导入、暂存、删除。
  *  · **部署格**(本模块):本服务记在一只会话上的格,全部住旁表 `session_ext`(属主 `session-ext-table.ts`)—— 列表投影的标题 / 置顶 / 行标签、
- *    换源通告的基线、位置与项目、执行放置那一格与 fork 键。读引擎座表只经它的公布列(身份、属主、化身、时刻、委派判别位);写只写旁表。
+ *    换源通告的基线、位置与项目、执行放置那一格与 fork 键。读引擎座表只经它的公布列(身份、属主、化身、时刻、委派判别位、fork 谱系的源 id);写只写旁表。
  * 座在它的写事务里锁住根行之后调部署的**事务内钩**({@link createSqlSessionWriteHooks},契约在 `stores-sql/session-write-hooks.ts`)——
  * 认领、本处写者、导入落 mirror、fork 键都在座的同一事务里由钩判 / 写(同事务两句:锁根行一句、钩的读写各一句)。
  *
@@ -17,17 +17,19 @@
  * 每个格写者在一只事务里:锁根 `session_meta` 行(行不在 ⇒ 不写)→ 补旁表行(行在不动)→ 要判格的再锁定读那一行 → 一句按 `session_id` 定址的格写。根行先 ⇒ 与座的删除 /
  * 导入 / 换装同一锁序,外键的补行不会与删除的级联互等;补行先于锁定读 ⇒ 锁定读永远落在一行在的记录上(不拿 InnoDB 间隙锁)。
  */
-import type { AcquiredSession, PlacedSessionRow, SessionHead, SessionPlacementRecord, SessionStore, SessionTreeEntry } from "@sema-agent/core";
+import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionPlacementRecord, type SessionStore, type 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 RegisterReceipt, type SessionBirth, 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 { 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">;
+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;
@@ -41,8 +43,9 @@ export interface SessionListOptions {
 }
 /**
  * 会话店的事务内钩(座锁住根行之后、写之前调;同一事务、同一连接):
- *  · `import` —— 判官 {@link judgeImportWrite}(local 店的写锁内同调这一只):认领在 ⇒ 拒 `SessionActiveRunError`;这一处是写者 ⇒ 拒 `SessionWriterPresentError`;放行 ⇒ 这一格落 mirror(写者在别处);
- *  · `delete` / `retention-delete` —— 认领在 ⇒ 拒 `SessionActiveRunError`(级联随根行带走旁表行,钩不另删);
+ *  · 四个词同一只判官 {@link judgeSessionWrite}(local 店的写锁内同调这一只):`erase` 只判这一行的在删令牌(不是 ⇒ 拒 `SessionDeletionSupersededError`);其余认领在 ⇒ 拒 `SessionActiveRunError`;
+ *    `import` 再判这一处是写者 ⇒ 拒 `SessionWriterPresentError`;
+ *  · `import` 放行 ⇒ 这一格落 mirror(写者在别处)、客户端写计数 +1;删除三词放行 ⇒ 什么都不写(级联随根行带走旁表行,钩不另删);
  *  · 键控 fork(服务扩展)—— `record`:新行的 fork 键落旁表(新行是本事务刚插下的,本事务持着它的锁);`targetOf`:撞上已在的目标时的一次池读(属主 + fork 键)。
  */
 export declare function createSqlSessionWriteHooks(db: Pick<SqlDriver, "dialect" | "query">): SessionWriteHooks;
@@ -60,9 +63,19 @@ 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>;
+    /** 条件撤回面:座的条件删除 + 本部署的判据(启用标记 / 客户端写计数 / 别的 run / 本次 run 的部署行;同一事务)。 */
+    withdrawBirth(birth: SessionBirth, ownTaskId: string | undefined): Promise<WithdrawOutcome>;
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
     listPlaced(...a: Parameters<SessionSeat["listPlaced"]>): Promise<PlacedSessionRow[]>;
+    /**
+     * 按 id 读一行(属主 / 住客 / 叶子一次读)—— 座的那一读加一条「不在删」:在删的行对删除门之外的读者读作不在(会话三态,`src/session-deletion.ts`)。
+     * 一条 PK SELECT(根行 LEFT JOIN 旁表行),不上锁。
+     */
     headOf(sessionId: string): Promise<SessionHead | undefined>;
+    /** 删除门的头读(`OwnerAwareSessionStore.deletionHeadOf`):活行 ∪ 在删行 —— 座的原始一读。开始删它的那位属主重发删除(= 接管)就过得了门;别人得到与「不在」同一句。 */
+    deletionHeadOf(sessionId: string): Promise<SessionHead | undefined>;
     touch(sessionId: string): Promise<void>;
     release(sessionId: string): Promise<void>;
     forget(sessionId: string): void;
@@ -76,28 +89,41 @@ export declare class SqlSessionStore implements SessionStore {
     beginImportStaging(...a: Parameters<SessionSeat["beginImportStaging"]>): ReturnType<SessionSeat["beginImportStaging"]>;
     readStagedEntries(stagingId: string): Promise<SessionTreeEntry[]>;
     sweepStagingSessions(): Promise<number>;
-    deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
+    readonly sessionDeletion: SessionDeletionFace;
+    /**
+     * 围栏(删除路唯一的认领判):一只事务 —— 锁根行(读属主与住客)→ 不在 / 属主不等 ⇒ 回滚、`undefined` → 补旁表行 + 锁定读在删令牌 →
+     *  · 活 ∧ 不带 `expect` ⇒ 判认领(判官 `judgeSessionWrite` 的 `delete` 臂,锁定读 `task_active`;在 ⇒ 回滚、抛 `SessionActiveRunError`)→ 写新令牌;
+     *    活 ∧ 带 `expect`(收尾者)⇒ 回滚、`undefined` —— 收尾者读到之后那一次删完、同 id 重登记的新行不被碰;
+     *  · 在删 ∧ 带 `expect` 而持有的不是它 ⇒ `undefined`;持有者仍可能活着(`running`,或 `elsewhere` 且令牌铸于接管期限之内 —— 别的副本上那一次可能还在跑)⇒
+     *    回滚、`{ inProgress }`;否则 ⇒ 接管(换新令牌;不判认领:在删期间规则 L 不让认领落下)。
+     * 写序与旁表的其余格写者同一条(根行 → 旁表;根行先 ⇒ 与认领事务、座的删除 / 导入同一锁序)。
+     */
+    private fenceDeletion;
     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)`.
+     * `session_meta` (owner-filtered on its owner column); the side table supplies the title / pin; LEFT JOINs onto the `task_run` runs ledger
+     * supply the run-derived half (latest run's status / task_id / runId, run count, the preview) but never gate 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. */
+     *  (no such session / placed). The run 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,
+     * three run subqueries to one session (the single-row read); the list leaves them whole. Placeholders are minted in text order (run scope ×3,
      * 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).
+     * The run JOINs (the run-derived half of the row — `SessionRunRollup` in `store-contracts.ts`; the local twin's rule is `session-run-rollup.ts`, one case table pins both):
+     *  · a count rollup;
+     *  · `latest` = the LATEST run per session (`created_at DESC, task_id DESC`, ties broken by task_id so EXACTLY one row joins) ⇒ status / task_id / runId;
+     *  · `preview` = the most recent run whose preview column is non-empty BY CHARACTER LENGTH ({@link RUN_PREVIEW_PRESENT}) ⇒ `objectivePreview` — decoupled
+     *    from `latest`: a last turn with no user text (column `""`) falls back to the sentence before it; none ⇒ NULL.
+     * 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;
     /**

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

@@ -1,14 +1,19 @@
+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 { SESSION_EXT_TABLE, ensureSessionExtRowStatement } from "./session-ext-table.js";
+import { DELETING_TOKEN_COLUMN, SESSION_EXT_TABLE, ensureSessionExtRowStatement, readDeletingTokenOn } 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 { judgeSessionWrite, sessionWriteTouchesCell } from "../execution-placement.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
-import { incarnationFromCell } from "../session-incarnation.js";
+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 { bumpClientWritesOn, createSqlWithdrawJudge } from "./session-withdraw-sql.js";
+import { WITHDRAWABLE_ENTRY_TYPES } from "./session-birth.js";
+const RUN_PREVIEW_PRESENT = "CHAR_LENGTH(objective_preview) > 0";
 function binder(dialect) {
     const values = [];
     return {
@@ -26,24 +31,14 @@ export function createSqlSessionWriteHooks(db) {
         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)}`);
-                }
+            const verdict = await judgeSessionWrite(write, { claim: () => readClaimOn(rows, dialect, root), cell: () => readCellOn(rows, dialect, root), deleting: () => readDeletingTokenOn(rows, dialect, root) });
+            if (verdict !== "proceed")
+                return verdict;
+            if (sessionWriteTouchesCell(write.op)) {
+                await writeCellOn(txn, dialect, root, markMirrorStatement(dialect, root));
+                await bumpClientWritesOn(txn, dialect, root);
             }
+            return "proceed";
         },
         keyedFork: {
             async record(txn, fork) {
@@ -91,6 +86,22 @@ async function withLockedSessionExt(db, sessionId, lock, write) {
     }
 }
 const pinnedOf = (dialect, v) => (dialect === "pg" ? v === true : Number(v) === 1);
+const listedLineageOf = (sessionId, forkedFrom) => {
+    const lineage = forkLineageOfRow(sessionId, forkedFrom, undefined);
+    return lineage.forkedFrom !== undefined ? { forkedFrom: lineage.forkedFrom } : {};
+};
+function holderMayBeAlive(holder, token) {
+    switch (holder) {
+        case "running":
+            return true;
+        case "ended":
+            return false;
+        case "elsewhere": {
+            const minted = deletionTokenMintedAt(token);
+            return minted === undefined || Date.now() - minted < CROSS_PROCESS_TAKEOVER_AFTER_MS;
+        }
+    }
+}
 export class SqlSessionStore {
     db;
     seat;
@@ -112,13 +123,32 @@ export class SqlSessionStore {
     register(sessionId, owner) {
         return this.seat.register(sessionId, owner);
     }
+    registerWithReceipt(sessionId, owner) {
+        return this.seat.registerWithReceipt(sessionId, owner);
+    }
+    withdrawBirth(birth, ownTaskId) {
+        const cond = {
+            expect: { owner: birth.owner, incarnation: birth.incarnation },
+            withdrawableEntryTypes: WITHDRAWABLE_ENTRY_TYPES,
+            judge: createSqlWithdrawJudge(this.db.dialect, birth.sessionId, ownTaskId),
+        };
+        return this.seat.deleteSessionIf(birth.sessionId, cond);
+    }
     placementOf(sessionId) {
         return this.seat.placementOf(sessionId);
     }
     listPlaced(...a) {
         return this.seat.listPlaced(...a);
     }
-    headOf(sessionId) {
+    async headOf(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT sm.owner, sm.incarnation, sm.leaf_id FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id ` +
+            `WHERE sm.session_id = ${b.p(sessionId)} AND se.${DELETING_TOKEN_COLUMN.name} IS NULL`, b.values)).rows[0];
+        if (row === undefined)
+            return undefined;
+        return headFromRow(sessionId, row.owner ?? null, row.incarnation, row.leaf_id ?? null);
+    }
+    deletionHeadOf(sessionId) {
         return this.seat.headOf(sessionId);
     }
     touch(sessionId) {
@@ -160,8 +190,66 @@ export class SqlSessionStore {
     sweepStagingSessions() {
         return this.seat.sweepStagingSessions();
     }
-    deleteSession(sessionId, owner) {
-        return this.seat.deleteSession(sessionId, owner);
+    sessionDeletion = {
+        fence: (sessionId, owner, opts) => this.fenceDeletion(sessionId, owner, opts),
+        holds: async (sessionId, token) => {
+            const b = binder(this.db.dialect);
+            const row = (await this.db.query(`SELECT ${DELETING_TOKEN_COLUMN.name} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+            return row !== undefined && row[DELETING_TOKEN_COLUMN.name] === token;
+        },
+        pending: async () => {
+            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) }));
+        },
+    };
+    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 (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) {
+                    await conn.rollback();
+                    return undefined;
+                }
+                const verdict = await judgeSessionWrite({ op: "delete", rootSessionId: sessionId }, { claim: () => readClaimOn(rows, dialect, sessionId), cell: async () => ({ role: "absent" }), deleting: async () => held });
+                if (verdict !== "proceed") {
+                    await conn.rollback();
+                    throw verdict.refuse;
+                }
+            }
+            else {
+                if (opts.expect !== undefined && held !== opts.expect) {
+                    await conn.rollback();
+                    return undefined;
+                }
+                if (holderMayBeAlive(opts.holder(held), held)) {
+                    await conn.rollback();
+                    return { inProgress: true };
+                }
+            }
+            const token = uuidv7();
+            const b = binder(dialect);
+            const res = await conn.query(`UPDATE ${SESSION_EXT_TABLE} SET ${DELETING_TOKEN_COLUMN.name} = ${b.p(token)} WHERE session_id = ${b.p(sessionId)}`, b.values);
+            if (res.affected !== 1)
+                throw new Error(`deletion fence of session ${sessionId}: the token write matched ${res.affected} row(s) of a side-table row this transaction ensured under a held root-row lock — engine/driver anomaly, refusing to guess`);
+            await conn.commit();
+            return { token, incarnation: incarnationFromCell(sessionId, root.incarnation, "absent") };
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
     }
     get size() {
         return this.seat.size;
@@ -202,24 +290,35 @@ export class SqlSessionStore {
         const dialect = this.db.dialect;
         const b = binder(dialect);
         const runWhere = () => (q.runSessionId !== undefined ? ` WHERE session_id = ${b.p(q.runSessionId)}` : "");
+        const runAnd = () => (q.runSessionId !== undefined ? ` AND 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" +
+            ? "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, 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, " +
+            : "LEFT JOIN (SELECT session_id, status, task_id, last_task_run_id FROM (" +
+                "    SELECT session_id, 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 " +
+        const preview = dialect === "pg"
+            ? `LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview FROM task_run WHERE ${RUN_PREVIEW_PRESENT}` +
+                runAnd() +
+                "  ORDER BY session_id, created_at DESC, task_id DESC) pv ON pv.session_id = sm.session_id "
+            : "LEFT JOIN (SELECT session_id, objective_preview FROM (" +
+                "    SELECT session_id, objective_preview, ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn " +
+                `FROM task_run WHERE ${RUN_PREVIEW_PRESENT}` +
+                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, " +
+            "  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 ` +
             runCount +
             latest +
-            (where.length ? "WHERE " + where.join(" AND ") + " " : "") +
+            preview +
+            "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) => {
@@ -242,6 +341,7 @@ export class SqlSessionStore {
                 title,
                 pinned,
                 ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
+                ...listedLineageOf(sessionId, r.forked_from),
             };
             return { row, occupant: { owner, incarnation } };
         });

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

@@ -0,0 +1,36 @@
+/**
+ * **条件撤回的部署那一半**(SQL 两方言;规则在 `plugins/session-birth.ts` 头注)—— 会话店座(`stores-sql/tidb-session-store.ts` 的 `withdrawSessionOn`,
+ * PG 孪生同调)锁住根行、判完化身 / 内容 / 认领之后,在**同一事务、同一连接**上问部署:启用标记、客户端写计数、别的 run;放行 ⇒ 删本次 run 的部署行。
+ * 客户端写计数的 +1 也在这里一处:四个 SQL 写者里不在自己 UPDATE 里带它的那几个(导入、会话规则、附件绑定)调 {@link countClientWriteOn}。
+ * 每一读都是锁定读(`FOR UPDATE`;TiDB 悲观事务里普通 SELECT 读事务开始时的快照,看不到等根锁期间别人提交的写)。
+ */
+import type { SqlDialect } from "./sql-driver.js";
+import type { WithdrawJudgeVerdict } from "../session-incarnation.js";
+/**
+ * 判据与计数句只用到的那一面:一句语句、交回行(会话店交给部署钩的事务语句面 `SessionTxStatements`、驱动的事务连接 `SqlTxConn` 都满足它 ——
+ * 结构型,本部署不读店目录里的型)。
+ */
+export interface WithdrawStatementFace {
+    query(sql: string, params?: unknown[]): Promise<{
+        readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>;
+    }>;
+}
+/** 撤回出口的启用标记在标记表(`plugins/one-time-migration-marker.ts`)里的键 = 落它的一次性迁移(窗口见 `plugins/one-time-migrations.ts` 登记表 M43 行)。 */
+export declare const WITHDRAW_MARK_ID = "M43";
+/**
+ * 部署判据(一次提交的一只候选;`ownTaskId` = 本次提交认领赢的那条 run):
+ *  · 启用标记(M43)不在 ⇒ `upgrade_pending`(混跑窗里旧副本的写者不递增计数,判不出「没人写过」⇒ 一律留);
+ *  · 客户端写计数 > 0 ⇒ `client_writes`(先补旁表行再锁定读 —— 锁定读落在在的行上,见 `execution-placement-sql.ts` 的写序律);
+ *  · 本会话有本次 run 之外的 run 行 ⇒ `runs`;
+ *  · 放行 ⇒ 同一语句面上删本次 run 的部署行(账本事件 / 认领 / run 行)与本会话的续跑输入(别的 run 都不在 ⇒ 那一行只能是本次写的)。
+ */
+export declare function createSqlWithdrawJudge(dialect: SqlDialect, sessionId: string, ownTaskId: string | undefined): (tx: WithdrawStatementFace) => Promise<WithdrawJudgeVerdict>;
+/**
+ * 一次客户端写:补旁表行 + 锁定读在删令牌 + 计数 +1(调用方已在同一事务里锁住根行、根行在)。会话规则、附件绑定两个 SQL 写者调这一只(会话规则店收它作构造参数,组合座交入,店目录不读部署);
+ * 这只会话在删(会话三态,`src/session-deletion.ts`)⇒ 抛 `SessionDeletingError`,调用方的写不发生(删除级联的规则 / 附件腿之后到的写不复活它们;local 孪生 = 会话店 `withClientWrite` 的计数口同判)。
+ * 导入臂的旁表行已由锁它的那一读补过,只调计数那一句 {@link bumpClientWritesOn};标题 / 置顶的写者在自己的 UPDATE 里带 `BUMP_CLIENT_WRITES`(`session-row-sql.ts`)。
+ */
+export declare function countClientWriteOn(tx: WithdrawStatementFace, dialect: SqlDialect, sessionId: string): Promise<void>;
+/** 客户端写计数 +1 的那一句(前提:同一事务里根行已锁、旁表行已在)。 */
+export declare function bumpClientWritesOn(tx: WithdrawStatementFace, dialect: SqlDialect, sessionId: string): Promise<void>;
+//# sourceMappingURL=session-withdraw-sql.d.ts.map

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

@@ -0,0 +1,42 @@
+import { BUMP_CLIENT_WRITES, ensureSessionExtRowStatement, readDeletingTokenOn, SESSION_EXT_TABLE } from "./session-ext-table.js";
+import { SessionDeletingError } from "../execution-placement.js";
+import { MIGRATION_MARKER_TABLE } from "./one-time-migration-marker.js";
+function placeholders(dialect, from, count) {
+    return Array.from({ length: count }, (_, i) => (dialect === "pg" ? `$${from + i}` : "?"));
+}
+export const WITHDRAW_MARK_ID = "M43";
+export function createSqlWithdrawJudge(dialect, sessionId, ownTaskId) {
+    const [p1, p2] = placeholders(dialect, 1, 2);
+    return async (tx) => {
+        const mark = await tx.query(`SELECT migration_id FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = ${p1}`, [WITHDRAW_MARK_ID]);
+        if (mark.rows.length === 0)
+            return { keep: "upgrade_pending" };
+        const ensure = ensureSessionExtRowStatement(dialect, sessionId);
+        await tx.query(ensure.text, [...ensure.values]);
+        const ext = (await tx.query(`SELECT client_writes FROM ${SESSION_EXT_TABLE} WHERE session_id = ${p1} FOR UPDATE`, [sessionId])).rows[0];
+        if (Number(ext?.client_writes ?? 0) > 0)
+            return { keep: "client_writes" };
+        const others = ownTaskId === undefined
+            ? await tx.query(`SELECT task_id FROM task_run WHERE session_id = ${p1} LIMIT 1 FOR UPDATE`, [sessionId])
+            : await tx.query(`SELECT task_id FROM task_run WHERE session_id = ${p1} AND task_id <> ${p2} LIMIT 1 FOR UPDATE`, [sessionId, ownTaskId]);
+        if (others.rows.length > 0)
+            return { keep: "runs" };
+        if (ownTaskId !== undefined) {
+            await tx.query(`DELETE FROM task_event WHERE task_id = ${p1}`, [ownTaskId]);
+            await tx.query(`DELETE FROM task_active WHERE task_id = ${p1}`, [ownTaskId]);
+            await tx.query(`DELETE FROM task_run WHERE task_id = ${p1}`, [ownTaskId]);
+        }
+        await tx.query(`DELETE FROM checkpoint_ctx WHERE session_id = ${p1}`, [sessionId]);
+        return "proceed";
+    };
+}
+export async function countClientWriteOn(tx, dialect, sessionId) {
+    if ((await readDeletingTokenOn(async (sql, values) => (await tx.query(sql, [...values])).rows, dialect, sessionId)) !== null)
+        throw new SessionDeletingError(sessionId);
+    await bumpClientWritesOn(tx, dialect, sessionId);
+}
+export async function bumpClientWritesOn(tx, dialect, sessionId) {
+    const [p1] = placeholders(dialect, 1, 1);
+    await tx.query(`UPDATE ${SESSION_EXT_TABLE} SET ${BUMP_CLIENT_WRITES} WHERE session_id = ${p1}`, [sessionId]);
+}
+//# sourceMappingURL=session-withdraw-sql.js.map

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

@@ -1,72 +1,3 @@
-/**
- * [ref] — the SQL `SharedMemoryStoreProvider`: the deployment's ORG-scoped shared memory libraries
- * (`memory_list` / `memory_read`), served out of the durable store instead of a BYOM host callback.
- *
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * WHAT THIS IS (and, just as load-bearing, what it is NOT)
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * core's seam is a document-only READ face reached exclusively through two tools. There is no model
- * write channel at all — write governance is the environment's, and the tool face's entire
- * participation in it is relaying each store's `writable` bit verbatim. This module keeps that shape:
- * {@link SqlSharedMemoryStore.snapshot} is the only method core ever calls; the `put*`/`delete*` half
- * is the DEPLOYMENT's admin plane (migrations, an import job, an operator face) and is deliberately
- * NOT reachable from any model-facing surface in this repo.
- *
- * 🔴 ORG PLANE ≠ THE LOCAL MEMORY CHAIN (设计 182 §13). `agent_memory_engine_*` (the [ref]
- * MemoryEngine) and these three tables share NOTHING: no join, no view, no shared row, no shared
- * scope registry. The local chain is an entry-transactional index injection with a write path; this
- * one is a read-only document library. Bridging them in EITHER direction would let harvested private
- * notes leak into a team library (or a team library into a model-writable disk), which is exactly the
- * boundary core's seam doc draws. If a future feature needs both, it composes them ABOVE this layer.
- *
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * AUTHORIZATION (v2/F4) — server-side, injected, never inferred here
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * `SharedMemoryRequestContext` carries the caller's `principal`. Who belongs to `org:acme` is NOT this
- * module's question: it takes a {@link SharedMemoryScopeAuthorizer} and serves exactly the scopes that
- * verdict names. The production binding folds the SAME `OrgMemoryDirectory` instance the memory-policy
- * face and core's admission seam already read (`src/shared-memory-scope-authorizer.ts`), so a process
- * has ONE answer to "who belongs to org:acme".
- *
- * The verdict is a discriminated union on purpose (same 裁定 as org-memory-admission's N3/C5): a
- * directory that CANNOT ANSWER must never collapse into "you belong to nothing". The first renders as
- * `unavailable` ("reads are refused until it is restored" — try again); the second renders as a
- * settled "no memory stores are connected to this session", which teaches the model to give up. Those
- * are opposite instructions and a fail-open collapse between them is a real defect, not a nuance.
- *
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * ORDERING / PAGINATION — why the collations are part of the contract
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * core's cursor vocabulary is "an EXCLUSIVE lower bound over document paths in plain UTF-16 code-unit
- * order", and its paging loop only advances while `nextCursor > windowCursor` **in JavaScript**. So the
- * SQL ordering must agree with JS string comparison or a listing would silently stop early.
- *   · MySQL: the tables are `COLLATE utf8mb4_bin` ⇒ comparison is by code point.
- *   · PG: every string column is `COLLATE "C"` ⇒ comparison is by UTF-8 byte, which for valid UTF-8 is
- *     also code-point order.
- * Code-point order equals UTF-16 code-unit order for every BMP character, and differs ONLY for
- * supplementary-plane characters (U+10000+, whose surrogates sort before U+E000..U+FFFF in UTF-16).
- * Rather than leave that as an invisible "listing silently truncates" hazard, {@link assertDocumentPath}
- * REFUSES a non-BMP path at write time — the divergence is made impossible by construction, loudly, at
- * the one place a human is watching. (Store ids and org scopes are already ASCII-only by their own
- * shape rules, so this is the only column that needed the ruling.)
- *
- * KEYSET, never OFFSET: `WHERE store_id = ? AND path > ?` walks the PRIMARY KEY. An OFFSET pager over a
- * live library both re-scans the prefix on every page and skips rows when a document is inserted mid-walk.
- *
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 事务与锁
- * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * **四个**写方法(putStore / putDocument / deleteDocument / deleteStore)都是「先读注册行、再按结果写」
- * 的形状,并且都用 `SELECT … FOR UPDATE` 拿同一把行锁,于是彼此串行。判据只有一处:
- * {@link SqlTxConn.begin} 的 `@contract txn.read-semantics` —— 加锁读在两引擎都是当前读,而「当前读」
- * 的前提(TiDB 悲观模式、MySQL 会话级 REPEATABLE READ)是**连接初始化**的结构保证,不是服务器默认值。
- *
- * 本店的**第二道防线**照旧在:`store_id` 的主键唯一性才是最终裁决者,撞键被 {@link isDupKey} 翻成一句
- * 响亮的拒绝(见 putStore)—— 即便某一天读语义出岔,结果也只会是「一方被响亮拒绝」,绝不会是一次静默
- * 的换属主。⚠️ 另一处不可混线的分歧:InnoDB 的加锁读对**不存在的键**取 gap/next-key 锁,TiDB 悲观事务
- * **没有** gap 锁(retention-store 的「先 ON DUPLICATE 造行、再 FOR UPDATE 锁行」就是为它而写)。
- * 「加锁读=当前读」两引擎同真,「gap 锁」只有 InnoDB 有 —— 两条性质不共享一个「同理」。
- */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SharedMemoryRequestContext, type SharedMemorySnapshot, type SharedMemoryStoreProvider } from "@sema-agent/core";

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

@@ -1,3 +1,4 @@
+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";
@@ -81,7 +82,7 @@ async function rollbackPreservingError(conn, primary) {
         await conn.rollback();
     }
     catch (rollbackErr) {
-        console.warn("[shared-memory-store] rollback failed after a failed transaction; reporting the PRIMARY error:", { primary, rollbackErr });
+        writeLogText("stderr", "[shared-memory-store] rollback failed after a failed transaction; reporting the PRIMARY error:", { primary, rollbackErr });
     }
 }
 function storeGone(storeId) {

package/dist/plugins/shell-sentinel-owner-m48.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 一次性迁移 **M48** 的唯一属主(窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表;随 M48 删整个文件)。
+ *
+ * cli ≤ 1.0.70 在本地单用户形下对每次请求自发主体头 `anon:shell-live`,于是那段时间写下的会话行 / run 行 / leader run 行的属主列是这一个字面量
+ * (不是真租户键:它与「不带主体的同一位本地用户」是同一个人的两种写法)。此前属主面表为它留了一格按字面量互认的资格;
+ * 本版起这一格退役 —— 存量行由本迁移改写成无主(`null`),之后它们与任何无主行同读(普通无主行一格),属主读法里不再有字面量。
+ *
+ * **改写的部署形**:「哨兵 ≡ 不带主体的本地单用户」只在没有身份边界的部署(dev-open)上成立 ⇒ 改写只在那里执行。判据 = 部署形表行 `identityBoundary`(只读配置:
+ * `REQUIRE_PRINCIPAL`、service 凭据、鉴权桥 issuer —— 含中心回退、直连门、只读 trace 凭据,任一在 ⇒ 有边界),dev-open 判据 `devOpenDeployment` 读同一行。
+ * 有身份边界的部署上哨兵是一位普通的具名属主,行只对字面相等的主体可见;改成无主 = 过了凭据门的任何主体都够得着 ⇒ 那里零改写、读数 0,行原样(本条照样记完成)。
+ * 读数由调用方读部署形表交进迁移段(`one-time-migrations.ts` 的 `ShellSentinelOwnerInput`),两条腿同读。
+ *
+ * 改写面 = 曾放那一格的读面读属主的那几处:SQL `session_meta` / `task_run` / `leader_run` 的 `owner` 列;local 会话元数据边档那一格的 `owner`、
+ * `FileRunStore` 的 run 行 `owner`(local 没有 leader run 店)。不改的(如实):规则行(存在哨兵键下的规则此前也不对无主体任务生效,改键 = 放宽,不做)、
+ * 收件箱条目 / 问账行 / 检查点 scope(这些读面从没放过那一格)。
+ */
+export declare const SHELL_SENTINEL_OWNER_M48 = "anon:shell-live";
+/** SQL 腿改写 `owner` 列的表(曾放那一格的读面读属主的表;local 腿的对应面见文件头)。 */
+export declare const SHELL_SENTINEL_OWNER_TABLES_M48: readonly ["session_meta", "task_run", "leader_run"];
+//# sourceMappingURL=shell-sentinel-owner-m48.d.ts.map

package/dist/plugins/shell-sentinel-owner-m48.js

@@ -0,0 +1,3 @@
+export const SHELL_SENTINEL_OWNER_M48 = "anon:shell-live";
+export const SHELL_SENTINEL_OWNER_TABLES_M48 = ["session_meta", "task_run", "leader_run"];
+//# sourceMappingURL=shell-sentinel-owner-m48.js.map

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

@@ -20,7 +20,8 @@
  *    `workspace` = k8s 车道的 `config.remoteExec.s3Snapshot.bucket`(`WORKSPACE_SNAPSHOT_BUCKET`,缺省 `workspaces`)—— 车道没开 / 没配对象存储 ⇒ 没有这只桶,不核。
  *    拒句的旋钮名跟着桶走(缺的是哪只桶就只点哪只的旋钮)。公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
  *  · 运行期的对应臂:工作区 `latest` 指针读答 404 `NoSuchBucket`(同一条「桶不在」判据 `isNoSuchBucketAnswer`)⇒ 那条 run 响亮拒绝,不再读成「空间头一回」
- *    (`remote-env-k8s.ts` `readPointer`)—— 起服核之后桶被删 / 起服核证明不了的部署,在运行期也有一道。
+ *    (`remote-env-k8s.ts` `readPointer`);恢复时归档 GET 答同一只 404 `NoSuchBucket`(pod 原样交回存储的答复,同一只判据读)⇒ 两条车道同拒、同一行
+ *    (`restoreSnapshot`)—— 起服核之后桶被删 / 起服核证明不了的部署,在运行期也有一道。
  */
 import type { ServiceConfig } from "../config-types.js";
 import { type StoreOpenWaitClock } from "./store-open-wait.js";

package/dist/plugins/sql-driver.d.ts

@@ -115,7 +115,7 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import type { Logger } from "../observability/logger.js";
+import { type Logger } from "../observability/logger.js";
 /**
  * SQL **文本**的语法族(调用方说,不探):`mysql` = MySQL 协议(TiDB / MySQL InnoDB / MariaDB 同一套语句),`pg` = PostgreSQL。
  * 与 `@sema-agent/core-stores-sql` 公面的 `SqlDialect` 同词同集 —— 部署词 / 引擎词都不是它的别名:谁在答是另一轴 {@link SqlEngine}(驱动探)。

package/dist/plugins/sql-driver.js

@@ -1,6 +1,7 @@
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { errorKindOf } from "../observability/err-text.js";
+import { writeLogText } from "../observability/logger.js";
 import { isConnectionUnusableError } from "./sql-errors.js";
 export class SqlStatementDeadlineExceeded extends Error {
     deadlineMs;
@@ -229,7 +230,7 @@ async function establishSession(session, pooled, c, init) {
         session.facts = null;
         session.connections = new WeakMap();
         if (stale !== null)
-            console.warn(`[sql-driver] connection initialization REFUSED — SQL engine facts invalidated (was: ${stale ? `${stale.engine} ${stale.version} ${stale.isolation} txnMode=${stale.txnMode ?? "-"}` : "<absent>"}). GET /v1/diagnostics/wiring -> sqlEngine and GET /v1/capabilities -> sql now report ABSENT, which is the honest ` +
+            writeLogText("stderr", `[sql-driver] connection initialization REFUSED — SQL engine facts invalidated (was: ${stale ? `${stale.engine} ${stale.version} ${stale.isolation} txnMode=${stale.txnMode ?? "-"}` : "<absent>"}). GET /v1/diagnostics/wiring -> sqlEngine and GET /v1/capabilities -> sql now report ABSENT, which is the honest ` +
                 `reading: this pool cannot currently establish the read semantics every "SELECT … FOR UPDATE" in this repo assumes. Cause: ${err.message}`);
         c.release();
         throw err;