omp-conductor 0.16.2 → 0.17.1

package/src/types.ts

@@ -412,8 +412,11 @@ export type BehindBaseAction = (typeof BEHIND_BASE_ACTIONS)[number];
  * the entry price for being in this list rather than in POLICY.md.
  */
 export const RELEASE_REQUIREMENTS = [
-  /** Every run this release covers reached `merged`, not merely `pushed-green`. */
+  /** Every active run of the released repo reached `merged`, not merely `pushed-green`. */
   "runs-settled",
+  /** Every active run in the project reached `merged` — the suite-wide form of
+   *  `runs-settled`, for shapes that consume several repos at once. */
+  "fleet-runs-settled",
   /** No pull request is still open against the branch being released. */
   "no-open-prs",
   /** Nothing still carries the queue label: the batch is finished, not paused. */
@@ -581,6 +584,63 @@ export const LABEL_REASONS = [
 
 export type LabelReason = (typeof LABEL_REASONS)[number];
 
+/**
+ * Why a green pull request is being returned to its worker for revision.
+ * Closed for the reason {@link MERGE_REASONS} is: a revision request is a
+ * decision the ledger has to be able to name, and the same request repeated
+ * must read the same both times.
+ */
+export const REVIEW_REASONS = [
+  /** The orchestrator read the green PR and found issues that block merging. */
+  "blocking-findings",
+] as const;
+
+export type ReviewReason = (typeof REVIEW_REASONS)[number];
+
+/**
+ * How a queued review revision ended, written by the daemon side of the
+ * transport. `revised` is a revision worker that again reached a verified
+ * green head; `pending` is a still-unverified push; `failed` is a revision
+ * worker that settled terminally; `skipped` is a queued round the daemon could
+ * not dispatch (its run moved, its transcript vanished, or the store already
+ * claimed the slot).
+ */
+export const REVIEW_REVISION_OUTCOMES = ["revised", "pending", "failed", "skipped"] as const;
+
+export type ReviewRevisionOutcome = (typeof REVIEW_REVISION_OUTCOMES)[number];
+
+/**
+ * One durable review-revision request (#677): the orchestrator returned a
+ * green, run-owned pull request to its worker with blocking findings, and
+ * everything the daemon needs to resume the *same* OMP session is recorded
+ * here before any worker is woken. The round numbers successive revisions of
+ * one run (1, 2, …); the findings text is delivered to the resumed session
+ * verbatim.
+ */
+export interface ReviewRevisionRecord {
+  id: string;
+  project: string;
+  /** The run whose pushed-green row this revises. The row is reused, never
+   *  cloned — no new attempt, and no failed-attempt or continuation charge. */
+  runId: string;
+  issue: number;
+  prUrl: string;
+  /** The exact reviewed head; re-verified against the live PR before persisting. */
+  headSha: string;
+  /** Structured blocking findings, delivered verbatim to the resumed session. */
+  findings: string;
+  round: number;
+  reason: ReviewReason;
+  /** The transcript the revision must resume, as the run recorded it — the
+   *  durable "same OMP session" identity, recorded before any wake. */
+  sessionFile?: string;
+  requestedAt: number;
+  /** Set when the daemon handed the revision to a worker. */
+  dispatchedAt?: number;
+  settledAt?: number;
+  outcome?: ReviewRevisionOutcome;
+}
+
 /**
  * A model-supplied justification: one value out of a closed set, plus prose that
  * is written down and read by nothing that decides.
@@ -612,6 +672,33 @@ export const ORCHESTRATOR_MODES = ["embedded", "external"] as const;
 
 export type OrchestratorMode = (typeof ORCHESTRATOR_MODES)[number];
 
+/**
+ * What `arm` accepts as proof that a human just approved arming (conductor
+ * #613). Declared as data for the reason {@link BASE_FRESHNESS} is: the schema,
+ * the setup wizard and the arm gate must all read one vocabulary, and a new
+ * proof must be a compile-time change everywhere at once.
+ *
+ * `challenge` is the pre-#613 behaviour, byte for byte: a Telegram challenge
+ * goes out and the armed marker is written only after the reply appears in the
+ * orchestrator session. `claim-only` arms on the shared live-plumbing verdict
+ * alone — no Telegram send and no wait — which is what makes an unattended
+ * recovery re-arm possible, at the cost spelled out in the wizard question:
+ * anything that can invoke the already-privileged `omp-conductor arm` command
+ * can start dispatch once the live claim and poller pass.
+ */
+export const ARM_PROOFS = ["challenge", "claim-only"] as const;
+
+export type ArmProof = (typeof ARM_PROOFS)[number];
+
+/**
+ * The proof a config that never answered the question gets: today's
+ * authenticated round-trip, so no existing install changes behaviour on
+ * upgrade. Read through `resolveArmProof` (config.ts), never off a raw
+ * `ProjectConfig` — the loader materialises `arm` complete, but a hand-built
+ * config may omit the key.
+ */
+export const DEFAULT_ARM_PROOF: ArmProof = "challenge";
+
 /**
  * Everything the dispatcher needs to service one product: where work comes
  * from, where code goes, and what it may spend doing it. Config is per project
@@ -682,6 +769,16 @@ export interface ProjectConfig {
    * the session that triages it. See {@link ORCHESTRATOR_MODES}.
    */
   escalation: { telegramChatId?: string; telegramTopicId?: number; fallbackToIssueComment: boolean; orchestrator: OrchestratorMode };
+  /**
+   * How `arm` proves a human just approved arming (conductor #613). Optional
+   * only for configs written before the key existed and for hand-built test
+   * configs: the loader always materialises a complete value, so read it
+   * through `resolveArmProof` rather than reaching for `.proof` on a project
+   * some test hand-built. Absent resolves to {@link DEFAULT_ARM_PROOF}
+   * (`challenge`), preserving today's authenticated round-trip — the one value
+   * that changes nothing on upgrade.
+   */
+  arm?: { proof: ArmProof };
   /**
    * Who lands green PRs, who cuts releases and who promotes. The daemon never
    * acts on this itself — it words the orchestrator's standing orders and the
@@ -742,7 +839,11 @@ export interface ProjectConfig {
    * the production daemon. With a marker configured, the dispatcher refuses to
    * reattach any preserved branch missing it, holds the issue as `stale-base`
    * (distinct from capacity or dependency holds), and never silently merges
-   * base into the user's work. Absent or empty, ordinary stale continuations
+   * base into the user's work. A branch the marker cannot be verified against
+   * at all — a failed mirror fetch, an unresolvable marker, or no probe wired
+   * — fails closed too, but as `critical-base-verify-error`: a verification
+   * failure, never a claim that the branch is stale, re-admitted automatically
+   * once a later probe succeeds. Absent or empty, ordinary stale continuations
    * keep today's behaviour. Optional and hand-edited, like
    * {@link recoveryMerges}.
    */
@@ -1028,6 +1129,20 @@ export interface Tracker {
     sha: string,
     opts?: { event?: string; branch?: string },
   ): Promise<WorkflowRun[] | undefined>;
+  /** Full failed-job logs of one workflow run across its attempts, oldest
+   *  attempt first, one chunk per failed job — never one aggregate per attempt,
+   *  so a mixed failure (setup 429 + sibling compile error) stays visible to
+   *  the caller's all-infra guard. `undefined` when the evidence is undecided:
+   *  the run register, any attempt's job register, or any failed job's log
+   *  could not be read, or the run has more attempts than `maxAttempts` (a
+   *  prefix is never presented as the complete attempt history); a no-mutation
+   *  refusal the next pass asks again. `[]` when the run is determinately
+   *  green across its attempts. Logs are full and untruncated — a truncated
+   *  last-400-lines view can discard contrary failure evidence. Read through
+   *  the tracker's own guarded runner — call/refusal accounting and the
+   *  rate-limit breaker apply exactly as they do to a live tick's reads
+   *  (#638). */
+  runFailedAttemptLogs(repo: string, runUrl: string, maxAttempts: number): Promise<string[] | undefined>;
   /** The live commit at one repository branch, or undefined when unreadable. */
   branchHead(repo: string, branch: string): Promise<string | undefined>;
   /** The newest run of this workflow on the base branch before `before`.
@@ -1374,6 +1489,7 @@ export type AdmissionHoldReason =
   | "plan-usage-cap"
   | "shutting-down"
   | "stale-base"
+  | "critical-base-verify-error"
   | "file-lane"
   | "depends-on"
   | "unroutable:no-repo-label"
@@ -1425,6 +1541,7 @@ export type FrictionAdmissionReason =
   | "issue-state-lookup-error"
   | "open-pr-lookup-error"
   | "stale-base"
+  | "critical-base-verify-error"
   | "unroutable:no-repo-label"
   | "unroutable:multiple-repo-labels"
   | "unroutable:unknown-repo";
@@ -1744,6 +1861,14 @@ export interface LabelOp {
  * carry, so the operator reconciles by hand, which is the only safe move once
  * the two disagree.
  */
+
+/**
+ * A settled `ci-deterministic` row offered to the historical infrastructure
+ * reconciliation, with the internal `rowid` that breaks start-time ties so the
+ * persisted review cursor can resume exactly below the last decided row (#638).
+ */
+export type HistoricalInfraCandidate = RunRecord & { rowid: number };
+
 export interface Store {
   /** A claimed run atomically consumes and applies its issue's pending turn override. */
   createRun(r: Omit<RunRecord, "id">): RunRecord;
@@ -1764,6 +1889,35 @@ export interface Store {
    *  per-issue view — a requeued continuation must never hide the PR its
    *  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;
+  /** 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[];
+  /** Round number of the newest revision ever requested for a run (0 = never). */
+  latestReviewRound(project: string, runId: string): number;
+  /** Record that a revision was handed to a worker. */
+  markReviewRevisionDispatched(id: string, at: number): void;
+  /** Record how a revision ended. */
+  settleReviewRevision(id: string, outcome: ReviewRevisionOutcome, at: number): void;
+  /** Every revision row not yet settled — queued (`dispatchedAt` unset) and
+   *  dispatched-but-unfinished — oldest first. This is what a restart reads to
+   *  find review rounds a previous daemon left in flight (#692): the row is
+   *  the durable home of the findings, reviewed head, round and target
+   *  session, so re-queuing the row is how the exact session resumes. */
+  unsettledReviewRevisions(project: string): ReviewRevisionRecord[];
+  /** Return a dispatched revision to the pending set (clear its dispatched
+   *  marker) so the next dispatch pass wakes it again — the reopen half of
+   *  restart recovery, paired with restoring its run to `pushed-green`. */
+  requeueReviewRevision(id: string): void;
+  /** Atomically take a settled green run out of reviewable state:
+   *  `pushed-green` → `running`, and only from `pushed-green`. False when the
+   *  row already moved (a prior revision was dispatched, the PR settled), so
+   *  two concurrent dispatchers cannot both wake one run. */
+  claimRunForReview(runId: string): boolean;
   /** Merged rows whose post-merge workflow verdict is still pending, oldest first. */
   runsNeedingBaseCheck(project: string, limit?: number): RunRecord[];
   /** Replace the current live-head health row for one routed repository. */
@@ -2014,6 +2168,43 @@ export interface Store {
    * than spending one tick on all of it.
    */
   runsNeedingClassification(project: string, limit?: number): RunRecord[];
+  /**
+   * Settled rows currently reading `ci-deterministic` — the only rows the
+   * historical infrastructure reconciliation may repair (#638): the verdict
+   * the forward classifier no longer gives, and nothing else. Newest first
+   * and bounded, because each candidate costs tracker calls to re-fetch the
+   * evidence its log carries.
+   *
+   * `after` is the persisted review cursor (the last row a prior pass decided):
+   * candidates are then only rows strictly *older* than it, so a bounded pass
+   * progresses through a long history instead of rescanning the newest
+   * non-matches forever. `rowid` on each candidate breaks the start-time tie,
+   * giving the cursor an exact resume boundary. */
+  historicalInfraCandidates(
+    project: string,
+    limit?: number,
+    after?: { startedAt: number; rowid: number },
+  ): HistoricalInfraCandidate[];
+  /** The persisted historical-review cursor for a project, or undefined before
+   *  any pass decided a row. The `classifierVersion` stamp tells the pass
+   *  whether the cursor is still current against the signature list. */
+  historicalInfraCursor(
+    project: string,
+  ): { startedAt: number; rowid: number; classifierVersion: string } | undefined;
+  /** Persist (or move) the historical-review cursor after a pass decided rows. */
+  setHistoricalInfraCursor(
+    project: string,
+    startedAt: number,
+    rowid: number,
+    classifierVersion: string,
+  ): void;
+  /** Reclassify one settled `ci-deterministic` row to `ci-infra` (budget
+   *  exempt) after its re-fetched check log matched the closed infrastructure
+   *  signature. Changes `failureClass` only — `recoveryAction`/`recoveredAt`
+   *  stay byte-for-byte unchanged, so a months-old run is never re-animated
+   *  into recovery. False when the row was no longer `ci-deterministic`: a
+   *  no-op, exactly what a second repair pass must be. */
+  reclassifyInfra(id: string): boolean;
   /** Unrecovered rows per class, for `status`. Empty when nothing is carrying one. */
   failureClassCounts(project: string): { cls: FailureClass; n: number }[];
   /** Rows whose recovery ran at or after `since`, newest first — the tick's
@@ -2275,6 +2466,11 @@ export const VERB_NAMES = [
    *  install shape gates it like a release shape; execution detaches from this
    *  session and the daemon, and the first tick after the restart verifies. */
   "conductor_install",
+  /** Return one green, run-owned pull request to its worker with blocking
+   *  findings: durably record the revision, and the daemon resumes the SAME
+   *  OMP session on the existing branch and PR. No close, no reopen, no
+   *  redispatch. */
+  "conductor_pr_review",
   /** 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. */
@@ -2357,6 +2553,12 @@ export const VERB_REFUSALS = [
   "checks-not-green",
   /** Another merge is in flight for this project. */
   "merge-in-flight",
+  /**
+   * The run backing a PR is not in a revisable settled-green state: a review
+   * revision is already in flight (queued or dispatched), a worker is still
+   * running on it, or the run settled otherwise. The detail names the state.
+   */
+  "review-in-flight",
   /**
    * 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

package/src/ui/progress.ts

@@ -0,0 +1,32 @@
+/** Whether the CLI owns an interactive terminal rather than a pipe or plain-UI session. */
+export function interactiveUi(): boolean {
+  return Boolean(
+    process.stdin.isTTY &&
+      process.stdout.isTTY &&
+      !process.env.OMP_CONDUCTOR_PLAIN_UI,
+  );
+}
+
+/** Run one long, silent operation with safe Clack progress on an interactive TTY. */
+export async function withProgress<T>(
+  message: string,
+  success: string,
+  operation: () => Promise<T>,
+  options: { plainMessage?: boolean } = {},
+): Promise<T> {
+  if (!interactiveUi()) {
+    if (options.plainMessage) process.stdout.write(`${message}\n`);
+    return operation();
+  }
+
+  const { log } = await import("@clack/prompts");
+  log.step(message);
+  try {
+    const result = await operation();
+    log.success(success);
+    return result;
+  } catch (err) {
+    log.error(`${message} failed`);
+    throw err;
+  }
+}

package/src/ui/style.ts

@@ -0,0 +1,11 @@
+import { styleText } from "node:util";
+
+function styled(format: Parameters<typeof styleText>[0], text: string): string {
+  return process.stdout.isTTY ? styleText(format, text) : text;
+}
+
+export const heading = (text: string): string => styled(["bold", "cyan"], text);
+export const ok = (text: string): string => styled("green", text);
+export const warn = (text: string): string => styled("yellow", text);
+export const fail = (text: string): string => styled("red", text);
+export const dim = (text: string): string => styled("dim", text);

package/src/upgrade.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { backupTimestamp, copyToUniqueBackup } from "./backups.ts";
 import { inspectBriefLayout, type BriefLayout } from "./brief-upgrade.ts";
-import { pauseInstance, setPaused, statusSnapshot } from "./daemon.ts";
+import { pauseInstance, setPaused, statusSnapshot, type AdmissionAckRecord } from "./daemon.ts";
 import {
   DEFAULT_HERDR_SESSION,
   fleetLayers,
@@ -335,6 +335,22 @@ export interface UpgradeScope {
   pauseKey: string | undefined;
 }
 
+/**
+ * The subset of {@link UpgradeDeps} the pause/drain fence needs. Factored out
+ * so a caller that only wants the fence — `setup host` — can provide just
+ * these members instead of a full install-and-verify deps object. Every
+ * {@link UpgradeDeps} is a `DrainDeps`.
+ */
+/**
+ * The daemon a transaction targets: running or not, its project when it
+ * recorded one, and a `generation` identifying the exact instance (#377).
+ */
+export interface DaemonIdentity {
+  running: boolean;
+  project?: string;
+  generation?: string;
+}
+
 /**
  * The subset of {@link UpgradeDeps} the pause/drain fence needs. Factored out
  * so a caller that only wants the fence — `setup host` — can provide just
@@ -352,11 +368,20 @@ export interface DrainDeps {
    * The daemon the transaction targets: running or not, its project when it
    * recorded one, and a `generation` identifying the exact instance (#377).
    */
-  daemonIdentity(): { running: boolean; project?: string; generation?: string };
+  daemonIdentity(): DaemonIdentity;
   /** The active pause sentinel as an instance, when one is readable (#377). */
   pauseState(project?: string): { source: string; reason?: string; since: number } | undefined;
   /** Write or clear the durable pause sentinel for the scope's project. */
   setPaused(value: boolean, project?: string): void;
+  /**
+   * The daemon's durable admission acknowledgement for the current fence, when
+   * one is readable: the daemon attests it has observed the pause sentinel at
+   * an admission boundary and will claim nothing while it stands (#651 review
+   * #3). Absent when no daemon is running, when the file cannot be read, or
+   * when the daemon has not (yet) observed the fence. The setup barrier
+   * requires this before any mutation when a daemon is running.
+   */
+  admissionAck?(project?: string): AdmissionAckRecord | undefined;
   sleep(ms: number): Promise<void>;
   log(message: string): void;
 }
@@ -455,31 +480,37 @@ export async function waitForDrain(
  * live state against this snapshot, so the destructive restart call only ever
  * acts on the world the request began in (#377).
  */
-interface RestartBegun {
+export interface RestartBegun {
   /** The durable pause sentinel this request relies on, proved readable as an instance. */
   pauseToken: { source: string; reason?: string; since: number };
   /** The daemon instance the restart targets, with its generation identity. */
-  daemon: ReturnType<UpgradeDeps["daemonIdentity"]>;
+  daemon: DaemonIdentity;
 }
 
 /**
- * Why a draining restart can no longer act, or `undefined` when it still owns
- * the pause and the daemon generation it began with. The pause check is the
- * *restart-owned sentinel instance* — `drainAndRestart` proves ownership up
- * front, so a token that cannot be re-read (sentinel removed, unreadable, or
- * re-created — even under the same source and reason) means this request's own
- * pause no longer exists and it must cancel. The generation check is the
- * later-daemon fence: a daemon created after this request began — by
- * `restart --now`, a crash-restart, or an operator start — must never be
- * stopped by it.
+ * Why a pause-and-drain transaction can no longer act, or `undefined` when it
+ * still owns the pause and the daemon generation it began with. The pause
+ * check is the *transaction-owned sentinel instance* — the caller proves
+ * ownership up front, so a token that cannot be re-read (sentinel removed,
+ * unreadable, or re-created — even under the same source and reason) means
+ * this request's own pause no longer exists and it must cancel. The
+ * generation check is the later-daemon fence: a daemon created after the
+ * transaction began — by `restart --now`, a crash-restart, or an operator
+ * start — must never be stopped by it.
+ *
+ * Exported so the setup apply's acknowledged quiescence barrier runs the same
+ * fence instead of inventing a second counter-only one (#618): it freezes
+ * admission host-wide through {@link pauseAndDrain}'s machinery, and this
+ * check is what proves the freeze is still the one it acknowledged.
  */
-function restartFenceProblem(
+export function restartFenceProblem(
   deps: DrainDeps,
   scope: UpgradeScope,
   begun: RestartBegun,
+  actor: string,
 ): string | undefined {
   if (!deps.layers(scope.pauseKey).paused) {
-    return "restart cancelled: dispatch was resumed while the drain was in progress — nothing was restarted";
+    return `${actor} cancelled: dispatch was resumed while the drain was in progress — nothing was restarted`;
   }
   const owned = deps.pauseState(scope.pauseKey);
   if (
@@ -488,11 +519,11 @@ function restartFenceProblem(
     owned.source !== begun.pauseToken.source ||
     owned.reason !== begun.pauseToken.reason
   ) {
-    return "restart cancelled: the restart-owned pause was lifted and replaced while the drain was in progress — nothing was restarted";
+    return `${actor} cancelled: the ${actor}-owned pause was lifted and replaced while the drain was in progress — nothing was restarted`;
   }
   const now = deps.daemonIdentity();
   if (now.running !== begun.daemon.running || (begun.daemon.running && now.generation !== begun.daemon.generation)) {
-    return "restart cancelled: the daemon instance was replaced while the drain was in progress — the newer daemon was left running";
+    return `${actor} cancelled: the daemon instance was replaced while the drain was in progress — the newer daemon was left running`;
   }
   return undefined;
 }
@@ -504,7 +535,7 @@ function restartFenceProblem(
  * {@link pauseSourceToken}; a verb with a space) fails the suite instead of
  * shipping an unprovable pause (#552).
  */
-export const DRAIN_VERBS = ["upgrade", "restart", "setup host"] as const;
+export const DRAIN_VERBS = ["upgrade", "restart", "setup host", "setup"] as const;
 export type DrainVerb = (typeof DRAIN_VERBS)[number];
 
 /**
@@ -556,7 +587,7 @@ export async function pauseAndDrain(
     pauseToken,
     daemon: deps.daemonIdentity(),
   };
-  const stale = () => restartFenceProblem(deps, scope, begun);
+  const stale = () => restartFenceProblem(deps, scope, begun, verb);
   await waitForDrain(
     deps,
     scope,

package/src/verbs/actions.ts

@@ -20,6 +20,13 @@ import { stateDir } from "../config.ts";
 import { ensureMirror } from "../worktree.ts";
 import { launchTransientUnit, readUpgradeJournal } from "../upgrade-journal.ts";
 import { classifyUpgrade } from "../upgrade-verify.ts";
+import {
+  GraphqlBreaker,
+  graphqlBreakerRefusal,
+  isGraphqlSurface,
+  isTransientServer5xx,
+  prUrlParts,
+} from "../tracker/github.ts";
 import type { ProjectConfig, ReleaseShape, RepoTarget } from "../types.ts";
 import type { ActionOutcome, InstallExecution, ReleaseExecution, VerbActions } from "./server.ts";
 
@@ -204,15 +211,32 @@ export function githubVerbActions(
   project: ProjectConfig,
   run: CommandRunner = spawnCommand,
   prepareMirror: MirrorPreparer = ensureMirror,
+  graphqlBreaker?: GraphqlBreaker,
 ): VerbActions {
   const env = (): Record<string, string> => credentialedEnv();
 
   const runGh = async (argv: string[], cwd?: string): Promise<{ argv: string[]; result: CommandRun }> => {
     const full = ["gh", ...argv];
-    return {
-      argv: full,
-      result: await run(full, { env: env(), ...(cwd === undefined ? {} : { cwd }) }),
-    };
+    // The mutation surface rides the same GraphQL endpoint the tracker's
+    // parent/closer checks ride in the pinned gh (2.86): `pr merge`,
+    // `pr update-branch`, `pr edit`, `pr create`. When a transient 5xx has
+    // already proven that surface unavailable — observed by admission or by a
+    // sibling mutation this pass — a mutation must fast-fail WITHOUT spawning
+    // `gh`, exactly like the tracker's candidate checks (#642 comment 4):
+    // attempting a mutation into a known-broken surface is how one provider
+    // outage defeats queue locking. REST-backed commands (`gh api repos/...`,
+    // `gh release create`) keep running: the outage is GraphQL-only.
+    if (graphqlBreaker !== undefined && isGraphqlSurface(argv) && graphqlBreaker.refused()) {
+      return {
+        argv: full,
+        result: { ok: false, stdout: "", stderr: graphqlBreakerRefusal(graphqlBreaker.until) },
+      };
+    }
+    const result = await run(full, { env: env(), ...(cwd === undefined ? {} : { cwd }) });
+    if (!result.ok && graphqlBreaker !== undefined && isGraphqlSurface(argv) && isTransientServer5xx(result.stderr)) {
+      graphqlBreaker.open();
+    }
+    return { argv: full, result };
   };
 
   const gh = async (argv: string[], cwd?: string): Promise<ActionOutcome> => {
@@ -573,7 +597,44 @@ export function githubVerbActions(
 
     createPr: (target, opts) => openRunPr(project, target, opts),
 
-    updatePrBranch: (prUrl) => gh(["pr", "update-branch", prUrl]),
+    updatePrBranch: async (prUrl) => {
+      // The branch refresh rides the REST update-branch endpoint, not `gh pr
+      // update-branch` (#655): `gh pr update-branch` is a GraphQL mutation, so
+      // a selective GraphQL outage made an otherwise mergeable PR unrefreshable
+      // even while REST answered. Both calls here are core REST, so they keep
+      // running while the GraphQL breaker is open.
+      const parts = prUrlParts(prUrl);
+      if (parts === undefined) {
+        return { ok: false, stderr: `could not parse ${prUrl} as a pull request URL` };
+      }
+      const pulls = `repos/${parts.owner}/${parts.repo}/pulls/${parts.number}`;
+      // The stale-head guard needs the exact head the update is bound to. It is
+      // the last observed head of the branch refresh, so a concurrent push is
+      // refused (422) rather than updating an unreviewed head.
+      const head = await runGh(["api", pulls, "--jq", ".head.sha"]);
+      if (!head.result.ok) return failed(head.result, head.argv);
+      const headSha = commitFrom(head.result.stdout);
+      if (headSha === undefined) {
+        return { ok: false, stderr: `${prUrl} returned no full head commit SHA` };
+      }
+      const updated = await gh([
+        "api",
+        "--method",
+        "PUT",
+        `${pulls}/update-branch`,
+        "-f",
+        `expected_head_sha=${headSha}`,
+      ]);
+      if (!updated.ok) return updated;
+      // The endpoint answers 202 Accepted and refreshes the branch
+      // asynchronously, so the head observed for `expected_head_sha` is the
+      // pre-update head. Producing it as `sha` would report a merge at a head
+      // nobody observed; the caller re-reads PR and check state instead.
+      return {
+        ok: true,
+        detail: `requested a base-branch update of ${prUrl} from its observed head ${headSha}; re-read PR and check state before merging`,
+      };
+    },
 
     updatePr: async (prUrl, fields) => {
       const argv = ["pr", "edit", prUrl];
@@ -589,19 +650,6 @@ export function githubVerbActions(
     // and braces on the one operation that cannot be undone.
     mergePr: (prUrl, headSha) => gh(["pr", "merge", prUrl, "--squash", "--match-head-commit", headSha]),
 
-    setLabel: async (issue, label, action) => {
-      const slug = project.tracker.repo;
-      return gh([
-        "issue",
-        "edit",
-        String(issue),
-        "--repo",
-        slug,
-        action === "add" ? "--add-label" : "--remove-label",
-        label,
-      ]);
-    },
-
     release: async (execution: ReleaseExecution): Promise<ActionOutcome> => {
       const slug = repoSlugFor(execution.repo);
       const tag = execution.tag;

package/src/verbs/protocol.ts

@@ -26,6 +26,7 @@ import {
   RELEASE_REASONS,
   RELEASE_SHAPES,
   RESERVED_VERB_FIELDS,
+  REVIEW_REASONS,
   VERB_NAMES,
 } from "../types.ts";
 import type { ReservedVerbField, SessionRole, VerbName, VerbRefusal } from "../types.ts";
@@ -326,6 +327,50 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
       `install authority is the orchestrator's, and this is a ${role} session. ` +
       "A worker session holds no install grant whatever the config says.",
   },
+  conductor_pr_review: {
+    name: "conductor_pr_review",
+    mutating: true,
+    allowedRoles: ["orchestrator"],
+    description:
+      "Return one green, run-owned pull request to its worker with blocking findings (#677). " +
+      "The daemon records the revision durably — findings, exact reviewed head, round number, " +
+      "target run and session — then resumes the SAME OMP session on the existing branch and PR: " +
+      "no close, no reopen, no issue redispatch, no fresh brief. The worker edits and pushes the " +
+      "same branch; a new green head returns to the normal orchestrator review surface. Refused " +
+      "for a stale head, a PR no run of this project owns, a run that is not settled green, or a " +
+      "revision already in flight for the same PR.",
+    args: {
+      prUrl: {
+        type: "string",
+        required: true,
+        description:
+          "Full pull request URL — one a run of this project opened and pushed green. Must be in " +
+          "a routed repository.",
+      },
+      headSha: {
+        type: "string",
+        required: true,
+        description:
+          "The exact reviewed head. The live head must match it and the checks at it must be green.",
+      },
+      findings: {
+        type: "string",
+        required: true,
+        description:
+          "Structured blocking findings. Delivered verbatim to the resumed session; the worker is " +
+          "told to address exactly these and push the same branch.",
+      },
+      reason: {
+        type: "string",
+        required: true,
+        description: `Why this revision, from the closed set: ${REVIEW_REASONS.join(", ")}.`,
+        oneOf: REVIEW_REASONS,
+      },
+      rationale: RATIONALE_ARG,
+    },
+    roleRefusalText: (role) =>
+      `review authority is the orchestrator's; this is a ${role} session, and a worker never returns its own PR for revision.`,
+  },
   conductor_pr_status: {
     name: "conductor_pr_status",
     mutating: false,