@sema-agent/server 7.147.0 → 7.148.0

package/dist/plugins/ensure-index.js

@@ -1,5 +1,7 @@
 import { recordFailOpen } from "../observability/fail-open.js";
 import { readLiveColumns } from "./schema-live-columns.js";
+import { isDupKeyErrorOfWrappedQuery } from "./sql-errors.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 function rowsOf(res) {
     if (Array.isArray(res)) {
         const first = res[0];
@@ -19,11 +21,120 @@ function lacksConcurrentlySupport(err) {
         return true;
     return typeof code !== "string";
 }
-async function pgIndexValid(q, name) {
-    const rows = rowsOf(await q(`SELECT i.indisvalid FROM pg_index i WHERE i.indexrelid = to_regclass(${quoteLiteral(name)})`));
+const EXPRESSION_PART = "<expression>";
+async function pgIndexLive(q, spec) {
+    const rows = rowsOf(await q("SELECT i.indisvalid AS indisvalid, i.indisunique AS indisunique, " +
+        "(i.indpred IS NULL AND i.indexprs IS NULL) AS whole, " +
+        "(SELECT c.relname::text FROM pg_class c WHERE c.oid = i.indrelid) AS tbl, " +
+        "(SELECT n.nspname::text FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = i.indrelid) AS nsp, " +
+        "COALESCE((SELECT string_agg(a.attname::text, ',' ORDER BY a.attname::text) FROM generate_series(0, i.indnkeyatts - 1) AS k(n) " +
+        "JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = i.indkey[k.n]), '') AS cols, " +
+        "EXISTS (SELECT 1 FROM pg_constraint k WHERE k.conindid = i.indexrelid AND k.contype = 'u') AS backs_constraint " +
+        "FROM pg_index i WHERE i.indexrelid = to_regclass(quote_ident((SELECT n.nspname FROM pg_class t JOIN pg_namespace n ON n.oid = t.relnamespace " +
+        `WHERE t.oid = to_regclass(${quoteLiteral(quoteId("pg", spec.table))}))) || '.' || quote_ident(${quoteLiteral(spec.name)}))`));
     if (rows.length === 0)
         return undefined;
-    return rows[0].indisvalid !== false;
+    const row = rows[0];
+    const schema = typeof row.nsp === "string" ? row.nsp : undefined;
+    const shape = typeof row.cols === "string" && typeof row.tbl === "string" && typeof row.indisunique === "boolean"
+        ? {
+            table: row.tbl,
+            schema,
+            unique: row.indisunique,
+            columns: row.cols === "" ? [] : row.cols.split(","),
+            whole: row.whole !== false,
+            constraint: row.backs_constraint === true,
+        }
+        : undefined;
+    return { valid: row.indisvalid !== false, schema, shape };
+}
+async function mysqlIndexRows(q, spec) {
+    const rows = rowsOf(await q(`SHOW INDEX FROM ${quoteId("mysql", spec.table)} WHERE Key_name = ${quoteLiteral(spec.name)}`));
+    return rows.map((r) => Object.fromEntries(Object.entries(r).map(([k, v]) => [k.toLowerCase(), v])));
+}
+function mysqlShapeOf(spec, rows) {
+    if (!rows.every((r) => "column_name" in r && "non_unique" in r))
+        return undefined;
+    const keyParts = [...rows].sort((a, b) => Number(a.seq_in_index) - Number(b.seq_in_index));
+    return {
+        table: spec.table,
+        schema: undefined,
+        unique: keyParts.every((r) => Number(r.non_unique) === 0),
+        columns: keyParts.map((r) => (isExpressionPart(r) ? EXPRESSION_PART : r.column_name)),
+        whole: keyParts.every((r) => r.sub_part === null || r.sub_part === undefined),
+        constraint: false,
+    };
+}
+const isExpressionPart = (r) => (typeof r.expression === "string" && r.expression !== "") || typeof r.column_name !== "string";
+const columnSet = (dialect, cols) => [...new Set(dialect === "mysql" ? cols.map((c) => c.toLowerCase()) : cols)].sort();
+function shapeProblem(dialect, spec, live) {
+    const problems = [];
+    if (live.table !== spec.table)
+        problems.push(`it is on table ${live.table}`);
+    if (!live.unique)
+        problems.push("it is not UNIQUE");
+    if (columnSet(dialect, live.columns).join(",") !== columnSet(dialect, spec.columns).join(",")) {
+        problems.push(`it covers (${live.columns.length === 0 ? "no plain key column" : live.columns.join(", ")})`);
+    }
+    if (!live.whole)
+        problems.push(dialect === "pg" ? "it is a partial or expression index" : "it is a prefix or expression index");
+    return problems.length === 0 ? undefined : problems.join("; ");
+}
+export class UniqueIndexRefusalError extends StoreBootRefusalError {
+    kind;
+    spec;
+    constructor(kind, spec, message, options) {
+        super(message, options);
+        this.kind = kind;
+        this.spec = spec;
+        this.name = "UniqueIndexRefusalError";
+    }
+}
+const declaredShape = (spec) => `UNIQUE (${spec.columns.join(", ")})`;
+function shapeRefusal(dialect, spec, live, problem) {
+    const name = quoteId(dialect, spec.name);
+    const where = live.schema === undefined ? "" : `${quoteId("pg", live.schema)}.`;
+    const drop = dialect === "mysql"
+        ? `ALTER TABLE ${quoteId("mysql", spec.table)} DROP INDEX ${name};`
+        : live.constraint
+            ? `ALTER TABLE ${where}${quoteId("pg", live.table)} DROP CONSTRAINT ${name};`
+            : `DROP INDEX CONCURRENTLY IF EXISTS ${where}${name};`;
+    return new UniqueIndexRefusalError("shape", spec, `ensureIndex: unique index ${spec.name} on table ${spec.table} is not the shape this build declares (${declaredShape(spec)}): ${problem} — refusing to start. ` +
+        "The name is taken, so the index is not rebuilt, and this build relies on it to reject duplicate rows. " +
+        `Way out: stop writers to ${spec.table}, run ${drop} and start again — the next start builds the index with the declared shape ` +
+        "(if rows already break it, that start refuses and names the duplicates). Until it is rebuilt nothing enforces the uniqueness.");
+}
+function duplicatesRefusal(dialect, spec, cause) {
+    const cols = columnList(dialect, spec);
+    const notNull = spec.columns.map((c) => `${quoteId(dialect, c)} IS NOT NULL`).join(" AND ");
+    const leftover = dialect === "pg" ? " The failed build leaves an INVALID index of that name; the next start drops and rebuilds it by itself." : "";
+    return new UniqueIndexRefusalError("duplicates", spec, `ensureIndex: unique index ${spec.name} on table ${spec.table} cannot be built — ${spec.table} already holds rows that share (${spec.columns.join(", ")}) — refusing to start, ` +
+        "because this build relies on this index to reject duplicate rows. " +
+        `Way out: find them with SELECT ${cols}, COUNT(*) FROM ${quoteId(dialect, spec.table)} WHERE ${notNull} GROUP BY ${cols} HAVING COUNT(*) > 1 ` +
+        "(rows with a NULL in any of these columns never conflict, so they are left out), remove or merge the extra rows — this build cannot choose which row survives — and start again; " +
+        `the next start builds the index.${leftover}`, { cause });
+}
+function isDuplicateKeyFailure(dialect, err) {
+    if (!isDupKeyErrorOfWrappedQuery(dialect, err))
+        return false;
+    switch (dialect) {
+        case "pg":
+            return Reflect.get(err, "constraint") !== "pg_class_relname_nsp_index";
+        case "mysql":
+            return true;
+        default: {
+            const _never = dialect;
+            throw new Error(`ensureIndex: 未知方言 ${String(_never)}`);
+        }
+    }
+}
+const failureOfBuild = (dialect, spec, err) => spec.unique === true && isDuplicateKeyFailure(dialect, err) ? duplicatesRefusal(dialect, spec, err) : err;
+function assertUniqueShape(dialect, spec, live) {
+    if (live === undefined)
+        return;
+    const problem = shapeProblem(dialect, spec, live);
+    if (problem !== undefined)
+        throw shapeRefusal(dialect, spec, live, problem);
 }
 const refusal = (spec, unique, what) => `ensureIndex: PostgreSQL 索引 ${spec.name}(表 ${spec.table})${what} —— 拒绝带病启动。` +
     "(一个 INVALID 索引会让此后每一次 CREATE INDEX … IF NOT EXISTS 静默跳过它,而规划器永不使用它。)" +
@@ -35,6 +146,8 @@ export async function ensureIndex(q, dialect, spec) {
         await applyIndex(q, dialect, spec);
     }
     catch (err) {
+        if (err instanceof UniqueIndexRefusalError)
+            throw err;
         let live;
         try {
             live = await readLiveColumns(async (sql) => rowsOf(await q(sql)), dialect);
@@ -54,40 +167,60 @@ function indexColumnMissing(live, spec) {
 async function applyIndex(q, dialect, spec) {
     switch (dialect) {
         case "mysql": {
-            const present = rowsOf(await q("SELECT 1 AS present FROM information_schema.statistics WHERE table_schema = DATABASE() " +
-                `AND table_name = ${quoteLiteral(spec.table)} AND index_name = ${quoteLiteral(spec.name)} LIMIT 1`));
-            if (present.length > 0)
+            const present = await mysqlIndexRows(q, spec);
+            if (present.length > 0) {
+                if (spec.unique === true)
+                    assertUniqueShape("mysql", spec, mysqlShapeOf(spec, present));
                 return;
-            await q(`ALTER TABLE ${quoteId("mysql", spec.table)} ADD ${spec.unique ? "UNIQUE " : ""}INDEX ` +
-                `${quoteId("mysql", spec.name)} (${columnList("mysql", spec)})`);
+            }
+            try {
+                await q(`ALTER TABLE ${quoteId("mysql", spec.table)} ADD ${spec.unique ? "UNIQUE " : ""}INDEX ` +
+                    `${quoteId("mysql", spec.name)} (${columnList("mysql", spec)})`);
+            }
+            catch (err) {
+                throw failureOfBuild("mysql", spec, err);
+            }
             return;
         }
         case "pg": {
             const unique = spec.unique ? "UNIQUE " : "";
             const name = quoteId("pg", spec.name);
             const tail = `${unique}INDEX CONCURRENTLY IF NOT EXISTS ${name} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)})`;
+            const build = async (sql) => {
+                try {
+                    await q(sql);
+                }
+                catch (err) {
+                    throw failureOfBuild("pg", spec, err);
+                }
+            };
             try {
-                await q(`CREATE ${tail}`);
+                await build(`CREATE ${tail}`);
             }
             catch (err) {
-                if (!lacksConcurrentlySupport(err))
+                if (err instanceof UniqueIndexRefusalError || !lacksConcurrentlySupport(err))
                     throw err;
                 recordFailOpen("server.ensure-index.concurrently-unsupported", `${spec.table}.${spec.name}`);
-                await q(`CREATE ${unique}INDEX IF NOT EXISTS ${name} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)})`);
+                await build(`CREATE ${unique}INDEX IF NOT EXISTS ${name} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)})`);
                 return;
             }
-            const valid = await pgIndexValid(q, spec.name);
-            if (valid !== false)
+            let live = await pgIndexLive(q, spec);
+            if (live === undefined)
                 return;
-            await q(`DROP INDEX CONCURRENTLY IF EXISTS ${name}`);
-            try {
-                await q(`CREATE ${tail}`);
-            }
-            catch (err) {
-                throw new Error(refusal(spec, unique, "重建时失败"), { cause: err });
+            if (!live.valid) {
+                await q(`DROP INDEX CONCURRENTLY IF EXISTS ${live.schema === undefined ? "" : `${quoteId("pg", live.schema)}.`}${name}`);
+                try {
+                    await build(`CREATE ${tail}`);
+                }
+                catch (err) {
+                    throw err instanceof UniqueIndexRefusalError ? err : new Error(refusal(spec, unique, "重建时失败"), { cause: err });
+                }
+                live = await pgIndexLive(q, spec);
+                if (live?.valid === false)
+                    throw new Error(refusal(spec, unique, "重建后仍是 INVALID"));
             }
-            if ((await pgIndexValid(q, spec.name)) === false)
-                throw new Error(refusal(spec, unique, "重建后仍是 INVALID"));
+            if (spec.unique === true)
+                assertUniqueShape("pg", spec, live?.shape);
             return;
         }
         default: {

package/dist/plugins/ensure-schema-lock-policy.d.ts

@@ -1,18 +1,3 @@
-/**
- * 两方言启动锁(`ensureSchema` / `oneTimeMigrations` 的 MySQL `GET_LOCK(?,0)` 与 PG `pg_try_advisory_lock`)的
- * **轮询策略唯一属主**(7.83.0 修复验证 车HC HC-1/HC-2 后收口:此前两只孪生各抄一份循环,一份改了「永不放弃」
- * 另一份还是「40 次放弃后无锁跑」,而 [ref] 之后无锁跑的那条腿发的是不带 `IF NOT EXISTS` 的 `ADD INDEX`,两副本
- * 双发 ⇒ 输的那只拒启)。方言只提供「试一次」的探针,循环、抖动、退避、进展 warn、坏连接上抛全在这里。
- *
- * 三条律:
- *  · **按进展轮询,不按次数放弃** —— 持锁方还活着(两方言的锁都是连接级,随连接消失,不会遗留)就一直等,
- *    每 {@link LOCK_PROBE_WARN_EVERY} 次 warn 一行说明在等谁;**永不**无锁跑(「响亮地等」严格优于「静默地竞争 DDL」)。
- *  · **坏连接不是争用**(HC-2,对 7.82.1 的回归):探针自己**连续**抛 {@link MAX_CONSECUTIVE_LOCK_PROBE_ERRORS} 次 =
- *    这条连接已不可用(`_queryable=false` / 半开 TCP),与「谁持锁」无关 ⇒ 上抛让启动响亮失败,不许无界轮。
- *    偶发一次抛(TiDB 悲观锁抖动)照旧继续轮,计数在一次成功探针后归零。
- *  · 轮询间隙进程不持任何快照(每次探针是亚毫秒的独立语句)⇒ 与 PG `CREATE INDEX CONCURRENTLY` 的
- *    `WaitForOlderSnapshots` 永不互等(理由全文见 `pg-pool.ts` `acquirePgEnsureSchemaLock` 头注)。
- */
 export declare const LOCK_PROBE_INITIAL_JITTER_MS = 400;
 export declare const LOCK_PROBE_WARN_EVERY = 40;
 export declare const MAX_CONSECUTIVE_LOCK_PROBE_ERRORS = 5;

package/dist/plugins/ensure-schema-lock-policy.js

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 export const LOCK_PROBE_INITIAL_JITTER_MS = 400;
 export const LOCK_PROBE_WARN_EVERY = 40;
 export const MAX_CONSECUTIVE_LOCK_PROBE_ERRORS = 5;
@@ -17,13 +18,13 @@ export async function pollUntilLocked(tryOnce, opts) {
         catch (err) {
             consecutiveErrors += 1;
             const msg = err?.message ?? String(err);
-            console.warn(`[${opts.tag}] ${opts.label} probe attempt ${attempt + 1} threw (${consecutiveErrors}/${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS}):`, msg);
+            writeLogText("stderr", `[${opts.tag}] ${opts.label} probe attempt ${attempt + 1} threw (${consecutiveErrors}/${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS}):`, msg);
             if (consecutiveErrors >= MAX_CONSECUTIVE_LOCK_PROBE_ERRORS) {
                 throw new Error(`[${opts.tag}] ${opts.label}: lock probe threw ${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS} times in a row — the connection itself is unusable, refusing to poll forever (last: ${msg})`, { cause: err });
             }
         }
         if (attempt > 0 && attempt % LOCK_PROBE_WARN_EVERY === 0) {
-            console.warn(`[${opts.tag}] still waiting for ${opts.label} (another replica is running the serialized DDL; attempt ${attempt})`);
+            writeLogText("stderr", `[${opts.tag}] still waiting for ${opts.label} (another replica is running the serialized DDL; attempt ${attempt})`);
         }
         await sleep(lockProbeBackoffMs(attempt));
     }

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";
@@ -65,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;
@@ -166,7 +176,8 @@ export declare class FileRunStore implements InProcessClaimFence {
     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>;
     /**
      * 写口里第四个盘面的那一段(与事件行的追加在**同一同步调用**里,块在前):帧经编解码拆成引用形 + 段体,本会话块账本里还没有的段体先追加
@@ -221,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>;
     /**
@@ -229,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?: {
@@ -268,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).
@@ -384,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;
 }