@coreplane/switchboard 1.250.0 → 1.252.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;
@@ -453,8 +466,21 @@ export type CoordinatorAction =
        *  submitted description when the record holds one) instead of answering
        *  `none` over stranded work. */
       recover?: { runId: string };
+      /** The pull request the machine has adopted (`state.pr`), when it holds
+       *  one: the child may have worked that pull request's own head branch,
+       *  not the unit's (issue 1799), so when nothing heads the unit's branch
+       *  the bot follows this number and answers the pull request's LIVE state
+       *  — open at a fresh head, merged, or closed (`prClosed`) — never `none`
+       *  over a record fact written minutes earlier. */
+      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 }
@@ -509,6 +535,10 @@ export type PrCheck =
        *  naming where the scope landed is the `already_landed` ending
        *  (agent-ship item 12); absent, the fact is unknown and never claimed. */
       aheadOfBase?: number;
+      /** The action's followed pull request (`pr`) was verified CLOSED
+       *  unmerged: the machine must not brief a review round on it. Absent when
+       *  nothing was followed or the follow could not read the pull request. */
+      prClosed?: boolean;
     }
   | {
       state: "open";
@@ -518,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 };
 
@@ -537,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
@@ -687,6 +770,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
@@ -704,6 +790,10 @@ export interface UnitPipelineInput {
    *  pre-check finds the open pull request still at exactly this head, there is
    *  nothing to code and the attempt starts at the review round. */
   lastPush?: string;
+  /** The runs page base (`<PUBLIC_BASE_URL>/runs`), the plan route's answer:
+   *  the report's pointer at a child's write-up links its run page with it and
+   *  names the run id without it — the machine never reads an environment. */
+  runPageBase?: string;
 }
 
 type Phase =
@@ -732,6 +822,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 {
@@ -864,9 +984,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,
@@ -876,6 +1006,7 @@ function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
     ...(priorReview !== undefined
       ? { prior: { reviewRunId: priorReview, ...(priorCoding !== undefined ? { codingRunId: priorCoding } : {}) } }
       : {}),
+    ...(priorChecks.length > 0 ? { checks: priorChecks } : {}),
   };
 }
 
@@ -935,6 +1066,24 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         type: "pr-check",
         step: `${roundStep(s, p.round)}/pr-check`,
         ...(p.dead !== undefined ? { recover: { runId: p.runId } } : {}),
+        // The adopted pull request rides the check so the bot can follow it
+        // 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 };
@@ -1174,6 +1323,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);
@@ -1207,32 +1513,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
@@ -1286,6 +1566,22 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
         [roundNote(round, "aborted")],
       );
     }
+    // Nothing heads the unit's branch, but the machine holds the round's pull
+    // request (`pr_opened` off the child's record, or an earlier round's
+    // adoption): the child worked on that pull request's own head branch, not
+    // the unit's — a re-issued task in the thread of an existing pull request
+    // (issue 1799). The round HAS its pull request — at round 0 and after a
+    // findings step alike, since the same child keeps repushing that branch
+    // through every later round — so it carries on to the (re-)review at the
+    // head the child pushed through the shared open settle (a findings step
+    // that repushed nothing keeps its abort, item 7), instead of the unit
+    // ending "no pull request" or "closed out from under" over work that
+    // stands. Never over a followed answer that VERIFIED the pull request
+    // closed (`prClosed`): a review briefed on a closed pull request reviews
+    // nothing, so the endings below stand — and are then truthful. Dead
+    // children never reach here: their endings are above.
+    if (s.pr !== undefined && pr.prClosed !== true)
+      return roundOnOpenPr(s, phase, { prNumber: s.pr.number, url: s.pr.url });
     if (round.index === 0) {
       // The scope already landed (agent-ship item 12): the child's handoff
       // names where, and the branch carries no commits over the base — two
@@ -1370,6 +1666,18 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
       [roundNote(round, "aborted")],
     );
   }
+  return roundOnOpenPr(s, phase, pr);
+}
+
+/** The round carried on its open pull request: the pr-check's `open` answer,
+ *  or — when nothing heads the unit's branch — the pull request the machine
+ *  already holds (issue 1799), at the head the child pushed. */
+function roundOnOpenPr(
+  s: UnitPipelineState,
+  phase: Extract<Phase, { at: "pr-check" }>,
+  pr: { prNumber: number; url: string; headSha?: string },
+): Transition {
+  const { round } = phase;
   const head = pr.headSha ?? phase.childHead;
   const next: UnitPipelineState = { ...s, pr: { number: pr.prNumber, url: pr.url } };
   if (round.kind === "findings") {
@@ -1581,6 +1889,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")
@@ -1647,6 +1978,18 @@ function dispositionFor(s: UnitPipelineState, finding: Finding, round: number):
   return undefined;
 }
 
+/** Where a child's write-up lives, for the report's pointer (agent-ship item
+ *  12): the child's own message in the thread is the single copy of the detail
+ *  — posted moments before the unit-end — so the report points at it instead
+ *  of repeating it: the run page when the plan named the base, the run id
+ *  otherwise. Undefined when no run is known to point at. */
+function writeUpPointer(s: UnitPipelineState, kind: RoundKind, runId: string | undefined): string | undefined {
+  if (runId === undefined) return undefined;
+  const base = s.input.runPageBase;
+  const at = base !== undefined ? `${base.replace(/\/+$/, "")}/${encodeURIComponent(runId)}` : `run ${runId}`;
+  return `The ${presetOf(kind)} child's write-up is its own message above in this thread — the single copy of the detail (${at}).`;
+}
+
 /** How the budget went, in the card's words: coding, review, waiting minutes. */
 function budgetSplitLine(spent: ShipBudgetSpent, maxMinutes: number): string {
   const min = (ms: number) => Math.round(ms / MIN);
@@ -1687,6 +2030,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. */
@@ -1697,9 +2048,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(", ")}` : "";
@@ -1711,9 +2072,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}` : "";
@@ -1751,11 +2124,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.
@@ -1765,11 +2140,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
@@ -1779,7 +2154,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
@@ -1802,20 +2179,26 @@ 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}`,
-        e.finalReply,
+        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."
           : undefined,
@@ -1823,22 +2206,32 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
       ]);
     case "aborted":
       return join([
-        e.finalReply,
         e.reason,
+        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([
-        e.finalReply,
+        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.`,
-        e.finalReply ? `Review round's final message:\n\n${e.finalReply}` : undefined,
+        aside(writeUpPointer(s, e.round.kind, s.reviewRunByRound[e.round.index])),
         `⚠️ Ship aborted after ${rounds}.`,
         reissue,
       ]);