omp-conductor 0.18.1 → 0.19.0

package/src/types.ts

@@ -51,6 +51,29 @@ export interface Caps {
    * still apply). `0` is a hard stop — deliberate, not "unset".
    */
   dailySpendUsd: number | null;
+  /**
+   * Ceiling on what ONE run may spend, and the size of the reservation
+   * admission takes out of the daily budget before it launches anything
+   * (#851).
+   *
+   * The daily cap alone is a post-spend stop: it compares spend-to-date
+   * against the ceiling at admission time and pauses the fleet on the *next*
+   * pass, so one expensive run can cross it by its whole cost before anything
+   * notices. On 2026-08-21 a single `@slow` run spent an estimated $25.16 of a
+   * $25.00 daily cap unopposed, and the fleet paused only once it had settled.
+   *
+   * `null` means "derive it": `dailySpendUsd / maxConcurrentWorkers`, the
+   * largest per-run allowance that still lets the fleet run at its configured
+   * concurrency. Reserving the whole daily cap per run would bound overshoot
+   * equally well and silently serialise every fleet on defaults, turning a
+   * spend guard into a concurrency change nobody asked for; N reservations of
+   * cap/N are still the cap, so nothing is given away. Set it explicitly to
+   * bound one run harder. It may never exceed `dailySpendUsd` — a per-run
+   * allowance larger than the day's budget is a reservation that can never be
+   * satisfied. With `dailySpendUsd: null` the fleet is unmetered and an
+   * explicit value still bounds one run.
+   */
+  maxRunSpendUsd: number | null;
   /**
    * Subscription/plan allowance guard, independent of `dailySpendUsd` and
    * enforced from the provider's own reported usage rather than from a dollar
@@ -638,26 +661,175 @@ export const REVIEW_MAX_ROUNDS_MAX = 6;
  *  for real correction cycles, and a hard stop against endless polishing. */
 export const DEFAULT_REVIEW_MAX_ROUNDS = 3;
 
