@coreplane/switchboard 1.251.0 → 1.253.0

package/dist/assets/src/core/ship/coordinator.ts

@@ -30,6 +30,7 @@
 // arrive in the input rather than from the agent registry.
 
 import type { ShipRoundOutcome } from "../runEvents.js";
+import { shows, type Verbosity } from "../verbosity.js";
 import type { Handoff, HandoffLanded } from "./handoff.js";
 import { progressOf, renderRenewal, renewalDecision, type PushedHeadFact, type RenewalDecision } from "./renewal.js";
 import type { RunStatus } from "../runRecord.js";
@@ -51,6 +52,7 @@ import {
   carve,
   DEFAULT_GRANT,
   loopPosition,
+  MERGE_WAIT_ASK_MINUTES,
   MINUTE_MS,
   SHIP_WAIT,
   type Carve,
@@ -430,8 +432,19 @@ export type Brief =
       round: number;
       /** The previous review round's run and the coding run that answered its findings, for a re-review. */
       prior?: { reviewRunId: string; codingRunId?: string };
+      /** The previous round's check findings (record 0055): they sit on no
+       *  run's record, so the brief carries them beside `prior` by value. */
+      checks?: Finding[];
     }
-  | { kind: "findings"; unit: string; pr: number; reviewRunId: string };
+  | {
+      kind: "findings";
+      unit: string;
+      pr: number;
+      reviewRunId: string;
+      /** The round's check findings (record 0055), carried by value — the
+       *  review run's record holds only the reviewer's own findings. */
+      checks?: Finding[];
+    };
 
 export interface PrRef {
   number: number;
@@ -462,6 +475,12 @@ export type CoordinatorAction =
       pr?: number;
     }
   | { type: "merge"; step: string; prNumber: number; headSha: string }
+  /** Read the check runs at the reviewed head (record 0055, the round verdict):
+   *  the merge door's own reading, folded into the round. `retry` names the
+   *  failed checks whose one flake re-run the machine is spending: the bot
+   *  re-runs their failed jobs (the CI retry the deploy already uses) instead
+   *  of reading. */
+  | { type: "checks"; step: string; prNumber: number; headSha: string; retry?: string[] }
   /** Wait for the intake's checks-settled event at the approved head, bounded as the fallback. */
   | { type: "wait-checks"; step: string; headSha: string; timeoutMs: number }
   | { type: "sleep"; step: string; ms: number }
@@ -529,6 +548,12 @@ export type PrCheck =
       autoMergeEnabled?: boolean;
       /** The check runs at the head, when the read asked for them (the ending's facts). */
       checks?: CommitChecksFacts;
+      /** GitHub's `mergeable_state`, when the read asked for the facts — `dirty`
+       *  keeps the report from calling a conflicting head merge-ready (item 9). */
+      mergeableState?: string;
+      /** The head's self-declared fix-up commit subjects (`fixup!`/`squash!`/`amend!`),
+       *  when the read asked for the facts — a head carrying one is not in the ready state. */
+      fixupCommits?: string[];
     }
   | { state: "merged"; prNumber: number; url: string; sha: string; mergedAt: string };
 
@@ -548,9 +573,56 @@ export type StepReturn =
   // fired, or a person merged — so the runner merged nothing (`by: other`).
   | { type: "merge"; step: string; outcome: "merged"; by: "other"; sha: string; mergedAt: string; at: number }
   | { type: "merge"; step: string; outcome: "pending" | "refused"; reason: string; at: number }
+  /** The checks read at the reviewed head; `checks` absent means GitHub could
+   *  not be read, which the machine treats as pending (record 0055). A retry
+   *  ask answers `retried` instead: whether the bot dispatched the re-run —
+   *  false means there is nothing to wait for at the unchanged head. */
+  | { type: "checks"; step: string; checks?: RoundChecks; retried?: boolean; at: number }
   | { type: "wait-checks"; step: string; outcome: "event" | "timeout" }
   | { type: "sleep"; step: string };
 
