omp-conductor 0.18.1 → 0.18.2

package/src/setup-wizard.ts

@@ -110,11 +110,13 @@ import {
   parseOmpSettingsYaml,
   planAgainstLabels,
   planLabels,
+  readConfiguredOmpRoles,
   summariseAmend,
   summarisePlan,
   wantedLabels,
   writeOrchestratorBrief,
   type AmendAreaId,
+  type ConfiguredOmpRoles,
   type LabelPlan,
   type OperatorJudgment,
   type ScopeCheck,
@@ -126,6 +128,7 @@ import {
   BASE_FRESHNESS,
   BEHIND_BASE_ACTIONS,
   DEFAULT_CAPS,
+  DEFAULT_REVIEW_ADJUDICATOR_ROLE,
   DEFAULT_REVIEW_MAX_ROUNDS,
   DEFAULT_REVIEW_STRICTNESS,
   DENIED_RELEASE_GRANTS,
@@ -133,6 +136,7 @@ import {
   RELEASE_REQUIREMENTS,
   INTERRUPT_CATEGORIES,
   RELEASE_SHAPES,
+  REVIEW_ADJUDICATOR_RE,
   REVIEW_MAX_ROUNDS_MAX,
   REVIEW_MAX_ROUNDS_MIN,
   REVIEW_STRICTNESS,
@@ -151,6 +155,7 @@ import {
   type ReviewPolicy,
 } from "./types.ts";
 import { withProgress } from "./ui/progress.ts";
+import { modelRolesIn } from "./omp-settings.ts";
 import type { WizardUi } from "./wizard-ui.ts";
 
 /**
@@ -1431,6 +1436,136 @@ async function askReviewRounds(ui: WizardUi, current: number): Promise<number> {
   throw new Cancelled();
 }
 
+/** The answer-file key the adjudicator question is recorded under. */
+const REVIEW_ADJUDICATOR_KEY = "review-adjudicator-role";
+
+/**
+ * Whether one role is a legitimate adjudicator answer on this host right now:
+ * it must be a single loadable role token (`REVIEW_ADJUDICATOR_RE`) AND a
+ * `modelRoles` key of the daemon's global settings or of the project's omp
+ * overlay — or the deterministic default, which setup must always be able to
+ * write back. Anything else — including a project's current role that was
+ * removed from both surfaces, or a malformed `modelRoles` key the loader
+ * would refuse — is an unavailable role and must not be accepted, whatever
+ * the config says (#875).
+ */
+function isAdjudicatorAvailable(live: ConfiguredOmpRoles, overlay: readonly string[], role: string): boolean {
+  if (!REVIEW_ADJUDICATOR_RE.test(role)) return false;
+  return role === DEFAULT_REVIEW_ADJUDICATOR_ROLE || live.global.includes(role) || overlay.includes(role);
+}
+
+/**
+ * The adjudicator roles the dialog accepts, derived from the live OMP role
+ * configuration — the daemon's global settings, then the project's omp
+ * overlay — with the current answer first and the deterministic default
+ * offered exactly once (#875). The order is the contract: an amend's Enter
+ * re-affirms the current value, and the shipped default stays expressible for
+ * a project whose operator never answered.
+ *
+ * Every role is filtered through the same token grammar the loader enforces:
+ * a `modelRoles` key the config gate would reject must never be offered (or
+ * accepted), because persisting it would write a policy the next loadConfig
+ * refuses and stop the fleet. The current answer leads the list only while it
+ * is still available: a role removed from both the global settings and the
+ * overlay must not be accepted back into the config by a bare Enter — the
+ * caller warns that it cannot be kept, and the accepted set excludes it, so
+ * Entering it refuses exactly like typing any other unavailable role.
+ */
+function adjudicatorChoices(live: ConfiguredOmpRoles, overlay: readonly string[], current: string): string[] {
+  const choices: string[] = [];
+  const seen = new Set<string>();
+  const first = isAdjudicatorAvailable(live, overlay, current) ? [current] : [];
+  for (const role of [...first, ...live.global, ...overlay, DEFAULT_REVIEW_ADJUDICATOR_ROLE]) {
+    if (REVIEW_ADJUDICATOR_RE.test(role) && !seen.has(role)) {
+      seen.add(role);
+      choices.push(role);
+    }
+  }
+  return choices;
+}
+
+/** One role row's description: what makes this role available and why. */
+function adjudicatorDescription(
+  role: string,
+  live: ConfiguredOmpRoles,
+  overlay: readonly string[],
+): string | undefined {
+  if (live.global.includes(role) || overlay.includes(role)) {
+    return role === DEFAULT_REVIEW_ADJUDICATOR_ROLE
+      ? "configured OMP model role — the deterministic default"
+      : "configured OMP model role";
+  }
+  if (role === DEFAULT_REVIEW_ADJUDICATOR_ROLE) {
+    return "the deterministic default every project loads until answered";
+  }
+  return undefined;
+}
+
+/**
+ * Which OMP model role runs a PR's terminal review-ceiling adjudication
+ * (#875). The offered roles are derived from the live OMP role configuration
+ * (the daemon account's global settings and the project's overlay, never a
+ * conductor-owned registry), the prompt opens on the current answer, and any
+ * answer that is not one of those configured roles is refused with the place
+ * to configure it named.
+ *
+ * Driven through `askValid`, not a select, on purpose: a select surface can
+ * only ever return an offered label, so the unconfigured-value refusal would
+ * be unreachable on the real UIs and the answer-file path would fail with a
+ * generic "must be a listed label" before this guidance ran. A validated text
+ * answer gives every surface — terminal, scripted and `--answers` — the same
+ * bounded three tries and the same actionable error naming the settings file.
+ */
+async function askReviewAdjudicator(
+  ui: WizardUi,
+  current: string,
+  live: ConfiguredOmpRoles,
+  overlay: readonly string[],
+): Promise<string> {
+  const choices = adjudicatorChoices(live, overlay, current);
+  if (!live.decoded) {
+    ui.notify(
+      `The daemon's OMP settings at ${live.path} could not be read — only the project's overlay roles and the default are offered.`,
+      "warning",
+    );
+  }
+  // A project whose configured role was removed from both surfaces must not be
+  // allowed to keep it: the warning names the role and the way back, and the
+  // accepted list above already excludes it — Entering it now refuses exactly
+  // like typing any other unavailable role (#875).
+  if (!isAdjudicatorAvailable(live, overlay, current)) {
+    ui.notify(
+      `"${current}" is this project's current adjudicator but not a currently configured OMP model role — it cannot be kept. ` +
+        `Add "${current}" back as a modelRoles key to ${live.path} or this project's omp settings overlay, ` +
+        `or type one of the available roles below.`,
+      "warning",
+    );
+  }
+  ui.notify(
+    choices
+      .map((role) => {
+        const described = adjudicatorDescription(role, live, overlay);
+        return `${role}${role === current ? " (current)" : ""}${described === undefined ? "" : ` — ${described}`}`;
+      })
+      .join("\n"),
+    "info",
+  );
+  return askValid(
+    ui,
+    REVIEW_ADJUDICATOR_KEY,
+    "Adjudicator for a PR at the review ceiling — one configured OMP model role, not a model",
+    current,
+    (value) => {
+      if (choices.some((choice) => choice === value)) return undefined;
+      return (
+        `"${value}" is not one of the OMP model roles available here — add it as a modelRoles key to the daemon's OMP settings ` +
+        `(${live.path}) or this project's omp settings overlay, or type an offered role. ` +
+        `A role is a single token like "task" — never a provider or model.`
+      );
+    },
+  );
+}
+
 /**
  * How green PRs are reviewed (#678), asked with the merge preconditions and
  * the arming proof: they are the same kind of declared policy — a typed,
@@ -1441,7 +1576,10 @@ async function askReviewRounds(ui: WizardUi, current: number): Promise<number> {
  * rather than between three words. The select cursor opens on the current
  * answer (the configured level on a re-run, the recommended default on a
  * first run); the rounds are a validated integer within the same range the
- * loader enforces.
+ * loader enforces; the adjudicator role is offered from the live OMP role
+ * configuration (#875) — the options and their availability come from the
+ * daemon's OMP settings and the project's overlay, never from a conductor
+ * model registry.
  */
 async function askReviewPolicy(ui: WizardUi, a: SetupAnswers): Promise<ReviewPolicy> {
   ui.notify(
@@ -1450,6 +1588,7 @@ async function askReviewPolicy(ui: WizardUi, a: SetupAnswers): Promise<ReviewPol
     ),
     "info",
   );
+  const live = readConfiguredOmpRoles();
   return {
     strictness: await askLiteral(
       ui,
@@ -1460,6 +1599,7 @@ async function askReviewPolicy(ui: WizardUi, a: SetupAnswers): Promise<ReviewPol
       a.review.strictness,
     ),
     maxRounds: await askReviewRounds(ui, a.review.maxRounds),
+    adjudicator: await askReviewAdjudicator(ui, a.review.adjudicator, live, modelRolesIn(a.ompSettings)),
   };
 }
 

package/src/setup.ts

@@ -50,7 +50,7 @@ import {
   stateDir,
 } from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
-import { ompSettingsOverlay } from "./omp-settings.ts";
+import { modelRolesIn, ompSettingsOverlay } from "./omp-settings.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_ARM_PROOF,
@@ -1575,6 +1575,53 @@ export function detectTelegram(): TelegramPresence {
   return result;
 }
 
+/**
+ * Env override for the daemon account's global omp settings file, exactly the
+ * seam `OMP_TELEGRAM_STATE_DIR` gives telegram discovery: a test (or a second
+ * fleet on the same machine) can redirect the read without touching a real
+ * `~/.omp/agent/config.yml`.
+ */
+export const OMP_GLOBAL_SETTINGS_ENV = "OMP_CONDUCTOR_OMP_SETTINGS_PATH";
+
+/**
+ * The model roles the daemon account's global omp settings actually configure
+ * — the keys of its `modelRoles` stanza (#875) — the "live OMP role
+ * configuration" an adjudicator answer must be checked against. OMP's own
+ * settings file (`~/.omp/agent/config.yml`) is the source rather than any
+ * conductor-owned registry: conductor stores only role names, so the only
+ * place an unrelated role could be invented is here, and reading this file is
+ * what keeps setup from offering (or accepting) a role OMP never configured.
+ *
+ * A missing file is no roles; an unreadable or malformed one is also no roles
+ * but is reported through `decoded: false` so the wizard can say why instead
+ * of silently offering the default alone.
+ */
+export function readConfiguredOmpRoles(): ConfiguredOmpRoles {
+  const override = process.env[OMP_GLOBAL_SETTINGS_ENV]?.trim();
+  const path = override && override.length > 0 ? override : join(homedir(), ".omp", "agent", "config.yml");
+  if (!existsSync(path)) return { path, global: [], decoded: true };
+  try {
+    const parsed = parseYaml(readFileSync(path, "utf8"));
+    return {
+      path,
+      global: [...new Set(modelRolesIn(parsed))].sort(),
+      decoded: true,
+    };
+  } catch {
+    return { path, global: [], decoded: false };
+  }
+}
+
+/** The global omp settings read (`readConfiguredOmpRoles`) reports. */
+export interface ConfiguredOmpRoles {
+  /** The path read (the override, or the default under the operator's home). */
+  readonly path: string;
+  /** The model-role names the file's `modelRoles` stanza declares. */
+  readonly global: readonly string[];
+  /** False when the file exists but could not be read or parsed. */
+  readonly decoded: boolean;
+}
+
 /** True when `.env` carries a non-empty `TELEGRAM_BOT_TOKEN`. The value is
  *  compared against emptiness and then dropped on the floor. */
 function hasTelegramToken(envPath: string): boolean {
@@ -1796,6 +1843,7 @@ export function summarisePlan(
 
   lines.push("", "review", `  strictness     ${a.review.strictness} — ${REVIEW_STRICTNESS_CHOICES[a.review.strictness]}`);
   lines.push(`  max rounds/PR  ${a.review.maxRounds} — at the ceiling the PR is left open, the findings recorded, and it is escalated once`);
+  lines.push(`  adjudicator    ${a.review.adjudicator} — the OMP model role that runs that ceiling adjudication`);
 
   const reporting = project.reporting as ReportingPolicy;
   const briefPath = orchestratorBriefPath(a);
@@ -2013,18 +2061,20 @@ export const AMEND_AREAS: {
   },
   policy: {
     name: "merge & release preconditions",
-    asks: "the checks, base freshness, draft rule and behind-base action for a merge, then what a release requires and what it ships — and how green PRs are reviewed, and how many rounds a PR may be returned",
+    asks: "the checks, base freshness, draft rule and behind-base action for a merge, then what a release requires and what it ships — and how green PRs are reviewed, how many rounds a PR may be returned, and which OMP model role adjudicates a PR at that ceiling",
     describe: (p) => {
       const policy = resolvePolicy(p);
       const review = resolveReview(p);
       // Counted rather than listed: this row is elided at 96 characters, and the
-      // full table is in the plan summary the consent screen shows next.
+      // full table is in the plan summary the consent screen shows next. The
+      // adjudicator is the third review decision, so it is named with the other
+      // two (#875).
       return (
         `merge: ${policy.merge.requiredChecks.length === 0 ? "every check" : `${policy.merge.requiredChecks.length} check(s)`}, ` +
         `base ${policy.merge.baseFreshness}, drafts ${policy.merge.drafts}, behind → ${policy.merge.whenBehindBase}; ` +
         `release: ${policy.release.requires.length} must-land, ${policy.release.artefacts.length} artefact(s), ` +
         `${policy.release.environments.length} env(s); ` +
-        `review ${review.strictness} ×${review.maxRounds}`
+        `review ${review.strictness} ×${review.maxRounds} (adjudicator ${review.adjudicator})`
       );
     },
   },

package/src/status-render.ts

@@ -18,7 +18,7 @@
  */
 
 import { formatZonedMinute } from "./availability.ts";
-import type { DaemonStop } from "./types.ts";
+import type { DaemonStop, GroomingRecord } from "./types.ts";
 import { settlementFlagSummary } from "./diff-flags.ts";
 import type { CodeGraphHealth } from "./graph-health.ts";
 import { formatDigestBacklog, formatOpenReports } from "./reports.ts";
@@ -206,6 +206,141 @@ function formatLastStop(lastStop: DaemonStop | undefined): string[] {
 }
 
 
+// durable to-spec grooming lifecycle (#809)
+// ---------------------------------------------------------------------------
+
+/**
+ * The durable mechanical-hold reasons admission's reconcile writes as blocked
+ * rows (#735) — the lane/dependency holds that clear by themselves. Mirrors
+ * `BLOCKED_GROOMING_HOLDS` in `store.ts`; the status reads the stored reason
+ * strings so both sides of the contract stay on the store vocabulary.
+ */
+const MECHANICAL_GROOMING_REASONS: Record<string, true> = {
+  "file-lane": true,
+  "depends-on": true,
+};
+
+/**
+ * The to-spec refusal classes persisted as blocked rows (#772) — a result
+ * that failed validation is a mechanical block, never a verdict. Mirrors the
+ * failure kinds of `ToSpecFailure` in `to-spec.ts`.
+ */
+const REFUSED_GROOMING_REASONS: Record<string, true> = {
+  malformed: true,
+  "missing-source": true,
+  "stale-source": true,
+};
+
+/** The durable in-flight launch marker (#777) — a batch is running right now.
+ *  Mirrors `TO_SPEC_IN_FLIGHT_REASON` in `orchestrator-tick.ts`. */
+const GROOMING_IN_FLIGHT_REASON = "in-flight";
+
+/**
+ * One project's durable grooming state as status lines, or nothing when there
+ * is nothing to report (#809).
+ *
+ * Renders the state already owned by the `grooming_verdicts` table plus the
+ * dispatch snapshot's parked count — each category below is derived from the
+ * project-scoped durable rows the caller passes, never from parsing evidence
+ * strings and never from a second cache:
+ *
+ *  - `awaiting to-spec` — the routable queue candidates the last dispatch
+ *    pass saw that no durable row covers: `routed − rows`, clamped at zero so
+ *    stale rows (candidates since removed from the queue) cannot push it
+ *    negative. `routed` is the same denominator the tick's grooming trigger
+ *    reads (`summary.routed >= groomBelow`), and the fleet's queue-digest
+ *    arithmetic already treats durable rows as current-queue facts
+ *    (`claimable = routed − knownBlocked`), so this is the operator-facing
+ *    half of the same subtraction. Parent/epic exclusions and backlog
+ *    candidates that never entered the queue are tracker-side and not
+ *    store-knowable; the row lines below carry the durable results either
+ *    way.
+ *  - `promotable` / `considered` / `blocked` — completed to-spec results
+ *    (`blocked` rows whose reason is a groomer verdict or a product-judgement
+ *    label, e.g. `needs-product-decision`).
+ *  - `mechanically blocked` — admission's lane/dependency holds.
+ *  - `refused` — to-spec results that failed validation (`malformed`,
+ *    `missing-source`, `stale-source`), told apart from the holds so an
+ *    operator sees whether the runway cannot move or a result cannot be
+ *    trusted.
+ *  - `in-flight` — a launched batch is running (#777).
+ *  - `operator-parked` — the dispatch snapshot's parked count (#507).
+ *
+ * Rendering is read-only: nothing here reconciles, promotes, retries, or
+ * mutates grooming records. Empty categories are omitted — zero-value rows
+ * would be noise, and an absent block means a fleet with no grooming state.
+ */
+export interface GroomingStatusInput {
+  /** Project-scoped durable rows (`Store.groomingVerdicts`), issue-ascending. */
+  records: readonly GroomingRecord[];
+  /** Routable queue candidates from the last dispatch pass
+   *  (`DispatchSummary.routed`). */
+  routed: number;
+  /** Operator-parked candidates from the last dispatch pass
+   *  (`DispatchSummary.parked`). */
+  parked: number;
+}
+
+/** How many issue identifiers one category line may carry — enough to act on,
+ *  never a queue dump. Mirrors the dispatch hold sampling. */
+const GROOMING_STATUS_SAMPLE = 5;
+
+/** One category line: label, count, and a bounded sample of issue identifiers
+ *  with their durable reasons where the reason differs from the line label
+ *  (e.g. `#13 already-done` under `considered`, `#19 malformed` under
+ *  `refused`). Absent at zero. */
+function groomingStatusLine(
+  label: string,
+  rows: readonly GroomingRecord[],
+): string | undefined {
+  if (rows.length === 0) return undefined;
+  const sample = rows
+    .slice(0, GROOMING_STATUS_SAMPLE)
+    .map((row) => (row.reason === label ? `#${row.issue}` : `#${row.issue} ${row.reason}`));
+  const more = rows.length > GROOMING_STATUS_SAMPLE ? ", …" : "";
+  return `  ${label.padEnd(21)}${rows.length}  ${sample.join(", ")}${more}`;
+}
+
+export function formatGroomingStatus(input: GroomingStatusInput): string | undefined {
+  const { records, routed, parked } = input;
+  const promotable = records.filter((row) => row.verdict === "promotable");
+  const considered = records.filter((row) => row.verdict === "considered");
+  const blockedResults = records.filter(
+    (row) =>
+      row.verdict === "blocked" &&
+      MECHANICAL_GROOMING_REASONS[row.reason] !== true &&
+      REFUSED_GROOMING_REASONS[row.reason] !== true &&
+      row.reason !== GROOMING_IN_FLIGHT_REASON,
+  );
+  const mechanical = records.filter(
+    (row) => row.verdict === "blocked" && MECHANICAL_GROOMING_REASONS[row.reason] === true,
+  );
+  const refused = records.filter(
+    (row) => row.verdict === "blocked" && REFUSED_GROOMING_REASONS[row.reason] === true,
+  );
+  const inFlight = records.filter(
+    (row) => row.verdict === "blocked" && row.reason === GROOMING_IN_FLIGHT_REASON,
+  );
+  const awaiting = Math.max(0, routed - records.length);
+  const lines: string[] = [];
+  if (awaiting > 0) {
+    lines.push(`  ${"awaiting to-spec".padEnd(21)}${awaiting} (of ${routed} routable)`);
+  }
+  for (const line of [
+    groomingStatusLine("promotable", promotable),
+    groomingStatusLine("considered", considered),
+    groomingStatusLine("blocked", blockedResults),
+    groomingStatusLine("mechanically blocked", mechanical),
+    groomingStatusLine("refused", refused),
+    groomingStatusLine("in-flight", inFlight),
+  ]) {
+    if (line !== undefined) lines.push(line);
+  }
+  if (parked > 0) lines.push(`  ${"operator-parked".padEnd(21)}${parked}`);
+  if (lines.length === 0) return undefined;
+  return ["grooming (to-spec)", ...lines].join("\n");
+}
+
 export function formatFleetStatus(
   s: StatusSnapshot,
   layers: FleetLayers,
@@ -220,6 +355,7 @@ export function formatFleetStatus(
   intake: string | undefined = undefined,
   lastStop: DaemonStop | undefined = undefined,
   siblings: { project: string; live: number }[] = [],
+  grooming: string | undefined = undefined,
 ): string {
   const tickLine =
     layers.ticksDetail === undefined
@@ -306,6 +442,7 @@ export function formatFleetStatus(
     ...(decisions === undefined ? [] : [decisions]),
     ...(failureClasses === undefined ? [] : [failureClasses]),
     ...(intake === undefined ? [] : [intake]),
+    ...(grooming === undefined ? [] : [grooming]),
     ...(graphBlock === undefined ? [] : [graphBlock]),
     daemonBlock,
     ...formatLastStop(lastStop),

package/src/to-spec.ts

@@ -33,6 +33,13 @@
  * "strict"` to the task tool. Conductor re-validates whatever the agent
  * returned before persisting, because the harness is permissive by design
  * and the store vets only what this module hands it.
+ *
+ * One contract, every surface (#883): this Zod schema is the single source of
+ * truth. `TO_SPEC_SCHEMA` generated from it stamps the native task launch,
+ * `parseToSpecResult` persists against it, and the drift test pins the
+ * rendered brief, the shipped agent role, and the floor's return contract to
+ * exactly these fields — a field the prose asks for that the schema refuses
+ * is a candidate recorded blocked for following instructions.
  */
 
 import { z } from "zod";
@@ -96,6 +103,12 @@ const ToSpecResultSchema = z
       .optional()
       .describe("Required when `routing` is `MULTI`: what each slice goes to."),
     source: ToSpecSourceSchema,
+    evidence: z
+      .array(z.string().trim().min(1))
+      .optional()
+      .describe(
+        "The files/symbols proving the verdict — required for ALREADY DONE (the code that already does the work, never a title match); welcome on every verdict.",
+      ),
     laterWorkInvalidates: z
       .boolean()
       .describe("Whether later work (an epic committed after this candidate was filed) invalidated its premise."),
@@ -126,8 +139,10 @@ const ToSpecResultSchema = z
       .min(1)
       .describe("The files/dirs this slice writes — the file lane that serialises concurrent work."),
     dependencies: z
-      .array(z.string().trim().min(1))
-      .describe("Open prerequisites this work is blocked on; empty when none."),
+      .array(z.union([z.string().trim().min(1), z.number().int().min(1)]))
+      .describe(
+        'Open prerequisites this work is blocked on, as bare issue numbers (875) or strings ("875"); empty when none.',
+      ),
     proposedBrief: z
       .string()
       .trim()
@@ -159,6 +174,12 @@ const ToSpecResultSchema = z
         ctx.addIssue({ code: "custom", message: `${verdict} must not carry proposedBrief` });
       }
     }
+    if (verdict === "ALREADY DONE" && (value.evidence === undefined || value.evidence.length === 0)) {
+      ctx.addIssue({
+        code: "custom",
+        message: "ALREADY DONE requires evidence naming the file/symbol that already does the work",
+      });
+    }
     if (value.routing === MULTI_ROUTING && value.routingSplit === undefined) {
       ctx.addIssue({ code: "custom", message: 'routing "MULTI" requires routingSplit' });
     }

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
@@ -2974,6 +3024,12 @@ 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",
+  /** 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",
   /**

package/src/verbs/server.ts

@@ -1751,8 +1751,9 @@ async function prReviewVerb(
   const findings = String(args["findings"]);
   const reason = String(args["reason"]) as ReviewReason;
 
-  // The shared review-readiness gate (#844): the newest project-owned run
-  // that recorded the PR, in a revisable state — the same predicate the
+  // The shared review-readiness gate (#844, #870): the newest project-owned
+  // run that recorded the PR — a stopped duplicate is transparent to that
+  // selection (#870) — in a revisable state; the same predicate the
   // `pr-review-ready` watch reads, so the verb and the condition resolve
   // ownership and revisability identically. A PR no run of this project
   // opened (or one outside the routed repos) cannot be returned to a worker
@@ -1958,6 +1959,18 @@ const FULL_HEAD_SHA = /^[0-9a-f]{40}$/i;
  */
 const ABBREVIATED_HEAD_SHA = /^[0-9a-f]{7,39}$/i;
 
+/**
+ * The durable PR field's worker settlement sentinel (#866). A run row whose
+ * settlement recorded "no PR observed yet" carries the literal `pending`
+ * instead of a URL. It asserts nothing about any GitHub pull request — there
+ * is no PR to read — so recovery normalizes it to absence and re-proves the
+ * no-duplicate shape before opening a PR, exactly like a row that recorded no
+ * URL at all. Querying GitHub with it would only produce the tracker's
+ * fail-closed `undefined`, which recovery would misread as an unreadable-but-
+ * real PR and refuse as retryable forever.
+ */
+const PR_PENDING_SENTINEL = "pending";
+
 /**
  * Open (or adopt) the missing pull request for a settled run whose branch was
  * preserved (#806).
@@ -2302,7 +2315,29 @@ async function prRecoverVerb(
     );
   }
 
-  if (target.prUrl !== undefined) {
+  // The durable PR field is normalized and validated before any recorded-PR
+  // lookup (#866). A real recorded PR is a pull-request URL the tracker can
+  // address — the `prUrlParts` shape, the same guard the tracker's own
+  // `prState` applies. The `pending` settlement sentinel is not a URL: it
+  // records the run believed a PR was in flight but never observed one, so it
+  // is normalized to absence and recovery proceeds like a run with no
+  // recorded PR. Any other non-URL value is corruption — there is nothing for
+  // the tracker to read, and had it been queried the fail-closed `undefined`
+  // would read as an unreadable-but-real PR that can never clear — so it
+  // refuses by name instead of hanging the run on a retry.
+  const recordedPrUrl = target.prUrl;
+  const pendingSentinel = recordedPrUrl === PR_PENDING_SENTINEL;
+  if (recordedPrUrl !== undefined && !pendingSentinel && prUrlParts(recordedPrUrl) === undefined) {
+    return refuse(
+      "recorded-pr-corrupt",
+      `refused: run ${target.id} for #${issue} records prUrl ${JSON.stringify(recordedPrUrl)}, which is not a pull ` +
+        "request URL. A non-URL durable prUrl is a corrupt run record, not an unreadable PR — recovery will not " +
+        "guess a GitHub pull request from it. Clear or correct the run's prUrl, then retry.",
+      issue,
+    );
+  }
+
+  if (!pendingSentinel && target.prUrl !== undefined) {
     // The run believes it has a PR. Before creating one, the recorded URL is
     // decided: still open → it is the recovery's answer (idempotent); merged →
     // the work landed; closed → a human declined it; definitively missing →