omp-conductor 0.18.0 → 0.18.2

package/src/types.ts

@@ -638,26 +638,76 @@ 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;
+}
+
 /**
  * One durable review-revision request (#677): the orchestrator returned a
  * green, run-owned pull request to its worker with blocking findings, and
@@ -690,6 +740,21 @@ export interface ReviewRevisionRecord {
   outcome?: ReviewRevisionOutcome;
 }
 
+/**
+ * The outcome of recording one `conductor_pr_review` finding against a run's
+ * review-revision outbox (#786). `created` opened a new revision round for the
+ * run; `appended` folded the finding into the revision already pending
+ * undelivered on the same reviewed head — one round, one row, one worker
+ * attempt either way, and the resumed session reads both findings. `refused`
+ * names the one in-flight shape that cannot be amended: a pending revision at
+ * a different head, which is a review of a moved PR and must dispatch and
+ * settle before another finding for the same run is recorded.
+ */
+export type ReviewRevisionEnqueue =
+  | { kind: "created"; record: ReviewRevisionRecord }
+  | { kind: "appended"; record: ReviewRevisionRecord }
+  | { kind: "refused"; block: "pending-different-head" };
+
 /**
  * A model-supplied justification: one value out of a closed set, plus prose that
  * is written down and read by nothing that decides.
@@ -926,6 +991,38 @@ export const CONFIG_VERSION = 2;
  */
 export const READABLE_CONFIG_VERSIONS = [1, CONFIG_VERSION] as const;
 
+/**
+ * Operator-authored host facts rendered into every worker brief (#721) — the
+ * typed replacement for host prose hand-written into an untracked agent
+ * context file. Only what cannot be derived lives here: cores and RAM are
+ * read from the host by `host.ts` at render time, and the guarded shell
+ * suites stay `SHARED_HOST_SCRIPTS`'s single source — nothing in this object
+ * may re-name a refused command.
+ *
+ * Every key is optional; a fleet that never fills the object loads a config
+ * with no `host` field at all and dispatches briefs byte-for-byte as before.
+ */
+export interface HostConstraints {
+  /**
+   * What this host is and what else it runs, in the operator's words ("a
+   * shared 4-core VPS that also runs Langfuse and the fleet"). The renderer
+   * folds the derived core/RAM count into this line.
+   */
+  description?: string;
+  /**
+   * The non-interactive PATH a script or `ssh host '<cmd>'` invocation must
+   * export (`/root/.bun/bin:/root/.local/bin:$PATH` on this fleet) — commands
+   * run from an ssh session do not see the interactive shell's PATH.
+   */
+  path?: string;
+  /**
+   * Per-repo command conventions, keyed by the repo slug the brief renders
+   * as its `{{REPO}}` (`owner/repo`). A repo without an entry renders nothing
+   * for it.
+   */
+  conventions?: Record<string, string>;
+}
+
 /**
  * On-disk root config. `version` is present from day one so a format change
  * can be migrated instead of silently misread by an older daemon.
@@ -938,6 +1035,9 @@ export interface ConductorConfig {
    *  `<stateDir()>/backups/db` when omitted. A snapshot that cannot land there
    *  is `doctor`'s `db-backup` failure. */
   dbBackupDir?: string;
+  /** Host facts every worker brief renders (#721). Absent or empty renders
+   *  nothing — no section — and the brief stays exactly what it always was. */
+  host?: HostConstraints;
 }
 
 /**
@@ -1025,6 +1125,11 @@ export const SETTLEMENT_FLAG_KINDS = [
   "assertions-removed",
   /** A named timeout in a test file went up. */
   "test-timeout-raised",
+  /** The PR diff touches files outside the effective declared file lane —
+   *  the declaration admission enforced and the brief rendered, so a widened
+   *  lane is named on evidence rather than found by reading the file list by
+   *  hand, and the queued work it blocks is explainable (#739). */
+  "lane-escape",
   /** A command the PR body claims as proof, with no matching command in the
    *  run's transcript — the claim has no attempt behind it at all. */
   "claimed-proof-missing",
