@sema-agent/server 7.138.0 → 7.140.0

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

@@ -6,7 +6,9 @@ import { escapeLike } from "./sql-escape.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
 import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
-import { carriedIncarnation, headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { sessionRowTagKey } from "../session-row.js";
+import { writeSessionRowCellsSql } from "./session-row-sql.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
 import { createLogger } from "../observability/logger.js";
@@ -14,17 +16,26 @@ import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, pla
 import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue } from "./session-ownership.js";
 import { selectForkRows } from "@sema-agent/core";
-import { FORK_LOG_ROW_SHAPE, forkPointOf } from "./session-fork.js";
+import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf } from "./session-fork.js";
+import { isMysqlDupKeyError } from "./sql-errors.js";
+import { mysqlDriver } from "./sql-driver.js";
+import { MIRROR_ON_COMMIT_GUARD, MIRROR_ON_COMMIT_SET, SESSION_META_PLACEMENT_READ_COLUMNS, createSqlExecutionPlacementSeat, importedRowCells, lockRootAndReadClaim, placementCellFromRow, readPlacementRowStatement } from "./execution-placement-sql.js";
+import { SessionActiveRunError, SessionWriterPresentError } from "../execution-placement.js";
+const rowsOnConnection = (conn) => async (sql, values) => (await conn.query(sql, [...values]))[0];
 export class TiDBSessionStore {
     pool;
     retention;
     placements = SQL_SESSION_PLACEMENTS;
     pending = new Map();
     log;
+    executionPlacement;
+    db;
     constructor(pool, opts = {}) {
         this.pool = pool;
         this.log = opts.log ?? createLogger();
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
+        this.db = mysqlDriver(pool);
+        this.executionPlacement = createSqlExecutionPlacementSeat(this.db);
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
@@ -78,7 +89,7 @@ export class TiDBSessionStore {
         }, this.log);
     }
     async claimOwnerless(sessionId, incarnation, owner) {
-        const [res] = await this.pool.query(CLAIM_OWNERLESS_PLACED_SQL.tidb, [...claimOwnerlessParams(sessionId, incarnation, owner)]);
+        const [res] = await this.pool.query(CLAIM_OWNERLESS_PLACED_SQL.mysql, [...claimOwnerlessParams(sessionId, incarnation, owner)]);
         return res.affectedRows > 0;
     }
     async sourceFaces(ids) {
@@ -172,34 +183,21 @@ export class TiDBSessionStore {
             where.push("(sm.updated_at < ? OR (sm.updated_at = ? AND sm.session_id < ?))");
             params.push(new Date(opts.cursor.lastActivityAt), new Date(opts.cursor.lastActivityAt), opts.cursor.sessionId);
         }
-        return this.selectSummaries({ where, params, limit: opts.limit });
+        return (await this.selectListRows({ where, params, limit: opts.limit })).map((a) => a.row);
     }
     async sessionSummaryOf(sessionId) {
-        const rows = await this.selectSummaries({ where: ["sm.placement_kind IS NULL", "sm.session_id = ?"], params: [sessionId], limit: 1, runSessionId: sessionId });
-        return rows[0];
+        return (await this.listRowOf(sessionId))?.row;
     }
