@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/execution-placement-sql.js

@@ -1,29 +1,15 @@
 import { isExecutionLane } from "../execution-lane-caps.js";
+import { retiredExecutionLaneHintM40 } from "./execution-lane-rename-m40.js";
 import { sessionFaceFromRow } from "../session-incarnation.js";
 import { toIso } from "./sql-row-helpers.js";
+import { SESSION_EXT_TABLE, ensureSessionExtRowStatement, ensureSessionExtRowsStatement } from "./session-ext-table.js";
 import { WRITABLE, assertPlaceableLane, boundDeviceOf, settledMirrorOutcome, settledPlaceOutcome, } from "../execution-placement.js";
-export const SESSION_META_PLACEMENT_COLUMNS = [
-    { name: "execution_role", mysql: "execution_role VARCHAR(16) NULL", pg: `execution_role VARCHAR(16) COLLATE "C"` },
-    { name: "execution_lane", mysql: "execution_lane VARCHAR(32) NULL", pg: `execution_lane VARCHAR(32) COLLATE "C"` },
-    { name: "execution_device_id", mysql: "execution_device_id VARCHAR(64) NULL", pg: `execution_device_id VARCHAR(64) COLLATE "C"` },
-    { name: "execution_device_owner_tenant", mysql: "execution_device_owner_tenant VARCHAR(190) NULL", pg: `execution_device_owner_tenant VARCHAR(190) COLLATE "C"` },
-    { name: "execution_device_owner_subject", mysql: "execution_device_owner_subject VARCHAR(190) NULL", pg: `execution_device_owner_subject VARCHAR(190) COLLATE "C"` },
-    { name: "execution_placed_at", mysql: "execution_placed_at DATETIME(3) NULL", pg: "execution_placed_at TIMESTAMPTZ(3)" },
-    { name: "execution_rev", mysql: "execution_rev BIGINT NULL", pg: "execution_rev BIGINT" },
-    { name: "fork_key", mysql: "fork_key VARCHAR(255) NULL", pg: `fork_key VARCHAR(255) COLLATE "C"` },
-];
-export function sessionMetaPlacementColumnsDdl(dialect) {
-    return SESSION_META_PLACEMENT_COLUMNS.map((c) => c[dialect]).join(",\n     ");
-}
 const WRITER = "writer";
 const MIRROR = "mirror";
 const NOT_WRITER = "(execution_role IS NULL OR execution_role <> 'writer')";
-export const MIRROR_ON_COMMIT_SET = "execution_role = 'mirror'";
-export const MIRROR_ON_COMMIT_GUARD = NOT_WRITER;
-export function importedRowCells(forkKey) {
-    return { columns: "fork_key, execution_role", values: [forkKey, MIRROR] };
-}
-export const SESSION_META_PLACEMENT_READ_COLUMNS = "owner, incarnation, placement_kind, execution_role, execution_lane, execution_device_id, execution_device_owner_tenant, execution_device_owner_subject, execution_placed_at, execution_rev";
+const EXECUTION_CELL_COLUMNS = "execution_role, execution_lane, execution_device_id, execution_device_owner_tenant, execution_device_owner_subject, execution_placed_at, execution_rev";
+const OCCUPANT_COLUMNS = "owner, incarnation, placement_kind";
+const READING_COLUMNS = `sm.owner, sm.incarnation, sm.placement_kind, ${EXECUTION_CELL_COLUMNS.split(", ").map((c) => `se.${c}`).join(", ")}`;
 function binder(dialect) {
     const values = [];
     return {
@@ -34,38 +20,37 @@ function binder(dialect) {
         },
     };
 }