+/** One failed check run at the reviewed head, as the round's checks step reads
+ *  it (record 0055): the name, GitHub's conclusion, the run's URL, and whether
+ *  the bot's classifier suspects a flake — a test timeout or runner stall on a
+ *  shard whose test files the pull request's changed paths never touch. */
+export interface CheckFailure {
+  name: string;
+  conclusion: string;
+  url?: string;
+  flakeSuspect?: boolean;
+}
+
+/** The check runs at the reviewed head as the round's checks step reads them. */
+export interface RoundChecks {
+  total: number;
+  pending: string[];
+  failed: CheckFailure[];
+}
+
+/** A failed check as a finding of the round (record 0055): a finding row like
+ *  a reviewer's — id `check:<name>`, the check's name as the file, severity
+ *  `blocking` so the level in force always counts it, the conclusion and URL
+ *  as the title — so the ledger, the findings brief and the dispositions
+ *  carry it exactly as a reviewer's. */
+export function checkFinding(f: CheckFailure): Finding {
+  return {
+    id: `check:${f.name}`,
+    severity: "blocking",
+    file: f.name,
+    title: `CI check failed (${f.conclusion})${f.url !== undefined ? ` — ${f.url}` : ""}`,
+    check: true,
+  };
+}
+
+/** The check findings of a review round: the rows the checks step appended to
+ *  the round's findings, told apart by provenance — the `check` flag only
+ *  `checkFinding` sets, never the id: a reviewer's id is a free string, and a
+ *  re-review brief names the prior check findings by id, so a reviewer
+ *  plausibly reuses `check:…` in its own verdict — a check finding sits on no
+ *  run's record, so a brief carries them by value. */
+export const checkFindingsOf = (findings: readonly Finding[] | undefined): Finding[] =>
+  (findings ?? []).filter((f) => f.check === true);
+
 /** How one unit's pipeline ended — the truthful vocabulary the ship pipeline
  *  has, plus the merge's own: `merged` by the runner, or found merged (`by:
  *  other` — a person's merge, or an earlier attempt's that died after it, so
@@ -624,7 +696,46 @@ export type UnitEnding =
     }
   | { kind: "no_verdict"; round: RoundRef; reviewRounds: number; finalReply?: string }
   | { kind: "interrupted"; round: RoundRef; runId: string; reviewRounds: number }
-  | { kind: "refused"; refusal: string; message?: string; round: RoundRef; reviewRounds: number };
+  | { kind: "refused"; refusal: string; message?: string; round: RoundRef; reviewRounds: number }
+  /** The unit idles instead of ending (record 0051): with the resolved
+   *  `ship.idleDays` above zero, `end()` wraps an idling kind — every kind but
+   *  the four ended ones (`merged`, `already_landed`, `merge_ready`,
+   *  `refused`) — in this ending: the old kind as `why`, the old kind's
+   *  report unchanged, and what a continuation needs (the renewals the grant
+   *  still holds — unspent: the wake spends one, this plan's fifth unit — the
+   *  head to continue from, the last coding child's run, the spend and its
+   *  handoff). `runId` is absent when the pipeline capped before any coding
+   *  child ran. */
+  | {
+      kind: "idle";
+      why: IdleWhy;
+      /** The ending the idle stands in for, whole: its report is rendered per
+       *  copy at that copy's level — the row's and the board's in full, the
+       *  thread's at the request's verbosity — never once at mapping time. */
+      idled: Exclude<UnitEnding, { kind: "idle" }>;
+      renewalsLeft: number;
+      from?: string;
+      runId?: string;
+      spendUsd: number | null;
+      handoff?: Handoff;
+      round?: RoundRef;
+      reviewRounds: number;
+    };
+
+/** The kinds that idle: every ending but the four ended ones — the unit is
+ *  unfinished (a cap, a stop, an abort, a refused merge, a segment's end) and
+ *  a reply could continue it. `merged`, `already_landed`, `merge_ready` and
+ *  `refused` never idle: the first two are done, merge-ready waits only for a
+ *  person's merge, and a refused child would be refused again. */
+export type IdleWhy = Exclude<UnitEnding["kind"], "idle" | "merged" | "already_landed" | "merge_ready" | "refused">;
+
+const NEVER_IDLES: ReadonlySet<UnitEnding["kind"]> = new Set([
+  "idle",
+  "merged",
+  "already_landed",
+  "merge_ready",
+  "refused",
+]);
 
 /** What a transition tells the driver beyond the next action: a round boundary
  *  the card draws (`shipRoundHeader`) and the run stream records, and the end. */