-    async patchSessionMeta(sessionId, patch, face) {
-        const sets = [];
-        const params = [];
-        if (patch.title !== undefined) {
-            sets.push("title = ?");
-            params.push(patch.title);
-        }
-        if (patch.pinned !== undefined) {
-            sets.push("pinned = ?");
-            params.push(patch.pinned);
-        }
-        if (sets.length > 0) {
-            params.push(sessionId, face.incarnation);
-            await this.pool.query(`UPDATE session_meta SET ${sets.join(", ")} WHERE session_id = ? AND incarnation = ? AND placement_kind IS NULL`, params);
-        }
-        const rows = await this.selectSummaries({ where: ["sm.placement_kind IS NULL", "sm.session_id = ?", "sm.incarnation = ?"], params: [sessionId, face.incarnation], limit: 1, runSessionId: sessionId });
-        return rows[0];
+    async listRowOf(sessionId) {
+        return (await this.selectListRows({ where: ["sm.placement_kind IS NULL", "sm.session_id = ?"], params: [sessionId], limit: 1, runSessionId: sessionId }))[0];
     }
-    async selectSummaries(q) {
+    async writeSessionRowCells(sessionId, cells, how) {
+        return writeSessionRowCellsSql(this.db, sessionId, cells, how, (id) => this.listRowOf(id));
+    }
+    async selectListRows(q) {
         const runWhere = q.runSessionId !== undefined ? " WHERE session_id = ?" : "";
         const runParams = q.runSessionId !== undefined ? [q.runSessionId, q.runSessionId] : [];
-        const sql = "SELECT sm.session_id, sm.owner, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, sm.pinned, " +
+        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, sm.pinned, " +
             "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
             "FROM session_meta sm " +
             "LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run" + runWhere + " GROUP BY session_id) r ON r.session_id = sm.session_id " +
@@ -212,9 +210,14 @@ export class TiDBSessionStore {
         const [rows] = await this.pool.query(sql, [...runParams, ...q.params, q.limit]);
         return rows.map((r) => {
             const runId = r.last_task_run_id;
-            return {
-                sessionId: String(r.session_id),
-                owner: r.owner ?? null,
+            const sessionId = String(r.session_id);
+            const owner = r.owner ?? null;
+            const incarnation = incarnationFromCell(sessionId, r.incarnation, "absent");
+            const title = r.title ?? null;
+            const pinned = Number(r.pinned) === 1;
+            const row = {
+                sessionId,
+                owner,
                 lastActivityAt: r.last_activity instanceof Date ? r.last_activity.toISOString() : String(r.last_activity),
                 firstActivityAt: r.first_activity instanceof Date ? r.first_activity.toISOString() : String(r.first_activity),
                 runCount: Number(r.run_count),
@@ -222,9 +225,11 @@ export class TiDBSessionStore {
                 lastStatus: r.status == null ? "" : String(r.status),
                 lastRunId: r.last_run_id ?? null,
                 ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
-                title: r.title ?? null,
-                pinned: Number(r.pinned) === 1,
+                title,
+                pinned,
+                ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
             };
+            return { row, occupant: { owner, incarnation } };
         });
     }
     async probeTitle(sessionId) {
@@ -251,7 +256,7 @@ export class TiDBSessionStore {
         }
     }
     async readSessionWorkspace(sessionId) {
-        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("tidb", "workspace")} FROM session_meta WHERE session_id = ?`, [sessionId]);
+        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("mysql", "workspace")} FROM session_meta WHERE session_id = ?`, [sessionId]);
         const row = rows[0];
         return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
     }
@@ -259,6 +264,17 @@ export class TiDBSessionStore {
         await this.pool.query("UPDATE session_meta SET workspace = ? WHERE session_id = ? AND incarnation = ?", [encodeSessionWorkspaceCell(workspace, JSON.stringify, sessionId), sessionId, incarnation]);
     }
     async fork(sourceId, owner) {
+        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner);
+    }
+    async forkTo(sourceId, owner, target) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const out = await this.forkToOnce(sourceId, owner, target);
+            if (out !== "unsettled")
+                return out;
+        }
+        throw new ForkTargetUnsettledError(target.id);
+    }
+    async forkToOnce(sourceId, owner, target) {
         const [metaRows] = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = ?", [sourceId]);
         if (!metaRows[0])
             return null;
@@ -268,21 +284,31 @@ export class TiDBSessionStore {
         if (storage === null)
             return null;
         const point = await forkPointOf(storage);
-        const [allRows] = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("tidb", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sourceId]);
+        const [allRows] = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("mysql", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sourceId]);
         const { rows: eventRows, leafId: forkLeafId } = selectForkRows(allRows, leafId, point, FORK_LOG_ROW_SHAPE);
-        const newId = uuidv7();
         const now = new Date();
         const conn = await this.pool.getConnection();
