omp-conductor 0.19.7 → 0.20.0

package/src/store.ts

@@ -10,7 +10,7 @@
  */
 
 import { Database } from "bun:sqlite";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
 
@@ -42,6 +42,7 @@ import type {
   DecisionState,
   DigestBacklog,
   DispatchSummary,
+  EpicApproval,
   DaemonStop,
   DaemonStopDraft,
   FrictionAdmissionReason,
@@ -70,6 +71,7 @@ import type {
   OrchestratorDownMode,
   OrchestratorIncident,
   OrchestratorIncidentDraft,
+  PromotedBy,
   ReleaseComposition,
   ReleaseCompositionOverride,
   ReportDeliveryState,
@@ -84,6 +86,9 @@ import type {
   ReviewAdjudicationProvenance,
   ReviewAdjudicationRecord,
   ReviewAdjudicationState,
+  ReviewCorrectionProvenance,
+  ReviewLaunchMode,
+  ReviewRevisionDraft,
   ReviewRevisionEnqueue,
   ReviewRevisionOutcome,
   ReviewRevisionRecord,
@@ -92,6 +97,8 @@ import type {
   RunRecord,
   RunState,
   SessionRole,
+  SessionSpendRole,
+  SessionSpendRow,
   SettlementFlag,
   Store,
   TurnOverride,
@@ -513,6 +520,15 @@ interface ReviewRevisionRow {
   /** Nullable rather than NOT NULL DEFAULT 0: rows written before #903 carry
    *  NULL, which reads back as absent and counts as zero retries. */
   infraRetries: number | null;
+  /** The #1045 launch decision and provenance. All nullable, none backfilled:
+   *  a pre-#1045 row and a round nobody has decided yet are the same fact —
+   *  nobody wrote a decision down — and both must read back as unknown. */
+  launchMode: string | null;
+  requestedModel: string | null;
+  resolvedModel: string | null;
+  originSessionRef: string | null;
+  correctionSessionRef: string | null;
+  launchDecidedAt: number | null;
 }
 
 /** The `model_escalations` table exactly as SQLite hands it back (#807). Every
@@ -525,6 +541,34 @@ interface ModelEscalationRow {
   at: number;
 }
 
+/**
+ * The #1045 launch decision and provenance, projected off one review-revision
+ * row. NULL becomes an absent property, so a round nobody has decided and a
+ * row written before the columns existed both read back as {} — the explicit
+ * unknown, never a fabricated `resume-original`.
+ *
+ * One helper, shared by the record converter and `reviewRevisionLaunch`, so
+ * the shape a status snapshot renders can never disagree with the shape the
+ * dispatcher reads.
+ */
+function toCorrectionProvenance(row: ReviewRevisionRow): ReviewCorrectionProvenance {
+  const provenance: ReviewCorrectionProvenance = {};
+  if (row.launchMode !== null) provenance.launchMode = row.launchMode as ReviewLaunchMode;
+  if (row.requestedModel !== null) provenance.requestedModel = row.requestedModel;
+  if (row.resolvedModel !== null) provenance.resolvedModel = row.resolvedModel;
+  if (row.originSessionRef !== null) provenance.originSessionRef = row.originSessionRef;
+  if (row.correctionSessionRef !== null) provenance.correctionSessionRef = row.correctionSessionRef;
+  return provenance;
+}
+
+/**
+ * The one launch mode that has a correction session of its own (#1045). Bound
+ * into the guarded UPDATE rather than written inline in SQL, so renaming the
+ * union member is a compile error here instead of a WHERE clause that quietly
+ * stops matching anything.
+ */
+const FRESH_CORRECTION: ReviewLaunchMode = "fresh-correction";
+
 /**
  * NULL columns become absent properties, matching the other row converters:
  * a record read back out of the store deep-equals the one that went in.
@@ -541,6 +585,10 @@ function toReviewRevision(row: ReviewRevisionRow): ReviewRevisionRecord {
     round: row.round,
     reason: row.reason as ReviewReason,
     requestedAt: row.requestedAt,
+    // Every read path — pending, unsettled, per-PR, by id — hands the launch
+    // provenance back on the row itself (#1045), so a caller never needs a
+    // second query per round to know how the round was launched.
+    ...toCorrectionProvenance(row),
   };
   if (row.sessionFile !== null) record.sessionFile = row.sessionFile;
   if (row.dispatchedAt !== null) record.dispatchedAt = row.dispatchedAt;
@@ -549,6 +597,7 @@ function toReviewRevision(row: ReviewRevisionRow): ReviewRevisionRecord {
   // Zero and NULL both read back as absent: a round nobody has retried and a
   // row written before the column existed are the same fact.
   if (row.infraRetries !== null && row.infraRetries > 0) record.infraRetries = row.infraRetries;
+  if (row.launchDecidedAt !== null) record.launchDecidedAt = row.launchDecidedAt;
   return record;
 }
 
@@ -616,6 +665,7 @@ interface IntakeRow {
   state: string;
   issueUrl: string | null;
   groomedAt: number | null;
+  source: string | null;
 }
 
 /**
@@ -631,10 +681,45 @@ function toIntakeItem(row: IntakeRow): IntakeItem {
     state: row.state as IntakeState,
     ...(row.issueUrl === null ? {} : { issueUrl: row.issueUrl }),
     ...(row.groomedAt === null ? {} : { groomedAt: row.groomedAt }),
+    // Absent, not empty string: an operator's own idea has no provenance to
+    // print, and "" would render as a machine-filed item with a blank source.
+    ...(row.source === null ? {} : { source: row.source }),
   };
   return item;
 }
 
+/** The `session_spend` table as SQLite hands it back (Phase 4). */
+interface SessionSpendSqlRow {
+  project: string;
+  role: string;
+  issue: number | null;
+  model: string | null;
+  resolvedModel: string | null;
+  turns: number;
+  spendUsd: number | null;
+  at: number;
+}
+
+/**
+ * Same NULL-becomes-absent posture as the converters above, and here it is
+ * load-bearing rather than tidy: a NULL `spendUsd` must come back ABSENT, not
+ * as `0`, because absent means the provider reported no cost and `0` means it
+ * reported zero. Collapsing the two is exactly the ambiguity in the `runs`
+ * table that forces `spend-telemetry.ts` to guess at a subscription verdict.
+ */
+function toSessionSpend(row: SessionSpendSqlRow): SessionSpendRow {
+  return {
+    project: row.project,
+    role: row.role as SessionSpendRole,
+    ...(row.issue === null ? {} : { issue: row.issue }),
+    ...(row.model === null ? {} : { model: row.model }),
+    ...(row.resolvedModel === null ? {} : { resolvedModel: row.resolvedModel }),
+    turns: row.turns,
+    ...(row.spendUsd === null ? {} : { spendUsd: row.spendUsd }),
+    at: row.at,
+  };
+}
+
 /** The `grooming` table exactly as SQLite hands it back (#735). */
 interface GroomingRow {
   project: string;
@@ -643,6 +728,8 @@ interface GroomingRow {
   reason: string;
   evidence: string;
   recordedAt: number;
+  promotedAt: number | null;
+  promotedBy: string | null;
 }
 
 function toGrooming(row: GroomingRow): GroomingRecord {
@@ -653,9 +740,23 @@ function toGrooming(row: GroomingRow): GroomingRecord {
     reason: row.reason,
     evidence: row.evidence,
     recordedAt: row.recordedAt,
+    // Both columns or neither: `markGroomingPromoted` writes them in one
+    // statement, so a row carrying one without the other cannot arise. Read
+    // off `promotedAt` alone rather than testing both, which would invent a
+    // half-promoted state nothing can produce (#1041).
+    ...(row.promotedAt === null
+      ? {}
+      : { promotedAt: row.promotedAt, promotedBy: (row.promotedBy ?? "operator") as PromotedBy }),
   };
 }
 
+/** The `epic_approvals` table exactly as SQLite hands it back (#1041). */
+interface EpicApprovalRow {
+  issue: number;
+  approvedAt: number;
+  approvedBy: string;
+}
+
 /** The `orchestrator_incidents` table exactly as SQLite hands it back (#288). */
 interface OrchestratorIncidentRow {
   project: string;
@@ -1101,7 +1202,20 @@ CREATE TABLE IF NOT EXISTS review_revisions (
   -- Infrastructure kills that returned this round to the pending set (#903).
   -- Nullable so an older database migrates by ALTER without a rewrite; NULL
   -- and 0 mean the same thing.
-  infraRetries INTEGER
+  infraRetries INTEGER,
+  -- How this round was launched, and by which model and session (#1045).
+  -- launchMode is 'resume-original' or 'fresh-correction' and is written
+  -- ONCE per round, by the deciding dispatch, through a guarded UPDATE -- so a
+  -- restart re-reads the decision instead of making a second one. All six are
+  -- nullable and nothing is backfilled: a row from before #1045 recorded no
+  -- decision, and inventing 'resume-original' for it would fabricate the one
+  -- fact this provenance exists to make honest.
+  launchMode           TEXT,
+  requestedModel       TEXT,
+  resolvedModel        TEXT,
+  originSessionRef     TEXT,
+  correctionSessionRef TEXT,
+  launchDecidedAt      INTEGER
 );
 CREATE INDEX IF NOT EXISTS review_revisions_pending
   ON review_revisions (project, dispatchedAt, runId);
@@ -1282,9 +1396,39 @@ CREATE TABLE IF NOT EXISTS grooming (
   reason     TEXT    NOT NULL,
   evidence   TEXT    NOT NULL,
   recordedAt INTEGER NOT NULL CHECK (recordedAt >= 0),
+  -- Promotion provenance (#1041): when this verdict was acted on by queueing
+  -- the issue, and which of the three actors did it. Nullable because most
+  -- verdicts are never promoted, and because a row written before mechanical
+  -- promotion existed recorded nobody -- NULL is the only honest reading.
+  -- Written once per verdict and cleared by the next upsert: a new verdict is a
+  -- new judgement, and provenance outliving its judgement audits the wrong one.
+  promotedAt INTEGER,
+  promotedBy TEXT,
   PRIMARY KEY (project, issue)
 );
 CREATE INDEX IF NOT EXISTS grooming_project_verdict ON grooming (project, verdict);
+-- The promoted index is NOT here, for the same reason decisions_group is not:
+-- this script runs before the additive migrations, so on a database written
+-- before #1041 the column does not exist yet and an index over it would fail
+-- the whole schema step. Created beside its ALTER below.
+
+-- The operator's standing approvals of epic scope (#1041). One row per approved
+-- epic, first write wins, revocable.
+--
+-- Its own table rather than a resolved decision row, and the reason is that a
+-- gate has to read it: a decision's resolution column is free text written by a
+-- human for a human, and no parser turns "yes, but do the migration first" into
+-- a boolean. Decision rows also expire after DECISION_TTL_MS, and scope consent
+-- must not lapse because nobody looked at it for a week. Project-scoped like
+-- every other table here, so one project's approvals can never gate another's
+-- children.
+CREATE TABLE IF NOT EXISTS epic_approvals (
+  project    TEXT    NOT NULL,
+  issue      INTEGER NOT NULL CHECK (issue > 0),
+  approvedAt INTEGER NOT NULL CHECK (approvedAt >= 0),
+  approvedBy TEXT    NOT NULL,
+  PRIMARY KEY (project, issue)
+);
 
 -- GitHub rate-limit refusals the tracker observed (#198). Written by the
 -- daemon's tracker hook, not polled, so status can show what GitHub actually
@@ -1297,6 +1441,69 @@ CREATE TABLE IF NOT EXISTS gh_refusals (
 );
 CREATE INDEX IF NOT EXISTS gh_refusals_at ON gh_refusals (at);
 
+-- Auto-restarts the daemon fired at a wedged orchestrator (#1049, Phase 4).
+-- The same windowed-event shape as gh_refusals above and for the same reason:
+-- the only question anyone asks is "how many in the last 6h", so a bare row
+-- per restart is the whole record and there is no cursor, no latch and no
+-- counter to corrupt. A crash between the restart and the next read costs at
+-- worst one row, never a mis-set high-water mark that silently disables the
+-- cap or spends it twice.
+--
+-- Project-scoped, unlike gh_refusals: a rate-limit refusal is a property of
+-- the host's GitHub token, but a wedged orchestrator belongs to exactly one
+-- project, and one project burning its three restarts must never consume
+-- another project's budget.
+--
+-- reason is NOT NULL because the whole value of the row past the count is the
+-- page it produces when the cap is reached: "3 restarts in 6h, all
+-- stall-marker" reads very differently from three different causes.
+CREATE TABLE IF NOT EXISTS orchestrator_restarts (
+  project TEXT    NOT NULL,
+  at      INTEGER NOT NULL CHECK (at >= 0),
+  reason  TEXT    NOT NULL
+);
+CREATE INDEX IF NOT EXISTS orchestrator_restarts_project_at
+  ON orchestrator_restarts (project, at);
+
+-- Spend and turns for the sessions the DAEMON owns rather than dispatches
+-- (Phase 4 attribution). Today that is to-spec grooming and review
+-- adjudication: both are real model sessions the fleet pays for, and both
+-- were previously logged to stdout and then forgotten, so a fleet's stats
+-- reported only the worker half of its bill.
+--
+-- Deliberately NOT the runs table. computeStats walks runs as issue journeys
+-- keyed on run.issue and folds FAILED_STATES into merged/settled counts, so a
+-- groom row parked in there would invent an extra journey for an issue that
+-- never had a worker, corrupt the settled counts, and skew $-per-merge by
+-- attributing grooming spend to a merge it did not produce. A small dedicated
+-- table is the honest shape.
+--
+-- spendUsd is NULLABLE, and that is the point. In runs, an unmetered request
+-- and a genuinely free one are both stored as 0, which is why
+-- spend-telemetry.ts has to infer a "subscription" verdict from the SHARE of
+-- zeros (SPEND_MISSING_SHARE) instead of reading a fact. Here the two are
+-- distinguishable at the row: NULL means the provider reported no cost for
+-- this session (subscription billing, or a harness that emitted no usage
+-- event), 0.0 means it reported exactly zero. A reader must render NULL as
+-- unmetered, never as $0.00 — a fabricated zero reads as free.
+--
+-- model is what the caller asked for and resolvedModel is what the harness
+-- actually ran; both nullable because a caller that did not observe either
+-- must not have one guessed for it. The per-model breakdown groups on
+-- resolvedModel, since that is the model that was billed.
+CREATE TABLE IF NOT EXISTS session_spend (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  project       TEXT    NOT NULL,
+  role          TEXT    NOT NULL CHECK (role IN ('groom', 'adjudicator')),
+  issue         INTEGER CHECK (issue IS NULL OR issue > 0),
+  model         TEXT,
+  resolvedModel TEXT,
+  turns         INTEGER NOT NULL CHECK (turns >= 0),
+  spendUsd      REAL,
+  at            INTEGER NOT NULL CHECK (at >= 0)
+);
+CREATE INDEX IF NOT EXISTS session_spend_project_at ON session_spend (project, at);
+
 -- The daemon's tracked gh call count, per UTC day and call source (#198).
 -- The single funnel in tracker/github.ts counts every spawn; the day/source
 -- pair is the partition, so today's column and today's row survive a restart.
@@ -1331,6 +1538,17 @@ CREATE INDEX IF NOT EXISTS label_ops_project_next ON label_ops (project, nextAtt
 -- and a reinstall, so it lives here rather than in any process's memory. The
 -- state CHECK keeps the three-state vocabulary exact; issueUrl and groomedAt
 -- stay NULL until an idea becomes (or is dropped instead of) an issue.
+--
+-- source is the provenance of a machine-filed item (Phase 4 signal mining):
+-- the stable key of the signal that produced it, e.g.
+-- "mined:settlement-weakening:omp/src/foo.ts". NULL means an operator typed
+-- this idea themselves, which is the only other way a row gets here. It is
+-- also the dedupe key: recordIntake derives a DETERMINISTIC id from
+-- project + source, so the hourly mining pass re-filing a signal it already
+-- filed is a no-op instead of an hourly duplicate. Declared here for fresh
+-- databases and added by a guarded ALTER for existing ones, with no backfill:
+-- every row written before mining existed was typed by the operator, and
+-- absent is exactly that.
 CREATE TABLE IF NOT EXISTS intake_items (
   id        TEXT    PRIMARY KEY,
   project   TEXT    NOT NULL,
@@ -1338,7 +1556,8 @@ CREATE TABLE IF NOT EXISTS intake_items (
   createdAt INTEGER NOT NULL,
   state     TEXT    NOT NULL CHECK (state IN ('pending', 'groomed', 'dismissed')),
   issueUrl  TEXT,
-  groomedAt INTEGER
+  groomedAt INTEGER,
+  source    TEXT
 );
 CREATE INDEX IF NOT EXISTS intake_items_project_state
   ON intake_items (project, state, createdAt);
@@ -1706,6 +1925,25 @@ function newReportId(): string {
   return crypto.randomUUID().replaceAll("-", "").slice(0, 12);
 }
 
+/**
+ * The id of a machine-filed intake item (Phase 4): a pure function of the
+ * project and the signal's source key, so the hourly mining pass re-deriving
+ * it lands on the row it already wrote.
+ *
+ * Same width and alphabet as {@link newReportId} on purpose. The id is the
+ * handle an operator types into `intake dismiss`, it is printed in a column
+ * next to other ids, and nothing downstream should have to care whether a row
+ * came from a machine — the `source` column says that, in the one place that
+ * asks. 48 bits over a per-project namespace of at most a few thousand mined
+ * signals is not a collision anyone has to handle.
+ *
+ * The project is part of the digest, not just a prefix, so two projects mining
+ * the same file path never share a row.
+ */
+function minedIntakeId(project: string, source: string): string {
+  return createHash("sha256").update(`${project}\u0000${source}`).digest("hex").slice(0, 12);
+}
+
 /**
  * A ledger row, with the same NULL-becomes-absent posture as {@link toReport}.
  *
@@ -2254,6 +2492,24 @@ export function openStore(dbPath: string): Store {
     }
   }
   db.exec("CREATE INDEX IF NOT EXISTS decisions_group ON decisions (groupId)");
+  // Promotion provenance on a grooming verdict (#1041). Purely additive, both
+  // nullable, nothing backfilled: a verdict recorded before mechanical
+  // promotion existed was queued — if it was queued at all — by a hand nobody
+  // wrote down, and inventing `promotedBy: 'operator'` for it would put a
+  // fabricated line in the very audit these columns exist to make honest.
+  const groomingColumns = db.query<{ name: string }, []>("PRAGMA table_info(grooming)").all();
+  for (const [name, type] of [
+    ["promotedAt", "INTEGER"],
+    ["promotedBy", "TEXT"],
+  ] as const) {
+    if (!groomingColumns.some((column) => column.name === name)) {
+      db.exec(`ALTER TABLE grooming ADD COLUMN ${name} ${type}`);
+    }
+  }
+  // Beside the ALTER, not in SCHEMA, so an upgraded database reads the audit
+  // window as fast as a fresh one without the schema step depending on a column
+  // it may still have to add.
+  db.exec("CREATE INDEX IF NOT EXISTS grooming_promoted ON grooming (project, promotedAt)");
   // Already-met watches, written before the deadline existed (#966). Unlike the
   // head binding above this IS backfilled, and the difference is that nothing is
   // being guessed: `conditionMetAt` is a recorded observation, and the deadline
@@ -2291,7 +2547,44 @@ export function openStore(dbPath: string): Store {
   if (!reviewRevisionColumns.some((column) => column.name === "infraRetries")) {
     db.exec("ALTER TABLE review_revisions ADD COLUMN infraRetries INTEGER");
   }
+  // The launch decision and its model/session provenance (#1045). Purely
+  // additive — one guarded ALTER per column, no backfill, no table rebuild —
+  // because the identity of an existing round is exactly what this lane must
+  // not disturb: its issue, run, attempt and continuation charges, round
+  // number, branch, PR URL, reviewed head, findings and settlement history all
+  // stay byte-identical across the upgrade.
+  //
+  // Nothing is backfilled, and that is the contract, not laziness. Every round
+  // that ran before #1045 resumed its original session — but nobody wrote that
+  // down, and a stamped 'resume-original' would be indistinguishable from a
+  // decision the daemon actually made. These columns exist to explain #1035
+  // afterwards; seeding them with a guess is precisely the lie they are meant
+  // to prevent. Legacy rows therefore project every field as absent, and every
+  // reader must render an explicit unknown.
+  for (const [name, type] of [
+    ["launchMode", "TEXT"],
+    ["requestedModel", "TEXT"],
+    ["resolvedModel", "TEXT"],
+    ["originSessionRef", "TEXT"],
+    ["correctionSessionRef", "TEXT"],
+    ["launchDecidedAt", "INTEGER"],
+  ] as const) {
+    if (!reviewRevisionColumns.some((column) => column.name === name)) {
+      db.exec(`ALTER TABLE review_revisions ADD COLUMN ${name} ${type}`);
+    }
+  }
 
+  // Mined-signal provenance on an intake item (Phase 4). Purely additive, no
+  // backfill: every row that predates signal mining was typed by an operator,
+  // so an absent source is not a gap to be filled but the accurate reading.
+  //
+  // Nothing is rewritten, and in particular no id is: a legacy row keeps its
+  // random id, and `intake dismiss <id>` on an id an operator wrote down last
+  // week still resolves the same row after the upgrade.
+  const intakeColumns = db.query<{ name: string }, []>("PRAGMA table_info(intake_items)").all();
+  if (!intakeColumns.some((column) => column.name === "source")) {
+    db.exec("ALTER TABLE intake_items ADD COLUMN source TEXT");
+  }
   // The escalation findings on an adjudication (#932). Rows written by #874's
   // lifecycle carried none — the ceiling still refused then — so NULL is the
   // honest reading and renders as "no findings recorded".
@@ -2987,18 +3280,32 @@ export function openStore(dbPath: string): Store {
   const selectDispatch = db.query<{ summary: string }, [string]>(
     `SELECT summary FROM dispatch_summaries WHERE project = ?`,
   );
+  // One projection list for every grooming read, so a new column can never be
+  // visible through one accessor and NULL through another.
+  const GROOMING_COLUMNS = "project, issue, verdict, reason, evidence, recordedAt, promotedAt, promotedBy";
   const selectGrooming = db.query<GroomingRow, [string, number]>(
-    `SELECT project, issue, verdict, reason, evidence, recordedAt
-       FROM grooming WHERE project = ? AND issue = ?`,
+    `SELECT ${GROOMING_COLUMNS} FROM grooming WHERE project = ? AND issue = ?`,
   );
   const selectGroomingAll = db.query<GroomingRow, [string]>(
-    `SELECT project, issue, verdict, reason, evidence, recordedAt
-       FROM grooming WHERE project = ? ORDER BY issue ASC`,
+    `SELECT ${GROOMING_COLUMNS} FROM grooming WHERE project = ? ORDER BY issue ASC`,
   );
   const selectGroomingByVerdict = db.query<GroomingRow, [string, string]>(
-    `SELECT project, issue, verdict, reason, evidence, recordedAt
-       FROM grooming WHERE project = ? AND verdict = ? ORDER BY issue ASC`,
-  );
+    `SELECT ${GROOMING_COLUMNS} FROM grooming WHERE project = ? AND verdict = ? ORDER BY issue ASC`,
+  );
+  // Newest promotion first, and `promotedAt DESC` alone would be a non-
+  // deterministic order for a batch promoted inside one millisecond, which the
+  // daemon's promotion loop does routinely — the issue number breaks the tie so
+  // an audit digest renders the same list twice.
+  const selectPromotionsSince = db.query<GroomingRow, [string, number]>(
+    `SELECT ${GROOMING_COLUMNS} FROM grooming
+      WHERE project = ? AND promotedAt IS NOT NULL AND promotedAt >= ?
+      ORDER BY promotedAt DESC, issue DESC`,
+  );
+  // The upsert deliberately does NOT carry the promotion columns forward: on
+  // conflict they are reset to NULL, because a re-recorded verdict is a new
+  // judgement and provenance that outlives its judgement audits the wrong
+  // decision (#1041). Spelled as explicit `= NULL` rather than left out, so the
+  // clearing is a stated choice a reader can weigh rather than an omission.
   const upsertGroomingRow = db.query<unknown, [string, number, string, string, string, number]>(
     `INSERT INTO grooming (project, issue, verdict, reason, evidence, recordedAt)
      VALUES (?, ?, ?, ?, ?, ?)
@@ -3006,12 +3313,33 @@ export function openStore(dbPath: string): Store {
        verdict = excluded.verdict,
        reason = excluded.reason,
        evidence = excluded.evidence,
-       recordedAt = excluded.recordedAt`,
-  );
+       recordedAt = excluded.recordedAt,
+       promotedAt = NULL,
+       promotedBy = NULL`,
+  );
+  // Stamp-once, and the `IS NULL` guard is the whole contract: `changes === 0`
+  // means either no such verdict or one already promoted, which is exactly the
+  // set of cases a caller must not queue the issue for. That makes this write
+  // the promotion latch, so it runs before the label op (#1041).
+  const markGroomingPromotedRow = db.query<unknown, [number, string, string, number]>(
+    `UPDATE grooming SET promotedAt = ?, promotedBy = ?
+      WHERE project = ? AND issue = ? AND promotedAt IS NULL`,
+  );
+  // A promoted row is inert to admission's blocked bookkeeping, in both
+  // directions (#1041): the sweep below skips it and the per-hold upsert never
+  // rewrites it. Promotion handed the issue to dispatch, and a lane/dependency
+  // hold on a queued issue is flow control of the moment, not a re-grooming.
+  // Without the exclusion the audit line would die inside one 5-minute
+  // admission pass — rewritten `blocked`, then swept — while the tick that must
+  // review the promotion runs every ~30 minutes.
   const clearGroomedBlocked = db.query<unknown, [string]>(
     `DELETE FROM grooming
       WHERE project = ? AND verdict = 'blocked'
-        AND reason IN ('file-lane', 'depends-on')`,
+        AND reason IN ('file-lane', 'depends-on')
+        AND promotedAt IS NULL`,
+  );
+  const selectGroomingPromotedAt = db.query<{ promotedAt: number | null }, [string, number]>(
+    `SELECT promotedAt FROM grooming WHERE project = ? AND issue = ?`,
   );
   // One transaction, so a pass can never leave the blocked inventory half
   // written: the stale rows are cleared (the hold no longer applies) and the
@@ -3021,6 +3349,7 @@ export function openStore(dbPath: string): Store {
       clearGroomedBlocked.run(project);
       for (const hold of holds) {
         if (BLOCKED_GROOMING_HOLDS[hold.reason] !== true) continue;
+        if (selectGroomingPromotedAt.get(project, hold.issue)?.promotedAt != null) continue;
         upsertGroomingRow.run(project, hold.issue, "blocked", hold.reason, hold.detail ?? hold.reason, Date.now());
       }
     },
@@ -3045,6 +3374,26 @@ export function openStore(dbPath: string): Store {
     for (const issue of issues) removed += deleteGroomingRow.run(project, issue).changes;
     return removed;
   });
+  // Epic scope approvals (#1041). `DO NOTHING` rather than `DO UPDATE` is the
+  // idempotence: the durable fact is when consent was first given, so a second
+  // `epic approve` must not silently restamp the timestamp and make an old
+  // approval look fresh in an audit.
+  const insertEpicApproval = db.query<unknown, [string, number, number, string]>(
+    `INSERT INTO epic_approvals (project, issue, approvedAt, approvedBy)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT(project, issue) DO NOTHING`,
+  );
+  const deleteEpicApproval = db.query<unknown, [string, number]>(
+    `DELETE FROM epic_approvals WHERE project = ? AND issue = ?`,
+  );
+  const selectEpicApproval = db.query<EpicApprovalRow, [string, number]>(
+    `SELECT issue, approvedAt, approvedBy FROM epic_approvals
+      WHERE project = ? AND issue = ?`,
+  );
+  const selectEpicApprovals = db.query<EpicApprovalRow, [string]>(
+    `SELECT issue, approvedAt, approvedBy FROM epic_approvals
+      WHERE project = ? ORDER BY issue ASC`,
+  );
   const selectFrictionRollup = db.query<FrictionRollupRow, [string, string, string]>(
     `SELECT * FROM friction_rollups WHERE project = ? AND day = ? AND kind = ?`,
   );
@@ -3091,6 +3440,43 @@ export function openStore(dbPath: string): Store {
     pruneGhRefusals.run(at - 24 * 60 * 60 * 1000);
   });
 
+  // Auto-restarts of a wedged orchestrator (Phase 4). Insert + prune share one
+  // transaction, exactly as above, so a project that keeps wedging can never
+  // grow this table without bound. The retention (7d) is deliberately longer
+  // than the 6h cap window: the cap needs the last few hours, but an operator
+  // reading the page wants to know whether this is the first bad night or the
+  // fourth.
+  const insertOrchestratorRestart = db.query<unknown, [string, number, string]>(
+    `INSERT INTO orchestrator_restarts (project, at, reason) VALUES (?, ?, ?)`,
+  );
+  const pruneOrchestratorRestarts = db.query<unknown, [number]>(
+    `DELETE FROM orchestrator_restarts WHERE at < ?`,
+  );
+  const selectOrchestratorRestartsSince = db.query<{ at: number; reason: string }, [string, number]>(
+    `SELECT at, reason FROM orchestrator_restarts
+      WHERE project = ? AND at >= ?
+      ORDER BY at DESC, rowid DESC`,
+  );
+  const recordOrchestratorRestartTx = db.transaction(
+    (project: string, at: number, reason: string): void => {
+      insertOrchestratorRestart.run(project, at, reason);
+      pruneOrchestratorRestarts.run(at - 7 * 24 * 60 * 60 * 1000);
+    },
+  );
+
+  // Daemon-owned session spend (Phase 4). Append-only: these sessions have no
+  // lifecycle, they either ran or they did not.
+  const insertSessionSpend = db.query<unknown, SqlValue[]>(
+    `INSERT INTO session_spend (project, role, issue, model, resolvedModel, turns, spendUsd, at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+  );
+  const selectSessionSpendSince = db.query<SessionSpendSqlRow, [string, number]>(
+    `SELECT project, role, issue, model, resolvedModel, turns, spendUsd, at
+       FROM session_spend
+      WHERE project = ? AND at >= ?
+      ORDER BY at DESC, id DESC`,
+  );
+
   // The daemon's tracked github call counts (#198): one UPSERT per spawn.
   const bumpGhCall = db.query<unknown, [string, string]>(
     `INSERT INTO gh_calls (day, source, calls) VALUES (?, ?, 1)
@@ -3437,9 +3823,23 @@ export function openStore(dbPath: string): Store {
         OR EXISTS (SELECT 1 FROM reports WHERE reports.id = material_events.digestReportId AND reports.state IN ('failed', 'withdrawn'))
       )`,
   );
+  // INSERT OR IGNORE, not plain INSERT (Phase 4). For an operator's own idea
+  // the id is random and the clause never fires; for a mined signal the id is
+  // derived from project + source, so the second filing of a signal already on
+  // file collides with its own row and does nothing. Crucially "does nothing"
+  // includes not touching `state`: an UPSERT here would resurrect an item the
+  // operator dismissed on every mining pass, which is the failure mode this
+  // shape exists to prevent.
   const insertIntake = db.query<unknown, SqlValue[]>(
-    `INSERT INTO intake_items (id, project, text, createdAt, state)
-     VALUES (?, ?, ?, ?, 'pending')`,
+    `INSERT OR IGNORE INTO intake_items (id, project, text, createdAt, state, source)
+     VALUES (?, ?, ?, ?, 'pending', ?)`,
+  );
+  // Read back what is actually on file after the insert, which for a collision
+  // is the row that was already there. The caller gets the truth (including a
+  // `dismissed` state and the original `createdAt`) rather than the draft it
+  // hoped to write.
+  const selectIntakeById = db.query<IntakeRow, [string]>(
+    `SELECT * FROM intake_items WHERE id = ?`,
   );
   const selectPendingIntake = db.query<IntakeRow, [string]>(
     `SELECT * FROM intake_items
@@ -3875,6 +4275,62 @@ export function openStore(dbPath: string): Store {
   const selectReviewRevisionById = db.query<ReviewRevisionRow, [string]>(
     `SELECT * FROM review_revisions WHERE id = ?`,
   );
+  // The write-once launch decision (#1045). ONE guarded UPDATE decides and
+  // writes, exactly as the infra retry above does, because a read-then-write
+  // is precisely how two dispatch passes both "find no decision" and both
+  // launch. `changes` is the answer:
+  //
+  //   - launchMode IS NULL           -> nobody has decided; this call wins.
+  //   - the guard triple matches     -> the SAME decision again (a retry, a
+  //                                     restart deciding identically). The row
+  //                                     is re-affirmed rather than refused, so
+  //                                     a dispatch retry is idempotent.
+  //   - anything else                -> 0 changes, and the caller must read the
+  //                                     recorded decision and honour it.
+  //
+  // `IS` rather than `=` on the guard: NULL = NULL is NULL in SQL, so `=`
+  // would refuse a re-affirmation of a decision that carried no requested
+  // model or no origin lineage — the shape a legacy-session round has.
+  //
+  // launchDecidedAt is COALESCE'd, never overwritten: a re-affirmation must
+  // leave the moment of the original decision alone, or a retry loop would
+  // make an old decision look freshly made in every audit that reads it.
+  //
+  // The SET touches decision columns only. The issue, run, round, branch, PR
+  // URL, reviewed head, findings, charges and settlement history are the
+  // round's identity and are never written by this lane.
+  const recordReviewRevisionLaunchRow = db.query<
+    unknown,
+    [string, string | null, string | null, number, string, string, string, string | null, string | null]
+  >(
+    `UPDATE review_revisions
+        SET launchMode = ?,
+            requestedModel = ?,
+            originSessionRef = ?,
+            launchDecidedAt = COALESCE(launchDecidedAt, ?)
+      WHERE id = ? AND project = ?
+        AND (launchMode IS NULL
+             OR (launchMode IS ? AND requestedModel IS ? AND originSessionRef IS ?))`,
+  );
+  // The fresh correction's own session lineage (#1045), attachable only to a
+  // round that was decided `fresh-correction`: a resumed round IS its origin
+  // session, so a separate correction lineage on one would name a session that
+  // never existed. The mode is bound rather than inlined so the vocabulary
+  // lives in exactly one place — {@link ReviewLaunchMode}.
+  //
+  // Deliberately not write-once: an infra-killed round relaunches under the
+  // same decision, and the newest fresh session is then the truth about what
+  // is running. `resolvedModel` is COALESCE'd from the argument side, so a
+  // later call that does not know the resolution cannot erase a known one.
+  const recordReviewCorrectionSessionRow = db.query<unknown, [string, string | null, string, string, string]>(
+    `UPDATE review_revisions
+        SET correctionSessionRef = ?,
+            resolvedModel = COALESCE(?, resolvedModel)
+      WHERE id = ? AND project = ? AND launchMode = ?`,
+  );
+  const selectReviewRevisionForProject = db.query<ReviewRevisionRow, [string, string]>(
+    `SELECT * FROM review_revisions WHERE id = ? AND project = ?`,
+  );
   // The exact-head merge gate (#888): every row that stands between a PR and
   // a merge at one head — anything not yet settled (queued, or dispatched and
   // crashed mid-review) plus anything settled `failed` there. `skipped`,
@@ -4093,7 +4549,7 @@ export function openStore(dbPath: string): Store {
   // appends to the winner's row. The unique pending-per-run index remains as
   // the schema-level backstop.
   const enqueueReviewRevisionTx = db.transaction(
-    (draft: Omit<ReviewRevisionRecord, "id">): ReviewRevisionEnqueue => {
+    (draft: ReviewRevisionDraft): ReviewRevisionEnqueue => {
       const pending = selectPendingReviewForRun.get(draft.project, draft.runId);
       if (pending !== null) {
         if (pending.headSha !== draft.headSha) {
@@ -4448,7 +4904,7 @@ export function openStore(dbPath: string): Store {
     runsForProjectPr(project: string, prUrl: string, mergedSinceEpochMs: number): RunRecord[] {
       return selectRunsForPr.all(project, prUrl, mergedSinceEpochMs).map(toRecord);
     },
-    enqueueReviewRevision(draft: Omit<ReviewRevisionRecord, "id">): ReviewRevisionEnqueue {
+    enqueueReviewRevision(draft: ReviewRevisionDraft): ReviewRevisionEnqueue {
       // `immediate` = BEGIN IMMEDIATE: the write lock is acquired before the
       // pending-row read, so a second connection's transaction cannot observe
       // a snapshot older than the first connection's commit (#786).
@@ -4467,6 +4923,51 @@ export function openStore(dbPath: string): Store {
     markReviewRevisionDispatched(id: string, at: number): void {
       markReviewRevisionDispatchedRow.run(at, id);
     },
+    recordReviewRevisionLaunch(
+      project: string,
+      id: string,
+      decision: {
+        launchMode: ReviewLaunchMode;
+        requestedModel?: string;
+        originSessionRef?: string;
+        at: number;
+      },
+    ): boolean {
+      // The decision and the write are one statement (#1045): `changes` is the
+      // verdict, so a second dispatch pass cannot observe "undecided" and
+      // launch its own. Re-affirming the identical decision reports true —
+      // a dispatch retry after a killed launch must be idempotent, not fatal.
+      const requestedModel = decision.requestedModel ?? null;
+      const originSessionRef = decision.originSessionRef ?? null;
+      return (
+        recordReviewRevisionLaunchRow.run(
+          decision.launchMode,
+          requestedModel,
+          originSessionRef,
+          decision.at,
+          id,
+          project,
+          decision.launchMode,
+          requestedModel,
+          originSessionRef,
+        ).changes > 0
+      );
+    },
+    recordReviewCorrectionSession(project: string, id: string, ref: string, resolvedModel?: string): boolean {
+      // Guarded on the recorded mode, in the statement: a round decided
+      // `resume-original` has no correction session to name, and answering
+      // false here is how the caller learns it read the wrong decision.
+      return (
+        recordReviewCorrectionSessionRow.run(ref, resolvedModel ?? null, id, project, FRESH_CORRECTION).changes > 0
+      );
+    },
+    reviewRevisionLaunch(project: string, id: string): ReviewCorrectionProvenance | undefined {
+      const row = selectReviewRevisionForProject.get(id, project);
+      // A missing round is `undefined`; a round nobody has decided is an empty
+      // provenance. The distinction matters: the first is "no such round", the
+      // second is "this round exists and nothing was written down".
+      return row === null || row === undefined ? undefined : toCorrectionProvenance(row);
+    },
     settleReviewRevision(id: string, outcome: ReviewRevisionOutcome, at: number): void {
       settleReviewRevisionRow.run(outcome, at, id);
     },
@@ -5081,6 +5582,38 @@ export function openStore(dbPath: string): Store {
       return { count: row.n, latestAt: row.latest };
     },
 
+    recordOrchestratorRestart(project: string, at: number, reason: string): void {
+      // Same guard as `recordGhRefusal`: a bad clock must not corrupt the
+      // store, and here it would corrupt the cap itself — a restart stamped in
+      // 1970 falls outside every window and is a free restart forever.
+      if (!Number.isSafeInteger(at) || at < 0) return;
+      recordOrchestratorRestartTx(project, at, reason);
+    },
+
+    orchestratorRestartsSince(project: string, since: number): { at: number; reason: string }[] {
+      return selectOrchestratorRestartsSince.all(project, since);
+    },
+
+    recordSessionSpend(row: SessionSpendRow): void {
+      insertSessionSpend.run(
+        row.project,
+        row.role,
+        row.issue ?? null,
+        row.model ?? null,
+        row.resolvedModel ?? null,
+        row.turns,
+        // `?? null` and NOT `?? 0`: an absent spend is an unmetered session,
+        // and writing 0 here would report it as free. The two readings are
+        // distinguishable at the row precisely because this stays NULL.
+        row.spendUsd ?? null,
+        row.at,
+      );
+    },
+
+    sessionSpendSince(project: string, since: number): SessionSpendRow[] {
+      return selectSessionSpendSince.all(project, since).map(toSessionSpend);
+    },
+
     bumpGhCalls(day: string, source: string): void {
       bumpGhCall.run(day, source);
     },
@@ -5506,15 +6039,23 @@ export function openStore(dbPath: string): Store {
     },
 
     recordIntake(draft: IntakeDraft): IntakeItem {
-      const item: IntakeItem = {
-        id: newReportId(),
-        project: draft.project,
-        text: draft.text,
-        createdAt: draft.at,
-        state: "pending",
-      };
-      insertIntake.run(item.id, item.project, item.text, item.createdAt);
-      return item;
+      // A mined signal's id is a function of its provenance, an operator's own
+      // idea gets a fresh random one. That single choice is the whole
+      // idempotency mechanism: the machine keeps landing on its own row, the
+      // human never does, and two identical thoughts on two days stay two
+      // thoughts.
+      const id =
+        draft.source === undefined ? newReportId() : minedIntakeId(draft.project, draft.source);
+      insertIntake.run(id, draft.project, draft.text, draft.at, draft.source ?? null);
+      const stored = selectIntakeById.get(id);
+      // The read cannot miss — the row is either the one just inserted or the
+      // one that made the insert a no-op — but a fabricated pending item would
+      // be worse than a loud failure, since the caller would report having
+      // filed something that is not on file.
+      if (stored === null) {
+        throw new Error(`intake item ${id} vanished immediately after insert`);
+      }
+      return toIntakeItem(stored);
     },
 
     pendingIntake(project: string): IntakeItem[] {
@@ -5572,6 +6113,43 @@ export function openStore(dbPath: string): Store {
       return condemned;
     },
 
+    markGroomingPromoted(project: string, issue: number, at: number, by: PromotedBy): boolean {
+      // One guarded UPDATE, so "did I win" is SQLite's answer rather than a
+      // read-then-write that two daemon passes could both pass (#1041).
+      return markGroomingPromotedRow.run(at, by, project, issue).changes > 0;
+    },
+
+    promotionsSince(project: string, since: number): GroomingRecord[] {
+      return selectPromotionsSince.all(project, since).map(toGrooming);
+    },
+
+    approveEpic(project: string, issue: number, at: number, by: string): void {
+      // Refused rather than stored: an approval is a standing gate other code
+      // reads, and a row keyed on #0 or #1.5 would be a permanent fact about an
+      // issue that cannot exist. The table's CHECK would catch the non-positive
+      // case as an opaque SQLite error; this names the argument instead.
+      if (!Number.isInteger(issue) || issue <= 0) {
+        throw new Error(`an epic approval needs a positive issue number, got ${String(issue)}`);
+      }
+      insertEpicApproval.run(project, issue, at, by);
+    },
+
+    revokeEpicApproval(project: string, issue: number): boolean {
+      if (!Number.isInteger(issue) || issue <= 0) {
+        throw new Error(`an epic approval needs a positive issue number, got ${String(issue)}`);
+      }
+      return deleteEpicApproval.run(project, issue).changes > 0;
+    },
+
+    epicApproval(project: string, issue: number): EpicApproval | undefined {
+      const row = selectEpicApproval.get(project, issue);
+      return row === null ? undefined : { ...row };
+    },
+
+    epicApprovals(project: string): EpicApproval[] {
+      return selectEpicApprovals.all(project).map((row) => ({ ...row }));
+    },
+
     close(): void {
       db.close(false);
     },