omp-conductor 0.17.1 → 0.18.1

package/src/types.ts

@@ -95,7 +95,8 @@ export interface RepoTarget {
   /**
    * Absolute path of the **conductor-owned, index-only clone** of this repo
    * whose code-graph index workers query. Optional: absent means this repo has
-   * no graph, and the worker brief says nothing about one.
+   * no graph, and the worker brief says so explicitly rather than staying
+   * silent — a worker that knows there is no graph stops looking for one.
    *
    * Two things it deliberately is not, and both were paid for:
    *
@@ -609,6 +610,54 @@ export const REVIEW_REVISION_OUTCOMES = ["revised", "pending", "failed", "skippe
 
 export type ReviewRevisionOutcome = (typeof REVIEW_REVISION_OUTCOMES)[number];
 
+/**
+ * How strictly this project's green PRs are reviewed before they merge
+ * (#678). One of three typed levels; each level's bar is documented once in
+ * {@link REVIEW_STRICTNESS_CHOICES} (setup.ts), which is the same single text
+ * the rendered orchestrator brief carries, so the level a config declares and
+ * the threshold a session actually enforces cannot disagree.
+ *
+ * `low` blocks only correctness, security, data-loss or explicit
+ * acceptance-criteria failures. `medium` (the recommended default for a new
+ * project) adds material maintainability or reliability defects likely to
+ * become incidents within six months. `high` adds concrete quality defects —
+ * never subjective style churn or unbounded refactoring.
+ */
+export const REVIEW_STRICTNESS = ["low", "medium", "high"] as const;
+
+export type ReviewStrictness = (typeof REVIEW_STRICTNESS)[number];
+
+/** The recommended strictness for a project that has never answered. */
+export const DEFAULT_REVIEW_STRICTNESS: ReviewStrictness = "medium";
+
+/** The small validated range a project's own review-round ceiling may sit in. */
+export const REVIEW_MAX_ROUNDS_MIN = 1;
+export const REVIEW_MAX_ROUNDS_MAX = 6;
+
+/** The typed default ceiling: three corrected heads per PR lifecycle — enough
+ *  for real correction cycles, and a hard stop against endless polishing. */
+export const DEFAULT_REVIEW_MAX_ROUNDS = 3;
+
+/**
+ * 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.
+ */
+export interface ReviewPolicy {
+  strictness: ReviewStrictness;
+  maxRounds: number;
+}
+
+/** The documented migration default: what a config written before the key
+ *  existed loads as, deterministically, until the operator answers setup. */
+export const DEFAULT_REVIEW_POLICY: ReviewPolicy = {
+  strictness: DEFAULT_REVIEW_STRICTNESS,
+  maxRounds: DEFAULT_REVIEW_MAX_ROUNDS,
+};
+
 /**
  * One durable review-revision request (#677): the orchestrator returned a
  * green, run-owned pull request to its worker with blocking findings, and
@@ -641,6 +690,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.
@@ -716,8 +780,11 @@ export interface ProjectConfig {
    *  orchestrator-tick.ts. */
   groomBelow?: number;
   /** Labels the dispatcher writes back so the tracker alone shows live state
-   *  to a human who never opens the daemon's logs. */
-  stateLabels: { inProgress: string; blocked: string; failed: string };
+   *  to a human who never opens the daemon's logs. `backlog` is the
+   *  operator's own park gesture (#507) — not dispatcher-written, but read by
+   *  eligibility so a parked issue can never be claimed while its queue label
+   *  is still physically present. */
+  stateLabels: { inProgress: string; blocked: string; failed: string; backlog: string };
   /** Maps a `${labelPrefix}${name}` label on an issue to the checkout it
    *  belongs in, so routing is declared by humans, not guessed. */
   routing: { labelPrefix: string; repos: Record<string, RepoTarget> };
@@ -811,6 +878,16 @@ export interface ProjectConfig {
    * reaching for `.merge` on a project some test hand-built.
    */
   policy?: ProjectPolicy;
+  /**
+   * How green PRs are reviewed and returned (#678): the strictness level and
+   * the hard ceiling on review rounds per PR lifecycle. Optional only for
+   * configs written before the key existed — the loader always materialises a
+   * complete value, so read it through `resolveReview` rather than reaching
+   * for `.review` on a project some test hand-built. A config that never
+   * answered migrates to {@link DEFAULT_REVIEW_POLICY} deterministically, and
+   * the schema's bounds agree with the runtime ones.
+   */
+  review?: ReviewPolicy;
   /**
    * Exact operator-authored exceptions for recovery PRs that no run recorded.
    * Optional and hand-edited: setup preserves entries but never invents them.
@@ -864,6 +941,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.
@@ -876,6 +985,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;
 }
 
 /**
@@ -963,6 +1075,17 @@ 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",
+  /** A claimed proof command was attempted, but the shared-host guard refused
+   *  it — the honest blocked shape, told apart from a claim with no attempt. */
+  "claimed-proof-blocked",
   /** A terminal run recovered an OPEN PR by exact issue, repo and branch identity. */
   "pr-adopted",
   /** A workflow on the merge commit's base branch failed after settlement. */
@@ -978,8 +1101,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. */
@@ -1063,6 +1186,14 @@ export interface Tracker {
    * read exists to prevent (#517).
    */
   listComments(issue: number): Promise<IssueComment[]>;
+  /**
+   * One issue's body, or undefined when the tracker could not produce it.
+   * The promotion echo (#724) renders the parsed file lane exactly where the
+   * author asserts the claim; the queue label is being added to an issue the
+   * `listReady` filter would have excluded by definition, so the verb needs
+   * this read rather than a list the issue is not on.
+   */
+  getIssue(issue: number): Promise<ReadyIssue | undefined>;
   addLabel(issue: number, label: string): Promise<void>;
   removeLabel(issue: number, label: string): Promise<void>;
   comment(issue: number, body: string): Promise<void>;
@@ -1109,10 +1240,27 @@ export interface Tracker {
    * when either fact cannot be read safely.
    */
   issueSnapshot(issue: number): Promise<IssueSnapshot | undefined>;
+  /**
+   * An issue's raw body, or undefined when it cannot be read. Used only by the
+   * dependency-graph cycle pass (#421) to follow a reachable prerequisite's
+   * own `Depends-on:` declarations; never a "no body" claim.
+   */
+  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,
@@ -1121,6 +1269,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. */
@@ -1175,6 +1328,13 @@ export interface Tracker {
    * better answer on a later tick.
    */
   prDiff(url: string): Promise<PrDiff | undefined>;
+  /**
+   * The pull request's body, or undefined when this adapter could not produce
+   * one — the same advisory contract as {@link Tracker.prDiff}. Its only
+   * consumer is the settlement audit's claimed-proof check (#582): a claim
+   * extracted from a body this port could not read is no claim at all.
+   */
+  prBody(url: string): Promise<string | undefined>;
   /**
    * Every check on a PR with the state the tracker reports for it (#132).
    *
@@ -1203,9 +1363,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 }[]>;
 }
 
@@ -1343,6 +1503,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.
@@ -1358,6 +1584,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;
@@ -1397,6 +1634,12 @@ export interface RunRecord {
   autoCompactionCount?: number;
   /** omp session transcript, so a human can read what the worker actually did. */
   sessionFile?: string;
+  /** 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
+   *  without opening the transcript, so "how often did resume fire and did it
+   *  save turns" is a query, not a file walk. */
+  resumedFromRunId?: string;
   prUrl?: string;
   /** Pull request head the worker observed after its deterministic CI watcher exited. */
   headSha?: string;
@@ -1424,9 +1667,41 @@ 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;
+  /** Why the retained tree is under quarantine (#737): the cleanup pass could
+   *  not make its object store sound (`repairAlternates`), so fetching into it
+   *  was refused and the tree's commits cannot be verified against any remote.
+   *  Present means the tree is quarantined right now; the pass clears it the
+   *  moment it reaps the tree or re-verifies the store on a later pass.
+   *  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. */
@@ -1479,6 +1754,10 @@ export type AdmissionHoldReason =
   | "issue-closed"
   | "issue-state-lookup-error"
   | "issue-dequeued"
+  /** An operator-parked issue: the park label beat the queue label at claim
+   *  time (#734). Unlike `issue-dequeued` it is an operator gesture, not a
+   *  queue edit — the queue label may still be physically present. */
+  | "issue-parked"
   | "parent-lookup-error"
   | "sibling-active"
   | "repo-active"
@@ -1489,9 +1768,14 @@ export type AdmissionHoldReason =
   | "plan-usage-cap"
   | "shutting-down"
   | "stale-base"
+  /** A ready issue whose lifecycle state label is residual: its newest run is
+   *  terminal (or absent), so nobody owns it — Duty 1 reconciliation work, not
+   *  occupied capacity (#611). */
+  | "stale-lifecycle"
   | "critical-base-verify-error"
   | "file-lane"
   | "depends-on"
+  | "dependency-cycle"
   | "unroutable:no-repo-label"
   | "unroutable:multiple-repo-labels"
   | "unroutable:unknown-repo";
@@ -1528,6 +1812,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;
@@ -1767,6 +2059,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).
  *
@@ -1818,6 +2153,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. */
@@ -1875,6 +2216,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}. */
@@ -1890,10 +2242,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[];
@@ -1962,6 +2324,11 @@ export interface Store {
    *  can name every WIP tip a re-claim would build on and every tree that is
    *  still the only copy. */
   salvagedRuns(project: string): RunRecord[];
+  /** Newest attempt per issue whose retained tree is under quarantine: the
+   *  object store could not be made sound, so the tree's commits cannot be
+   *  verified against any remote and the daemon refused to fetch into it
+   *  (#737). Newest-attempt-only for the same reason the board is. */
+  quarantinedRuns(project: string): RunRecord[];
   /** Total run segments, used only for the monotonically increasing run number. */
   attemptsFor(project: string, issue: number): number;
   /** Terminal implementation failures that consume `maxAttemptsPerIssue`. */
@@ -2038,6 +2405,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. */
@@ -2223,8 +2612,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[];
@@ -2471,6 +2873,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. */
@@ -2536,6 +2948,32 @@ 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 has no pull request to act on. */
   "pr-missing",
   /**
@@ -2559,6 +2997,13 @@ export const VERB_REFUSALS = [
    * running on it, or the run settled otherwise. The detail names the state.
    */
   "review-in-flight",
+  /**
+   * The PR has already been through the configured review-round ceiling
+   * (#678): the policy's hard bound against endless polishing. Refused rather
+   * than recorded — the orchestrator leaves the PR open, records the
+   * unresolved findings and escalates once instead of spending a worker round.
+   */
+  "review-round-ceiling",
   /**
    * The routed repository's base branch is frozen because a watched merge (or
    * live base observation) turned it red — a base-red-freeze. Further merges to
@@ -2571,6 +3016,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). */