@@ -1046,8 +1151,8 @@ export type SettlementFlagKind = (typeof SETTLEMENT_FLAG_KINDS)[number];
  */
 export interface SettlementFlag {
   kind: SettlementFlagKind;
-  /** Repo-relative path, `(report)` for report evidence, or `(base branch)` for
-   *  a post-merge workflow result. */
+  /** Repo-relative path, `(report)` for report evidence, `(lane)` for a
+   *  lane-escape finding, or `(base branch)` for a post-merge workflow result. */
   file: string;
   /** 1-based line in the side of the diff the evidence came from: the
    *  post-image for an added line, the pre-image for a removed one. */
@@ -1193,8 +1298,19 @@ export interface Tracker {
   issueBody(issue: number): Promise<string | undefined>;
   /**
    * The state of one specific pull request, or undefined when this adapter
-   * could not tell — a network failure, a deleted PR, a URL it cannot parse.
-   * Undefined never means "no".
+   * could not tell — a network failure, a revoked token, a URL it cannot
+   * parse, or a 404 the adapter could not corroborate. Undefined never means
+   * "no". The one exception is a definitively missing PR: a REST 404 on the
+   * individual read that a same-repository pulls-list read corroborates (a
+   * deleted or never-created number in a repository the credential can still
+   * read) is reported by throwing a classified `GhPrMissingError`. A
+   * repository hidden from the credential answers the same 404 bytes, so a
+   * bare 404 — token scope/SSO loss included — is never "missing": it stays
+   * undefined and the row stays retryable. Every other tracker implementation
+   * keeps the "never throws, undefined is could-not-tell" contract, and every
+   * caller not acting on a missing PR keeps its existing fail-closed handling
+   * by catching the throw exactly as it already catches any other tracker
+   * failure.
    *
    * Deliberately separate from {@link Tracker.openCloserFor}, which asks
    * whether any OPEN closing PR exists and answers undefined for merged,
@@ -1203,6 +1319,11 @@ export interface Tracker {
    * is how a PR a human rejected gets recorded as merged.
    */
   prState(url: string): Promise<PrState | undefined>;
+  /** The live head commit SHA of one pull request, or undefined when the
+   *  tracker could not tell. `pr-checks-green` binds its green verdict to the
+   *  head it was read at, so a head read that cannot answer is "not yet
+   *  satisfied" for that pass, never a green verdict (#808). */
+  prHead(url: string): Promise<string | undefined>;
   /** The merge commit and base ref for a merged pull request. */
   mergedPrInfo(url: string): Promise<MergedPrInfo | undefined>;
   /** Workflow runs GitHub associated with one exact commit SHA. */
@@ -1292,9 +1413,9 @@ export interface Tracker {
   /** Issues carrying `label`, open or closed, bounded. Empty on any failure —
    *  a reconcile that cannot list must remove no labels. */
   listLabeled(label: string, limit?: number): Promise<{ number: number; state: IssueState }[]>;
-  /** Sub-issues of `issue`, with their states. Empty when there are none *or*
-   *  when the lookup failed: both mean "no evidence this was decomposed", and
-   *  the reconcile below only ever acts on positive evidence. */
+  /** Sub-issues of `issue`, with their states. Propagates lookup failures so
+   *  callers can choose the safe polarity: settlement catches and treats an
+   *  unread probe as no positive evidence, while launch selection fails closed. */
   childrenOf(issue: number): Promise<{ number: number; state: IssueState }[]>;
 }
 
@@ -1432,6 +1553,72 @@ export type RunState =
   /** In flight when its daemon process died; reconciled at the next startup. */
   | "orphaned";
 
+/** One parsed `File lane:` declaration: the paths and the verbatim source
+ *  line, so a renderer can reproduce the declaration itself rather than a
+ *  summary of it. Exported for the brief's guarantee that the gate's effective
+ *  lane is always visible to the worker (#608). */
+export interface LaneDeclaration {
+  files: string[];
+  /** The declaration line verbatim, as written on the surface it came from. */
+  source: string;
+}
+
+/**
+ * The effective file lane as both admission and the worker brief must read it
+ * (#608): the latest `File lane:` declaration among the issue body and every
+ * comment, in the tracker's oldest-first order. This is the "later correction
+ * visibly supersedes" contract applied across both surfaces at once, and it is
+ * the single source of truth the gate enforces and the brief renders — so a
+ * declaration can never control admission while staying invisible to the
+ * worker. `at` records which surface won (`"body"`, or the 0-based comment
+ * index), letting the brief reproduce the declaration verbatim when the
+ * winning comment sits beyond its rendered discussion budget.
+ */
+export interface FileLane extends LaneDeclaration {
+  at: "body" | number;
+}
+
+/** One parsed `Model:` declaration (#535): the selector and the verbatim
+ *  source line, so a renderer can reproduce the declaration itself rather
+ *  than a summary of it. */
+export interface ModelDeclaration {
+  /** The selector in omp's own model syntax — a role alias (`@slow`) or a
+   *  concrete `provider/model`, either optionally `:thinking`-suffixed —
+   *  passed straight through as the session's `modelPattern`, for omp's
+   *  resolver to interpret. */
+  model: string;
+  /** The declaration line verbatim, as written on the surface it came from. */
+  source: string;
+}
+
+/**
+ * The effective model as both dispatch and the worker brief must read it
+ * (#535): the latest `Model:` declaration among the issue body and every
+ * comment, in the tracker's oldest-first order — the same "later correction
+ * visibly supersedes" contract applied across both surfaces at once as
+ * {@link FileLane}, so a pre-dispatch comment can change the model a
+ * promotion brief named in the body. `at` records which surface won
+ * (`"body"`, or the 0-based comment index).
+ */
+export interface EffectiveModel extends ModelDeclaration {
+  at: "body" | number;
+}
+
+/**
+ * One dispatched run's observation of the code-graph MCP tools (#726): a
+ * runtime fact read off the session's own registry at session start, never a
+ * config guess. `present: true` and `present: false` are both observations —
+ * an absent field (no `graphTools` on the row at all) means no observation was
+ * recorded, which is deliberately distinct from "tools absent": the whole
+ * point of the boolean is that "the model ignored a tool it had" and "the tool
+ * was missing" no longer look identical from outside the session.
+ */
+export interface GraphToolsObservation {
+  present: boolean;
+  /** Session-start wall clock (ms epoch), the moment the registry was read. */
+  at: number;
+}
+
 /**
  * One attempt at one issue. Persisted so a daemon restart can reconcile
  * orphaned worktrees and branches instead of leaking them.
@@ -1447,6 +1634,17 @@ export interface RunRecord {
   state: RunState;
   /** 1-based attempt number, checked against `Caps.maxAttemptsPerIssue`. */
   attempt: number;
+  /**
+   * The file-lane declaration admission resolved for this run, persisted at
+   * dispatch from the carried `Admission.lane` (#744). It is the exact
+   * snapshot the overlap gate enforced — the same value the brief renders —
+   * and it is durable on purpose: the next dispatch pass builds lane occupancy
+   * from it, so a run admitted with a declared lane it has not yet written
+   * still holds those files across passes, until the row reaches a terminal
+   * state and leaves the active set. Absent means the run predates the column
+   * or was admitted with no declaration (fail open) — never "empty lane".
+   */
+  lane?: FileLane;
   turns: number;
   /** Effective turn ceiling for this run; operators may only raise it. */
   maxTurns: number;
@@ -1519,6 +1717,18 @@ export interface RunRecord {
    * (#286).
    */
   model?: string;
+  /**
+   * The code-graph session observation (#726): whether the graph MCP tools were
+   * in this run's own session registry when the session started. Read off the
+   * session itself, once, at dispatch — never derived from `mcp.json`, which
+   * only says what a session *should* mount. It is the difference between "the
+   * model ignored a tool it had" and "the tool was missing", which look
+   * identical from outside a session. Absent means the run predates the column
+   * or no worker session recorded an observation — never "graph tools were
+   * absent": `present: false` is the only absence claim, and it is a runtime
+   * fact, not an inference.
+   */
+  graphTools?: GraphToolsObservation;
   /** When an operator accepted the loss or recovered the tree by hand
    *  (`unblock --force`). Clears the hold without erasing what happened. */
   salvageAckAt?: number;
@@ -1530,6 +1740,18 @@ export interface RunRecord {
    *  Absent means never quarantined, or no longer — never "quarantine not
    *  checked", because every retained-tree pass checks. */
   quarantineDetail?: string;
+  /** Failed-attempt budget charges this row has accumulated through review
+   *  claims (#795 review round 2). Every chargeable terminal event that was
+   *  claimed into a review round adds one here, so `failuresFor` keeps
+   *  counting each event even after the round leaves the row `pushed-green`;
+   *  repeated failed rounds therefore keep consuming the failed-attempt
+   *  budget. Absent means zero charges were ever preserved on this row. */
+  failureCharges?: number;
+  /** Continuation budget charges this row has accumulated through review
+   *  claims, same semantics as {@link RunRecord.failureCharges}: each
+   *  chargeable cap or returned-for-revision event claimed into a round adds
+   *  one, and `continuationsFor` sums the column. */
+  continuationCharges?: number;
   startedAt: number;
   endedAt?: number;
   /** Last failure text, surfaced verbatim in escalations. */
@@ -1640,6 +1862,14 @@ export interface DispatchSummary {
    *  sweep and by classification recovery. Optional: persisted old rows lack
    *  it, so readers use `?? 0`. (#497) */
   settled?: number;
+  /**
+   * Queue-labelled candidates the operator's park label disqualified — the
+   * same eligibility read the claim gate uses, so the status number cannot
+   * disagree with what admission would hold (#507). Distinguishes "0 claimable,
+   * 12 parked" from "0 claimable, nothing to do". Optional: persisted old rows
+   * lack it, and a pass with nothing parked omits it, so readers use `?? 0`.
+   */
+  parked?: number;
   /** True for a held pass's own record (#497): the queue was never routed, so
    *  ready/routed/claimed are absent queue facts, not an empty queue. */
   paused?: boolean;
@@ -1879,6 +2109,49 @@ export interface IntakeDraft {
   at: number;
 }
 
+/**
+ * The verdict surface of per-issue grooming state (#735). Admission writes
+ * `blocked` when it holds a candidate for a file-lane or dependency reason —
+ * the durable half of the misleading "groom the backlog" fix, because the tick
+ * reads these instead of re-deriving why the runway cannot move. `promotable`
+ * and `considered` are the outcomes #679's scout loop writes into the same
+ * table, so grooming knowledge lives in one store rather than a second memory.
+ */
+export const GROOMING_VERDICTS = ["promotable", "blocked", "considered"] as const;
+
+export type GroomingVerdict = (typeof GROOMING_VERDICTS)[number];
+
+/**
+ * One issue's current grooming verdict, durable across restarts and keyed by
+ * project + issue — one row per issue, replaced in place by upsert, never a
+ * history. Deliberately NOT a decision row: a verdict is neither owed to the
+ * operator nor TTL-exempt, so it sits outside `decisions` (7-day expiry,
+ * operator-facing) and `material_events` (append-only digest outbox) alike.
+ */
+export interface GroomingRecord {
+  project: string;
+  issue: number;
+  verdict: GroomingVerdict;
+  /** Why this verdict — admission's hold reason for `blocked` (`file-lane`,
+   *  `depends-on`), or the groomer's own label for #679's verdicts. */
+  reason: string;
+  /** What proved it: the hold detail naming the overlapping file/holder run,
+   *  or a scout summary. Free text, bounded at the write site. */
+  evidence: string;
+  recordedAt: number;
+}
+
+/** What a caller hands over. The store owns the timestamp and the replace-in-
+ *  place semantics, nothing else. */
+export interface GroomingDraft {
+  project: string;
+  issue: number;
+  verdict: GroomingVerdict;
+  reason: string;
+  evidence: string;
+  at: number;
+}
+
 /**
  * Where one operator decision stands (#136).
  *
@@ -1930,6 +2203,12 @@ export interface DecisionRecord {
   /** When that precondition was first observed true. Set once; the digest
    *  promotes the row from "parked" to "act on this now". */
   conditionMetAt?: number;
+  /** For `pr-checks-green` / `pr-review-ready`: the exact PR head whose checks
+   *  satisfied the condition, read in the same pass as the green verdict. A
+   *  head change invalidates the verdict, so a met row whose PR head has moved
+   *  returns to pending instead of rendering `[CONDITION MET]` for a stale
+   *  head (#808). */
+  conditionHead?: string;
   state: DecisionState;
   resolvedAt?: number;
   /** The answer, the withdrawal reason, or the expiry note. */
@@ -1987,6 +2266,17 @@ export interface Store {
   /** Partial patch; an explicit `null` clears a column, `undefined`/absence leaves it alone (#468). */
   updateRun(id: string, patch: RunPatch): void;
   getRun(id: string): RunRecord | undefined;
+  /**
+   * Counts of this project's runs that recorded a graph-tools session
+   * observation (#726), split by the observed truth value. The doctor reads
+   * these to report what dispatched sessions actually saw, and reports nothing
+   * as "observed" when no run has recorded one.
+   */
+  graphToolsObservationCounts(project: string): {
+    recorded: number;
+    present: number;
+    absent: number;
+  };
   /** Runs whose issue is occupied: a live worker, or a green PR awaiting merge. */
   activeRuns(project: string): RunRecord[];
   /** Runs backed by a worker process — what capacity counts. Subset of {@link Store.activeRuns}. */
@@ -2002,10 +2292,20 @@ export interface Store {
    *  predecessor opened. Merged rows keep the same recent-history bound. */
   runsForProjectPr(project: string, prUrl: string, mergedSinceEpochMs: number): RunRecord[];
   /** Persist one review-revision request (#677), durably, before anything is
-   *  woken. Returns `undefined` when a revision for the same run is already
-   *  pending undelivered — the atomic half of the duplicate in-flight guard
-   *  (the other half is the run row's state once the revision is dispatched). */
-  createReviewRevision(draft: Omit<ReviewRevisionRecord, "id">): ReviewRevisionRecord | undefined;
+   *  woken. A same-run, same-head finding folds into the revision already
+   *  pending undelivered (`appended` — one round, one row, one worker
+   *  attempt, and the resumed session gets both findings); otherwise it opens
+   *  a new round (`created`). A revision already pending at a different head
+   *  cannot be amended (`refused`) — that round must dispatch and settle
+   *  first. The duplicate in-flight guard is the same single transaction, so
+   *  two concurrent same-head findings cannot both create a row or overwrite
+   *  each other (the run row's state is the other half once the revision is
+   *  dispatched). */
+  enqueueReviewRevision(draft: Omit<ReviewRevisionRecord, "id">): ReviewRevisionEnqueue;
+  /** The pending revision for one run, if any — the header the verb reads to
+   *  tell "this call folds into the in-flight round" from "this call opens a
+   *  new round" before the round-ceiling gate applies. */
+  pendingReviewForRun(project: string, runId: string): ReviewRevisionRecord | undefined;
   /** Review revisions not yet handed to a worker, oldest first — what the
    *  daemon's dispatch pass wakes on its next tick. */
   pendingReviewRevisions(project: string): ReviewRevisionRecord[];
@@ -2155,6 +2455,28 @@ export interface Store {
   /** Resolve one idea to `groomed` (recording the issue URL #300 chose) or
    *  `dismissed`. `false` when the id is unknown. */
   resolveIntake(id: string, state: "groomed" | "dismissed", issueUrl?: string): boolean;
+  /** Record the current grooming verdict for one issue, replacing any prior
+   *  row — one row per project + issue, never a history (#735). */
+  upsertGrooming(draft: GroomingDraft): void;
+  /** The current grooming verdict for one issue, or undefined when none. */
+  grooming(project: string, issue: number): GroomingRecord | undefined;
+  /** Current grooming verdicts for a project, issue-ascending; `verdict`
+   *  narrows to one verdict — the tick's known-blocked read is
+   *  `groomingVerdicts(project, "blocked")`. */
+  groomingVerdicts(project: string, verdict?: GroomingVerdict): GroomingRecord[];
+  /**
+   * Reconcile admission's lane/dependency holds against the persisted blocked
+   * verdicts: each currently held issue is recorded as `blocked`, and in the
+   * same transaction every `blocked` row whose lane/dependency hold this pass
+   * does not name is deleted — the hold no longer applies, so the state
+   * self-heals instead of lingering as a cache someone must invalidate. Runs
+   * at the end of every admission pass. Never touches `promotable` or
+   * `considered` rows, which belong to #679's scout loop.
+   */
+  reconcileGrooming(
+    project: string,
+    holds: readonly { issue: number; reason: AdmissionHoldReason; detail?: string }[],
+  ): void;
   /** Count and age source for status and digest prompt bounds. */
   digestBacklog(project: string): DigestBacklog;
   /** Add one bounded observation to the per-day friction rollup. */
@@ -2340,8 +2662,21 @@ export interface Store {
   /** Answer or withdraw one. `false` when the id is unknown or already closed,
    *  so a double-resolve cannot overwrite the first answer. */
   resolveDecision(id: string, state: "answered" | "withdrawn", resolution: string, at: number): boolean;
-  /** First observation that a row's condition came true. Idempotent. */
-  markDecisionConditionMet(id: string, at: number): boolean;
+  /**
+   * First observation that a row's condition came true. Idempotent per head:
+   * a second call changes nothing, but a `pr-checks-green` / `pr-review-ready`
+   * row whose PR head moved is cleared first and then re-marks against the new
+   * head.
+   * `head` binds the verdict to the PR head it was observed at (#808).
+   */
+  markDecisionConditionMet(id: string, at: number, head?: string): boolean;
+  /**
+   * Drop a condition's met state — timestamp and any head binding — when the
+   * observation it was set from stopped holding. The head-bound conditions
+   * call this when the PR head changed, so the row returns to pending instead
+   * of rendering `[CONDITION MET]` for checks that are still running (#808).
+   */
+  clearDecisionConditionMet(id: string): boolean;
   /** Close every open row past its deadline and return them, so the caller can
    *  say what it just closed rather than reporting a count. */
   expireDueDecisions(project: string, now: number): DecisionRecord[];
@@ -2588,6 +2923,16 @@ export const VERB_NAMES = [
    *  OMP session on the existing branch and PR. No close, no reopen, no
    *  redispatch. */
   "conductor_pr_review",
+  /** 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
+   *  worker's own `conductor_pr_create` took for granted from a live channel —
+   *  no worker is live, the routed repo matches, the remote branch is at the
+   *  exact recorded head, the issue is still open, and no PR already
+   *  represents that head — so a stranded `pushed-pending` / lost-PR run can
+   *  re-enter normal review/merge without a fresh clone. Idempotent: an
+   *  already-matching PR is returned, not duplicated. */
+  "conductor_pr_recover",
   /** The one read verb. It answers with the merge gate's own verdict, so
    *  "pushed-green" is the dispatcher's reading of the PR rather than a claim the
    *  worker makes about itself from whatever it happened to run. */
@@ -2653,6 +2998,38 @@ export const VERB_REFUSALS = [
   "pr-not-this-run",
   /** An unrecorded recovery PR was authorized, but not for these exact inputs. */
   "recovery-authorization-mismatch",
+  /** The recovery target resolved to a run that does not exist in the store. */
+  "recovery-no-run",
+  /** The run the recovery was pointed at still has a live worker on it. */
+  "recovery-run-live",
+  /** The run is terminal but not in a state the settlement sweep owns, so a
+   *  recovered PR would never re-enter verification/review/merge. */
+  "recovery-unsettled-state",
+  /** The tracker could not say whether the issue is open. Recovery fails
+   *  closed rather than opening a PR beside (or for) a possibly-closed
+   *  issue. */
+  "issue-state-unreadable",
+  /** The recovered work has already landed or been declined: the issue is
+   *  closed, the run settled merged, or its recorded PR merged. Nothing to
+   *  recover, and recovery must not reopen it. */
+  "recovery-issue-resolved",
+  /** The run records no exact 40-hex head to compare its stored branch
+   *  against, so there is nothing durable to verify a recovered PR would
+   *  publish. */
+  "recovery-unrecorded-head",
+  /** The branch exists but not at the run's recorded head (replaced,
+   *  force-pushed or superseded by a live PR), so a created PR would publish
+   *  work the daemon never verified. */
+  "recovery-head-mismatch",
+  /** 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",
+  /** 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",
   /**
@@ -2695,6 +3072,15 @@ export const VERB_REFUSALS = [
   "label-not-in-vocabulary",
   /** The label is a lifecycle label; those transitions stay the daemon's (#26). */
   "label-is-lifecycle",
+  /** The label is the operator's park gesture; only the operator may set or
+   *  clear it, orchestrator and worker alike (#507). */
+  "label-is-operator-owned",
+  /** Adding the queue label was refused because the issue carries a clearly
+   *  delimited write-lane section heading that parsed no path-like files
+   *  (#825): promoting it would fail open beside overlapping work, so the
+   *  verb refuses with an actionable syntax error instead of echoing a
+   *  fail-open the heading contradicts. */
+  "file-lane-unparseable",
   /** The release grant does not permit this shape for this caller. */
   "release-not-granted",
   /** The artefact or environment is not one this project declared (#129). */