+        let collided = false;
         try {
             await conn.beginTransaction();
-            for (let seq = 0; seq < eventRows.length; seq++) {
-                const r = eventRows[seq];
-                const payload = String(r.payload);
-                await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
+            try {
+                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, fork_key) VALUES (?,?,?,?,?,?,?,?)", [target.id, forkOwner, now, now, forkLeafId, eventRows.length, mintSessionIncarnation(), target.key ?? null]);
             }
-            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?)", [newId, forkOwner, now, now, forkLeafId, eventRows.length, mintSessionIncarnation()]);
-            await conn.commit();
-            return newId;
+            catch (err) {
+                if (!isMysqlDupKeyError(err))
+                    throw err;
+                collided = true;
+            }
+            if (!collided) {
+                for (let seq = 0; seq < eventRows.length; seq++) {
+                    const r = eventRows[seq];
+                    const payload = String(r.payload);
+                    await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [target.id, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
+                }
+                await conn.commit();
+                return { outcome: "created", id: target.id };
+            }
+            await conn.rollback();
         }
         catch (err) {
             try {
@@ -295,12 +321,15 @@ export class TiDBSessionStore {
         finally {
             conn.release();
         }
+        const [existing] = await this.pool.query("SELECT owner, fork_key FROM session_meta WHERE session_id = ?", [target.id]);
+        const row = existing[0];
+        return row === undefined ? "unsettled" : classifyForkTarget(target, { owner: row.owner ?? null, forkKey: row.fork_key ?? null }, forkOwner);
     }
     async exportEntries(sessionId) {
         const [metaRows] = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = ?", [sessionId]);
         if (!metaRows[0])
             return null;
-        const [eventRows] = await this.pool.query(`SELECT seq, entry_id, parent_id, type, ${jsonColumnText("tidb", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sessionId]);
+        const [eventRows] = await this.pool.query(`SELECT seq, entry_id, parent_id, type, ${jsonColumnText("mysql", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sessionId]);
         return eventRows.map((r) => decodeSessionEventPayload(r.payload, sessionId, r.seq));
     }
     async listEntryIds(sessionId) {
@@ -319,7 +348,7 @@ export class TiDBSessionStore {
         async function* gen() {
             let cursor = opts?.afterSeq ?? -1;
             for (;;) {
-                const [rows] = await pool.query(`SELECT seq, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?`, [sessionId, cursor, batchSize]);
+                const [rows] = await pool.query(`SELECT seq, ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?`, [sessionId, cursor, batchSize]);
                 for (const r of rows)
                     yield decodeSessionEventPayload(r.payload, sessionId, r.seq);
                 if (rows.length < batchSize)
@@ -334,7 +363,7 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            await this.insertValidatedLog(conn, sessionId, owner, validated, mintSessionIncarnation());
+            await this.writeImportedLog(conn, sessionId, owner, validated, { incarnation: mintSessionIncarnation(), forkKey: null }, "create");
             await conn.commit();
         }
         catch (err) {
@@ -343,7 +372,7 @@ export class TiDBSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError)
+            if (err instanceof SessionError || err instanceof SessionActiveRunError)
                 throw err;
             throw new SessionError("storage", `import of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -357,14 +386,21 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            const [placedRows] = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
-            if (placedRows[0]?.placement_kind != null) {
+            const [placedRows] = await conn.query(`SELECT ${SESSION_META_PLACEMENT_READ_COLUMNS}, fork_key FROM session_meta WHERE session_id = ? FOR UPDATE`, [sessionId]);
+            const prior = placedRows[0];
+            if (prior?.placement_kind != null) {
                 await conn.rollback();
-                throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${String(placedRows[0].placement_kind)} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
+                throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${String(prior.placement_kind)} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
             }
-            await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
-            await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [sessionId, owner]);
-            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(sessionId, placedRows[0] === undefined ? undefined : { incarnation: placedRows[0].incarnation }));
+            const [purged] = await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [sessionId, owner]);
+            const swapped = purged.affectedRows === 1 ? prior : undefined;
+            const cells = carriedRowCells(sessionId, swapped === undefined ? undefined : { incarnation: swapped.incarnation, forkKey: swapped.fork_key });
+            const priorCell = swapped === undefined ? undefined : placementCellFromRow(sessionId, swapped);
+            if (priorCell?.role === "writer") {
+                await conn.rollback();
+                throw new SessionWriterPresentError(sessionId, priorCell.lane);
+            }
+            await this.writeImportedLog(conn, sessionId, owner, validated, cells, "replace");
             await conn.commit();
         }
         catch (err) {
@@ -373,7 +409,7 @@ export class TiDBSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError)
+            if (err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
                 throw err;
             throw new SessionError("storage", `replace of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -381,16 +417,29 @@ export class TiDBSessionStore {
             conn.release();
         }
     }
-    async insertValidatedLog(conn, sessionId, owner, validated, incarnation) {
+    async writeImportedLog(conn, sessionId, owner, validated, cells, mode) {
         let leafId = null;
         for (const e of validated)
             leafId = leafIdAfterEntry(e);
         const now = new Date();
+        const imported = importedRowCells(cells.forkKey);
+        await conn.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${imported.columns}) VALUES (?,?,?,?,?,?,?,?,?)` +
+            (mode === "create" ? " ON DUPLICATE KEY UPDATE session_id = session_id" : ""), [sessionId, owner, now, now, leafId, validated.length, cells.incarnation, ...imported.values]);
+        if (mode === "create") {
+            const [held] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
+            if (String(held[0]?.incarnation) !== cells.incarnation) {
+                throw new SessionError("storage", `import of session ${sessionId} failed`, new Error(`session ${sessionId} already exists — importEntries only creates a session (replaceEntries rewrites one); nothing was written`));
+            }
+        }
+        const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "mysql", sessionId);
+        if (claim.activeTaskId !== null)
+            throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+        if (mode === "replace")
+            await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
         for (let seq = 0; seq < validated.length; seq++) {
             const e = validated[seq];
             await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [sessionId, seq, e.id, e.parentId ?? null, e.type, JSON.stringify(e), new Date(e.timestamp)]);
         }
-        await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?)", [sessionId, owner, now, now, leafId, validated.length, incarnation]);
     }
     beginImportStaging(realSessionId, token) {
         return new TiDBStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
@@ -402,7 +451,7 @@ export class TiDBSessionStore {
         }
     }
     async readStagedEntries(stagingId) {
-        const [rows] = await this.pool.query(`SELECT seq, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [stagingId]);
+        const [rows] = await this.pool.query(`SELECT seq, ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [stagingId]);
         return rows.map((r) => decodeSessionEventPayload(r.payload, stagingId, r.seq));
     }
     async sweepStagingSessions() {
@@ -421,6 +470,11 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
+            const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "mysql", sessionId);
+            if (claim.activeTaskId !== null) {
+                await conn.rollback();
+                throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+            }
             const [metaRes] = await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ?", [sessionId, owner]);
             if (metaRes.affectedRows > 0)
                 await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
@@ -499,6 +553,11 @@ class TiDBStagingHandle {
                     throw new StagedCommitOwnerChangedError(this.realSessionId);
                 }
             }
+            const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "mysql", this.realSessionId);
+            if (claim.activeTaskId !== null) {
+                await conn.rollback();
+                throw new SessionActiveRunError(this.realSessionId, claim.activeTaskId);
+            }
             const [stagedRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const [dstRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
             const [dstMeta] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ?", [this.realSessionId]);
@@ -514,8 +573,8 @@ class TiDBStagingHandle {
                 throw new SyncConflictError(this.realSessionId, rel);
             }
             if (rel.relation === "fast_forward" && opts.resolution !== "overwrite-dst" && dstIds !== null && dstIds.length > 0) {
-                const [dstFull] = await conn.query(`SELECT seq, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE`, [this.realSessionId]);
-                const [stagedFull] = await conn.query(`SELECT entry_id, ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE`, [this.stagingId]);
+                const [dstFull] = await conn.query(`SELECT seq, ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE`, [this.realSessionId]);
+                const [stagedFull] = await conn.query(`SELECT entry_id, ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE`, [this.stagingId]);
                 const dstSet = new Set(dstIds);
                 const dstEntries = dstFull.map((r) => decodeSessionEventPayload(r.payload, this.realSessionId, r.seq));
                 const stagedShared = stagedFull
@@ -529,11 +588,20 @@ class TiDBStagingHandle {
             }
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [this.realSessionId]);
             await conn.query("UPDATE session_event SET session_id = ? WHERE session_id = ?", [this.realSessionId, this.stagingId]);
-            const [lastRow] = await conn.query(`SELECT ${jsonColumnText("tidb", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq DESC LIMIT 1 FOR UPDATE`, [this.realSessionId]);
+            const [lastRow] = await conn.query(`SELECT ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? ORDER BY seq DESC LIMIT 1 FOR UPDATE`, [this.realSessionId]);
             let leafId = null;
             if (lastRow[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRow[0].payload, this.realSessionId, "last staged row"));
-            await conn.query("UPDATE session_meta SET owner = ?, updated_at = ?, leaf_id = ?, leaf_seq = ? WHERE session_id = ?", [owner, now, leafId, srcIds.length, this.realSessionId]);
+            const [settle] = await conn.query(`UPDATE session_meta SET owner = ?, updated_at = ?, leaf_id = ?, leaf_seq = ?, ${MIRROR_ON_COMMIT_SET} WHERE session_id = ? AND ${MIRROR_ON_COMMIT_GUARD}`, [owner, now, leafId, srcIds.length, this.realSessionId]);
+            if (settle.affectedRows !== 1) {
+                const locked = readPlacementRowStatement("mysql", this.realSessionId, { lock: true });
+                const [lockedRows] = await conn.query(locked.text, [...locked.values]);
+                const cell = lockedRows[0] === undefined ? undefined : placementCellFromRow(this.realSessionId, lockedRows[0]);
+                await conn.rollback();
+                if (cell?.role === "writer")
+                    throw new SessionWriterPresentError(this.realSessionId, cell.lane);
+                throw new SessionError("storage", `staged commit for ${this.realSessionId}: the commit point matched no row under a held row lock and the row is not a writer — refusing to guess`);
+            }
             const [afterMeta] = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = ?", [this.realSessionId]);
             if (afterMeta[0]?.placement_kind != null) {
                 await conn.rollback();
@@ -548,7 +616,7 @@ class TiDBStagingHandle {
                 await conn.rollback();
             }
             catch { }
-            if (err instanceof SyncConflictError || err instanceof SessionError)
+            if (err instanceof SyncConflictError || err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
                 throw err;
             throw new SessionError("storage", `staged commit for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
         }

package/dist/plugins/tool-result-store-sql.d.ts

@@ -1,7 +1,7 @@
 import type { ToolResultProvenance, ToolResultStore, ToolResultSlice, ToolResultDeletionReport } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
-import { type SqlDriver } from "./sql-driver.js";
+import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 /** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
@@ -15,18 +15,19 @@ export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>
 /**
  * [ref] 升级前置断言 —— **拒启**,不是 warn(codex 复审 [high],已核真)。
  *
- * 病:本仓不发 `ALTER TABLE` 迁移(标准裁定:改列就改 CREATE + 删库重建)。于是一台**没删表**就升上来的
+ * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:代码是唯一真源,存量库缺列由部署者按拒启句打印的 ALTER 自己执行)。于是一台**没跟上**就升上来的
  * 部署,`CREATE TABLE IF NOT EXISTS` 对它是空操作,旧表既没有出处两列也只有 `VARCHAR(190)` 的 ref 列。
  * 那样跑起来的后果不是「少个功能」:每一次 offload 写都会撞 unknown column 报错,而 core 的 offload
  * 失败臂会把错误吞成一条内联占位("[offload LOST at write time…]")—— 服务照跑,工具产物全丢,日志里只有
  * 一句看不出根因的话。这正是「响亮或 fail-closed,禁静默降级」那条要挡的形态。
  *
  * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
- * 探不通即拒启,错误文案直接给出两条方言的动作(删表重建),不让运维去猜。
+ * 探针读抛且是**可证**的缺列 ⇒ 拒启(其余错误原样上抛,与兄弟探针同一条规则)。拒因的出路是**闭集三条**(与整库对账同一份,{@link describeProbedTableDrift} / {@link schemaWaysOut}),没有销毁性的一条:
+ * 缺的出处两列由对账同一套件逐条打印 `ALTER TABLE tool_result ADD COLUMN …`;键宽不够则第 (2) 条是部署者自己把 `ref` 加宽到本构建的定义。
  */
 export declare function assertToolResultProvenanceSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
-}>, dialect: "tidb" | "pg"): Promise<void>;
+}>, dialect: SqlDialect): Promise<void>;
 /** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;

package/dist/plugins/tool-result-store-sql.js

@@ -3,6 +3,8 @@ import { pgSanitizeText } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { describeProbedTableDrift, schemaWaysOut } from "./schema-drift-sentence.js";
+import { isMissingColumnError } from "./sql-errors.js";
 export const PG_TOOL_RESULT_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS tool_result (
      ref              VARCHAR(518) COLLATE "C" NOT NULL,
@@ -22,29 +24,35 @@ export async function ensureSchema(pool) {
     await ensureIndexes((t, p) => pool.query(t, p), "pg", TOOL_RESULT_INDEXES);
 }
 export async function assertToolResultProvenanceSchema(query, dialect) {
-    const widthRow = await query(dialect === "tidb"
+    const widthRow = await query(dialect === "mysql"
         ? "SELECT CHARACTER_MAXIMUM_LENGTH AS len FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = 'tool_result' AND column_name = 'ref'"
         : "SELECT character_maximum_length AS len FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = 'tool_result' AND column_name = 'ref'").catch(() => ({ rows: [] }));
     const width = Number(widthRow.rows[0]?.len ?? NaN);
     if (Number.isFinite(width) && width < MAX_MINTED_TOOL_RESULT_REF_CHARS) {
         throw new Error(`tool_result.ref is VARCHAR(${width}) but core 5.26.0 mints refs up to ${MAX_MINTED_TOOL_RESULT_REF_CHARS} characters ` +
-            `(#119 made the ref injective: four \`~\`-separated segments). A truncating primary key aliases two distinct refs onto ` +
-            `one row — one run's tool output reads back from another run's ref. This repository ships no ALTER TABLE migrations: ` +
-            `run \`DROP TABLE tool_result;\` on the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart ` +
-            `(the schema is recreated at boot; offloaded results are a recoverable-window cache, inline previews are unaffected).`);
+            `(#119 made the ref injective: four \`~\`-separated segments) — refusing to start. A truncating primary key aliases two distinct refs onto ` +
+            `one row — one run's tool output reads back from another run's ref. ` +
+            `The ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database is behind this build on that key column; offloaded results are a recoverable-window cache, ` +
+            `inline previews in transcripts are unaffected.\n\n` +
+            `  table tool_result: column ref is VARCHAR(${width}); this build needs at least VARCHAR(${MAX_MINTED_TOOL_RESULT_REF_CHARS}) — the database is OLDER than this build.\n\n` +
+            schemaWaysOut({
+                when: "a key column is narrower than this build declares",
+                action: "run an ALTER TABLE that widens tool_result.ref to this build's definition yourself",
+            }).join("\n"));
     }
     try {
         await query("SELECT owner_session_id, owner_task_id FROM tool_result WHERE 1=0");
     }
     catch (err) {
+        if (!isMissingColumnError(err, dialect))
+            throw err;
         throw new Error(`tool_result is missing the #119 provenance columns (owner_session_id / owner_task_id) — refusing to start. ` +
             `This release picks up @sema-agent/core 5.26.0, which changed how an offloaded tool result is addressed ` +
-            `(the ref grew past the old VARCHAR(190) key) and made the store record who wrote each row. This repository ` +
-            `ships no ALTER TABLE migrations, so the table must be recreated: run \`DROP TABLE tool_result;\` on the ` +
-            `${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart — the schema is recreated at boot. ` +
-            `Offloaded tool results are a recoverable-window cache (the inline previews in transcripts are unaffected), ` +
-            `so the cost is at most the full text of results from runs still in flight. ` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+            `(the ref grew past the old VARCHAR(190) key) and made the store record who wrote each row. Without the columns every offload write ` +
+            `fails with unknown column and core's failure arm turns it into an inline placeholder — the service keeps running and the tool output is lost. ` +
+            `Offloaded tool results are a recoverable-window cache (the inline previews in transcripts are unaffected).\n` +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+            (await describeProbedTableDrift(query, dialect, ["tool_result"])));
     }
 }
 export class SqlToolResultStore {
@@ -54,8 +62,8 @@ export class SqlToolResultStore {
         this.db = db;
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     isUnsafeRef(ref) {
         try {

package/dist/plugins/user-input-ledger-sql.js

@@ -69,8 +69,8 @@ export class SqlUserInputLedgerStore {
     constructor(db) {
         this.db = db;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     async accept(a) {
         try {

package/dist/plugins/workflow-journal-store-sql.js

@@ -15,8 +15,8 @@ export class SqlWorkflowJournalStore {
         this.db = db;
         this.resumeClaimTtlMs = opts?.resumeClaimTtlMs ?? DEFAULT_RESUME_CLAIM_TTL_MS;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     async append(runId, scope, entry) {
         assertJournalEntryFits(entry);
@@ -35,7 +35,7 @@ export class SqlWorkflowJournalStore {
         }
     }
     async load(runId, scope) {
-        const { rows } = await this.db.query(this.q(`SELECT call_key, ${jsonColumnText("tidb", "result")} FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC`, `SELECT call_key, ${jsonColumnText("pg", "result")} FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC`), [runId, scope]);
+        const { rows } = await this.db.query(this.q(`SELECT call_key, ${jsonColumnText("mysql", "result")} FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC`, `SELECT call_key, ${jsonColumnText("pg", "result")} FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC`), [runId, scope]);
         return rows.map((r) => {
             const callKey = String(r.call_key);
             return journalEntryOfCell(runId, callKey, r.result, `workflow_journal.result for run ${runId} entry ${callKey}`);
@@ -69,10 +69,10 @@ export class SqlWorkflowJournalStore {
         return row !== undefined && row.ordinal === ordinal && row.resultJson !== null ? row.resultJson : undefined;
     }
     async readRows(runId, scope, from, limit, inlineBytes) {
-        const params = this.db.dialect === "tidb"
+        const params = this.db.dialect === "mysql"
             ? [inlineBytes, runId, scope, from, limit]
             : [runId, scope, inlineBytes, from, limit];
-        const { rows } = await this.db.query(this.q(`SELECT ordinal, call_key, CASE WHEN LENGTH(result) > ? THEN NULL ELSE ${jsonColumnTextExpr("tidb", "result")} END AS result_json, LENGTH(result) AS result_bytes FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = ? AND scope = ? AND ordinal >= ? ORDER BY ordinal ASC LIMIT ?`, `SELECT ordinal, call_key, CASE WHEN OCTET_LENGTH(result) > $3 THEN NULL ELSE ${jsonColumnTextExpr("pg", "result")} END AS result_json, OCTET_LENGTH(result) AS result_bytes FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = $1 AND scope = $2 AND ordinal >= $4 ORDER BY ordinal ASC LIMIT $5`), params);
+        const { rows } = await this.db.query(this.q(`SELECT ordinal, call_key, CASE WHEN LENGTH(result) > ? THEN NULL ELSE ${jsonColumnTextExpr("mysql", "result")} END AS result_json, LENGTH(result) AS result_bytes FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = ? AND scope = ? AND ordinal >= ? ORDER BY ordinal ASC LIMIT ?`, `SELECT ordinal, call_key, CASE WHEN OCTET_LENGTH(result) > $3 THEN NULL ELSE ${jsonColumnTextExpr("pg", "result")} END AS result_json, OCTET_LENGTH(result) AS result_bytes FROM workflow_journal JOIN workflow_journal_owner USING (run_id, incarnation) WHERE run_id = $1 AND scope = $2 AND ordinal >= $4 ORDER BY ordinal ASC LIMIT $5`), params);
         return rows.map((r) => ({ ordinal: Number(r.ordinal), callKey: String(r.call_key), resultJson: r.result_json === null ? null : String(r.result_json), resultBytes: Number(r.result_bytes) }));
     }
     async deleteByRun(runId) {