@sema-agent/server 7.23.0 → 7.24.0

package/dist/leader/fanout.d.ts

@@ -2,12 +2,22 @@
  * v2 MVP — leader fan-out composition layer (design/50 §3, V2-MVP-PLAN.md M1, core seam).
  *
  * Runs N sub-task workers in parallel over `runner.runTaskStream` sharing ONE AbortController, bounded by a
- * Semaphore, with an overall deadline (no infinite wait — council#5), a concurrency claim (run-store
- * createRun unique-key CAS — the rule-5 dual-session tax solved at worker scale), and a
+ * Semaphore, with an overall deadline (no infinite wait — council#5), and a
  * `cancelAll` that ABORTS first (stopping not-yet-started workers + aborting running ones) then interrupts the
  * snapshot — closing the late-registration race (council round-2). Returns a typed WorkerReport per worker (council#6 — the
  * Coordinator needs a defined shape to route diffs in merge(b)).
  *
+ * ── 重复 spawn 的去重由谁负责(#193 车4 件1,台账 P1-9③ 更正)────────────────────────────────────
+ * 这段头注**曾经**写着 fan-out 带一道「concurrency claim(run-store createRun unique-key CAS)」并称
+ * 「the rule-5 dual-session tax solved at worker scale」。亲读后裁定:那道 claim 全链路无人传,而且
+ * **由构造即无效** —— 它的 CAS 键是 `(workerId, sessionId)`,而 sessionId 是 `wire.ts` 每次现铸的
+ * `leader-<workerId>-<Date.now()>`;一次重投的 leader run 铸出来的是**不同的** sessionId,claim 永远
+ * 不会输。真正需要去重的那件事(同一逻辑请求被重投两次 ⇒ 两次真 git push)只能在**准入**处判,它的
+ * 属主是 `leader_run.idem_key` UNIQUE(`plugins/leader-run-store-sql.ts` 的原子赢或观察)。
+ * ⇒ 那个可选字段、它的函数类型别名、以及只有它才产得出的 `status:"rejected"`,三者同批删除(留一个
+ * 没人传的字段 + 一句「已解决」的头注,比没有这道防线更坏:它让读者以为这件事有人管)。
+ * 常驻门:`test/leader-failclosed-193.test.ts` 的 P1-9③(声明了就必须有生产者)。
+ *
  * cancelAll uses `TaskStream.destroy()` (core 1.71): abort + await run-settle + CAS-expire the checkpoint
  * (fencing any concurrent resume) + reap a SUSPENDED worker's paused container — closing the interim-`interrupt()`
  * gap (a cancel hitting a suspended worker no longer leaks a paused container or an orphan checkpoint). Per core's
@@ -22,8 +32,9 @@ import type { TaskSpec, TaskResult, TaskStream, RepairTerminal } from "@sema-age
 export interface WorkerReport {
     workerId: string;
     sessionId: string;
-    /** completed = mergeable; failed/suspended/timeout/rejected = not merged (quarantined). */
-    status: "completed" | "failed" | "suspended" | "timeout" | "rejected";
+    /** completed = mergeable; failed/suspended/timeout = not merged (quarantined).
+     *  (`rejected` 随那道并发去重面一并删除 —— 那面是它的唯一生产者,留下就是一个永不出现的闭集成员。) */
+    status: "completed" | "failed" | "suspended" | "timeout";
     /** Worker's branch + the base it forked from — drives the merge(b) `git format-patch <baseSha>` diff-out. */
     branch?: string;
     baseSha?: string;
@@ -64,8 +75,6 @@ export type FanOutStream = Pick<TaskStream, "result" | "destroy">;
 export interface RunnerLike {
     runTaskStream(spec: TaskSpec): FanOutStream;
 }
-/** Concurrency claim (run-store `createRun` unique-key CAS). Returns false = a duplicate spawn lost the claim. */
-export type ClaimFn = (workerId: string, sessionId: string) => Promise<boolean>;
 export interface FanOutOptions {
     runner: RunnerLike;
     /** Overall fan-out deadline (ms). On expiry → cancelAll, the still-running workers are cancelled. */
@@ -75,15 +84,13 @@ export interface FanOutOptions {
     cancelGraceMs?: number;
     /** Semaphore cap on concurrent workers (MVP = 2; structure scales to N). */
     maxConcurrency: number;
-    /** Optional concurrency claim; omitted = always-claim (single-session MVP). */
-    claim?: ClaimFn;
     logger?: {
         warn?: (msg: string, meta?: Record<string, unknown>) => void;
         info?: (msg: string, meta?: Record<string, unknown>) => void;
     };
     /** Optional per-worker run override (e.g. runWithVerification). When set, runOne routes through THIS instead of
-     *  the default runTaskStream-and-map — still bounded by the semaphore, the overall timeout→cancelAll, and the
-     *  claim. Lets the verify path reuse fan-out's concurrency/timeout/cancellation rather than an unbounded
+     *  the default runTaskStream-and-map — still bounded by the semaphore and the overall
+     *  timeout→cancelAll. Lets the verify path reuse fan-out's concurrency/timeout/cancellation rather than an unbounded
      *  Promise.all (council). The override receives the shared abort signal; pass it into the run so a hung or
      *  cancelled worker actually aborts (else the overall-timeout's `await work` can never unblock). Like the default
      *  path it need not catch — runOne maps a throw to failed/timeout. */

package/dist/leader/fanout.js

@@ -88,10 +88,6 @@ export async function fanOut(subtasks, opts) {
     };
     const runOne = async (st) => {
         const base = { workerId: st.workerId, sessionId: st.sessionId, branch: st.branch, baseSha: st.baseSha };
-        // Concurrency claim (CAS) BEFORE provisioning — a lost claim means a duplicate spawn; skip, don't run.
-        if (opts.claim && !(await opts.claim(st.workerId, st.sessionId))) {
-            return { ...base, status: "rejected", error: "claim lost (duplicate spawn)" };
-        }
         return sem.run(async () => {
             if (sharedAC.signal.aborted)
                 return { ...base, status: "timeout", error: "cancelled before start" };

package/dist/leader/grader-env-factory.d.ts

@@ -16,12 +16,15 @@
  *    Before re-measure, the caller mechanically checks the patch's changed-file list against an allowlist
  *    (`changedFilesWithinAllowlist`, §10.4(ii)) — an out-of-allowlist / build-config touch denies the candidate.
  *
- * The standalone, mint-a-distinct-sandbox grader factory (`createGraderEnvFactory`) is the AUTO-ACCEPT slice path
- * (flag `LEADER_GRADER_FACTORY`, default OFF until the §7 OFF-Gate-1 end-to-end verification). It is documented +
- * stubbed here, NOT wired — v1 reuses the integration sandbox (R1) + re-seeds it (R2) instead.
+ * A standalone, mint-a-distinct-sandbox grader belongs to the AUTO-ACCEPT slice, which has NOT been designed or
+ * built. v1 reuses the integration sandbox (R1) + re-seeds it (R2) instead. **There is no config key that turns
+ * such a factory on** — an earlier revision of this header named one and shipped a `throw`-only stub beside it,
+ * but no such key ever existed in `config.ts`, so an operator following that text set an env var that did
+ * nothing. Both the stub and the promise were removed (#193 车4 件3 / staleness ledger P2-9); the auto-accept
+ * slice, when it happens, is a new design件 that lands its factory, its wiring and its knob in one batch.
  *
  * Everything here is additive + OFF by default: nothing in this file runs unless the Stage-2 seams call it behind
- * `LEADER_REPAIR_LOOP` / `LEADER_MEASURE_GATES` / `LEADER_GRADER_FACTORY`.
+ * `LEADER_REPAIR_LOOP` / `LEADER_MEASURE_GATES`.
  */
 import { type ExecutionEnv, type ExecStep } from "@sema-agent/core";
 /**
@@ -63,48 +66,4 @@ export declare function applyAndGrade(handle: GraderHandle, patch: string, steps
 export declare function changedFilesOutOfAllowlist(changedFiles: string[], allowlist: string[]): string[];
 /** §10.4(ii): true iff EVERY changed file is within the allowlist and none is a denied build-config path. */
 export declare function changedFilesWithinAllowlist(changedFiles: string[], allowlist: string[]): boolean;
-/**
- * §3.2 — the FUTURE standalone grader factory (the auto-accept-slice sibling of `main.ts`'s `executionEnvFactory`,
- * `main.ts:204-249`). Mints a DISTINCT sandbox via the same `e2b/k8sExecutionEnvFactory`, seeds `seedCmd` + the
- * oracle files ONLY there, and returns a `GraderHandle` with `provenance:"control_plane"`. v1 does NOT mint a
- * standalone grader (R1 reuses the integration sandbox; R2 re-seeds it) — this is the path the auto-accept slice
- * (flag `LEADER_GRADER_FACTORY`, default OFF) opens once the §7 OFF-Gate-1 deployment-contract proof lands. It is
- * a documented STUB (NOT wired): minting + seeding a per-run sandbox is real provisioning work that belongs to the
- * auto-accept stage, and shipping a half-mint here would be a stopgap (clay rule). The signature is fixed so the
- * Stage-N auto-accept wiring drops in without a contract change.
- */
-export interface GraderEnvFactoryCfg {
-    /** Mint a distinct, isolated sandbox env (the same factory the workers/integration sandbox use). */
-    mint: (sessionId: string) => {
-        env: ExecutionEnv;
-        writeFile: (p: string, c: string) => Promise<void>;
-        sh: (cmd: string) => Promise<string>;
-        destroy: () => Promise<void>;
-    };
-    /** Shell to seed the base repo (idempotent) — runs ONLY in the minted grader. */
-    seedCmd: string;
-    /** Repo dir inside the grader. */
-    repoDir: string;
-    /** Hidden-oracle files seeded ONLY in the grader (never the worker env). */
-    oracleFiles?: Array<{
-        path: string;
-        content: string;
-    }>;
-}
-/** §3.2 — a minted standalone grader plus its lifecycle + isolation brand (for the auto-accept slice). */
-export interface MintedGrader extends GraderHandle {
-    /** The control-plane provenance brand (distinguishes a minted grader from the reused integration sandbox). */
-    provenance: "control_plane";
-    /** The grader's hidden-oracle paths (passed to `runRepairLoop.immutableOraclePaths` ONLY when the auto-accept
-     *  slice runs the full `assertOracleIsolation` — v1 OMITS these; §10.2). */
-    immutableOraclePaths: string[];
-    /** Reap the minted sandbox. */
-    destroy: () => Promise<void>;
-}
-/**
- * §3.2 STUB — build the standalone grader factory. NOT wired in v1 (the auto-accept slice owns it, flag
- * `LEADER_GRADER_FACTORY`). Throws a clearly-marked not-implemented error if invoked before that slice lands so a
- * stray call fails loudly rather than silently mis-grading — this is an explicit placeholder, not a quiet stopgap.
- */
-export declare function createGraderEnvFactory(_cfg: GraderEnvFactoryCfg): () => Promise<MintedGrader>;
 //# sourceMappingURL=grader-env-factory.d.ts.map

package/dist/leader/grader-env-factory.js

@@ -16,12 +16,15 @@
  *    Before re-measure, the caller mechanically checks the patch's changed-file list against an allowlist
  *    (`changedFilesWithinAllowlist`, §10.4(ii)) — an out-of-allowlist / build-config touch denies the candidate.
  *
- * The standalone, mint-a-distinct-sandbox grader factory (`createGraderEnvFactory`) is the AUTO-ACCEPT slice path
- * (flag `LEADER_GRADER_FACTORY`, default OFF until the §7 OFF-Gate-1 end-to-end verification). It is documented +
- * stubbed here, NOT wired — v1 reuses the integration sandbox (R1) + re-seeds it (R2) instead.
+ * A standalone, mint-a-distinct-sandbox grader belongs to the AUTO-ACCEPT slice, which has NOT been designed or
+ * built. v1 reuses the integration sandbox (R1) + re-seeds it (R2) instead. **There is no config key that turns
+ * such a factory on** — an earlier revision of this header named one and shipped a `throw`-only stub beside it,
+ * but no such key ever existed in `config.ts`, so an operator following that text set an env var that did
+ * nothing. Both the stub and the promise were removed (#193 车4 件3 / staleness ledger P2-9); the auto-accept
+ * slice, when it happens, is a new design件 that lands its factory, its wiring and its knob in one batch.
  *
  * Everything here is additive + OFF by default: nothing in this file runs unless the Stage-2 seams call it behind
- * `LEADER_REPAIR_LOOP` / `LEADER_MEASURE_GATES` / `LEADER_GRADER_FACTORY`.
+ * `LEADER_REPAIR_LOOP` / `LEADER_MEASURE_GATES`.
  */
 import { runExecGate } from "@sema-agent/core";
 import { shellQuote as sq } from "../plugins/remote-shell.js";
@@ -116,16 +119,17 @@ export function changedFilesOutOfAllowlist(changedFiles, allowlist) {
 export function changedFilesWithinAllowlist(changedFiles, allowlist) {
     return changedFilesOutOfAllowlist(changedFiles, allowlist).length === 0;
 }
-/**
- * §3.2 STUB — build the standalone grader factory. NOT wired in v1 (the auto-accept slice owns it, flag
- * `LEADER_GRADER_FACTORY`). Throws a clearly-marked not-implemented error if invoked before that slice lands so a
- * stray call fails loudly rather than silently mis-grading — this is an explicit placeholder, not a quiet stopgap.
+/*
+ * §3.2 的「standalone 铸新沙箱 grader 工厂」曾以 `GraderEnvFactoryCfg` / `MintedGrader` / `createGraderEnvFactory`
+ * 三件的形式停在这里:一个固定好的签名 + 一个必抛的 not-implemented 实现,理由写的是「签名先定好,将来
+ * 自动接受切片直接接线,不改契约」。#193 车4(台账 P2-9)裁定删除,理由三条:
+ *   ① 它零调用零测试,而它承诺的开关(见文件头注)在 `config.ts` 里从来不存在 —— 「签名已定」这句话
+ *      本身在骗读者:没有任何消费方按它写过一行码,所谓的契约稳定性没有被任何东西验证过;
+ *   ② 一个 `throw` 工厂在 grep 结果里长得像「这条路已经有了」,恰恰是本仓 doc-rot 战役反复清理的那一类
+ *      「过期的在哪里比缺失的在哪里更危险」;
+ *   ③ 真需求出现时,铸沙箱 + 播种 + oracle 隔离本来就要跟着 `assertOracleIsolation` 一起重新设计
+ *      (§10.2 明说 v1 OMITS immutableOraclePaths),旧签名大概率也不会被原样采用。
+ * 复原坐标(需要时按此重建):sema-internal `server/docs/LEADER-REPAIRLOOP-INTEGRATION.md` §3.2/§7,
+ * 以及本文件的 git 历史(#193 车4 之前的任一版本)。
  */
-export function createGraderEnvFactory(_cfg) {
-    return async () => {
-        throw new Error("createGraderEnvFactory: the standalone control-plane grader is the auto-accept slice (LEADER_GRADER_FACTORY) — " +
-            "NOT wired in v1 (which reuses the integration sandbox for R1 and re-seeds it for R2). " +
-            "See sema-internal server/docs/LEADER-REPAIRLOOP-INTEGRATION.md §3.2/§7.");
-    };
-}
 //# sourceMappingURL=grader-env-factory.js.map

package/dist/main.js

@@ -850,7 +850,7 @@ async function main() {
         workflowCompletionInbox,
     });
     // design/158 A10:leader 段搬到 src/boot/leader.ts(逐字)。
-    const leaderEndpoint = createLeaderFace({ config, logger, brain, pricing, executionEnvFactory, toolResultStore, sessionStore, checkpointStore, governanceSeams });
+    const leaderEndpoint = createLeaderFace({ config, logger, brain, pricing, executionEnvFactory, toolResultStore, sessionStore, checkpointStore, governanceSeams, backend });
     // Graceful drain: shared mutable state — SIGTERM flips `draining` (shutdown below), createHttpServer
     // assigns `inflight` (live leg count on this instance), /health + the submit 503 gate read it.
     const drainState = { draining: false };

package/dist/plugins/leader-run-store-sql.d.ts

@@ -0,0 +1,118 @@
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type SqlDriver } from "./sql-driver.js";
+/** 表名(#192 单数纪律;`schema-naming-invariants` 的闭集词表执法)。 */
+export declare const LEADER_RUN_TABLE = "leader_run";
+/** leader run 的四态 —— 与 `leader/endpoint.ts` 的 `LeaderRun["status"]` 同词表(闭集)。 */
+export type LeaderRunStatus = "running" | "completed" | "failed" | "needs_human";
+/** 库里一行 leader run 的读出形。`result` 是 `LeaderResult` 的 JSON 原样(店不解释它的内部结构)。 */
+export interface LeaderRunRecord {
+    id: string;
+    status: LeaderRunStatus;
+    /** BL-4 属主(null = 匿名/单租)。GET 的 404 门读它。 */
+    owner: string | null;
+    /** 运维列表面的可读预览(**不是**完整 objective —— 名字即语义,见 DDL 列注)。 */
+    objectivePreview: string;
+    result?: unknown;
+    error?: string;
+    startedAtMs: number;
+    finishedAtMs?: number;
+}
+/** 准入入参。`idemKey` 缺席(null)= 调用方没要求去重 ⇒ 每次都是新行(现行为)。 */
+export interface NewLeaderRun {
+    objective: string;
+    owner: string | null;
+    /** 已 scope 过的幂等键的 sha256 hex(见 {@link leaderIdemKey});null = 不去重。 */
+    idemKey: string | null;
+}
+/** 终局补丁 —— `finishRun` 一次写完(状态 + 结果/错误 + 完成时刻)。 */
+export interface LeaderRunTerminal {
+    status: Exclude<LeaderRunStatus, "running">;
+    result?: unknown;
+    error?: string;
+}
+/** `objective_preview` 的字符上限,与 DDL 的 VARCHAR(160) 同源(`task_run.objective_preview` 先例同宽)。 */
+export declare const LEADER_OBJECTIVE_PREVIEW_CHARS = 160;
+/**
+ * 幂等键的**落库形** = `sha256(scope \x1f raw)` 的 hex(64 字符,定宽)。
+ *
+ * 为什么 hash 而不是像 bake 店那样存 scope 过的明文:明文形的列宽(VARCHAR(255))与「principal(≤190)
+ * + 调用方自选的 raw 键(≤255)」的上界对不上 —— 溢出时 PG 报 `value too long`、非严格 MySQL **静默截断**,
+ * 而截断一个去重键的后果是**两个不同的请求折叠成同一次 leader run**(= 一次该跑的 run 被静默吞掉)。
+ * 定宽 hash 让这条路径按构造不存在;顺带,库里也不再留调用方的原始键字面量。
+ * (碰撞面:sha256,不在工程风险量级。)
+ */
+export declare function leaderIdemKey(raw: string, owner: string | null): string;
+/** MySQL 协议方言的建表语句(真源;由 `tidb-pool.ts` 展开进中央 SCHEMA_STATEMENTS)。 */
+export declare const TIDB_LEADER_RUN_STATEMENTS: readonly string[];
+/** PG 方言的建表语句(MySQL 孪生的逐条翻译:JSON→JSONB,逐列 `COLLATE "C"`,内联 KEY→独立 CREATE INDEX)。 */
+export declare const PG_LEADER_RUN_SCHEMA: readonly string[];
+/** 幂等的 PG schema 应用(中央 `ensurePgSchema` 组合它;集成套件也直接调)。 */
+export declare function ensurePgLeaderRunSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
+/** 清算腿写进 `error` 列的 WHY(消费方读到的就是这句;不是一个空的 failed)。 */
+export declare const STALE_SWEEP_REASON: string;
+/** 双方言 leader-run 店。方言差异台账见文件头注。 */
+export declare class SqlLeaderRunStore {
+    protected readonly db: SqlDriver;
+    constructor(db: SqlDriver);
+    /** 挑本方言的 SQL 文本。两条语句**都写在调用点**(A12 判据:读者一眼看到两份)。 */
+    private q;
+    /**
+     * 准入一次 leader run(状态 `running`)。提交幂等照 `createBake`/`createRun` 的**原子赢或观察**:
+     * `idem_key` 是 UNIQUE,重投的那一方 INSERT 撞 dup-key ⇒ 回读**既有行**返回 `{created:false}`,
+     * 调用方据此**不再**起第二条后台腿。`idemKey=null` 恒插入(没要求去重)。
+     *
+     * 🔴 为什么不是「先 SELECT 再 INSERT」:两个副本的 check-then-act 会双双看到「没有」然后双双插入 ——
+     * 而这条路径的第二次插入意味着**第二次真 git push**。UNIQUE 是唯一能在两个进程之间成立的判据。
+     */
+    createRun(input: NewLeaderRun): Promise<{
+        created: boolean;
+        run: LeaderRunRecord;
+    }>;
+    /** 按 id 读一行(跨副本可见性的全部依据)。不存在 ⇒ undefined。 */
+    getRun(id: string): Promise<LeaderRunRecord | undefined>;
+    /** 按幂等键读回既有行(dup-key 观察臂;也给集成套件直查)。 */
+    getByIdem(idemKey: string): Promise<LeaderRunRecord | undefined>;
+    /**
+     * 陈旧 `running` 清算(codex 对抗复审 R1-high②,验真后修)。
+     *
+     * 病:准入(INSERT)与驱动(后台腿)是**两步**,而驱动腿只活在受理它的那个进程里。副本在这两步之间
+     * 挂掉、或在一条 24h 的 run 中途挂掉,行就永远停在 `running`:跨副本读面永远显示「在跑」,而没有任何
+     * 东西在跑;更坏的是那把幂等键被永久绑在这条无人驱动的行上,重投拿回的还是它。
+     *
+     * 处置 = **有界地说实话**,不是自动接管:把超期的 `running` 迁成 `failed` 并写清 WHY。
+     * 🔴 刻意**不做**跨副本接管(claim/lease/queued 状态机):接管一条产物是「真 git push」的 24h run
+     * 是一个独立的设计决定(要持久化完整可恢复请求、要 fencing、要想清楚两个副本同时以为自己是属主时
+     * 谁去 push),不是一次清算腿能顺手带过的。本腿把「永远 running」这个**静默**面消灭掉,把接管留给
+     * 一件具名的后续设计;当前语义写在这里,不藏着。
+     *
+     * 幂等键的后果同批写明:键**永久绑定**它当初准入的那条 run(与 `/v1/runs` 的 taskId 幂等同语义)。
+     * 一条被清算成 `failed` 的 run,用**同一个键**重投拿回的仍是那条 failed —— 调用方要重跑就换一个新键。
+     *
+     * @param staleMs 超过这个时长仍是 `running` 就算陈旧(部署旋钮 `LEADER_RUN_STALE_MS`)。
+     * @param now 注入时钟(测试要确定性)。
+     * @returns 本次迁走的行数。
+     */
+    reapStaleRunning(staleMs: number, now: number): Promise<number>;
+    /**
+     * TEST-ONLY:把一行的 `started_at_ms` 推到过去,好让 {@link reapStaleRunning} 的判据在一次测试里成立。
+     * 生产零调用(`started_at_ms` 只在准入时写一次)——具名 `ForTest` 是为了让这件事在 grep 里一眼可见,
+     * 而不是长成一个看起来像正经写口的方法(本仓 `setStatus` 那条欠账的教训)。
+     */
+    backdateStartedAtForTest(id: string, startedAtMs: number): Promise<void>;
+    /**
+     * 落终局。**只从 `running` 迁**(`WHERE status = 'running'`):终局是一次性的,一条已经结算过的 run
+     * 不该被后来的写者改写。回执 = 是否真的迁了,调用方据此决定要不要出声(静默丢一次终局写 = 用户永远
+     * 看到 `running`)。
+     */
+    finishRun(id: string, patch: LeaderRunTerminal): Promise<boolean>;
+}
+/** MySQL-协议孪生(TiDB / MySQL / MariaDB 同一只 mysql2 池)。 */
+export declare class TiDBLeaderRunStore extends SqlLeaderRunStore {
+    constructor(pool: MySqlPool);
+}
+/** PostgreSQL 孪生。 */
+export declare class PgLeaderRunStore extends SqlLeaderRunStore {
+    constructor(pool: PgPool);
+}
+//# sourceMappingURL=leader-run-store-sql.d.ts.map

package/dist/plugins/leader-run-store-sql.js

@@ -0,0 +1,246 @@
+/**
+ * Durable **leader-run** registry — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场;先例 =
+ * `image-bake-store-sql.ts`)。#193 车4 件1(台账 P1-9;设计稿 `docs/DESIGN-193-CAR4-leader-failclosed.md`)。
+ *
+ * ── 为什么这张表必须存在 ────────────────────────────────────────────────────────────────────────────
+ * 一次 leader run = 规划成 N 个子任务 → 起 N 个 worker 沙箱 → 真模型编码 → 合并 → **真 git push**,
+ * 最长 24h。它此前的登记表是 `leader/endpoint.ts` 里的一只进程内 `Map`,于是三条缺口同源:
+ *   ① 跨副本 GET 404(提交打到 A、轮询打到 B),违反仓级前提「durable state lives in an external SQL store」;
+ *   ② POST 零幂等 —— 每次都铸新 uuidv7,一次网络重试 = 第二次真跑 + 可能第二次 push;
+ *   ③ `fanout.ts` 的 `claim` 面全链路无人传,而它的头注称并发去重「已解决」。
+ * 一张带 `idem_key UNIQUE` 的表一次解掉三条:①靠行本身,②靠 UNIQUE 的「原子赢或观察」,
+ * ③ 的真属主就是 ② —— 提交幂等挡在**准入**那一刻,比在 worker 层再补一道 CAS 早得多也准得多
+ * (worker 的 sessionId 是每次现铸的 `leader-<workerId>-<Date.now()>`,拿它做 CAS 键**永远不会**冲突,
+ * 那道 claim 由构造即无效;详见同批对 `fanout.ts` 头注的更正)。
+ *
+ * ── 这是一张 DEDICATED 表,不是 `task_run` 的复用 ────────────────────────────────────────────────────
+ * 与 bake 店同一条理由:`task_run` 与 `task_active`/run reaper/`GET /v1/runs` 列表 FK 式耦合,把 leader run
+ * (无 session、无 spend 账、无 checkpoint)混进去 = 让非任务行漏进 reapStale/listRuns 的类别错误。
+ *
+ * ── 两条保留/清算裁定(分开的两件事,别混)────────────────────────────────────────────────────────
+ * **① 行的保留:不建 TTL 腿。** 进程内 Map 时代那条 1h 的 `RUN_RETENTION_MS` 驱逐,目的是**给进程内存
+ * 封顶**,不是保留策略。落库后这个理由消失:一行 leader run 对应一次「N 个沙箱 + 数分钟到 24h + 一次真
+ * push」的动作,它就是这次动作的审计记录;行的产生速率与它的价值都不支持自动清账。要清账时按
+ * workflow_run/roster 的先例加一个 `*_RETENTION_MS` 旋钮 + reaper 腿,那是独立一件。
+ *
+ * **② 陈旧 `running` 的清算:建了**({@link SqlLeaderRunStore.reapStaleRunning},旋钮 `LEADER_RUN_STALE_MS`,
+ * 腿在 `boot/reapers.ts`)。这条与 ① 无关 —— 它不是为了控表大小,而是因为准入与驱动是两步、驱动腿只活在
+ * 受理它的那个进程里:副本一死,行就永远停在 `running`,跨副本读面永远显示「在跑」而没有任何东西在跑。
+ * 那是**静默**,不是保留问题。(本裁定是 codex 对抗复审 R1-high② 逼出来的:初版把两件事合成一件、一起
+ * 判了「不建」,而第二件的论据完全不同。)
+ *
+ * ── 方言差异台账(显式,永不藏进抽象;A12 判据)────────────────────────────────────────────────────
+ *   - `?` 占位符 vs `$n`                         - `CAST(? AS JSON)` vs `$n::jsonb`
+ *   - 表级 `COLLATE utf8mb4_bin` vs 逐列 `COLLATE "C"`(PG 无表级形;`isolation-key-collation` 门执法)
+ *   - dup-key 判别走 `sql-errors.ts` 单一属主(`isDupKeyError`),本店只有一根 UNIQUE ⇒ 无需归属判别
+ *   - schema 属主:MySQL DDL 由本文件导出、展开进 `tidb-pool.ts` 的 SCHEMA_STATEMENTS(跟着中央
+ *     named-lock 的那条 conn 建);PG DDL 由本文件的 `ensurePgLeaderRunSchema` 导出、由 `pg-pool.ts`
+ *     的中央 `ensurePgSchema` 组合(与 approval-ask 同姿势)。
+ */
+import { uuidv7 } from "@sema-agent/core";
+import { createHash } from "node:crypto";
+import { isDupKeyError } from "./sql-errors.js";
+import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
+import { parseJsonOr } from "./sql-row-helpers.js";
+/** 表名(#192 单数纪律;`schema-naming-invariants` 的闭集词表执法)。 */
+export const LEADER_RUN_TABLE = "leader_run";
+const LEADER_RUN_STATUSES = new Set(["running", "completed", "failed", "needs_human"]);
+/** `objective_preview` 的字符上限,与 DDL 的 VARCHAR(160) 同源(`task_run.objective_preview` 先例同宽)。 */
+export const LEADER_OBJECTIVE_PREVIEW_CHARS = 160;
+/**
+ * 幂等键的**落库形** = `sha256(scope \x1f raw)` 的 hex(64 字符,定宽)。
+ *
+ * 为什么 hash 而不是像 bake 店那样存 scope 过的明文:明文形的列宽(VARCHAR(255))与「principal(≤190)
+ * + 调用方自选的 raw 键(≤255)」的上界对不上 —— 溢出时 PG 报 `value too long`、非严格 MySQL **静默截断**,
+ * 而截断一个去重键的后果是**两个不同的请求折叠成同一次 leader run**(= 一次该跑的 run 被静默吞掉)。
+ * 定宽 hash 让这条路径按构造不存在;顺带,库里也不再留调用方的原始键字面量。
+ * (碰撞面:sha256,不在工程风险量级。)
+ */
+export function leaderIdemKey(raw, owner) {
+    return createHash("sha256").update(`${owner ?? ""}\x1f${raw}`).digest("hex");
+}
+/** MySQL 协议方言的建表语句(真源;由 `tidb-pool.ts` 展开进中央 SCHEMA_STATEMENTS)。 */
+export const TIDB_LEADER_RUN_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS ${LEADER_RUN_TABLE} (
+     leader_run_id  VARCHAR(64)  NOT NULL,
+     -- idem_key:提交幂等的**唯一**执法点(sha256 hex,定宽 64;见 leaderIdemKey 的头注)。NULL = 调用方
+     -- 没带 Idempotency-Key ⇒ 不参与去重(MySQL/PG 的 UNIQUE 都不约束 NULL,两方言同形)。
+     idem_key       VARCHAR(64)  NULL,
+     -- owner:BL-4 提交者(null = 匿名/单租)。GET 的属主门读它 —— 非属主 404(不是 403),不给存在性预言机。
+     owner          VARCHAR(190) NULL,
+     -- objective_preview:**预览**不是全文(task_run 同名列先例同宽)。完整 objective 属于调用方的请求体,
+     -- 这里只为运维看一眼「这行是哪次 run」;写入侧按 LEADER_OBJECTIVE_PREVIEW_CHARS 截断,名字已说明这件事。
+     objective_preview VARCHAR(160) NULL,
+     status         VARCHAR(16)  NOT NULL,
+     -- result:LeaderResult 的 JSON 原样(店不解释内部结构)。仅终局时写。
+     result         JSON         NULL,
+     error          TEXT         NULL,
+     started_at_ms  BIGINT       NOT NULL,
+     finished_at_ms BIGINT       NULL,
+     PRIMARY KEY (leader_run_id),
+     UNIQUE KEY uq_leader_run_idem (idem_key),
+     KEY idx_leader_run_owner (owner),
+     KEY idx_leader_run_started (started_at_ms)
+   ) COLLATE utf8mb4_bin`,
+];
+/** PG 方言的建表语句(MySQL 孪生的逐条翻译:JSON→JSONB,逐列 `COLLATE "C"`,内联 KEY→独立 CREATE INDEX)。 */
+export const PG_LEADER_RUN_SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS ${LEADER_RUN_TABLE} (
+     leader_run_id  VARCHAR(64) COLLATE "C"  NOT NULL,
+     idem_key       VARCHAR(64) COLLATE "C"  NULL,
+     owner          VARCHAR(190) COLLATE "C" NULL,
+     objective_preview VARCHAR(160) COLLATE "C" NULL,
+     status         VARCHAR(16) COLLATE "C"  NOT NULL,
+     result         JSONB        NULL,
+     error          TEXT COLLATE "C"         NULL,
+     started_at_ms  BIGINT       NOT NULL,
+     finished_at_ms BIGINT       NULL,
+     PRIMARY KEY (leader_run_id),
+     CONSTRAINT uq_leader_run_idem UNIQUE (idem_key)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_leader_run_owner ON ${LEADER_RUN_TABLE} (owner)`,
+    `CREATE INDEX IF NOT EXISTS idx_leader_run_started ON ${LEADER_RUN_TABLE} (started_at_ms)`,
+];
+/** 幂等的 PG schema 应用(中央 `ensurePgSchema` 组合它;集成套件也直接调)。 */
+export async function ensurePgLeaderRunSchema(q) {
+    for (const stmt of PG_LEADER_RUN_SCHEMA)
+        await q(stmt);
+}
+/** 清算腿写进 `error` 列的 WHY(消费方读到的就是这句;不是一个空的 failed)。 */
+export const STALE_SWEEP_REASON = "leader run went stale: no replica settled it within LEADER_RUN_STALE_MS (the replica driving it most likely died). " +
+    "The run was NOT taken over — re-submit with a NEW Idempotency-Key to run it again.";
+const SELECT_COLS = "leader_run_id, owner, objective_preview, status, result, error, started_at_ms, finished_at_ms";
+/** 未知 status 字面量 = 库里躺着一条本进程不认识的行 ⇒ **响亮拒**,不静默折成 failed(闭集词表纪律 #157)。 */
+function statusOf(raw, id) {
+    const s = String(raw);
+    if (!LEADER_RUN_STATUSES.has(s)) {
+        throw new Error(`leader_run ${id}: unknown status ${JSON.stringify(s)} (closed word table: ${[...LEADER_RUN_STATUSES].join("|")}) — a newer replica wrote a word this build cannot interpret`);
+    }
+    return s;
+}
+function mapRow(r) {
+    const id = String(r.leader_run_id);
+    const result = r.result == null ? undefined : parseJsonOr(r.result, undefined);
+    const error = r.error == null ? undefined : String(r.error);
+    const finished = r.finished_at_ms == null ? undefined : Number(r.finished_at_ms);
+    return {
+        id,
+        status: statusOf(r.status, id),
+        owner: r.owner == null ? null : String(r.owner),
+        objectivePreview: r.objective_preview == null ? "" : String(r.objective_preview),
+        ...(result === undefined ? {} : { result }),
+        ...(error === undefined ? {} : { error }),
+        startedAtMs: Number(r.started_at_ms),
+        ...(finished === undefined ? {} : { finishedAtMs: finished }),
+    };
+}
+/** 双方言 leader-run 店。方言差异台账见文件头注。 */
+export class SqlLeaderRunStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** 挑本方言的 SQL 文本。两条语句**都写在调用点**(A12 判据:读者一眼看到两份)。 */
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    /**
+     * 准入一次 leader run(状态 `running`)。提交幂等照 `createBake`/`createRun` 的**原子赢或观察**:
+     * `idem_key` 是 UNIQUE,重投的那一方 INSERT 撞 dup-key ⇒ 回读**既有行**返回 `{created:false}`,
+     * 调用方据此**不再**起第二条后台腿。`idemKey=null` 恒插入(没要求去重)。
+     *
+     * 🔴 为什么不是「先 SELECT 再 INSERT」:两个副本的 check-then-act 会双双看到「没有」然后双双插入 ——
+     * 而这条路径的第二次插入意味着**第二次真 git push**。UNIQUE 是唯一能在两个进程之间成立的判据。
+     */
+    async createRun(input) {
+        const id = uuidv7();
+        const now = Date.now();
+        const preview = input.objective.slice(0, LEADER_OBJECTIVE_PREVIEW_CHARS);
+        const params = [id, input.idemKey, input.owner, preview, "running", now];
+        try {
+            await this.db.query(this.q(`INSERT INTO ${LEADER_RUN_TABLE} (leader_run_id, idem_key, owner, objective_preview, status, started_at_ms) VALUES (?,?,?,?,?,?)`, `INSERT INTO ${LEADER_RUN_TABLE} (leader_run_id, idem_key, owner, objective_preview, status, started_at_ms) VALUES ($1,$2,$3,$4,$5,$6)`), params);
+        }
+        catch (err) {
+            if (isDupKeyError(this.db.dialect, err) && input.idemKey) {
+                const existing = await this.getByIdem(input.idemKey);
+                // 回读为空 = 赢家的行在这两步之间消失了(本店无删除口 ⇒ 只可能是外部 DELETE)。原样上抛而不是
+                // 悄悄再插一次:后者会在「运维正在手工清行」的窗口里放出第二次真 push。
+                if (existing)
+                    return { created: false, run: existing };
+            }
+            throw err;
+        }
+        const run = await this.getRun(id);
+        if (!run)
+            throw new Error(`createRun: leader_run ${id} vanished right after insert`);
+        return { created: true, run };
+    }
+    /** 按 id 读一行(跨副本可见性的全部依据)。不存在 ⇒ undefined。 */
+    async getRun(id) {
+        const res = await this.db.query(this.q(`SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE leader_run_id = ?`, `SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE leader_run_id = $1`), [id]);
+        const row = res.rows[0];
+        return row ? mapRow(row) : undefined;
+    }
+    /** 按幂等键读回既有行(dup-key 观察臂;也给集成套件直查)。 */
+    async getByIdem(idemKey) {
+        const res = await this.db.query(this.q(`SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE idem_key = ?`, `SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE idem_key = $1`), [idemKey]);
+        const row = res.rows[0];
+        return row ? mapRow(row) : undefined;
+    }
+    /**
+     * 陈旧 `running` 清算(codex 对抗复审 R1-high②,验真后修)。
+     *
+     * 病:准入(INSERT)与驱动(后台腿)是**两步**,而驱动腿只活在受理它的那个进程里。副本在这两步之间
+     * 挂掉、或在一条 24h 的 run 中途挂掉,行就永远停在 `running`:跨副本读面永远显示「在跑」,而没有任何
+     * 东西在跑;更坏的是那把幂等键被永久绑在这条无人驱动的行上,重投拿回的还是它。
+     *
+     * 处置 = **有界地说实话**,不是自动接管:把超期的 `running` 迁成 `failed` 并写清 WHY。
+     * 🔴 刻意**不做**跨副本接管(claim/lease/queued 状态机):接管一条产物是「真 git push」的 24h run
+     * 是一个独立的设计决定(要持久化完整可恢复请求、要 fencing、要想清楚两个副本同时以为自己是属主时
+     * 谁去 push),不是一次清算腿能顺手带过的。本腿把「永远 running」这个**静默**面消灭掉,把接管留给
+     * 一件具名的后续设计;当前语义写在这里,不藏着。
+     *
+     * 幂等键的后果同批写明:键**永久绑定**它当初准入的那条 run(与 `/v1/runs` 的 taskId 幂等同语义)。
+     * 一条被清算成 `failed` 的 run,用**同一个键**重投拿回的仍是那条 failed —— 调用方要重跑就换一个新键。
+     *
+     * @param staleMs 超过这个时长仍是 `running` 就算陈旧(部署旋钮 `LEADER_RUN_STALE_MS`)。
+     * @param now 注入时钟(测试要确定性)。
+     * @returns 本次迁走的行数。
+     */
+    async reapStaleRunning(staleMs, now) {
+        const cutoff = now - staleMs;
+        const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = 'failed', error = ?, finished_at_ms = ? WHERE status = 'running' AND started_at_ms < ?`, `UPDATE ${LEADER_RUN_TABLE} SET status = 'failed', error = $1, finished_at_ms = $2 WHERE status = 'running' AND started_at_ms < $3`), [STALE_SWEEP_REASON, now, cutoff]);
+        return res.affected;
+    }
+    /**
+     * TEST-ONLY:把一行的 `started_at_ms` 推到过去,好让 {@link reapStaleRunning} 的判据在一次测试里成立。
+     * 生产零调用(`started_at_ms` 只在准入时写一次)——具名 `ForTest` 是为了让这件事在 grep 里一眼可见,
+     * 而不是长成一个看起来像正经写口的方法(本仓 `setStatus` 那条欠账的教训)。
+     */
+    async backdateStartedAtForTest(id, startedAtMs) {
+        await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET started_at_ms = ? WHERE leader_run_id = ?`, `UPDATE ${LEADER_RUN_TABLE} SET started_at_ms = $1 WHERE leader_run_id = $2`), [startedAtMs, id]);
+    }
+    /**
+     * 落终局。**只从 `running` 迁**(`WHERE status = 'running'`):终局是一次性的,一条已经结算过的 run
+     * 不该被后来的写者改写。回执 = 是否真的迁了,调用方据此决定要不要出声(静默丢一次终局写 = 用户永远
+     * 看到 `running`)。
+     */
+    async finishRun(id, patch) {
+        const json = dialectJsonEncoder(this.db.dialect);
+        const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = ?, result = CAST(? AS JSON), error = ?, finished_at_ms = ? WHERE leader_run_id = ? AND status = 'running'`, `UPDATE ${LEADER_RUN_TABLE} SET status = $1, result = $2::jsonb, error = $3, finished_at_ms = $4 WHERE leader_run_id = $5 AND status = 'running'`), [patch.status, patch.result === undefined ? null : json(patch.result), patch.error ?? null, Date.now(), id]);
+        return res.affected > 0;
+    }
+}
+/** MySQL-协议孪生(TiDB / MySQL / MariaDB 同一只 mysql2 池)。 */
+export class TiDBLeaderRunStore extends SqlLeaderRunStore {
+    constructor(pool) {
+        super(mysqlDriver(pool));
+    }
+}
+/** PostgreSQL 孪生。 */
+export class PgLeaderRunStore extends SqlLeaderRunStore {
+    constructor(pool) {
+        super(pgDriver(pool));
+    }
+}
+//# sourceMappingURL=leader-run-store-sql.js.map

package/dist/plugins/pg-pool.js

@@ -38,6 +38,7 @@ import { ensurePgImageBakeSchema as ensureImageBakeSchema } from "./image-bake-s
 import { ensurePgApprovalAskSchema } from "./approval-ask-store-sql.js";
 import { ensurePgAdoptionLogSchema } from "./adoption-log-sql.js";
 import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
+import { ensurePgLeaderRunSchema } from "./leader-run-store-sql.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -394,6 +395,8 @@ export async function ensurePgSchema(pool) {
         // #154 车二:持久化权限规则店三张表(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。
         // 同上一行的绑法 —— DDL 跑在**同一条** client 上,advisory lock 的 session 语义不受影响。
         await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
+        // #193 车4 件1:durable leader-run 登记表(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。同上绑法。
+        await ensurePgLeaderRunSchema((text, params) => client.query(text, params));
     }
     finally {
         if (locked) {

package/dist/plugins/store-backend.d.ts

@@ -16,6 +16,7 @@ import { TiDBRunStore, PgRunStore } from "./run-store-sql.js";
 import { TiDBCheckpointStore, PgCheckpointStore } from "./checkpoint-store-sql.js";
 import { TiDBImageIndex, PgImageIndex } from "./image-index-sql.js";
 import { TiDBImageBake, PgImageBake } from "./image-bake-store-sql.js";
+import { TiDBLeaderRunStore, PgLeaderRunStore } from "./leader-run-store-sql.js";
 import { TiDBBreakerState, PgBreakerState } from "./breaker-state-sql.js";
 import { TiDBCostQuota } from "./tidb-cost-quota.js";
 import { PgCostQuota } from "./pg-cost-quota.js";
@@ -80,6 +81,8 @@ export type ServiceWorkflowJournalStore = WorkflowJournalStore & {
 };
 export type ImageIndex = TiDBImageIndex | PgImageIndex;
 export type ImageBake = TiDBImageBake | PgImageBake;
+/** #193 车4 件1:durable leader-run 登记表的双方言孪生(union 同族——TS 私有字段让具体类名义上不同)。 */
+export type LeaderRunStore = TiDBLeaderRunStore | PgLeaderRunStore;
 /** The FULL checkpoint store (core CheckpointStore + the service operator-queue/ctx methods listPending/
  *  listByScope/findPendingTokenBySession/peekPendingScope/putCtx/getCtx/reapCtx) — the SQL twins carry them,
  *  and the LOCAL lane now does too (core FileCheckpointStore + the service half — TOC plan-mode /
@@ -195,6 +198,15 @@ export interface StoreBackend {
     toolResult?(): ToolResultStoreFull;
     imageIndex?(): ImageIndex;
     imageBake?(): ImageBake;
+    /**
+     * #193 车4 件1(台账 P1-9):durable leader-run 登记表。**SQL 后端专有**,`local` 刻意省略。
+     *
+     * 🔴 local 缺席不是欠账、也不是「以后补个 File 形」:leader run 是 N worker fan-out + 真 git push,
+     * 而 config 层已经把「LEADER_ENABLED=true 且无外部 SQL 店」整个组合**拒启**了(件2 门②)——
+     * 所以 local 车道上根本不存在一个需要这张表的 leader 端点。消费点按 `backend?.leaderRun?.()` 取,
+     * 缺席 ⇒ endpoint 落到显式的单副本内存降级臂(见 `leader/endpoint.ts` 的 store 缺席注)。
+     */
+    leaderRun?(): LeaderRunStore;
     breaker?(onWriteFail?: (streak: number) => void): BreakerStateStore;
     costQuota?(limitMicroUsd: number, windowMs: number, onDegraded?: CounterDegradeHook): CostQuotaStore;
     rateLimiter?(limit: number, onDegraded?: CounterDegradeHook): RateLimiterStore;