@@ -698,6 +809,9 @@ export interface UnitPipelineInput {
    *  it yet: the renewal decision is the segment's end, not this unit's. */
   grant?: Grant;
   grantSource?: GrantSource;
+  /** The request's verbosity (routing-and-config item 28): the level the
+   *  thread's copy of the unit report is rendered at; absent reads as quiet. */
+  verbosity?: Verbosity;
   /** The segment this pipeline runs (decision 0046, Renewal): absent for the
    *  first; a renewal's carries its number, the renewals spent before it, the
    *  session's spend so far, the sha it continues from and the previous
@@ -708,6 +822,11 @@ export interface UnitPipelineInput {
    *  `plan` with an id and no `path` — whose unit runs in the requesting
    *  thread and is re-issued with the request's own text, never a plan path. */
   generated: boolean;
+  /** The idle flag (record 0051; agent-ship item 8): `ship.idleDays` as the
+   *  ship fork resolved it onto the instance — above zero, an idling kind ends
+   *  `idle` instead; zero or absent is today's behavior byte for byte. The
+   *  wait itself lands with this plan's fifth unit. */
+  idleDays?: number;
   /** Resume at review: an open pull request of ship's own the requester named. */
   resume?: { pr: number; headSha?: string; url?: string };
   /** The head the previous attempt's coding child last pushed (a
@@ -747,6 +866,36 @@ type Phase =
     }
   | { at: "merge"; pr: PrRef; headSha: string; n: number; since: number; waitMs: number }
   | { at: "merge-wait"; pr: PrRef; headSha: string; n: number; since: number; waitMs: number }
+  /** The round's checks step (record 0055): the check runs at the reviewed head
+   *  are read after an approve settles, before merge_ready or the merge door.
+   *  `graced`: a head with no check reported has had its one-chunk grace;
+   *  `retried`: the one flake re-run is spent; `retry` names the failed checks
+   *  the next ask re-runs instead of reading. */
+  | {
+      at: "checks";
+      round: RoundRef;
+      prNumber: number;
+      headSha: string;
+      n: number;
+      since: number;
+      waitMs: number;
+      graced: boolean;
+      retried: boolean;
+      retry?: string[];
+    }
+  /** Waiting on `checks-settled-<head>` between two checks reads, in the merge
+   *  wait's own chunks — the intake wakes the machine when the head settles. */
+  | {
+      at: "checks-wait";
+      round: RoundRef;
+      prNumber: number;
+      headSha: string;
+      n: number;
+      since: number;
+      waitMs: number;
+      graced: boolean;
+      retried: boolean;
+    }
   | { at: "ended" };
 
 export interface UnitPipelineState {
@@ -771,6 +920,10 @@ export interface UnitPipelineState {
   readonly findingsRunByRound: Readonly<Record<number, string>>;
   /** The last coding run (round 0's child or a findings step's): its record carries the unit's handoff. */
   readonly lastCodingRunId?: string;
+  /** The head the last coding child left the branch at, and its handoff — the
+   *  continuation facts an `idle` ending carries (record 0051). */
+  readonly lastChildHead?: string;
+  readonly lastCodingHandoff?: Handoff;
   /** How the budget went so far, accrued as each answer moves the clock. */
   readonly spentMs: ShipBudgetSpent;
   /** The session's dollars so far: the input's from earlier segments plus each
@@ -879,9 +1032,19 @@ function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
     };
   }
   const pr = s.pr!.number;
-  if (round.kind === "findings") return { kind: "findings", unit, pr, reviewRunId: s.reviewRunByRound[round.index]! };
+  if (round.kind === "findings") {
+    const checks = checkFindingsOf(s.findingsByRound[round.index]);
+    return {
+      kind: "findings",
+      unit,
+      pr,
+      reviewRunId: s.reviewRunByRound[round.index]!,
+      ...(checks.length > 0 ? { checks } : {}),
+    };
+  }
   const priorReview = s.reviewRunByRound[round.index - 1];
   const priorCoding = s.findingsRunByRound[round.index - 1];
+  const priorChecks = checkFindingsOf(s.findingsByRound[round.index - 1]);
   return {
     kind: "review",
     unit,
@@ -891,6 +1054,7 @@ function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
     ...(priorReview !== undefined
       ? { prior: { reviewRunId: priorReview, ...(priorCoding !== undefined ? { codingRunId: priorCoding } : {}) } }
       : {}),
+    ...(priorChecks.length > 0 ? { checks: priorChecks } : {}),
   };
 }
 
@@ -954,6 +1118,21 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         // when nothing heads the unit's branch (issue 1799).
         ...(s.pr !== undefined ? { pr: s.pr.number } : {}),
       };
+    case "checks":
+      return {
+        type: "checks",
+        step: `${roundStep(s, p.round)}/checks/${p.n}`,
+        prNumber: p.prNumber,
+        headSha: p.headSha,
+        ...(p.retry !== undefined ? { retry: p.retry } : {}),
+      };
+    case "checks-wait":
+      return {
+        type: "wait-checks",
+        step: `${roundStep(s, p.round)}/checks/wait/${p.n}`,
+        headSha: p.headSha,
+        timeoutMs: Math.max(MIN, Math.min(MERGE_WAIT_CHUNK_MS, p.waitMs - (s.clock - p.since))),
+      };
     case "merge":
       return { type: "merge", step: `${unit}/merge/${p.n}`, prNumber: p.pr.number, headSha: p.headSha };
     case "merge-wait":
@@ -986,7 +1165,55 @@ function addSpend(sum: number | null, cost: number | null | undefined): number |
 }
 
 function end(s: UnitPipelineState, ending: UnitEnding, notes: CoordinatorNote[] = []): Transition {
-  return { state: { ...s, phase: ENDED, ending }, notes: [...notes, { type: "ended", ending }] };
+  const idled = idleEnding(s, ending);
+  const final = idled ?? ending;
+  return { state: { ...s, phase: ENDED, ending: final }, notes: [...notes, { type: "ended", ending: final }] };
+}
+
+/** The idle mapping (record 0051; agent-ship item 8): with the input's
+ *  `idleDays` above zero an idling kind ends `idle` — the old kind as `why`,
+ *  the old ending itself for the report, and the continuation facts off the state
+ *  (a `continued` ending's own where it carries them). At zero, undefined:
+ *  every ending is byte for byte today's. The round notes keep the old kind's
+ *  outcome — the row and the card say what happened. */
+function idleEnding(s: UnitPipelineState, ending: UnitEnding): Extract<UnitEnding, { kind: "idle" }> | undefined {
+  if ((s.input.idleDays ?? 0) <= 0) return undefined;
+  if (NEVER_IDLES.has(ending.kind)) return undefined;
+  const old = ending as Exclude<UnitEnding, { kind: "idle" | "merged" | "already_landed" | "merge_ready" | "refused" }>;
+  const grant = s.input.grant ?? DEFAULT_GRANT;
+  // Unspent: an idle spends no renewal — the wake's segment does (this plan's
+  // fifth unit) — so the row says what the grant still holds.
+  const renewalsLeft = Math.max(0, grant.renewals - (s.input.session?.renewalsSpent ?? 0));
+  // The head to continue from: a segment's own; a review_pending's reviewed
+  // head — the pull request's, known even when the coding record carried none,
+  // so the re-issue's resume-at-review fact survives the idle; else the last
+  // coding child's recorded head.
+  const from =
+    old.kind === "continued"
+      ? old.from
+      : old.kind === "review_pending"
+        ? (old.headSha ?? s.lastChildHead)
+        : s.lastChildHead;
+  // The last coding child's run: a segment's own, a dead coding child's own —
+  // a review child that died names nothing here, the coding run before it does.
+  const runId =
+    old.kind === "continued" || (old.kind === "interrupted" && old.round.kind !== "review")
+      ? old.runId
+      : s.lastCodingRunId;
+  const handoff = old.kind === "continued" ? old.handoff : s.lastCodingHandoff;
+  const round = "round" in old ? old.round : undefined;
+  return {
+    kind: "idle",
+    why: old.kind,
+    idled: old,
+    renewalsLeft,
+    ...(from !== undefined ? { from } : {}),
+    ...(runId !== undefined ? { runId } : {}),
+    spendUsd: s.spendUsd,
+    ...(handoff !== undefined ? { handoff } : {}),
+    ...(round !== undefined ? { round } : {}),
+    reviewRounds: s.reviewRounds,
+  };
 }
 
 /** A gated finding as the gate note names it: `F1 (minor)`. */
@@ -1059,6 +1286,9 @@ function settleCoding(
   let next: UnitPipelineState = {
     ...s,
     spendUsd: addSpend(s.spendUsd, facts.costUsd),
+    // The continuation facts an idle ending reads off the state (record 0051).
+    ...(facts.headSha !== undefined ? { lastChildHead: facts.headSha } : {}),
+    ...(facts.handoffLists !== undefined ? { lastCodingHandoff: facts.handoffLists } : {}),
     ...(facts.pr !== undefined ? { pr: { number: facts.pr.number, url: facts.pr.url } } : {}),
     ...(round.kind === "findings" && facts.dispositions !== undefined
       ? {
@@ -1192,6 +1422,163 @@ function settleReview(
         );
       return enterRound(next, { index: round.index, kind: "findings" }, notes);
     }
+    // The round verdict (record 0055): the approve is joined with the check
+    // runs at the reviewed head before merge_ready or the merge door — the
+    // checks step reads them and a failed one becomes a finding of the round.
+    return enterChecks(next, round, notes);
+  }
+  // request_changes: the verdict settled (and posted) — now a stop
+  // short-circuits the findings step, naming the review standing on the pull request.
+  if (mode !== undefined)
+    return end(
+      next,
+      {
+        kind: "stopped",
+        mode,
+        round,
+        reviewRounds: next.reviewRounds,
+        ...(facts.finalReply !== undefined ? { finalReply: facts.finalReply } : {}),
+        ...(facts.reviewPosted === true ? { postedReview: true } : {}),
+      },
+      notes,
+    );
+  if (next.reviewRounds >= next.input.caps.maxRounds)
+    return end(
+      next,
+      { kind: "round_cap", maxRounds: next.input.caps.maxRounds, reviewRounds: next.reviewRounds },
+      notes,
+    );
+  // The findings step (agent-ship item 7): the review's findings dispatched into
+  // the unit thread as a coding run, under the review round's index. A run live
+  // there is a person's (this machine awaited its own child's end), so the
+  // spawn answers busy and the step waits under the unit's clock like any round.
+  return enterRound(next, { index: round.index, kind: "findings" }, notes);
+}
+
+/** The round's checks step (record 0055): after an approve settles, the check
+ *  runs at the reviewed head are read with the merge door's own reading and
+ *  folded into the round verdict. With no reviewed head known the step is
+ *  skipped as the merge step's guard is, and the unit ends as today. The wait
+ *  on a pending head is bounded by the merge wait's own ask, clipped to the
+ *  pipeline's remainder. */
+function enterChecks(s: UnitPipelineState, round: RoundRef, notes: CoordinatorNote[]): Transition {
+  const headSha = normalizeHead(s.lastReviewHead);
+  const pr = s.pr;
+  if (headSha === undefined || pr === undefined) return approveOutcome(s, notes);
+  const waitMs = Math.max(MIN, Math.min(MERGE_WAIT_ASK_MINUTES * MIN, remainingMs(s)));
+  return {
+    state: {
+      ...s,
+      phase: {
+        at: "checks",
+        round,
+        prNumber: pr.number,
+        headSha,
+        n: 1,
+        since: s.clock,
+        waitMs,
+        graced: false,
+        retried: false,
+      },
+    },
+    notes,
+  };
+}
+
+/** What the checks step answered, folded into the round (record 0055). Pure
+ *  over the phase: a retry ask waits for the head to settle and reads again;
+ *  an unreadable or pending head waits a chunk inside the step's ask and then
+ *  proceeds — the ending's facts read names what is still pending; a head with
+ *  no check reported waits one chunk of grace and never more; a failed check
+ *  becomes a check finding under a round note of its own and the findings step
+ *  runs as for any changes-requested round — never merge_ready, never the
+ *  merge door; a green head proceeds with no wait added. */
+function settleChecks(
+  s: UnitPipelineState,
+  p: Extract<Phase, { at: "checks" }>,
+  checks: RoundChecks | undefined,
+  retried?: boolean,
+): Transition {
+  const { round } = p;
+  const wait = (over: Partial<Extract<Phase, { at: "checks-wait" }>>): Transition => ({
+    state: {
+      ...s,
+      phase: {
+        at: "checks-wait",
+        round,
+        prNumber: p.prNumber,
+        headSha: p.headSha,
+        n: p.n,
+        since: p.since,
+        waitMs: p.waitMs,
+        graced: p.graced,
+        retried: p.retried,
+        ...over,
+      },
+    },
+    notes: [],
+  });
+  // The retry ask. Dispatched: wait for the head to settle, then read again;
+  // a second failure is the finding. NOT dispatched (`retried: false` — no
+  // re-runnable run behind the checks, or GitHub refused): the one re-run is
+  // spent all the same — the machine never asks twice — but nothing changes
+  // at the head, so the checks are read again at once instead of waiting on a
+  // settle event that never comes, and the failure becomes the finding.
+  if (p.retry !== undefined) {
+    if (retried === false) {
+      const { retry: _retry, ...read } = p;
+      return { state: { ...s, phase: { ...read, n: p.n + 1, retried: true } }, notes: [] };
+    }
+    return wait({ retried: true });
+  }
+  // GitHub unreadable answers as pending and is re-read at the chunk's end
+  // (record 0055); a head still pending or unreadable at the ask's end
+  // proceeds — the ending's facts read names what is still pending, and the
+  // merge door (under `merge: runner`) is the guard that never merges over it.
+  if (checks === undefined || checks.pending.length > 0) {
+    if (s.clock - p.since >= p.waitMs) return approveOutcome(s, []);
+    return wait({});
+  }
+  if (checks.failed.length > 0) {
+    // The flake rule (record 0055): a suspected flake — a test timeout or
+    // runner stall on a shard whose test files the pull request's changed
+    // paths never touch — is re-run once before it becomes a finding. One
+    // real failure among them makes the round's answer already known, so the
+    // re-run is spent only when every failure is a suspect.
+    if (!p.retried && checks.failed.every((f) => f.flakeSuspect === true))
+      return {
+        state: { ...s, phase: { ...p, n: p.n + 1, retry: checks.failed.map((f) => f.name) } },
+        notes: [],
+      };
+    const findings = [...(s.findingsByRound[round.index] ?? []), ...checks.failed.map(checkFinding)];
+    const next: UnitPipelineState = {
+      ...s,
+      findingsByRound: { ...s.findingsByRound, [round.index]: findings },
+    };
+    // The failed checks get a round note of their own (record 0055) — never
+    // the parser-mismatch gate — and the findings step runs as for any
+    // changes-requested round: dispositions, a fix round, a re-review.
+    const notes: CoordinatorNote[] = [roundNote(round, "checks_failed")];
+    if (next.reviewRounds >= next.input.caps.maxRounds)
+      return end(
+        next,
+        { kind: "round_cap", maxRounds: next.input.caps.maxRounds, reviewRounds: next.reviewRounds },
+        notes,
+      );
+    return enterRound(next, { index: round.index, kind: "findings" }, notes);
+  }
+  // No check reported at the head: one chunk of grace — the first check starts
+  // within minutes where CI exists — then the round proceeds, so a repository
+  // without CI costs one chunk per round and never idles (record 0055).
+  if (checks.total === 0 && !p.graced) return wait({ graced: true });
+  // Green (or none reported after the grace): today's path, no wait added.
+  return approveOutcome(s, []);
+}
+
+/** An approve past the checks read: merge_ready for a person, the merge door
+ *  under `merge: runner` — the tail the round verdict guards (record 0055). */
+function approveOutcome(next: UnitPipelineState, notes: CoordinatorNote[]): Transition {
+  {
     const pr = next.pr!;
     if (next.input.merge !== "runner")
       return end(next, { kind: "merge_ready", pr, reviewRounds: next.reviewRounds }, notes);
@@ -1225,32 +1612,6 @@ function settleReview(
       notes,
     };
   }
-  // request_changes: the verdict settled (and posted) — now a stop
-  // short-circuits the findings step, naming the review standing on the pull request.
-  if (mode !== undefined)
-    return end(
-      next,
-      {
-        kind: "stopped",
-        mode,
-        round,
-        reviewRounds: next.reviewRounds,
-        ...(facts.finalReply !== undefined ? { finalReply: facts.finalReply } : {}),
-        ...(facts.reviewPosted === true ? { postedReview: true } : {}),
-      },
-      notes,
-    );
-  if (next.reviewRounds >= next.input.caps.maxRounds)
-    return end(
-      next,
-      { kind: "round_cap", maxRounds: next.input.caps.maxRounds, reviewRounds: next.reviewRounds },
-      notes,
-    );
-  // The findings step (agent-ship item 7): the review's findings dispatched into
-  // the unit thread as a coding run, under the review round's index. A run live
-  // there is a person's (this machine awaited its own child's end), so the
-  // spawn answers busy and the step waits under the unit's clock like any round.
-  return enterRound(next, { index: round.index, kind: "findings" }, notes);
 }
 
 /** The unit's ending when its pull request is found merged — by a person, or
@@ -1627,6 +1988,29 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
     }
     case "pr-check":
       return settlePrCheck(clocked, p, (ret as Extract<StepReturn, { type: "pr-check" }>).pr);
+    case "checks": {
+      const r = ret as Extract<StepReturn, { type: "checks" }>;
+      return settleChecks(clocked, p, r.checks, r.retried);
+    }
+    case "checks-wait":
+      // The event fired or the chunk elapsed either way the head is read again.
+      return {
+        state: {
+          ...s,
+          phase: {
+            at: "checks",
+            round: p.round,
+            prNumber: p.prNumber,
+            headSha: p.headSha,
+            n: p.n + 1,
+            since: p.since,
+            waitMs: p.waitMs,
+            graced: p.graced,
+            retried: p.retried,
+          },
+        },
+        notes: [],
+      };
     case "merge": {
       const r = ret as Extract<StepReturn, { type: "merge" }>;
       if (r.outcome === "merged")
@@ -1745,6 +2129,14 @@ export interface MergeReadyFacts {
   merged?: { sha: string; mergedAt: string };
   /** The check runs at the approved head as the merge door reads them (record 0055). */
   checks?: CommitChecksFacts;
+  /** GitHub's `mergeable_state` for the pull request — `dirty` is a conflict
+   *  with the base, and the report says so instead of "merge-ready", exactly
+   *  as the merge door refuses it before reading the checks (agent-ship item 9). */
+  mergeableState?: string;
+  /** The subjects of the head's commits that mark themselves as fix-ups
+   *  (git's autosquash prefixes `fixup!`, `squash!`, `amend!`): a head
+   *  carrying one is by its own words not in the ready state. */
+  fixupCommits?: string[];
 }
 
 /** The check runs at one commit: how many, which still run, which failed. */
@@ -1755,9 +2147,19 @@ export interface CommitChecksFacts {
 }
 
 /** The merge-ready report's headline is a claim about the approved head
- *  (record 0055): a failed check is never called merge-ready, a pending one
- *  is named, green is said, and without the fact the line is unchanged. */
-function mergeReadyHeadline(rounds: string, url: string, checks: CommitChecksFacts | undefined): string {
+ *  (record 0055, agent-ship item 9): a head that conflicts with its base is
+ *  never called merge-ready and neither is one carrying an unsquashed fix-up
+ *  commit — the ready state is read beside the checks, in the merge door's
+ *  order (the conflict first) — then a failed check is never called
+ *  merge-ready, a pending one is named, green is said, and without any fact
+ *  the line is unchanged. */
+function mergeReadyHeadline(rounds: string, url: string, base: string, facts: MergeReadyFacts | undefined): string {
+  if (facts?.mergeableState === "dirty")
+    return `⚠️ Approved but not merge-ready after ${rounds}: ${url} — the head conflicts with \`${base}\`: rebase onto \`${base}\`, push, and re-review. The approved work stands.`;
+  const fixups = facts?.fixupCommits ?? [];
+  if (fixups.length > 0)
+    return `⚠️ Approved but not merge-ready after ${rounds}: ${url} — ${fixups.length} unsquashed fix-up commit${fixups.length === 1 ? "" : "s"} on the head (${fixups.join("; ")}): squash into the unit's commit, push, and re-review.`;
+  const checks = facts?.checks;
   if (checks === undefined) return `✅ Merge-ready after ${rounds}: ${url}`;
   if (checks.failed.length > 0) {
     const pending = checks.pending.length > 0 ? `; pending: ${checks.pending.join(", ")}` : "";
@@ -1769,9 +2171,21 @@ function mergeReadyHeadline(rounds: string, url: string, checks: CommitChecksFac
   return `✅ Merge-ready after ${rounds}: ${url} — ${checks.total} check${checks.total === 1 ? "" : "s"} green at the approved head.`;
 }
 
-export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts): string {
+export function renderUnitReport(
+  s: UnitPipelineState,
+  facts?: MergeReadyFacts,
+  /** The level the report speaks at (routing-and-config item 28). The default
+   *  is the full report — the row's and the board's copy; the thread's copy is
+   *  rendered at the request's level, where the asides about the machinery
+   *  (the level in force, the grant, the write-up pointer, the budget split,
+   *  a segment boundary) are `verbose` and the outcome, the verdict, the
+   *  findings left below the gate, the declined ones and what to do next are
+   *  everyone's. */
+  verbosity: Verbosity = "verbose",
+): string {
   const e = s.ending;
   if (!e) return "";
+  const aside = (line: string | undefined) => (shows(verbosity, "verbose") ? line : undefined);
   const rounds = `${e.reviewRounds} review round${e.reviewRounds === 1 ? "" : "s"}`;
   const prUrl = s.pr?.url;
   const prLine = prUrl ? ` PR: ${prUrl}` : "";
@@ -1809,11 +2223,13 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
       return [
         `✅ Merged after ${rounds}: ${e.pr.url} (squash \`${e.sha.slice(0, 7)}\`) — merged by the plan runner under \`plan:merge\`: the review approved at this head and the guards were green.`,
         verdictLine,
-        levelLine,
-        grantLine,
-        ...(skippedLine ? [skippedLine] : []),
+        aside(levelLine),
+        aside(grantLine),
+        skippedLine,
         declinedLine,
-      ].join("\n");
+      ]
+        .filter(Boolean)
+        .join("\n");
     case "already_landed":
       // No compare link, no renewal line, no re-issue prompt: there was
       // nothing to ship, so none of them has a question to answer.
@@ -1823,11 +2239,11 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
         // A merge that already happened outranks the checks: there is no head left to gate.
         facts?.merged
           ? `✅ Merge-ready after ${rounds}: ${e.pr.url}`
-          : mergeReadyHeadline(rounds, e.pr.url, facts?.checks),
+          : mergeReadyHeadline(rounds, e.pr.url, s.input.base, facts),
         verdictLine,
-        levelLine,
-        grantLine,
-        ...(skippedLine ? [skippedLine] : []),
+        aside(levelLine),
+        aside(grantLine),
+        skippedLine,
         declinedLine,
         // What the driver read at the approved head when it composed this
         // ending (agent-ship item 9): a merge that already happened is named
@@ -1837,7 +2253,9 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
           : facts?.autoMergeEnabled
             ? "Auto-merge is on for this pull request: the approval merges it once checks pass."
             : "Remaining gate: a person's merge — the runner merges only when the instance's `merge` field says runner, and ship never approves.",
-      ].join("\n");
+      ]
+        .filter(Boolean)
+        .join("\n");
     case "merge_refused":
       // The approved work is on the branch, so the remedy is a person's hand
       // merge, never a re-run: a seeded plan re-issued afterwards finds the
@@ -1860,23 +2278,25 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
     case "wall_clock_cap":
       return join([
         `🧢 Ship stopped at a cap: the remaining pipeline time (~${Math.max(0, Math.round(e.remainingMs / MIN))} min of the ${s.input.caps.maxMinutes}-minute budget) cannot hold another round${e.refused ? ` (the ${e.refused.round} round would get ${e.refused.minutes} min, under its floor of ${e.refused.floor})` : ""} — no approval after ${rounds}.${prLine}`,
-        budgetSplitLine(e.spent, s.input.caps.maxMinutes),
+        aside(budgetSplitLine(e.spent, s.input.caps.maxMinutes)),
         splitReport(s),
         reissue,
       ]);
     case "review_pending":
       return join([
         `⏳ Review pending: the coding child shipped ${e.pr.url}${e.headSha !== undefined ? ` (head \`${e.headSha.slice(0, 7)}\`)` : ""} but the remaining pipeline time cannot hold the review round — the work stands, only the review is missing. The next attempt starts at the review round while the pull request still heads at the child's own last push.`,
-        budgetSplitLine(e.spent, s.input.caps.maxMinutes),
+        aside(budgetSplitLine(e.spent, s.input.caps.maxMinutes)),
         reissue,
       ]);
     case "stopped":
       return join([
         `${e.mode === "hard" ? "⛔" : "⏹"} Ship stopped by operator (${e.mode} stop) after ${rounds}.${prLine}`,
-        writeUpPointer(
-          s,
-          e.round.kind,
-          e.round.kind === "review" ? s.reviewRunByRound[e.round.index] : s.lastCodingRunId,
+        aside(
+          writeUpPointer(
+            s,
+            e.round.kind,
+            e.round.kind === "review" ? s.reviewRunByRound[e.round.index] : s.lastCodingRunId,
+          ),
         ),
         e.postedReview
           ? "ℹ️ A changes-requested review was posted this round before the stop — its findings stand on the PR."
@@ -1886,25 +2306,31 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
     case "aborted":
       return join([
         e.reason,
-        writeUpPointer(
-          s,
-          e.round?.kind ?? "coding",
-          e.round?.kind === "review" ? s.reviewRunByRound[e.round.index] : s.lastCodingRunId,
+        aside(
+          writeUpPointer(
+            s,
+            e.round?.kind ?? "coding",
+            e.round?.kind === "review" ? s.reviewRunByRound[e.round.index] : s.lastCodingRunId,
+          ),
         ),
         e.renewal !== undefined ? `🔁 Not renewed: ${e.renewal.line}.` : undefined,
         `⚠️ Ship aborted after ${rounds}.`,
         reissue,
       ]);
     case "continued":
+      // A segment boundary is the runner continuing — an acknowledgement, verbose
+      // material (item 28); the thread's copy is empty at quiet, and the row keeps
+      // no ending either way (decision 0046).
+      if (!shows(verbosity, "verbose")) return "";
       return join([
         writeUpPointer(s, e.round.kind, e.runId),
         `🔁 Segment ${e.segment - 1} ended at its lease with the unit unfinished — ${e.line}. Segment ${e.segment} opens in this thread${e.from !== undefined ? ` from \`${e.from.slice(0, 7)}\`` : ""} under a fresh ${s.input.caps.maxMinutes}-minute lease, with this segment's write-up as its request; ${e.renewalsLeft} renewal${e.renewalsLeft === 1 ? "" : "s"} remain${e.spendUsd !== null ? `, $${e.spendUsd.toFixed(2)} spent so far` : ""}.`,
-        budgetSplitLine(e.spent, s.input.caps.maxMinutes),
+        aside(budgetSplitLine(e.spent, s.input.caps.maxMinutes)),
       ]);
     case "no_verdict":
       return join([
         `⚠️ Review round ${e.round.index} ended without a submitted verdict (budget, refusal, or stop) — ship never converts that into a request for changes, so no findings step ran.`,
-        writeUpPointer(s, e.round.kind, s.reviewRunByRound[e.round.index]),
+        aside(writeUpPointer(s, e.round.kind, s.reviewRunByRound[e.round.index])),
         `⚠️ Ship aborted after ${rounds}.`,
         reissue,
       ]);
@@ -1915,5 +2341,9 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
         `🚫 The ${presetOf(e.round.kind)} child of round ${e.round.index} was refused by the authorize stage (${e.refusal})${e.message ? `: ${e.message}` : ""} — every child is authorized as the requesting user, so the pipeline ends here.`,
         reissue,
       ]);
+    case "idle":
+      // The old kind's sentence at this copy's level — the report is unchanged
+      // by the idle at every verbosity (record 0051).
+      return renderUnitReport({ ...s, ending: e.idled }, facts, verbosity);
   }
 }