+/**
+ * The one spelling a review policy may ask the adjudicator for: a token naming
+ * an OMP model role (`"task"`, `"worker"`, a project's own `modelRoles` key).
+ * A role name is never a provider/model — OMP owns provider selection and
+ * named model roles, and conductor stores only the role. Used by the config
+ * grammar and by the setup dialog's availability check; they must read the
+ * same shape or one of them accepts an answer the other rejects.
+ */
+export const REVIEW_ADJUDICATOR_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * Which OMP model role carries a PR's terminal review-ceiling adjudication
+ * (#875) when no project policy names one. The deterministic migration default
+ * every existing project loads until its operator answers setup: the general
+ * OMP session role each install can launch without a provider or model being
+ * pinned here.
+ */
+export const DEFAULT_REVIEW_ADJUDICATOR_ROLE = "task";
+
 /**
  * One project's review policy (#678): the strictness its orchestrator applies
- * when deciding whether a green PR is returned to its worker, and the hard
- * ceiling on how many such rounds one PR lifecycle may consume. The ceiling is
- * enforced by the dispatch side, never left to the session's reading of the
- * brief: at the ceiling `conductor_pr_review` refuses, the orchestrator leaves
- * the PR open, records the unresolved findings and escalates once.
+ * when deciding whether a green PR is returned to its worker, the hard
+ * ceiling on how many such rounds one PR lifecycle may consume, and which OMP
+ * model role carries the final adjudication once that ceiling is reached
+ * (#875). The ceiling is enforced by the dispatch side, never left to the
+ * session's reading of the brief: at the ceiling `conductor_pr_review`
+ * refuses, the orchestrator leaves the PR open, records the unresolved
+ * findings and escalates once.
  */
 export interface ReviewPolicy {
   strictness: ReviewStrictness;
   maxRounds: number;
+  /**
+   * The OMP model role that runs a PR's terminal review-ceiling adjudication:
+   * a named role from OMP's configured model roles (`"task"`, `"worker"`, or a
+   * project's own `modelRoles` key), in omp's model-role syntax — never a
+   * provider/model, which OMP owns. Absent in config loads as
+   * {@link DEFAULT_REVIEW_ADJUDICATOR_ROLE}, the deterministic default every
+   * existing install upgrades to.
+   */
+  adjudicator: string;
 }
 
-/** The documented migration default: what a config written before the key
+/** The documented migration default: what a config written before the fields
  *  existed loads as, deterministically, until the operator answers setup. */
 export const DEFAULT_REVIEW_POLICY: ReviewPolicy = {
   strictness: DEFAULT_REVIEW_STRICTNESS,
   maxRounds: DEFAULT_REVIEW_MAX_ROUNDS,
+  adjudicator: DEFAULT_REVIEW_ADJUDICATOR_ROLE,
 };
 
+/**
+ * The resolved launch provenance of one review-ceiling adjudication (#875):
+ * what the policy named and what the role actually resolved to when the
+ * adjudicator session launched. OMP owns named roles and exact provider
+ * selection, so this record is where a launch's real model/provider lands —
+ * the typed fields later status/ledger code reads to show what genuinely
+ * adjudicated, not what a config said it should.
+ */
+export interface ReviewAdjudicationProvenance {
+  /** The policy's adjudicator role, verbatim from {@link ReviewPolicy.adjudicator}. */
+  readonly role: string;
+  /** The model pattern the role resolved to at launch, in omp's model syntax. */
+  readonly model: string;
+  /** The provider OMP selected, when the harness could name one at launch. */
+  readonly provider?: string;
+  /** Epoch ms when this launch resolution was recorded. */
+  readonly resolvedAt: number;
+}
+
+/**
+ * The lifecycle of one PR's terminal review-ceiling adjudication (#874).
+ *
+ * The terminal states ARE the verdict — there is deliberately no second
+ * `verdict` column beside this one. A state plus an independently-stored verdict
+ * is two sources of truth for one fact, and the copy nobody updates is the one a
+ * renderer reads. What is stored alongside is what the state cannot say:
+ * the evidence that produced it and the disposition applied because of it.
+ *
+ *  - `pending` — recorded, one-shot claimed, no session launched yet.
+ *  - `running` — an adjudicator session is live on it.
+ *  - `cleared` — the PR may take the ordinary orchestrator-owned merge path.
+ *  - `rejected` — it may not; #876 owns the autonomous disposition.
+ *  - `unavailable-model` — the configured role could not be resolved or
+ *    launched. Distinct from `failed` because the remedy is configuration, not
+ *    a retry.
+ *  - `stale-head` — the PR moved after this adjudication was recorded, so its
+ *    verdict can no longer describe what would merge.
+ *  - `failed` — it ran and could not produce a verdict.
+ */
+export type ReviewAdjudicationState =
+  | "pending"
+  | "running"
+  | "cleared"
+  | "rejected"
+  | "unavailable-model"
+  | "stale-head"
+  | "failed";
+
+/** The terminal states: a row in one of these is finished forever, and is the
+ *  verdict. Exported so the store's transition guard and every reader agree on
+ *  the same set rather than each spelling its own list. */
+export const TERMINAL_REVIEW_ADJUDICATION_STATES: readonly ReviewAdjudicationState[] = [
+  "cleared",
+  "rejected",
+  "unavailable-model",
+  "stale-head",
+  "failed",
+];
+
+/**
+ * One durable review-ceiling adjudication (#874): the record that makes the
+ * final adjudication a lifecycle rather than an in-memory fourth review round.
+ *
+ * Its identity is the exact reviewed head, and that is the one-shot guarantee:
+ * a repeated tick, a racing dispatcher or a daemon restart re-reads this row
+ * instead of launching a second adjudicator. A round in `review_revisions` is
+ * deliberately NOT reused for this — that would spend a worker review round the
+ * ceiling has already exhausted, and would let the same session and model
+ * produce a nominal fourth opinion, which is exactly what #873 forbids.
+ */
+export interface ReviewAdjudicationRecord {
+  id: string;
+  project: string;
+  issue: number;
+  prUrl: string;
+  /** The exact head this adjudication is about. The one-shot key, with
+   *  `project` and `prUrl`: a moved head is a different adjudication, and a
+   *  verdict never travels to a head it did not read. */
+  headSha: string;
+  /** The policy's adjudicator role at admission, verbatim — what was asked for,
+   *  which stays readable even when the role later resolves differently. */
+  role: string;
+  /** What the role actually resolved to at launch (#875). Absent while
+   *  `pending`: nothing has resolved a model yet, and recording an intention as
+   *  provenance would make status claim a launch that never happened. */
+  provenance?: ReviewAdjudicationProvenance;
+  state: ReviewAdjudicationState;
+  /** Why the terminal state is what it is: the adjudicator's verdict text, or
+   *  the diagnostic for a fail-closed outcome (the two heads of a `stale-head`,
+   *  the unresolvable role, the failure). */
+  evidence?: string;
+  /** What was done about the verdict (#876 writes it), kept separate from the
+   *  verdict itself so "rejected" and "rejected, and here is what happened"
+   *  are never conflated. */
+  disposition?: string;
+  requestedAt: number;
+  /** Set when an adjudicator session was launched for this row. */
+  dispatchedAt?: number;
+  settledAt?: number;
+  /** The findings that provoked the escalation (#932): what the orchestrator was
+   *  submitting when `conductor_pr_review` hit the ceiling. Evidence for the
+   *  adjudicator, deliberately not a `review_revisions` round — a round would
+   *  spend a ceiling that is already exhausted and would wake an implementer. */
+  findings?: string;
+}
+
+/**
+ * What admitting an adjudication did (#874). Idempotent by construction: the
+ * second caller for one head is told the row already exists rather than being
+ * allowed to create a twin, and a non-terminal adjudication at a DIFFERENT head
+ * on the same PR refuses — that PR moved, and adjudicating two heads at once is
+ * the duplicate this lifecycle exists to prevent.
+ */
+export type ReviewAdjudicationAdmission =
+  | { kind: "created"; record: ReviewAdjudicationRecord }
+  | { kind: "existing"; record: ReviewAdjudicationRecord }
+  | { kind: "refused"; block: "in-flight-different-head"; record: ReviewAdjudicationRecord };
+
 /**
  * One durable review-revision request (#677): the orchestrator returned a
  * green, run-owned pull request to its worker with blocking findings, and
@@ -688,6 +860,12 @@ export interface ReviewRevisionRecord {
   dispatchedAt?: number;
   settledAt?: number;
   outcome?: ReviewRevisionOutcome;
+  /** How many times an infrastructure kill has returned this round to the
+   *  pending set (#903). A dispatch that died before the resumed session took
+   *  a turn spent no review round, so the row is re-queued rather than settled
+   *  `failed` — and this counter is what bounds that, durably, so an outage
+   *  loop cannot retry one round forever. Absent means zero. */
+  infraRetries?: number;
 }
 
 /**
@@ -705,6 +883,72 @@ export type ReviewRevisionEnqueue =
   | { kind: "appended"; record: ReviewRevisionRecord }
   | { kind: "refused"; block: "pending-different-head" };
 
+/**
+ * How many times one review round may be returned to the pending set after an
+ * infrastructure kill before the daemon stops retrying it (#903).
+ *
+ * The same bound, and the same reasoning, as the run-level infra strike caps:
+ * three dispatches killed before the resumed session took a turn mean the host
+ * or the harness is broken rather than unlucky, and a fourth retry per tick
+ * would loop forever against it. Below the bound the round is free — it spent
+ * no worker turn, so charging it against the review-round ceiling would let an
+ * outage close a PR's last route to a merge; at the bound it settles `failed`
+ * exactly as it does today and escalates once.
+ */
+export const REVIEW_ROUND_INFRA_MAX_RETRIES = 3;
+
+/**
+ * What the store did with a review round whose dispatch was killed by
+ * infrastructure (#903). `requeued` cleared the dispatch marker so the next
+ * pass resumes the same session on the same round; `exhausted` means the bound
+ * is spent and the caller must settle the round the ordinary way.
+ */
+export type ReviewRevisionRetry =
+  | { kind: "requeued"; retries: number }
+  | { kind: "exhausted"; retries: number };
+
+/**
+ * One recorded review clearance (#913): an explicit orchestrator disposition
+ * that the durable review findings standing at one exact head are settled, so
+ * `conductor_pr_merge` may proceed at that head.
+ *
+ * It exists because the #888 merge gate had no reachable clearance at an
+ * unchanged head: a re-review at the same head *adds* a blocking round rather
+ * than superseding one, and nothing an orchestrator can call settles a round —
+ * so a PR at the review-round ceiling was permanently unmergeable. Rows are
+ * append-only audit records, and they clear only **backwards**: a clearance
+ * suppresses a revision row whose own last activity is at or before the
+ * clearance's `at`, never a finding recorded afterwards. It bypasses nothing
+ * but the review gate — authority, pause, base-red-freeze, exact-head,
+ * green-checks, release composition and single-flight all still apply.
+ */
+export interface ReviewClearance {
+  id: string;
+  project: string;
+  prUrl: string;
+  /** The exact head the findings were cleared at. Matched case-insensitively. */
+  headSha: string;
+  at: number;
+  /** The caller's role, as the verb channel resolved it. */
+  by: string;
+  reason: string;
+}
+
+/**
+ * The durable review evidence standing between one pushed-green PR and a
+ * merge at its exact recorded head (#888). Derived from the same
+ * `review_revisions` rows `conductor_pr_merge` refuses on, so status can
+ * never present a green PR as merge-ready while the privileged verb will
+ * (correctly) refuse it.
+ */
+export interface ReviewHeadBlocker {
+  /** The review round whose findings still stand at this head. */
+  round: number;
+  /** Why the round still blocks: queued and not yet addressed, dispatched but
+   *  never finished (crashed mid-review), or settled `failed` at this head. */
+  state: "pending" | "crashed" | "failed";
+}
+
 /**
  * A model-supplied justification: one value out of a closed set, plus prose that
  * is written down and read by nothing that decides.
@@ -811,6 +1055,36 @@ export interface ProjectConfig {
    * when absent or unusable.
    */
   modelFallbackThreshold?: number;