-function occupantPredicate(dialect, p, root, occupant) {
-    const nullSafeEq = dialect === "pg" ? "IS NOT DISTINCT FROM" : "<=>";
-    return `session_id = ${p(root)} AND incarnation = ${p(occupant.incarnation)} AND owner ${nullSafeEq} ${p(occupant.owner)} AND placement_kind IS NULL`;
-}
-export function readPlacementRowStatement(dialect, root, opts) {
+export function readPlacementRowStatement(dialect, root) {
     const b = binder(dialect);
-    return { text: `SELECT ${SESSION_META_PLACEMENT_READ_COLUMNS} FROM session_meta WHERE session_id = ${b.p(root)}${opts.lock ? " FOR UPDATE" : ""}`, values: b.values };
+    return { text: `SELECT ${READING_COLUMNS} FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE sm.session_id = ${b.p(root)}`, values: b.values };
 }
-export function placeWriterStatement(dialect, root, occupant, cell, now) {
+export function placeWriterStatement(dialect, root, cell, now) {
     const b = binder(dialect);
     const set = `execution_role = '${WRITER}', execution_lane = ${b.p(cell.lane)}, execution_device_id = ${b.p(cell.device?.id ?? null)}, ` +
         `execution_device_owner_tenant = ${b.p(cell.device?.owner.tenant ?? null)}, execution_device_owner_subject = ${b.p(cell.device?.owner.subject ?? null)}, ` +
         `execution_placed_at = ${b.p(now)}, execution_rev = 0`;
-    return { text: `UPDATE session_meta SET ${set} WHERE ${occupantPredicate(dialect, b.p, root, occupant)} AND execution_role IS NULL`, values: b.values };
+    return { text: `UPDATE ${SESSION_EXT_TABLE} SET ${set} WHERE session_id = ${b.p(root)} AND execution_role IS NULL`, values: b.values };
 }
-export function bindDeviceStatement(dialect, root, occupant, device, now) {
+export function bindDeviceStatement(dialect, root, device, now) {
     const b = binder(dialect);
     const set = `execution_device_id = ${b.p(device.id)}, execution_device_owner_tenant = ${b.p(device.owner.tenant)}, execution_device_owner_subject = ${b.p(device.owner.subject)}, execution_placed_at = ${b.p(now)}, execution_rev = 0`;
     return {
-        text: `UPDATE session_meta SET ${set} WHERE ${occupantPredicate(dialect, b.p, root, occupant)} AND execution_role = '${WRITER}' AND execution_lane = 'device' AND execution_device_id IS NULL`,
+        text: `UPDATE ${SESSION_EXT_TABLE} SET ${set} WHERE session_id = ${b.p(root)} AND execution_role = '${WRITER}' AND execution_lane = 'device' AND execution_device_id IS NULL`,
         values: b.values,
     };
 }
-export function rebindDeviceStatement(dialect, root, occupant, owner, expectedRev, targetDeviceId, now) {
+export function rebindDeviceStatement(dialect, root, owner, expectedRev, targetDeviceId, now) {
     const b = binder(dialect);
     const set = `execution_device_id = ${b.p(targetDeviceId)}, execution_placed_at = ${b.p(now)}, execution_rev = execution_rev + 1`;
-    const where = `${occupantPredicate(dialect, b.p, root, occupant)} AND execution_role = '${WRITER}' AND execution_lane = 'device' ` +
+    const where = `session_id = ${b.p(root)} AND execution_role = '${WRITER}' AND execution_lane = 'device' ` +
         `AND execution_device_owner_tenant = ${b.p(owner.tenant)} AND execution_device_owner_subject = ${b.p(owner.subject)} AND execution_rev = ${b.p(expectedRev)}`;
-    return { text: `UPDATE session_meta SET ${set} WHERE ${where}`, values: b.values };
+    return { text: `UPDATE ${SESSION_EXT_TABLE} SET ${set} WHERE ${where}`, values: b.values };
 }
 export function deviceCellRowsStatement() {
-    return { text: `SELECT session_id, ${SESSION_META_PLACEMENT_READ_COLUMNS} FROM session_meta WHERE execution_device_id IS NOT NULL AND placement_kind IS NULL`, values: [] };
+    return {
+        text: `SELECT se.session_id, ${EXECUTION_CELL_COLUMNS.split(", ").map((c) => `se.${c}`).join(", ")} FROM ${SESSION_EXT_TABLE} se JOIN session_meta sm ON sm.session_id = se.session_id WHERE se.execution_device_id IS NOT NULL AND sm.placement_kind IS NULL`,
+        values: [],
+    };
 }
 export async function countDeviceBindingsOn(conn) {
     const s = deviceCellRowsStatement();
@@ -75,9 +60,9 @@ export async function countDeviceBindingsOn(conn) {
             bindings += 1;
     return bindings;
 }
-export function markMirrorStatement(dialect, root, occupant) {
+export function markMirrorStatement(dialect, root) {
     const b = binder(dialect);
-    return { text: `UPDATE session_meta SET execution_role = '${MIRROR}' WHERE ${occupantPredicate(dialect, b.p, root, occupant)} AND ${NOT_WRITER}`, values: b.values };
+    return { text: `UPDATE ${SESSION_EXT_TABLE} SET execution_role = '${MIRROR}' WHERE session_id = ${b.p(root)} AND ${NOT_WRITER}`, values: b.values };
 }
 export function backfillWriterStatement(dialect, lane, now) {
     const b = binder(dialect);
@@ -105,6 +90,31 @@ export function migrateDeviceBindingsStatement(dialect, sourceTable) {
         values: [],
     };
 }
+export function migrateDeviceBindingsOntoSideTableStatements(dialect, sourceTable) {
+    if (dialect === "pg") {
+        return [
+            ensureSessionExtRowsStatement(dialect, `SELECT sm.session_id FROM ${sourceTable} ds JOIN session_meta sm ON sm.session_id = ds.root_session_id WHERE sm.placement_kind IS NULL`),
+            {
+                text: `UPDATE ${SESSION_EXT_TABLE} SET execution_role = '${WRITER}', execution_lane = 'device', execution_device_id = ds.device_id, ` +
+                    "execution_device_owner_tenant = ds.owner_tenant, execution_device_owner_subject = ds.owner_subject, execution_placed_at = ds.bound_at, execution_rev = ds.rev " +
+                    `FROM ${sourceTable} ds, session_meta sm WHERE ds.root_session_id = ${SESSION_EXT_TABLE}.session_id AND sm.session_id = ${SESSION_EXT_TABLE}.session_id AND sm.placement_kind IS NULL`,
+                values: [],
+            },
+        ];
+    }
+    const str = (col) => `CONVERT(ds.${col} USING utf8mb4)`;
+    const rootKey = `${str("root_session_id")} COLLATE utf8mb4_bin`;
+    return [
+        ensureSessionExtRowsStatement(dialect, `SELECT sm.session_id FROM ${sourceTable} ds JOIN session_meta sm ON ${rootKey} = sm.session_id WHERE sm.placement_kind IS NULL`),
+        {
+            text: `UPDATE ${SESSION_EXT_TABLE} se JOIN session_meta sm ON sm.session_id = se.session_id JOIN ${sourceTable} ds ON ${rootKey} = se.session_id ` +
+                `SET se.execution_role = '${WRITER}', se.execution_lane = 'device', se.execution_device_id = ${str("device_id")}, ` +
+                `se.execution_device_owner_tenant = ${str("owner_tenant")}, se.execution_device_owner_subject = ${str("owner_subject")}, se.execution_placed_at = ds.bound_at, se.execution_rev = ds.rev ` +
+                "WHERE sm.placement_kind IS NULL",
+            values: [],
+        },
+    ];
+}
 export function countOrphanBindingsStatement(dialect, sourceTable) {
     const rootKey = dialect === "pg" ? "ds.root_session_id" : "CONVERT(ds.root_session_id USING utf8mb4) COLLATE utf8mb4_bin";
     return {
@@ -135,7 +145,7 @@ export function placementCellFromRow(root, row) {
         throw new ExecutionPlacementRowError(root, `role ${JSON.stringify(text(role))} is not writer / mirror / NULL`);
     const lane = isNull(row.execution_lane) ? "" : text(row.execution_lane);
     if (!isExecutionLane(lane))
-        throw new ExecutionPlacementRowError(root, `writer lane ${JSON.stringify(lane)} is not an execution lane`);
+        throw new ExecutionPlacementRowError(root, `writer lane ${JSON.stringify(lane)} is not an execution lane${retiredExecutionLaneHintM40(lane)}`);
     if (isNull(row.execution_device_id)) {
         if (deviceCols.some((v) => !isNull(v)))
             throw new ExecutionPlacementRowError(root, "device owner without a device");
@@ -164,37 +174,69 @@ export function placementReadingFromRow(root, row) {
 export function rowsOnSqlExec(exec) {
     return async (sql, values) => (await exec.query(sql, [...values])).rows;
 }
-export async function lockRootAndReadClaim(conn, dialect, root) {
+async function lockRootOn(conn, dialect, root) {
+    const ph = dialect === "pg" ? "$1" : "?";
+    return (await conn(`SELECT ${OCCUPANT_COLUMNS} FROM session_meta WHERE session_id = ${ph} FOR UPDATE`, [root]))[0];
+}
+export async function readClaimOn(conn, dialect, root) {
     const ph = dialect === "pg" ? "$1" : "?";
-    const row = await conn(`SELECT session_id FROM session_meta WHERE session_id = ${ph} FOR UPDATE`, [root]);
-    if (row.length === 0)
-        return { rowPresent: false, activeTaskId: null };
     const claim = await conn(`SELECT task_id FROM task_active WHERE session_id = ${ph} FOR UPDATE`, [root]);
-    return { rowPresent: true, activeTaskId: claim[0] === undefined ? null : text(claim[0].task_id) };
+    return claim[0] === undefined ? null : text(claim[0].task_id);
+}
+export async function lockRootAndReadClaim(conn, dialect, root) {
+    if ((await lockRootOn(conn, dialect, root)) === undefined)
+        return { rowPresent: false, activeTaskId: null };
+    return { rowPresent: true, activeTaskId: await readClaimOn(conn, dialect, root) };
+}
+export async function readCellOn(conn, dialect, root) {
+    const ph = dialect === "pg" ? "$1" : "?";
+    const ensure = ensureSessionExtRowStatement(dialect, root);
+    await conn(ensure.text, ensure.values);
+    const row = (await conn(`SELECT ${EXECUTION_CELL_COLUMNS} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${ph} FOR UPDATE`, [root]))[0];
+    return placementCellFromRow(root, row ?? {});
 }
 export async function readPlacementOn(conn, dialect, root) {
-    const s = readPlacementRowStatement(dialect, root, { lock: true });
-    return placementReadingFromRow(root, (await conn(s.text, s.values))[0]);
+    const occupant = await lockRootOn(conn, dialect, root);
+    if (occupant === undefined || !isNull(occupant.placement_kind))
+        return undefined;
+    return { occupant: sessionFaceFromRow(root, isNull(occupant.owner) ? null : text(occupant.owner), occupant.incarnation), cell: await readCellOn(conn, dialect, root) };
+}
+export async function writeCellOn(exec, dialect, root, statement) {
+    const res = await exec.query(statement.text, [...statement.values]);
+    if (res.affected !== 1)
+        throw placementInvariant(root, `a cell write (${statement.text.slice(0, 48)}…)`);
 }
 function placementInvariant(root, what) {
-    return new Error(`execution placement of session ${root}: ${what} matched no row while a re-read finds the cell writable — engine/driver anomaly, refusing to guess`);
+    return new Error(`execution placement of session ${root}: ${what} matched no row under a held root-row lock after the judge found the cell writable — engine/driver anomaly, refusing to guess`);
 }
 export function createSqlExecutionPlacementSeat(db) {
     const read = async (root) => {
-        const s = readPlacementRowStatement(db.dialect, root, { lock: false });
+        const s = readPlacementRowStatement(db.dialect, root);
         return placementReadingFromRow(root, (await db.query(s.text, [...s.values])).rows[0]);
     };
     return {
         read,
         async place(root, occupant, cell) {
             assertPlaceableLane(root, cell);
-            const s = placeWriterStatement(db.dialect, root, occupant, { lane: cell.lane }, new Date());
-            if ((await db.query(s.text, [...s.values])).affected === 1)
+            const conn = await db.connect();
+            try {
+                await conn.begin();
+                const settled = settledPlaceOutcome(root, await readPlacementOn(rowsOnSqlExec(conn), db.dialect, root), occupant, cell);
+                if (settled !== WRITABLE) {
+                    await conn.rollback();
+                    return settled;
+                }
+                await writeCellOn(conn, db.dialect, root, placeWriterStatement(db.dialect, root, { lane: cell.lane }, new Date()));
+                await conn.commit();
                 return { outcome: "placed" };
-            const settled = settledPlaceOutcome(root, await read(root), occupant, cell);
-            if (settled === WRITABLE)
-                throw placementInvariant(root, "place");
-            return settled;
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
         },
         async markMirror(root, occupant) {
             const conn = await db.connect();
@@ -215,9 +257,7 @@ export function createSqlExecutionPlacementSeat(db) {
                     await conn.rollback();
                     return { outcome: "active", activeTaskId: claim.activeTaskId };
                 }
-                const s = markMirrorStatement(db.dialect, root, occupant);
-                if ((await conn.query(s.text, [...s.values])).affected !== 1)
-                    throw placementInvariant(root, "markMirror under a held row lock");
+                await writeCellOn(conn, db.dialect, root, markMirrorStatement(db.dialect, root));
                 await conn.commit();
                 return { outcome: "mirrored" };
             }

package/dist/plugins/file-run-store.d.ts

@@ -1,6 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
-import { StoreBootRefusalError, type FenceLanded, type FencedRun, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } from "./store-contracts.js";
+import { StoreBootRefusalError, type RunStallWiring, type SessionRootRows, type FenceLanded, type FencedRun, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionRunRollup, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
@@ -8,8 +8,8 @@ import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState }
  * `RUN_STORE_STRICT_HYDRATE=on` 下 hydrate 列不出 `runs/` 时的**拒启**类型([ref] 件B;codex 对抗复审
  * R1-[high] 验真后从裸 `Error` 升成具名类型)。
  *
- * 🔴 **为什么必须是一个类型而不是一句文案**:`openStoreBackendWithFallback` 对**默认推导**的 local
- * (`DB_BACKEND` 未设)有一条既有降级臂 —— mkdir / 只读盘那类「这台机器存不了盘」的失败降级到内存继续起。
+ * 🔴 **为什么必须是一个类型而不是一句文案**(修前形;降级臂改按数据根状态判之后,`runs/` 在场的根已不会降级,类型仍是拒句的属主):`openStoreBackendWithFallback` 对**默认推导**的 local
+ * (`DB_BACKEND` 未设)曾有一条按错误种类判的降级臂 —— mkdir / 只读盘那类「这台机器存不了盘」的失败降级到内存继续起。
  * 本拒启从 `new LocalBackend(...)` 里冒出来,长得和它们一模一样,不给它一个可判别的身份就会被同一个
  * catch 吞掉:operator 明确要的 **fail-closed 反而变成 fail-open**,而且丢的正是持久 run 账本(这根旋钮
  * 存在的全部理由)。判据锚在**类型**上,不在文案上 —— 文案会改,类型不会(同文件族先例:`AdoptionError`
@@ -22,6 +22,13 @@ import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState }
 export declare class RunStoreStrictHydrateError extends StoreBootRefusalError {
     readonly name = "RunStoreStrictHydrateError";
 }
+/** run 店在数据根下自己铸的目录(构造器与一次性迁移 M39 的名册同读这一只:名册的路径 = 店真实铸的路径)。 */
+export declare function fileRunStoreDirsFor(root: string): {
+    readonly runs: string;
+    readonly active: string;
+    readonly tmp: string;
+    readonly spaceCommits: string;
+};
 export declare class FileRunStore implements InProcessClaimFence {
     private readonly runsDir;
     private readonly activeDir;
@@ -58,12 +65,22 @@ export declare class FileRunStore implements InProcessClaimFence {
     private readonly claimLocks;
     /** 件6(#43 案 [ref]):启动期告警座(可选)。既有调用方不传 ⇒ 只走 fail-open 遥测那一半,不炸。 */
     private readonly logger;
+    /**
+     * 规则 L 的根行面({@link SessionRootRows}):`createRun` 先在它的锁里判根行在不在,再取认领锁。**必填**、惰性取(会话店构造时要本店,
+     * 所以装配方交一只取法:`LocalBackend` = `() => this.sessionStore`)。没有可选形、没有 setter、没有缺省:缺它的 run 店答不出 `sessionAbsent`,
+     * 删除 / 导入 / markMirror 读到的认领就又能被超车。
+     */
+    private readonly rootRows;
     /** [ref] 件B(census 第 29 行终局):`RUN_STORE_STRICT_HYDRATE` 的**部署级**表态。
      *  `true` ⇒ hydrate 的 readdir 失败拒启;缺席/`false` ⇒ 件6 的记债腿,行为字节不变。 */
     private readonly strictHydrate;
-    constructor(root: string, opts?: {
+    /** 落死亡判决的窗与计数(构造时拿到;SQL 孪生同注,见 {@link RunStallWiring})。 */
+    private readonly stall;
+    constructor(root: string, opts: {
+        readonly rootRows: () => SessionRootRows;
         error?(msg: string, fields?: Record<string, unknown>): void;
         strictHydrate?: boolean;
+        readonly stall?: RunStallWiring;
     });
     private runDir;
     private runJsonPath;
@@ -96,7 +113,7 @@ export declare class FileRunStore implements InProcessClaimFence {
      *
      * `readJsonlRecords` 对 ENOENT 答 `[]`、对其余读错(EACCES / EIO / EISDIR / ENOTDIR)**抛普通 Error**
      * (亲验 core `dist/stores/file/fs-atomic.js`)。那个普通 Error 从构造器冒出去之后,在**默认
-     * 推导**的 local 后端上会被 `openStoreBackendWithFallback` 的降级臂吞成 memory —— 也就是说 strict 开着
+     * 推导**的 local 后端上修前会被 `openStoreBackendWithFallback` 的降级臂吞成 memory —— 也就是说 strict 开着
      * 也照样带着残缺账本(或直接换成内存)起动,两处 readdir 门白守。
      *
      * ⇒ strict 档:非 ENOENT 的读盘失败一律转成 {@link RunStoreStrictHydrateError}(带路径 + 原文),由
@@ -118,13 +135,21 @@ export declare class FileRunStore implements InProcessClaimFence {
      */
     private refuseIfUnreadable;
     private hydrate;
-    /** run.json 的整文件原子替换 —— {@link persist} 的落盘那一半,不碰索引。 */
+    /** run.json 的整文件原子替换 —— {@link persist} 的落盘那一半,不碰索引(只有 `persist` 调它)。 */
     private writeRunFile;
-    /** Commit a RunRow to disk (whole-file atomic replace) AND the index — the single write path for every status change.
-     *  落盘在前、`runs.set` 在后:落盘抛 ⇒ 索引原样。要「全有或全无」的写口因此不在索引里那只行上原地先改再调 —— 原地改过的行,落盘一抛就是「内存已改、盘上没改」。
-     *  两种不原地的写法:对**副本**调本口(索引里换成副本:`releaseIdemKey` / `bindIdemBodyFingerprint` / `takeOverClaim`);或副本只走 {@link writeRunFile},
-     *  落成之后把改动**合回索引里的同一只行**(`fillObjectivePreview`)——后一种用在会撞进收割腿 await 窗的写口上:`reapSuspended` 等收割腿在 probe 的 await 之间手里持着索引里的行对象,
-     *  await 之后的复核读的就是这只对象,索引里的行被换成副本,它们就看不见之后的认领 / 取消了。 */
+    /**
+     * 索引里的行**只有这一条写律**,每个写口(建行 / 状态迁移 / 心跳 / 取消位 / 幂等绑定 / 接管 / 预览补写)都走它:
+     * **对副本判改 → 落盘成功 → 把改动合进索引里的同一只行对象**(索引里没有这一行才 `set` —— 建行)。
+     * 写口的形状恒为「在入口守卫读到的行上判,`{ ...r, 改动 }` 铸一份副本,交给本口」;`RunRow` 字段全 `readonly`,原地改一只行编不过。
+     *
+     * 三条后果都从这一条律拿到,不另设规则:
+     *  · 落盘抛 ⇒ 索引里的行一字未动 —— 内存与盘同值,入口守卫读到的还是旧状态,重试照常补回。原地先改再落盘的写法,抛的那一拍把内存和盘劈成两半,
+     *    而改过的 `status` 还会让「首个终局写者赢」一类守卫把重试挡回 —— 盘上永远落不下那一笔(终局结果丢失,重启后被当孤儿记成 failed);
+     *  · 落成之后索引里还是**同一只**行对象 —— 跨 await 持着行的收割腿(`reapSuspended` / `failSuspendedWithExpiredCheckpoint` / `reclaimOrphanedAtBoot`)
+     *    await 之后的复核读的就是手上这只对象,换成副本它们就看不见期间的认领 / 取消 / 接管(再写一遍,把已被别腿落定的行盖掉);
+     *  · 落盘与合回之间没有让出点(本口同步、体内无 await)⇒ 别的写者与收割腿读到的要么是落成前的行、要么是落成后的行,没有「盘已新、索引未合」的中间态。
+     *    在落盘与合回之间插 await 或别的事,就回到了收割写者会撞中间态的形(`test/file-run-store-persist-law.test.ts` 的结构钉守这一格)。
+     */
     private persist;
     private eventLogFor;
     /** Create a run iff the session has no active run (the task_active unique-key claim) AND no submission key of this
@@ -143,16 +168,16 @@ export declare class FileRunStore implements InProcessClaimFence {
      *  different claim locks) cannot both pass the check: the loser observes the winner's row. */
     private commitNewRun;
     /** run 行预览的写一次补写(SQL 孪生同义:列仍是 null 才写,建行写过 / 已补过的不动;行不在 ⇒ 无事)。
-     *  **副本判改 → 落盘 → 合回**:先把改动落在副本上写盘,落盘抛 ⇒ 内存里的行一字未动(预览仍是 null)、盘上也原样,下一次补写照常再试;
-     *  落成之后再把预览合回索引里的**同一只**行对象(不换对象:跨 await 持着行的收割腿复核读的是手上这只对象)。
+     *  走 {@link persist} 的写律:落盘抛 ⇒ 内存里的行一字未动(预览仍是 null)、盘上也原样,下一次补写照常再试 ——
      *  原地先改再落盘,抛的那一拍就把内存和盘劈成两半(内存带预览、盘上 null),且「列已有值」的早退让这一分叉再也补不回来。
-     *  本体同步执行到底,中间没有 await ⇒ 副本落盘与合回之间没有别的写者插进来。 */
+     *  预览补写不碰 `updatedAt`(一次预览补写不是一次活性刷新)。 */
     fillObjectivePreview(taskId: string, preview: string): Promise<void>;
     requestCancel(taskId: string, owner: string | null): Promise<boolean>;
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
     requestPreempt(taskId: string, owner: string | null): Promise<boolean>;
     isPreemptRequested(taskId: string, owner: string | null): Promise<boolean>;
-    heartbeat(taskId: string, owner: string | null): Promise<void>;
+    /** 心跳:刷新并交回「行还在 running 吗」(持有者据它停腿;SQL 孪生同注)。 */
+    heartbeat(taskId: string, owner: string | null): Promise<boolean>;
     appendEvent(taskId: string, seq: number, type: LedgerEventType, data: unknown): Promise<void>;
     /**
      * 写口里第四个盘面的那一段(与事件行的追加在**同一同步调用**里,块在前):帧经编解码拆成引用形 + 段体,本会话块账本里还没有的段体先追加
@@ -207,7 +232,7 @@ export declare class FileRunStore implements InProcessClaimFence {
     listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
      * [ref] —— 这个会话**最近一条腿**的窄指针({@link SqlRunStore.latestRunForSession} 的孪生:同一个排序口径
-     *  `createdAt DESC, taskId DESC`,与本店 {@link FileRunStore.listSessions} 挑 `rn=1` 那一行的比较器逐字同一份)。
+     *  `createdAt DESC, taskId DESC`,与本店窄读面 {@link FileRunStore.sessionRunRollups} 挑最新一条的比较器同一口径 —— `session-run-rollup.ts` 的 `newer`)。
      */
     latestRunForSession(sessionId: string): Promise<LatestRunRef | undefined>;
     /**
@@ -215,25 +240,16 @@ export declare class FileRunStore implements InProcessClaimFence {
      * {@link SqlRunStore.latestMemoryObservationForSession} 的孪生:同一只已结谓词(`isTerminalRunStatus`)、同一个排序口径 —— 与本店 {@link FileRunStore.latestRunForSession} 的比较器逐字同一份)。
      */
     latestMemoryObservationForSession(sessionId: string): Promise<SettledLegMemoryObservation | undefined>;
-    /** DISTINCT sessions newest-first by last activity (the CC /resume picker): latest run's preview/status + first/last/count. */
-    listSessions(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<SessionSummary[]>;
+    /** 会话枚举面读 run 账的窄读面(`SessionRunRollupSource`;规则 = 共用纯函数 {@link buildSessionRunRollups},与内存孪生、SQL 会话店的列表子查询同读)。 */
+    sessionRunRollups(opts?: {
+        readonly q?: string;
+    }): Promise<ReadonlyMap<string, SessionRunRollup>>;
     /** E21 (§0.5 delete) — purge the runs ledger for one session, scoped by `session_id` ALONE (per-row owner is the
-     *  submitting principal and diverges from the session owner — full 判据 see the SQL twin's head-note, F-A);
-     *  aborts (returns {active}) if a run is live。`expectedSessionOwner` = SQL 双生的化身围栏入参,本孪生执行不了
-     *  (账本里没有 session_meta),理由与替代围栏逐字见 {@link MemoryRunStore.deleteBySession}。 */
-    deleteBySession(sessionId: string, expectedSessionOwner: string | null): Promise<{
+     *  submitting principal and diverges from the session owner — full 判据 see the SQL twin's head-note, F-A)。
+     *  **不判认领**(会话三态,`src/session-deletion.ts`):唯一的生产调用点是删除协调器的账本腿,它在围栏(根行锁里判过「没有认领」、写下在删令牌)之后才调,
+     *  在删期间规则 L 不让认领落下 —— 这里没有可判的东西。 */
+    deleteBySession(sessionId: string): Promise<{
         removed: number;
-    } | {
-        active: string;
     }>;
     /** 用量扫窗——in-memory 腿:遍历窗内行,投影同 usage-analytics 纯函数(SQL 孪生 parity)。 */
     usageScan(fromMs: number, toMs: number, opts?: {
@@ -254,7 +270,13 @@ export declare class FileRunStore implements InProcessClaimFence {
     private sweepClaims;
     /** Flip every `running` row matching `pred` → failed (with the death sentence `reason` + its machine `code`), then sweep terminal claims. */
     private reapRunning;
-    reapStale(olderThanMs: number): Promise<number>;
+    /** 收割器(全表形;SQL 孪生同注):判决 `due` 的 `running` 行判死 + 放终局认领。窗读构造时拿到的 getter。 */
+    reapStale(): Promise<number>;
+    /**
+     * 观察口(落判决的三处之一;SQL 孪生同注):属主门之后的那条行 —— `due` ⇒ 单行判死(与收割器同一只 {@link reapRunning})+ 放认领、交回当前行;否则原样、零 I/O。
+     * 落盘失败 ⇒ F 类留痕 + 行原样交回(收割器下一拍补;副本写律保证索引里的行一字未动)。
+     */
+    observeRun(row: RunRecord): Promise<RunRecord>;
     /** TOC integration ask③ (INTEGRATION-DESIGN §11): a host-lane engine restart leaves the PREVIOUS process's
      *  `running` rows orphaned — their in-process driver (runInBackground, in the dead process's memory) is gone, but the
      *  `active/<sessionId>` claim persists on disk and EEXIST-blocks a re-submit (the shell reads the session as stuck).
@@ -370,13 +392,45 @@ export declare class FileRunStore implements InProcessClaimFence {
     private takeOverClaim;
     /** Release a session's single-active claim: unlink the claim file + drop the index entry (idempotent). */
     private releaseClaim;
-    /** Drop a run entirely (registry + event log + open fd + on-disk dir) — used by deleteBySession. */
+    /**
+     * 删一条 run 的**唯一删法**(删会话 {@link deleteBySession} 与提交出口的撤回 {@link withdrawRunsOf} 同一形)—— **严格**:盘先、索引后。
+     * 先关这条 run 的事件 fd(开着的文件在 win32 上删不掉;fd 只是缓存,下一次追加按需重开)→ 删 run 目录(删不掉 ⇒ **抛**,索引一个字节不动:这条 run 仍完整可读,
+     * 重试从同一状态开始)→ fsync `runs` 目录(删掉的目录项在盘上;win32 不 fsync 目录,与原子写同一条平台律)→ 才拆内存索引(事件、幂等键、行)。
+     * 修前是「先拆索引、删目录失败静默」:删不掉的目录在重启后 hydrate 回一条僵尸 run,而调用方已答「删了」。
+     */
     private dropRun;
+    /**
+     * 提交出口条件撤回的 run 半(`local-session-store.ts` 的 {@link SessionRunWithdrawSource};local 会话店在这只会话的写锁 = 根行锁里调 —— 本方法不取根行锁、不让出事件循环):
+     * 本会话有 `ownTaskId` 之外的 run 行 ⇒ `{ keep: "runs" }`,一个字节不删;否则与 {@link deleteBySession} 同序删:块账本先、本次 run 后(严格删法 {@link dropRun})。
+     * `ownTaskId` 那一行不属于这只会话 ⇒ 响亮抛(调用方交错了 id,不猜)。认领由调用方的判官先判过(在 ⇒ 不会走到这里)。
+     */
+    withdrawRunsOf(sessionId: string, ownTaskId: string | undefined): "proceed" | {
+        readonly keep: "runs";
+    };
+    /**
+     * 一次性迁移 **M44 的 local 腿**(窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):`errorCode` 只读列 —— 列建立之前 / 停驻写口不写列时写下的行,
+     * 列改写成「这条行在稳定、非到期时修前 `GET` 会答的码」= 结果投影的码(读盘面认两代形并折码)?? 列的原值;`running` 行的列置空(续跑认领清列)。盘上与内存同改(副本写律)。
+     * 起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);数据根独占 ⇒ 本车道没有混跑窗,不需要读侧半场。幂等:第二跑零命中零写盘。
+     */
+    migrateRunErrorCodeColumnM44(): number;
+    /**
+     * 一次性迁移 **M45 的 local 腿**(窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):预览列以闭集注入块开标签起头的行(7.124.0 之前写下的形)
+     * 剥到不动点 —— 判据与新值同 SQL 腿(`run-preview-m45.ts` 唯一一份)。盘上与内存同改(副本写律)。
+     * 起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);数据根独占 ⇒ 没有混跑窗。幂等:写后的值不再以开标签起头 ⇒ 第二跑零命中零写盘。
+     */
+    migrateRunObjectivePreviewM45(): number;
+    /**
+     * 一次性迁移 **M48 的 local 腿**(run 行半场;窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):属主恰为 cli 哨兵(`shell-sentinel-owner-m48.ts`)的 run 行
+     * 改写成无主。盘上与内存同改(副本写律)。起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);数据根独占 ⇒ 没有混跑窗。幂等:第二跑零命中零写盘。
+     */
+    clearShellSentinelOwnersM48(): number;
     /**
      * 一次性迁移 **M32 的 local 腿**(执行放置回填;窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):有 run 行的会话 id(去重)。
      * 起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);读内存索引(构造时已从盘上 hydrate),零写。
      */
     sessionIdsWithRuns(): ReadonlySet<string>;
+    /** 一次性迁移 **M42 的 local 腿**(场景前缀的切换检查;窗口见 `plugins/one-time-migrations.ts` 登记表):属主以保留前缀开头的 run 行数。读内存索引(构造时已 hydrate),零写。 */
+    scenarioPrefixOwnerRowsM42(): number;
     /** Release every open event-log fd (called by LocalBackend.close so a graceful restart can re-open the data dir). */
     dispose(): void;
 }