omp-conductor 0.17.0 → 0.18.0

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:
    *
@@ -412,8 +413,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 +585,111 @@ 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];
+
+/**
+ * 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
+ * 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 +721,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
@@ -629,8 +765,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> };
@@ -682,6 +821,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
@@ -714,6 +863,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.
@@ -742,7 +901,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}.
    */
@@ -862,6 +1025,12 @@ export const SETTLEMENT_FLAG_KINDS = [
   "assertions-removed",
   /** A named timeout in a test file went up. */
   "test-timeout-raised",
+  /** 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. */
@@ -962,6 +1131,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>;
@@ -1008,6 +1185,12 @@ 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.
@@ -1028,6 +1211,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`.
@@ -1060,6 +1257,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).
    *
@@ -1282,6 +1486,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;
@@ -1312,6 +1522,14 @@ export interface RunRecord {
   /** 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;
   startedAt: number;
   endedAt?: number;
   /** Last failure text, surfaced verbatim in escalations. */
@@ -1364,6 +1582,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"
@@ -1374,8 +1596,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";
@@ -1425,6 +1653,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 +1973,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 +2001,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. */
@@ -1808,6 +2074,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`. */
@@ -2014,6 +2285,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 +2583,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 +2670,19 @@ 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 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

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,