+  /**
+   * An opaque omp selector for one stronger worker tier, used exactly once per
+   * issue chain when a run spun to a cap with nothing to show (#807).
+   *
+   * Conductor never resolves it: `@slow`, a role name or a bare model pattern
+   * are all the same string here, handed to the harness at dispatch the way
+   * {@link workerModel} is. It is deliberately NOT part of
+   * {@link modelFallbacks} — that chain answers provider faults and must stay
+   * provider-only — and absent or blank preserves today's settle/escalate
+   * behaviour byte for byte.
+   */
+  workerEscalationModel?: string;
+  /**
+   * Providers whose routes must bill to a subscription (OAuth) credential, and
+   * never to an API key (#852).
+   *
+   * Declared per **provider**, not per model or per run, because that is the only
+   * truthful unit: a credential belongs to a provider — a model has none of its
+   * own — and a run's provider is not knowable in advance, since
+   * {@link workerModel} is an opaque selector that may be a role alias and the
+   * provider-fault fallback chain (#286) can move a live run onto another
+   * provider mid-flight. So the declaration reads "this provider must bill to its
+   * subscription", and every candidate is held while that is untrue.
+   *
+   * Enforced by conductor rather than omp because omp cannot express it:
+   * `AuthStorage.getApiKey` cascades from a disabled OAuth credential into the
+   * same provider's API key, and no setting, selector suffix or request option
+   * stops it. Absent or empty dispatches byte-for-byte as it always has.
+   */
+  requireOauthProviders?: readonly string[];
   /**
    * An opaque omp settings map layered into every worker session this project
    * dispatches (#537). At dispatch it is materialised verbatim to a fleet-owned
@@ -1417,9 +1691,23 @@ export type FailureClass = (typeof FAILURE_CLASSES)[number];
 /**
  * What the daemon does about a class.
  *
- * `none` completes the vocabulary rather than naming an outcome: an
- * unclassifiable run escalates and never silently retries, so nothing in the
- * decision table maps to it.
+ * Two of these perform nothing, and they are not the same nothing:
+ *
+ * - `hold` — recorded and deliberately left alone, because acting would destroy
+ *   something. `orphan-dirty` is the case: the tree is the only copy, so
+ *   `unblock` refuses rather than re-claiming over it.
+ * - `none` — the classifier declining to name a failure at all. Two callers
+ *   reach it, and neither is "unclassifiable": `classifyRun` returns it for a
+ *   terminal row whose PR is open and fully green, where `classifyAndRecover`
+ *   restores `pushed-green` *without* persisting a class (#766); and the settle
+ *   sweep persists it beside `returned-for-revision` when a reviewer closes
+ *   pushed work without merging, where the remedy is the queue label the sweep
+ *   deliberately leaves on.
+ *
+ * An *unclassifiable* run is `unknown` → `escalate`, and never a silent retry.
+ * This comment previously said nothing in the decision table maps to `none`,
+ * which both callers above contradict; it cost a reading of two modules to
+ * discover, which is what a wrong comment costs (#132).
  */
 export const RECOVERY_ACTIONS = [
   "requeue",
@@ -1479,6 +1767,48 @@ export interface BaseFreeze {
   clearedReason?: string;
 }
 
+/**
+ * The active release composition for one project (#850): the campaign whose
+ * release is being assembled, and the exact PRs allowed into it. While
+ * `closedAt` is absent the composition is active and `prMergeVerb` refuses
+ * every `conductor_pr_merge` whose PR is neither named here nor covered by a
+ * recorded operator override, with the `outside-active-release` refusal — the
+ * mechanical form of "a patch contains no unrelated merges". The row is
+ * SQLite-backed, so the guard survives daemon and orchestrator restarts, and
+ * it retires only through an explicit completion or cancellation; each
+ * transition also writes an immutable material event as its audit trail.
+ */
+export interface ReleaseComposition {
+  /** The campaign identifier, e.g. `v0.18.1-reliability`. */
+  campaign: string;
+  /** Full PR URLs explicitly allowed into this release. */
+  allowedPrUrls: string[];
+  declaredAt: number;
+  declaredBy?: string;
+  /** When the composition retired — absent means it is active. */
+  closedAt?: number;
+  /** `operator` via the CLI on every path that retires a composition. */
+  closedBy?: string;
+  closedReason?: string;
+}
+
+/**
+ * One operator override admitting exactly one PR into one release (#850).
+ * Rows are append-only audit records: an override applies to its campaign
+ * only, never outlives it, and bypasses nothing but the composition check —
+ * authority, pause, base-red-freeze, exact-head, green-checks and
+ * single-flight all still apply to the overridden merge.
+ */
+export interface ReleaseCompositionOverride {
+  id: string;
+  project: string;
+  campaign: string;
+  prUrl: string;
+  at: number;
+  by: string;
+  reason: string;
+}
+
 /**
  * Execution state is separate from the tracker's own labels on purpose: labels
  * are coarse and human-editable, while the loop needs to distinguish "pushed
@@ -1599,6 +1929,18 @@ export interface RunRecord {
   /** Effective turn ceiling for this run; operators may only raise it. */
   maxTurns: number;
   spendUsd: number;
+  /**
+   * The per-run spend allowance admission reserved out of the daily budget
+   * before this run launched (#851). Held for as long as the row is live, and
+   * released the moment it is not — reservations are summed over live rows, so
+   * a settle releases the unspent remainder with no bookkeeping to forget and
+   * a daemon restart re-reads the same reservations off the same rows.
+   *
+   * Absent means the row predates the reservation, or was admitted while the
+   * fleet had no spend cap at all. Never "reserved nothing": a run admitted
+   * under a cap always records what it reserved.
+   */
+  spendReservedUsd?: number;
   /** How many in-session HTTP 429 responses the harness retried before the run
    *  ended, counted by the worker from the session's `message_end` events while
    *  the run was live (#573). Absent means the column predates the count or no
@@ -1634,6 +1976,42 @@ export interface RunRecord {
   autoCompactionCount?: number;
   /** omp session transcript, so a human can read what the worker actually did. */
   sessionFile?: string;
+  /**
+   * The exact `session-host` pid this run's Herdr representation was reported
+   * for, and the pane Herdr knows it as (#842).
+   *
+   * Durable so a restart can find the pane its dead worker left behind, rather
+   * than leaving a workspace showing a live worker that no longer exists. All
+   * three are absent together — a run with a pane always has a pid, because the
+   * pid is what the pane was opened from.
+   *
+   * A matching pid is deliberately NOT treated as proof of life: pids are reused,
+   * and a session-host child dies with the daemon that owns its socket, so a live
+   * row after a restart is an orphan whatever pid it recorded.
+   */
+  workerPid?: number;
+  paneId?: string;
+  paneLabel?: string;
+  /**
+   * Why this run has no workspace representation right now (#841).
+   *
+   * Present only beside a live run with no pane, and cleared the moment one is
+   * established. This is what makes Herdr unavailability a *named* degraded state
+   * rather than an absence: `status` reads it, so a fleet running blind says so
+   * instead of looking identical to a fleet with no workers.
+   */
+  paneUnavailable?: string;
+  /**
+   * Cumulative output and reasoning tokens for this run (#518).
+   *
+   * Both are read off the same `usage` block the spend already comes from, so
+   * they cost no extra provider call. Their ratio is the fact that explains a run
+   * reading `24/180 turns  $0.05` after 43 minutes: 96% of its output was
+   * reasoning. Absent rather than zero when a provider reports no token block —
+   * a share computed from a fabricated zero is worse than no share.
+   */
+  outputTokens?: number;
+  reasoningTokens?: number;
   /** The run id of the orphan-clean attempt whose session this row resumes
    *  (#536, #567). Set only when the dispatch-time resume verdict fired;
    *  absent means a fresh dispatch, never "resumed from unknown". Readable
@@ -1746,6 +2124,25 @@ export interface TurnOverride {
   setAt: number;
 }
 
+/**
+ * The one-shot model escalation a run chain has already spent (#807).
+ *
+ * Written before the continuation it authorises is queued, and never removed:
+ * its presence is both "this chain dispatches on the stronger tier" and "this
+ * chain may never escalate again", so a restart mid-recovery cannot hand the
+ * same chain a second tier.
+ */
+export interface ModelEscalation {
+  /** The opaque selector the chain escalated to — the project's
+   *  `workerEscalationModel` as configured when the marker was claimed. */
+  model: string;
+  /** The spinning-cap class that bought the escalation. */
+  failureClass: FailureClass;
+  /** The run whose settlement claimed it. */
+  runId: string;
+  at: number;
+}
+
 export type AdmissionHoldReason =
   | "capacity"
   | "issue-active"
@@ -1765,7 +2162,20 @@ export type AdmissionHoldReason =
   | "open-pr"
   | "unsalvaged-wip"
   | "daily-spend-cap"
+  /** The candidate's own per-run spend reservation does not fit in what is
+   *  left of the daily budget once spend-to-date and every live run's
+   *  reservation are counted (#851). Distinct from `daily-spend-cap`, which is
+   *  the fleet-stopping "today is already spent" verdict: this one holds a
+   *  candidate while admitted work is still running, and clears by itself as
+   *  those runs settle for less than they reserved. */
+  | "spend-reservation"
   | "plan-usage-cap"
+  /** A provider this project requires to bill to its subscription is currently
+   *  resolving to something else, or could not be verified (#852). Fleet-wide
+   *  like `plan-usage-cap`, and self-clearing: the operator re-authenticates and
+   *  the next pass admits. The hold's detail carries which provider, what it
+   *  resolves to, and the remediation. */
+  | "credential-class"
   | "shutting-down"
   | "stale-base"
   /** A ready issue whose lifecycle state label is residual: its newest run is
@@ -1992,6 +2402,42 @@ export interface ReportEnqueue {
  * stay first, so a busy day drains deterministically over later digests. */
 export const DIGEST_BACKLOG_LIMIT = 20;
 
+/**
+ * The three install identities one host carried at one moment (#919).
+ *
+ * Recorded by the daemon's dispatch pass rather than probed at render time:
+ * reading them costs three subprocesses (`omp-conductor --version`, `omp plugin
+ * list --json`, `herdr … plugin list`), and calling that from the tick took the
+ * tick suite from 8.4s to 83.4s — three spawns every fifteen minutes, forever,
+ * to answer a question whose answer changes only when someone installs
+ * something. So the surfaces that an operator and an agent actually read
+ * consult this row and spawn nothing.
+ *
+ * A missing `ompVersion` or `herdrSource` is "this host does not carry that
+ * surface", which `doctor` reports with full nuance. Only a proven
+ * disagreement — two different releases live at once — is a fault the cheap
+ * surfaces name.
+ */
+export interface InstallSurfaceObservation {
+  /** When the daemon read the surfaces. */
+  at: number;
+  cliVersion: string;
+  ompVersion?: string;
+  herdrSource?: string;
+  /**
+   * The `omp-telegram` peer's three versions (#961), each absent when that
+   * surface did not answer.
+   *
+   * Absent is not agreement. A pass with no registry access records the two it
+   * could read and leaves `telegramPublished` off, and every renderer must show
+   * that as unverified — the whole point being that a stale plugin silently
+   * broke a contract the brief mandates, and "no finding" is what let it.
+   */
+  telegramInstalled?: string;
+  telegramDaemon?: string;
+  telegramPublished?: string;
+}
+
 /** One ordinary material outcome waiting for a rendered digest (#274). */
 export interface MaterialEvent {
   id: string;
@@ -2146,6 +2592,21 @@ export interface DecisionRecord {
   blocks?: string;
   askedAt: number;
   expiresAt: number;
+  /**
+   * The questionnaire this row belongs to (#947): N rows written in one
+   * transaction, delivered as one message, resolved independently. Absent on
+   * every ordinary single ask, which is why the column is nullable rather than
+   * defaulted — a historical row was never part of a group and must not read as
+   * a group of one.
+   */
+  groupId?: string;
+  /**
+   * The issue being specced when this question was asked (#947). A
+   * questionnaire's whole point is that its answers are the spec's provenance,
+   * so a later reader can see why a slice is shaped the way it is instead of
+   * re-litigating it; a group without one is refused at the store boundary.
+   */
+  specIssue?: number;
   /** Raw machine-checkable precondition, e.g. `pr-merged:<url>`. Stored as
    *  written and parsed on read, so a grammar this build does not know is a row
    *  that still lists rather than a row that fails to load. */
@@ -2176,6 +2637,10 @@ export interface DecisionDraft {
   kind?: DecisionKind;
   blocks?: string;
   condition?: string;
+  /** Set by {@link Store.createDecisionGroup}; never by a single ask (#947). */
+  groupId?: string;
+  /** The issue this question specs out (#947). Required inside a group. */
+  specIssue?: number;
   at: number;
 }
 
@@ -2231,6 +2696,19 @@ export interface Store {
   activeRuns(project: string): RunRecord[];
   /** Runs backed by a worker process — what capacity counts. Subset of {@link Store.activeRuns}. */
   liveRuns(project: string): RunRecord[];
+  /**
+   * Runs holding an **active mutation lease** (#899, #925): something is
+   * writing through them right now — a live worker, or a review revision the
+   * daemon has dispatched and that has not settled. Narrower than
+   * {@link Store.activeRuns}, whose worker-free `pushed-*` rows own an issue
+   * and an artifact but no longer own their files.
+   *
+   * This is the one answer to "may this file be written", and it is a single
+   * query because two independent readers ask it — admission's file-lane gate
+   * and `conductor_pr_recover`'s fail-closed lane check — and a lease rule that
+   * disagreed between them would be the exact bug both exist to prevent.
+   */
+  leasedRuns(project: string): RunRecord[];
   /** Failed/killed/orphaned rows whose retained tree has not been reaped. */
   retainedRuns(project: string): RunRecord[];
   /** Newest attempt per issue for the live board. Non-merged work remains
@@ -2275,11 +2753,107 @@ export interface Store {
    *  marker) so the next dispatch pass wakes it again — the reopen half of
    *  restart recovery, paired with restoring its run to `pushed-green`. */
   requeueReviewRevision(id: string): void;
+  /** Return one round to the pending set after an infrastructure kill, and
+   *  count it (#903), or report the bound spent. One transaction: the count is
+   *  read and written with the requeue, so two daemons cannot both spend the
+   *  same retry. `max` is {@link REVIEW_ROUND_INFRA_MAX_RETRIES}, passed in so
+   *  the bound stays a caller's policy rather than a number buried in SQL. A
+   *  settled row is never revived — `exhausted` is the honest answer for one. */
+  retryReviewRevisionAfterInfra(id: string, max: number): ReviewRevisionRetry;
   /** Atomically take a settled green run out of reviewable state:
    *  `pushed-green` → `running`, and only from `pushed-green`. False when the
    *  row already moved (a prior revision was dispatched, the PR settled), so
    *  two concurrent dispatchers cannot both wake one run. */
   claimRunForReview(runId: string): boolean;
+  /** Every review-revision row that blocks merging one PR at one exact head
+   *  (#888): rows not yet settled (queued, or dispatched and crashed
+   *  mid-review) and rows settled `failed` at that head, oldest first.
+   *  Keyed by project + PR + head — never by a label or eventually consistent
+   *  issue search — so a finding tied only to an older head never poisons a
+   *  corrected new head. A row is excluded when a {@link ReviewClearance} for
+   *  the same project + PR + head was recorded at or after that row's own last
+   *  activity (#913) — the clearance is the one reachable disposition at an
+   *  unchanged head, and the timestamp bound keeps it from blessing findings
+   *  recorded after it. */
+  mergeBlockingReviews(project: string, prUrl: string, headSha: string): ReviewRevisionRecord[];
+  /** Append one review clearance for an exact head (#913). Append-only: a
+   *  second clearance at the same head is another audit row, never an update. */
+  recordReviewClearance(clearance: {
+    project: string;
+    prUrl: string;
+    headSha: string;
+    by: string;
+    reason: string;
+    at?: number;
+  }): ReviewClearance;
+  /** Clearances recorded for one PR at one exact head, newest first (#913).
+   *  Head comparison is case-insensitive, exactly as the merge gate's. */
+  reviewClearances(project: string, prUrl: string, headSha: string): ReviewClearance[];
+  /**
+   * Admit one terminal review-ceiling adjudication for an exact PR head (#874),
+   * idempotently. The second caller for the same head is handed the existing
+   * row (`existing`), and a non-terminal adjudication on the same PR at a
+   * DIFFERENT head refuses (`in-flight-different-head`) — the PR moved, and two
+   * live adjudications on one PR is the duplicate this lifecycle prevents.
+   *
+   * Never consumes a review round: this is a separate table from
+   * `review_revisions` precisely so a ceiling that is already exhausted is not
+   * charged again.
+   */
+  openReviewAdjudication(draft: {
+    project: string;
+    issue: number;
+    prUrl: string;
+    headSha: string;
+    role: string;
+    requestedAt?: number;
+    /** The findings that provoked the escalation, when a caller has them. */
+    findings?: string;
+  }): ReviewAdjudicationAdmission;
+  /** `pending` → `running`, recording what the role actually resolved to at
+   *  launch. The transition is the WHERE clause, so two dispatchers racing one
+   *  row cannot both launch: the loser changes nothing and reads `false`. */
+  markReviewAdjudicationRunning(
+    id: string,
+    provenance: ReviewAdjudicationProvenance,
+    at?: number,
+  ): boolean;
+  /** Settle into a terminal state, once, with the evidence that produced it.
+   *  A non-terminal target state or an already-settled row changes nothing and
+   *  reads `false`, so an invalid transition preserves the diagnostic the row
+   *  already carried instead of overwriting it. */
+  settleReviewAdjudication(
+    id: string,
+    state: ReviewAdjudicationState,
+    evidence?: string,
+    at?: number,
+  ): boolean;
+  /** Record what was done about a verdict (#876's half), kept separate from the
+   *  verdict so the two are never conflated. */
+  recordReviewAdjudicationDisposition(id: string, disposition: string): boolean;
+  /** One adjudication by id. */
+  reviewAdjudication(id: string): ReviewAdjudicationRecord | undefined;
+  /** The adjudication for one exact PR head, if any. Case-insensitive on the
+   *  SHA, exactly as the merge gate and the clearance lookup are. */
+  reviewAdjudicationForHead(
+    project: string,
+    prUrl: string,
+    headSha: string,
+  ): ReviewAdjudicationRecord | undefined;
+  /** Every non-terminal adjudication for a project, oldest first: what a daemon
+   *  restart re-reads instead of launching a second adjudicator, and what status
+   *  projects as pending/running. */
+  openReviewAdjudications(project: string): ReviewAdjudicationRecord[];
+  /** Every adjudication recorded for one PR, newest first. */
+  reviewAdjudicationsForPr(project: string, prUrl: string): ReviewAdjudicationRecord[];
+  /**
+   * Every review round recorded for one PR, oldest first (#932): the history an
+   * adjudication is shown. Keyed by PR rather than by run so a continuation that
+   * inherited the PR cannot hide its predecessor's findings — and a finding
+   * without its settled outcome reads as an outstanding complaint even when the
+   * worker fixed it, so both travel together.
+   */
+  reviewRevisionsForPr(project: string, prUrl: string): ReviewRevisionRecord[];
   /** Merged rows whose post-merge workflow verdict is still pending, oldest first. */
   runsNeedingBaseCheck(project: string, limit?: number): RunRecord[];
   /** Replace the current live-head health row for one routed repository. */
@@ -2320,6 +2894,44 @@ export interface Store {
     reason: string,
     at?: number,
   ): boolean;
+  /** The project's active release composition, if one is declared (#850). */
+  activeReleaseComposition(project: string): ReleaseComposition | undefined;
+  /**
+   * Declare the active release composition for a project (#850). One at a
+   * time per project: returns the still-active conflicting composition
+   * unchanged when one exists (the caller refuses), `undefined` when the
+   * declaration took. Replaces only already-closed rows.
+   */
+  declareReleaseComposition(
+    project: string,
+    composition: {
+      campaign: string;
+      allowedPrUrls: string[];
+      declaredBy?: string;
+      declaredAt?: number;
+    },
+  ): ReleaseComposition | undefined;
+  /**
+   * Retire the active composition as completed (#850). Records who closed it
+   * and why on the row itself. Returns true only when an active composition
+   * was actually retired, so the CLI event fires once.
+   */
+  completeReleaseComposition(project: string, by: string, reason: string, at?: number): boolean;
+  /** Retire the active composition as cancelled (#850), same contract as completion. */
+  cancelReleaseComposition(project: string, by: string, reason: string, at?: number): boolean;
+  /** Append one operator override admitting `prUrl` into `campaign` (#850). */
+  grantReleaseCompositionOverride(
+    project: string,
+    override: { campaign: string; prUrl: string; by: string; reason: string; at?: number },
+  ): ReleaseCompositionOverride;
+  /** The newest live override for one PR in one campaign, if recorded (#850). */
+  releaseCompositionOverride(
+    project: string,
+    campaign: string,
+    prUrl: string,
+  ): ReleaseCompositionOverride | undefined;
+  /** Every override recorded for one campaign, newest first (#850). */
+  releaseCompositionOverrides(project: string, campaign: string): ReleaseCompositionOverride[];
   /** Newest attempt per issue that preserved work or failed to, so `status`
    *  can name every WIP tip a re-claim would build on and every tree that is
    *  still the only copy. */
@@ -2346,6 +2958,29 @@ export interface Store {
   /** Every attempt for one issue, oldest first, so an escalation can group the
    *  continuation budget by failure class (#439). */
   runsForIssue(project: string, issue: number): RunRecord[];
+  /**
+   * Spends the single model escalation an issue chain may buy (#807): the
+   * one-shot marker, the `swapFrom` → `queueLabel` hand-back that the
+   * escalation authorises, and the settling run's recovery stamp, all in one
+   * transaction. `true` when this call spent it, `false` when the chain had
+   * already escalated and nothing was written — the second-cap decomposition
+   * verdict. Atomic on purpose: a restart must never find a chain that reads
+   * as escalated with the continuation it promised never queued. Throws when
+   * `runId` names no row.
+   */
+  escalateModel(escalation: {
+    project: string;
+    issue: number;
+    model: string;
+    failureClass: FailureClass;
+    runId: string;
+    swapFrom: string;
+    queueLabel: string;
+    at?: number;
+  }): boolean;
+  /** The escalation this chain has already spent; `undefined` for every chain
+   *  that never bought one, which is what dispatch reads for a fresh issue. */
+  modelEscalation(project: string, issue: number): ModelEscalation | undefined;
   /** Persist a one-shot ceiling and append the operator action to its audit ledger. */
   setTurnOverride(project: string, issue: number, maxTurns: number, setAt?: number): void;
   turnOverride(project: string, issue: number): number | undefined;
@@ -2359,11 +2994,26 @@ export interface Store {
   ): TurnOverride[];
   runsStartedSince(project: string, sinceEpochMs: number): number;
   spendSince(project: string, sinceEpochMs: number): number;
+  /** Total per-run allowance currently reserved by LIVE runs (#851). What
+   *  admission must subtract from the daily budget on top of spend-to-date:
+   *  a run that has spent little has still committed its whole allowance, and
+   *  reading the sum off the live rows means a settle releases the remainder
+   *  and a restart re-reads it rather than losing it. */
+  reservedSpendUsd(project: string): number;
   /** The rows one stats window needs (#282): every run settling at or after
    *  `sinceEpochMs`, plus the full attempt chain of each issue whose merge
    *  settled there (so continuation chains collapse into one journey), ordered
    *  by issue then startedAt. Read-only. */
   statsRuns(project: string, sinceEpochMs: number): RunRecord[];
+  /**
+   * The newest terminal runs, as `{ turns, spendUsd }`, for judging whether the
+   * spend cap's input is still arriving (#970).
+   *
+   * Bounded by `limit` rows, not by `limit` *working* runs: the judgement
+   * discards 0-turn rows, so the caller over-samples and lets the shared
+   * predicate pick the window. Read-only.
+   */
+  recentSpendSamples(project: string, limit: number): { turns: number; spendUsd: number }[];
   /** Total tracked `gh` calls between two UTC day keys, inclusive (#198). */
   ghCallsBetween(sinceDay: string, untilDay: string): number;
   /** Idempotence guard so a retry loop cannot page a human repeatedly for the
@@ -2393,6 +3043,14 @@ export interface Store {
     categories?: readonly InterruptCategory[],
     urgent?: boolean,
   ): HeldNotice[];
+  /** Record the install identities this host carried on this pass (#919).
+   *  One row, replaced: the question is "what is installed now", and a history
+   *  of installs is what the upgrade journal already keeps. */
+  recordInstallSurfaces(observation: InstallSurfaceObservation): void;
+  /** The newest recorded install-surface observation, or `undefined` when no
+   *  pass has read them yet — which the surfaces must render as "not observed",
+   *  never as agreement (#919). */
+  installSurfaces(): InstallSurfaceObservation | undefined;
   /** Persist one ordinary material outcome without sending it. */
   recordMaterialEvent(event: MaterialEventDraft): MaterialEvent;
   getMaterialEvent(id: string): MaterialEvent | undefined;
@@ -2427,6 +3085,21 @@ export interface Store {
     project: string,
     holds: readonly { issue: number; reason: AdmissionHoldReason; detail?: string }[],
   ): void;
+  /**
+   * Delete every grooming row whose issue is not in a **complete** open-issue
+   * snapshot, returning the issues retired (#964).
+   *
+   * A verdict describes an open issue: "promotable" means "promote this", and a
+   * closed issue cannot be promoted. Nothing retired one before, so the rows
+   * accumulated and `status` reported a groomed backlog that did not exist —
+   * measured at 64 of 65 rows, including all 26 promotable ones.
+   *
+   * The completeness of the snapshot is the caller's contract, not this
+   * method's: pass the result of `Tracker.listOpenIssues` (which throws rather
+   * than returning a short list), never a label-filtered read. A partial
+   * snapshot here deletes verdicts nobody re-derived.
+   */
+  retireGroomingNotOpen(project: string, openIssues: readonly number[]): number[];
   /** Count and age source for status and digest prompt bounds. */
   digestBacklog(project: string): DigestBacklog;
   /** Add one bounded observation to the per-day friction rollup. */
@@ -2594,8 +3267,24 @@ export interface Store {
    *  into recovery. False when the row was no longer `ci-deterministic`: a
    *  no-op, exactly what a second repair pass must be. */
   reclassifyInfra(id: string): boolean;
-  /** Unrecovered rows per class, for `status`. Empty when nothing is carrying one. */
+  /**
+   * Rows still **awaiting a recovery the sweep will take**, per class (#132).
+   *
+   * Excludes the recorded-only actions (`none`, `hold`), which never stamp
+   * `recoveredAt` by design — see {@link Store.recordedOnlyClassCounts}. Empty
+   * when nothing is waiting, which is the healthy state and reads as one.
+   */
   failureClassCounts(project: string): { cls: FailureClass; n: number }[];
+  /**
+   * Rows classified but deliberately not acted on, per class (#132): the
+   * `none`/`hold` actions.
+   *
+   * A separate reader because these are a *signal*, not a backlog — 44
+   * `returned-for-revision` rows say something real about review outcomes, and
+   * nothing about work that is stuck. Counting them as unrecovered is what hid
+   * every actionable class behind a monotonically growing tally.
+   */
+  recordedOnlyClassCounts(project: string): { cls: FailureClass; n: number }[];
   /** Rows whose recovery ran at or after `since`, newest first — the tick's
    *  "auto-recovered since last tick" line, and its count. */
   recoveredSince(project: string, since: number): RunRecord[];
@@ -2605,6 +3294,17 @@ export interface Store {
    * remembering things.
    */
   createDecision(draft: DecisionDraft): DecisionRecord;
+  /**
+   * Record one spec-out questionnaire (#947): every item durable in a single
+   * transaction, before its single delivery, sharing a minted group id and the
+   * issue being specced. Refuses an empty batch and a non-issue spec binding —
+   * a questionnaire with nothing waiting on it, or with no spec, is a caller
+   * bug rather than a degenerate case worth supporting.
+   */
+  createDecisionGroup(drafts: readonly DecisionDraft[], specIssue: number): DecisionRecord[];
+  /** One questionnaire's rows in asked order, whatever their states — the
+   *  per-item view a digest renders and a timeout pass resolves against. */
+  decisionGroup(groupId: string): DecisionRecord[];
   /** Everything still owed an answer, oldest first — what a tick digest reads. */
   openDecisions(project: string): DecisionRecord[];
   /** One row by id, whatever its state — what a bounded ask polls while waiting. */
@@ -2839,6 +3539,10 @@ export const DEFAULT_CAPS: Caps = {
   maxConcurrentWorkers: 2,
   maxConcurrentWorkersPerRepo: 1,
   dailySpendUsd: 25,
+  // Derived as `dailySpendUsd / maxConcurrentWorkers` unless an operator names
+  // a per-run allowance: bounded overshoot without changing how many workers
+  // the fleet runs (#851).
+  maxRunSpendUsd: null,
   // Off unless an operator names a window. A default threshold would need a
   // default window id, and guessing which allowance a fleet lives on is how a
   // guard silently watches the wrong meter (#110).
@@ -2873,6 +3577,11 @@ export const VERB_NAMES = [
    *  OMP session on the existing branch and PR. No close, no reopen, no
    *  redispatch. */
   "conductor_pr_review",
+  /** Record that the durable review findings standing at one exact head are
+   *  settled, so the #888 merge gate stops refusing that head (#913). A
+   *  separate verb, never an argument on the merge: the disposition is its own
+   *  recorded act, and it clears only rows older than itself. */
+  "conductor_pr_review_clear",
   /** The orchestrator-only, settled-run recovery operation (#806): open (or
    *  adopt) the missing pull request for a terminal run whose stored branch
    *  exists at its exact recorded head. The recovery proves everything a
@@ -2974,6 +3683,21 @@ export const VERB_REFUSALS = [
   /** The routed repository a terminal run recorded no longer has an entry in
    *  this project's routing, so the daemon cannot create a PR for it. */
   "recovery-repo-unrouted",
+  /** A live mutation lease already holds a file the preserved branch carries
+   *  (#925): publishing it now would put a frozen diff into review beside a
+   *  worker still rewriting the same file. Retryable — the lease releases when
+   *  that worker settles. */
+  "recovery-lane-occupied",
+  /** The lane a recovery would publish could not be read (#925). Unlike
+   *  admission's fail-open interlock, a single deliberate recovery call refuses
+   *  on "could not tell" rather than publishing on an unproven lane. */
+  "recovery-lane-unprovable",
+  /** The run's durable `prUrl` is a non-URL value the tracker cannot address
+   *  (other than the normalized `pending` settlement sentinel, #866). There is
+   *  no PR to read and none to guess at — a corrupt record, not an unreadable
+   *  one, so it refuses by name instead of reading as a never-clearing
+   *  `head-unresolvable`. */
+  "recorded-pr-corrupt",
   /** The run has no pull request to act on. */
   "pr-missing",
   /**
@@ -3012,6 +3736,31 @@ export const VERB_REFUSALS = [
    * repos are unaffected.
    */
   "base-red-freeze",
+  /**
+   * The requested merge head carries durable, unresolved review evidence
+   * (#888): a review revision for this PR that is queued or crashed at
+   * exactly that head, or one settled `failed` there. Green checks do not
+   * clear it — the head must be re-reviewed with `conductor_pr_review` or
+   * superseded by a corrected push to a different head.
+   */
+  "merge-blocked-by-review",
+  /**
+   * A review clearance was asked for at a head where nothing blocks (#913).
+   * A clearance is a disposition of specific evidence, so recording one "just
+   * in case" — before a round exists, or after a corrected push moved the
+   * head — is refused rather than stored as a standing pass.
+   */
+  "review-clearance-vacuous",
+  /**
+   * The project has an active release composition (#850) — a declared
+   * campaign plus the exact PRs allowed into it — and this PR is neither,
+   * with no operator override recorded for it. Merging would smuggle
+   * unrelated work into an assembling release. Refused before the merge lock
+   * and any tracker call; the guard clears only by completing or cancelling
+   * the release, or recording an explicit per-PR override through
+   * `omp-conductor release-composition`, never through the merge reason.
+   */
+  "outside-active-release",
   /** The label is not in this project's own vocabulary. */
   "label-not-in-vocabulary",
   /** The label is a lifecycle label; those transitions stay the daemon's (#26). */