omp-conductor 0.17.0 → 0.18.0

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,

package/src/verbs/server.ts

@@ -41,12 +41,14 @@
 import { randomUUID } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
 
-import { resolvePolicy, resolveReleaseGrants } from "../config.ts";
+import { resolvePolicy, resolveReleaseGrants, resolveReview } from "../config.ts";
+import { effectiveLane, laneEcho } from "../admission.ts";
 import { chainEntriesFromDiff, chainViolations } from "../chain-check.ts";
 import { repoSlugFor, type readBaseChain as readBaseChainType } from "../gitops.ts";
 import { releaseRefusal } from "../release-policy.ts";
 import { LIVE_STATES } from "../store.ts";
 import type {
+  IssueComment,
   OpenCloser,
   PrState,
   PrVerification,
@@ -54,6 +56,7 @@ import type {
   ReleaseRequirement,
   ReleaseShape,
   RepoTarget,
+  ReviewReason,
   RunRecord,
   Store,
   Tracker,
@@ -167,7 +170,6 @@ export interface VerbActions {
     fields: { title?: string; body?: string },
   ): Promise<{ ok: true } | { ok: false; stderr: string }>;
   mergePr(prUrl: string, headSha: string): Promise<ActionOutcome>;
-  setLabel(issue: number, label: string, action: "add" | "remove"): Promise<ActionOutcome>;
   release(execution: ReleaseExecution): Promise<ActionOutcome>;
   /**
    * Request the fleet upgrade itself to `version`: refuse when npm does not
@@ -298,6 +300,12 @@ export interface ReleaseFacts {
    * must wait on a process; these clear by themselves on the next sweep.
    */
   unconfirmedMerges?: number;
+  /**
+   * The unsettled runs themselves, routed-repo and issue each, so the refusal
+   * names what is blocking instead of a bare count (#603). Absent when the
+   * caller could not gather them (the plain wording is used then).
+   */
+  blockingRuns?: { repo: string; issue: number }[];
   /** Queue depth, or `undefined` when the tracker could not be read. */
   queueDepth: number | undefined;
   /** Current live-head workflow verdict for the released routed repository. */
@@ -311,7 +319,7 @@ export function releaseRequirementRefusal(
   facts: ReleaseFacts,
 ): string | undefined {
   for (const requirement of requires) {
-    if (requirement === "runs-settled" && facts.unsettledRuns > 0) {
+    if ((requirement === "runs-settled" || requirement === "fleet-runs-settled") && facts.unsettledRuns > 0) {
       // The same blocker reads differently depending on WHY the row is still
       // active: a live worker is the operator's wait, an unconfirmed merge or
       // an unrecorded sweep clears by itself on the next settle pass. The
@@ -328,9 +336,16 @@ export function releaseRequirementRefusal(
       if (open > 0) parts.push(`${open} pull request(s) still open`);
       if (unconfirmed > 0) parts.push(`${unconfirmed} run(s) whose PR merge the settle sweep has not yet recorded`);
       if (remaining > 0) parts.push(`${remaining} run(s) with no merged PR (closed or none yet)`);
+      // Name the runs behind the count so the operator can see at a glance
+      // whether this is the release's own work or someone else's (#603).
+      const blocking =
+        facts.blockingRuns === undefined || facts.blockingRuns.length === 0
+          ? ""
+          : ` — blocking: ${facts.blockingRuns.map((r) => `${r.repo} #${r.issue}`).join(", ")}`;
       return (
-        `policy.release.requires includes runs-settled and ${facts.unsettledRuns} run(s) have not settled` +
-        (parts.length === 0 ? "" : ` — ${parts.join("; ")}`)
+        `policy.release.requires includes ${requirement} and ${facts.unsettledRuns} run(s) have not settled` +
+        (parts.length === 0 ? "" : ` — ${parts.join("; ")}`) +
+        blocking
       );
     }
     if (requirement === "no-open-prs" && facts.openPrs > 0) {
@@ -505,6 +520,7 @@ async function decide(deps: VerbDeps, channel: VerbChannel, raw: unknown): Promi
     (verb === "conductor_pr_merge" ||
       verb === "conductor_pr_update_branch" ||
       verb === "conductor_pr_update" ||
+      verb === "conductor_pr_review" ||
       verb === "conductor_label");
   const stopped =
     spec.mutating && verb !== "conductor_release" && verb !== "conductor_install" && !orchestratorCompletion
@@ -540,6 +556,8 @@ async function decide(deps: VerbDeps, channel: VerbChannel, raw: unknown): Promi
       return releaseVerb(deps, project, channel, args, refuse, allow);
     case "conductor_install":
       return installVerb(deps, project, channel, args, refuse, allow);
+    case "conductor_pr_review":
+      return prReviewVerb(deps, project, channel, args, refuse, allow);
     case "conductor_pr_status":
       return prStatusVerb(deps, project, channel, args, refuse, allow);
   }
@@ -797,7 +815,15 @@ async function prUpdateBranchVerb(
   if (!outcome.ok) {
     return refuse("action-failed", `refused: gh could not update the branch:\n${outcome.stderr}`, target?.issue);
   }
-  return allow(`updated ${prUrl} with its base branch. Re-check its checks before merging.`, outcome.sha, target?.issue);
+  // The REST endpoint answers 202 Accepted: the refresh runs asynchronously, so
+  // this call produces no head SHA and the reply/ledger must not claim one —
+  // the head the action observed is the pre-update guard head, never a result
+  // (#655 review). The caller re-reads PR and check state before merging.
+  return allow(
+    `requested a base-branch update of ${prUrl} from its observed head; PR and check state must be re-read before merging.`,
+    undefined,
+    target?.issue,
+  );
 }
 
 async function prMergeVerb(
@@ -1064,11 +1090,59 @@ async function labelVerb(
   }
 
   const action = args["action"] === "remove" ? "remove" : "add";
-  const outcome = await deps.actions.setLabel(ref.issue, label, action);
-  if (!outcome.ok) {
-    return refuse("action-failed", `refused: the tracker rejected the label change:\n${outcome.stderr}`, ref.issue);
+  // The queue label is the fleet's lock, so it must not ride the GraphQL
+  // surface a provider outage just broke: `gh issue edit` is a GraphQL
+  // mutation in gh 2.86, and #642 comment 4 measured a label withdrawal
+  // refused by a GraphQL 503 leaving two overlapping issues claimable. The
+  // tracker's label methods are core REST with noop classification for the
+  // already-holding end state — the guarded path.
+  try {
+    if (action === "add") {
+      await deps.tracker.addLabel(ref.issue, label);
+    } else {
+      await deps.tracker.removeLabel(ref.issue, label);
+    }
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    return refuse("action-failed", `refused: the tracker rejected the label change:\n${why}`, ref.issue);
   }
-  return allow(`${action === "add" ? "added" : "removed"} ${label} on #${ref.issue}.`, undefined, ref.issue);
+
+  const outcome = `${action === "add" ? "added" : "removed"} ${label} on #${ref.issue}.`;
+  // Adding the queue label is the promotion: the author is asserting the file
+  // lane right now, so the verb echoes the one admission will enforce — the
+  // parsed file list, or the explicit fail-open note (#724). Best-effort: an
+  // unreadable issue or thread must never block the promotion itself (the
+  // label is the point), so a failed read falls back to the plain message.
+  let echo: string | undefined;
+  if (action === "add" && label === project.queueLabel) {
+    echo = await laneEchoForIssue(deps, ref.issue);
+  }
+  return allow(
+    echo === undefined ? outcome : `${outcome} File lane: ${echo}.`,
+    undefined,
+    ref.issue,
+  );
+}
+
+/**
+ * The effective file lane admission will enforce for one issue, as the
+ * one-line echo (#724): the body plus the whole comment thread, the same
+ * inputs `effectiveLane` reads at admission. `undefined` when either read
+ * fails or the tracker cannot produce the issue — the promotion is never
+ * blocked by its own feedback.
+ */
+async function laneEchoForIssue(deps: VerbDeps, issue: number): Promise<string | undefined> {
+  let body: string;
+  let comments: IssueComment[];
+  try {
+    const row = await deps.tracker.getIssue(issue);
+    if (row === undefined) return undefined;
+    body = row.body;
+    comments = await deps.tracker.listComments(issue);
+  } catch {
+    return undefined;
+  }
+  return laneEcho(effectiveLane(body, comments));
 }
 
 async function releaseVerb(
@@ -1151,22 +1225,36 @@ async function releaseVerb(
   // this release by holding. Fail-closed stays fail-closed: a row whose PR
   // state cannot be read is still unsettled, and an unknown PR is still
   // treated as open.
+  //
+  // The run facts are scoped to the released repo (#603): a run in another
+  // routed repo cannot invalidate a tag on this one, so it must not gate this
+  // release. A genuinely suite-wide shape — a pin or manifest that consumes
+  // several repos — opts back into project-wide strictness through the named
+  // `fleet-runs-settled` requirement, which widens the scope to every active
+  // run. `no-open-prs` shares the scope: the branch being released is this
+  // repo's, so an open PR elsewhere is not "against" it either.
+  const fleetWide = policy.release.requires.includes("fleet-runs-settled");
   const wantsRunFacts =
     policy.release.requires.includes("runs-settled") ||
+    fleetWide ||
     policy.release.requires.includes("no-open-prs");
-  let unsettledRuns = active.length;
-  let openPrs = active.filter((r) => r.prUrl !== undefined).length;
+  const scoped = fleetWide ? active : active.filter((r) => r.repo === repoName);
+  let unsettledRuns = scoped.length;
+  let openPrs = scoped.filter((r) => r.prUrl !== undefined).length;
   let liveWorkers: number | undefined;
   let unconfirmedMerges: number | undefined;
+  let blockingRuns: { repo: string; issue: number }[] | undefined;
   if (wantsRunFacts) {
     let unsettled = 0;
     let open = 0;
     let live = 0;
     let unconfirmed = 0;
-    for (const run of active) {
+    const blocking: { repo: string; issue: number }[] = [];
+    for (const run of scoped) {
       if (run.state === "claimed" || run.state === "running") {
         unsettled += 1;
         live += 1;
+        blocking.push({ repo: run.repo, issue: run.issue });
         // A live worker's PR is not yet confirmable; count it as open, the
         // same fail-closed answer the old row-count gave it.
         if (run.prUrl !== undefined) open += 1;
@@ -1175,6 +1263,7 @@ async function releaseVerb(
       // pushed-pending / pushed-green: the worker is finished; the PR decides.
       if (run.prUrl === undefined) {
         unsettled += 1; // nothing to read; the sweep cannot settle it either
+        blocking.push({ repo: run.repo, issue: run.issue });
         continue;
       }
       let pr: PrState | undefined;
@@ -1185,6 +1274,7 @@ async function releaseVerb(
       }
       if (pr === "merged") continue; // settled in fact; not an open PR
       unsettled += 1;
+      blocking.push({ repo: run.repo, issue: run.issue });
       if (pr === "open") open += 1;
       else if (pr === undefined) {
         // Cannot confirm the merge (or its absence): fail closed, and count
@@ -1200,12 +1290,14 @@ async function releaseVerb(
     openPrs = open;
     liveWorkers = live;
     unconfirmedMerges = unconfirmed;
+    blockingRuns = blocking;
   }
   const unmet = releaseRequirementRefusal(policy.release.requires, {
     unsettledRuns,
     openPrs,
     ...(liveWorkers === undefined ? {} : { liveWorkers }),
     ...(unconfirmedMerges === undefined ? {} : { unconfirmedMerges }),
+    ...(blockingRuns === undefined ? {} : { blockingRuns }),
     queueDepth,
     ...(health === undefined ? {} : { baseCheck: health.verdict }),
     ...(health?.verdict === "red" && health.detail !== undefined
@@ -1509,6 +1601,171 @@ async function prUpdateVerb(
   return allow(`updated ${prUrl}.`, undefined, issue);
 }
 
+/**
+ * Return one green, run-owned pull request to its worker with blocking
+ * findings (#677): the transport that replaces the manual close-PR →
+ * comment-on-issue → unblock → continuation dance.
+ *
+ * Everything is recorded durably BEFORE anything is woken: the findings, the
+ * exact reviewed head, the round number, and the target run/session. The wake
+ * itself is the daemon's next dispatch pass (the verb has no handle on the
+ * worker machinery, and the CLI path must behave exactly like the embedded
+ * one), and the run row is reused — same branch, same PR, same attempt, same
+ * session directory — so a revision round never creates a new attempt and
+ * never touches the failed-attempt or continuation budgets.
+ *
+ * The duplicate in-flight guard has two halves: while a revision is queued
+ * but not yet dispatched, the pending `review_revisions` row refuses the
+ * second request atomically inside `claimReviewRevision`; once dispatched,
+ * the run row itself is `running` (claimed from `pushed-green` by the
+ * dispatch pass), which this verb refuses by name.
+ */
+async function prReviewVerb(
+  deps: VerbDeps,
+  project: ProjectConfig,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  const prUrl = String(args["prUrl"]);
+  const headSha = String(args["headSha"]);
+  const findings = String(args["findings"]);
+  const reason = String(args["reason"]) as ReviewReason;
+
+  // The run whose pushed-green row owns the PR — same resolution as merge: the
+  // newest attempt that recorded this PR within the recent-history window. A
+  // PR no run of this project opened (or one outside the routed repos) cannot
+  // be returned to a worker this project can resume.
+  const target = runForPr(deps, project.name, prUrl);
+  if (target === undefined) {
+    return refuse(
+      "pr-not-this-run",
+      `refused: ${prUrl} is not a pull request any run in ${project.name} opened. ` +
+        "A review revision acts on a run-owned PR only.",
+    );
+  }
+  if (!prInProjectRouting(project, prUrl)) {
+    return refuse(
+      "pr-not-this-run",
+      `refused: ${prUrl} is not in ${project.name}'s routed repositories ` +
+        `(${Object.values(project.routing.repos).map(repoSlugFor).join(", ") || "none"}).`,
+      target.issue,
+    );
+  }
+  const issue = target.issue;
+
+  if (findings.trim() === "") {
+    return refuse(
+      "malformed-argument",
+      "refused: conductor_pr_review needs a non-empty findings string — an empty revision returns the worker nothing to fix.",
+      issue,
+    );
+  }
+
+  // The revisable state is a settled green run. Any other state is a worker in
+  // flight (the original run or an earlier revision) or a run whose PR no
+  // longer waits on revision — the detail names the state field that produced
+  // the refusal.
+  if (target.state !== "pushed-green") {
+    const live = target.state === "running" || target.state === "claimed";
+    return refuse(
+      "review-in-flight",
+      `refused: run ${target.id} is ${target.state}, not pushed-green — ${
+        live
+          ? `a worker (the original run or an earlier revision) is still live on ${prUrl}; wait for it to settle before returning it.`
+          : `a review revision starts from a settled green run, and this one is ${target.state}.`
+      }`,
+      issue,
+    );
+  }
+
+  const paused = orchestratorPauseRefusal(deps, channel, target, refuse);
+  if (paused !== undefined) return paused;
+
+  // Exact-head, re-read at request time: the orchestrator reviewed a specific
+  // head, and a PR that moved since is not the thing it reviewed. Same verdict
+  // the merge gate uses, so "green at headSha" here is the same fact the merge
+  // would have required.
+  let verification: PrVerification | undefined;
+  try {
+    verification = await deps.tracker.verifyPr(prUrl, headSha);
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    return refuse(
+      "head-unresolvable",
+      `refused: the live head of ${prUrl} could not be read (${why}).`,
+      issue,
+    );
+  }
+  if (verification === undefined) {
+    return refuse(
+      "head-unresolvable",
+      `refused: the live head of ${prUrl} could not be resolved. Refusing rather than returning a PR you did not re-read.`,
+      issue,
+    );
+  }
+  if (verification.status !== "green") {
+    const stale = verification.status === "failed" && isHeadMismatch(verification.reason);
+    return refuse(
+      stale ? "head-stale" : "checks-not-green",
+      stale
+        ? `refused: ${verification.reason}. You reviewed ${headSha}; that is not what is on the branch now. Re-read the head and re-review.`
+        : `refused: ${prUrl} is not green at ${headSha} — ${verification.reason}. A revision is returned to a green PR only.`,
+      issue,
+    );
+  }
+
+  // The hard bound (#678): the round ceiling is the dispatcher's, not the
+  // orchestrator's to re-read from prose. A PR may be returned at most
+  // `maxRounds` times per lifecycle; at the ceiling this refuses, and the
+  // refusal states the two non-actions that replace a further round — leave
+  // the PR open, record the unresolved findings and escalate once. The same
+  // count `latestReviewRound` drives the renderer's `review-revision N`, so
+  // the bound and the visible round can never disagree.
+  const review = resolveReview(project);
+  if (deps.store.latestReviewRound(project.name, target.id) >= review.maxRounds) {
+    return refuse(
+      "review-round-ceiling",
+      `refused: ${prUrl} has already been through ${review.maxRounds} review round(s) ` +
+        `(project "${project.name}" is ${review.strictness} strictness, ceiling ${review.maxRounds}). ` +
+        "Leave the PR open, record the unresolved findings, and escalate once — a further revision round is not available.",
+      issue,
+    );
+  }
+
+  // Durable, and refused atomically against a concurrent duplicate: the row is
+  // persisted before any wake, and a second request for the same run bumps
+  // into the pending row rather than racing it.
+  const round = deps.store.latestReviewRound(project.name, target.id) + 1;
+  const recorded = deps.store.createReviewRevision({
+    project: project.name,
+    runId: target.id,
+    issue,
+    prUrl,
+    headSha,
+    findings,
+    round,
+    reason,
+    ...(target.sessionFile === undefined ? {} : { sessionFile: target.sessionFile }),
+    requestedAt: deps.now(),
+  });
+  if (recorded === undefined) {
+    return refuse(
+      "review-in-flight",
+      `refused: a review revision is already pending for ${prUrl} (run ${target.id}); exactly one revision is in flight per PR.`,
+      issue,
+    );
+  }
+
+  return allow(
+    `recorded review round ${round} for ${prUrl} at ${headSha}; the daemon will resume run ${target.id}'s session` +
+      `${target.sessionFile === undefined ? "" : ` (${target.sessionFile})`} on its next dispatch pass.`,
+    undefined,
+    issue,
+  );
+}
+
 // ------------------------------------------------------------------ the listener
 
 export interface VerbListener {