@coreplane/switchboard 1.255.0 → 1.257.0

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

@@ -41,6 +41,7 @@ import {
   findingsAtOrAbove,
   formatFinding,
   isAddressSeverity,
+  severityCounts,
   type AddressSeverity,
   type AddressSeveritySource,
   type Finding,
@@ -76,21 +77,70 @@ export interface ShipCaps {
  *  rounds that must still follow, capped at the preset's ask, refused under the
  *  round's floor. Nothing here holds a reserve of its own. */
 
-/** What a ship pipeline's thread and card say when the bot died under it (run-
- *  history item 36): the work it did stands on GitHub with nobody driving it,
- *  so the note names the PR when one was opened and the exact re-issue that
- *  continues the loop — the same entry the preflight's resume-at-review takes
- *  (agent-ship item 10). Without a PR the task itself is the re-issue: round 0
- *  runs again on the pipeline's own deterministic branch. The coordinator says
- *  the same when a child of its closed `interrupted`. */
-export function shipInterruptedNote(prUrl?: string): string {
+/** What actually ended an interrupted child, from the ledger that saw it
+ *  (issue 1876): the ending's sentence names the cause in the user's nouns —
+ *  the bot restarted, the resident container was replaced, the sandbox failed
+ *  — never "the bot restarted" for a site three causes reach. Read off the
+ *  child's record by the bot's `read-record` (`child_interrupted` / the resume
+ *  notes) and carried on the `interrupted` ending; absent when the record
+ *  named none. */
+export type InterruptionCause = "bot_restart" | "container_replaced" | "sandbox_fault";
+
+/** What a ship pipeline's thread and card say when its child died under it
+ *  (run-history item 36): the work it did stands on GitHub with nobody driving
+ *  it, so the note names the actual cause (issue 1876 — the site is reached by
+ *  a bot restart, a resident container replacement and a sandbox fault, and
+ *  only the ledger's word picks one; with none the sentence claims no cause),
+ *  the PR when one was opened and the exact re-issue that continues the loop —
+ *  the same entry the preflight's resume-at-review takes (agent-ship item 10).
+ *  Without a PR the task itself is the re-issue: round 0 runs again on the
+ *  pipeline's own deterministic branch. A child whose container was replaced
+ *  resumes from its request by itself (issue 1903) and the pipeline keeps
+ *  waiting — this note is written only when that resume failed or no resume
+ *  applied. */
+/** The cause an interruption's recorded words name (issue 1876): the ledger
+ *  that saw the roll wrote them — the relaunch refusals and the lost-workspace
+ *  notes name the replaced container, the sandbox executor's wordings the
+ *  sandbox, the boot gap names the restart — and the ending's sentence repeats
+ *  the cause, never "the bot restarted" for words that say otherwise. Each
+ *  pattern is anchored on the exact phrases those ledgers write —
+ *  `src/core/harness/contract.ts` and `src/core/dispatch/relaunch.ts`
+ *  ("container replaced under the run", "replacement container"),
+ *  `src/core/dispatch/reattach.ts` ("workspace lost", "could not be
+ *  re-attached"), `src/execution/sandboxLifecycle.ts` and the sandbox worker's
+ *  failures ("sandbox recycled", "sandbox worker", "sandbox exec"),
+ *  `src/core/boot.ts` and the resume notes ("bot restarted", the deploy
+ *  hand-off's "next generation") — so an unrelated word ("regenerating…", a
+ *  reason merely mentioning a sandbox path) cannot classify. Unrecognized
+ *  words are no cause: the sentence then claims none. */
+export function interruptionCauseOfWords(words: string): InterruptionCause | undefined {
+  if (
+    /\bcontainer (?:was )?replaced\b|\breplac(?:ed|ement) container\b|\bworkspace lost\b|\bcould not be re-attached\b/i.test(
+      words,
+    )
+  )
+    return "container_replaced";
+  if (/\bsandbox (?:recycled|worker|exec|runtime)\b/i.test(words)) return "sandbox_fault";
+  if (/\bbot restart(?:ed|s)?\b|\b(?:next|previous|another) generation\b/i.test(words)) return "bot_restart";
+  return undefined;
+}
+
+export function shipInterruptedNote(prUrl?: string, cause?: InterruptionCause): string {
   const stands = prUrl
     ? `Its work stands on GitHub: ${prUrl}.`
     : "Whatever it pushed stands on its pipeline branch; no PR was opened yet.";
   const reissue = prUrl
     ? `To continue the review loop, re-issue \`agent:ship\` in this thread with only the PR URL (${prUrl}).`
     : "To continue, re-issue `agent:ship` in this thread with the task — round 0 runs again on the same branch.";
-  return `⚠️ The bot restarted while this ship pipeline was running, so the pipeline stopped. ${stands} ${reissue}`;
+  const opening =
+    cause === "container_replaced"
+      ? "⚠️ The resident container running this pipeline's child was replaced (a deploy's image swap) and the child could not resume, so the pipeline stopped."
+      : cause === "sandbox_fault"
+        ? "⚠️ The sandbox running this pipeline's child failed and the child could not resume, so the pipeline stopped."
+        : cause === "bot_restart"
+          ? "⚠️ The bot restarted while this ship pipeline was running, so the pipeline stopped."
+          : "⚠️ This ship pipeline's child was interrupted and could not resume, so the pipeline stopped.";
+  return `${opening} ${stands} ${reissue}`;
 }
 
 // ---- the plan graph --------------------------------------------------------------------------------
@@ -473,9 +523,10 @@ export type CoordinatorAction =
        *  over an already-shipped pull request. */
       entry?: true;
       /** Set after a coding child died: the bot opens the pull request from the
-       *  pushed branch itself (title from the unit, body from this run's
-       *  submitted description when the record holds one) instead of answering
-       *  `none` over stranded work. */
+       *  pushed branch itself (title from this run's submitted description when
+       *  the record holds one, else a conventional fallback from the unit's
+       *  title — issue 1877; body from the 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,
@@ -536,6 +587,10 @@ export type ChildFacts =
        *  `provider_transient` marks a child a gateway 5xx, a cut stream or a
        *  gateway timeout ended past the harness's retry ladder (issue 1932). */
       failure?: { kind: string };
+      /** What ended an `interrupted` child, off its record's own events (issue
+       *  1876): the ending's sentence names it instead of claiming a bot
+       *  restart for every cause. */
+      interruption?: InterruptionCause;
     };
 
 /** What heads the unit's branch on GitHub: nothing, an open pull request, or —
@@ -599,7 +654,10 @@ export type StepReturn =
   | { type: "wait"; step: string; outcome: "event" | "timeout" }
   // `stopped` on a read: the instance row carries the hard stop's mark, so a
   // finished child ends its unit `stopped` whatever the child's own status.
-  | { type: "read-record"; step: string; run: ChildFacts; stopped?: true; at: number }
+  /** `restartedAs`: the interrupted child restarted from its request as this
+   *  run (issue 1903 — a replaced container's child resumes by itself), so the
+   *  machine keeps waiting on the successor instead of ending the unit. */
+  | { type: "read-record"; step: string; run: ChildFacts; stopped?: true; restartedAs?: string; at: number }
   | { type: "pr-check"; step: string; pr: PrCheck; at: number }
   | { type: "merge"; step: string; outcome: "merged"; sha: string; at: number }
   // The door found the pull request already merged after the approval — auto-merge
@@ -612,7 +670,7 @@ export type StepReturn =
    *  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: "checks"; step: string; checks?: RoundChecks; draft?: boolean; retried?: boolean; at: number }
   | { type: "wait-checks"; step: string; outcome: "event" | "timeout" }
   | { type: "sleep"; step: string };
 
@@ -627,11 +685,16 @@ export interface CheckFailure {
   flakeSuspect?: boolean;
 }
 
-/** The check runs at the reviewed head as the round's checks step reads them. */
+/** The check runs at the reviewed head as the round's checks step reads them.
+ *  `expected` names checks the head must still gain — a required check, or the
+ *  repository's approve workflow whose run does not exist yet (issue 2063):
+ *  the base's required contexts not among the reported runs. The table reads
+ *  an expected-but-unreported check exactly as a pending one. */
 export interface RoundChecks {
   total: number;
   pending: string[];
   failed: CheckFailure[];
+  expected?: string[];
 }
 
 /** A failed check as a finding of the round (record 0055): a finding row like
@@ -695,12 +758,24 @@ export type UnitEnding =
    *  review round once the receipt is posted (item 10's resume path). */
   | {
       kind: "held";
+      cause?: undefined;
       pr?: PrRef;
       round: RoundRef;
       findings: Finding[];
       verdict: "approve" | "request_changes";
       reviewRounds: number;
     }
+  /** The pull request is a draft (issue 2063): nothing can merge and a fix
+   *  round would change nothing, so the checks step waits for the ready event
+   *  inside its ask and, still a draft at the ask's end, the unit ends held —
+   *  `held: draft — mark it ready to continue` — never an unnamed exit. */
+  | {
+      kind: "held";
+      cause: "draft";
+      pr?: PrRef;
+      round: RoundRef;
+      reviewRounds: number;
+    }
   | { kind: "merge_refused"; pr: PrRef; reason: string; reviewRounds: number }
   | { kind: "round_cap"; maxRounds: number; reviewRounds: number }
   | {
@@ -766,7 +841,7 @@ export type UnitEnding =
    *  `transient` so it reads as a condition beside `checks_failed` and `held`
    *  in the plane's table, never as the child failing on its task. */
   | { kind: "transient"; round: RoundRef; runId: string; reviewRounds: number }
-  | { kind: "interrupted"; round: RoundRef; runId: string; reviewRounds: number }
+  | { kind: "interrupted"; round: RoundRef; runId: string; reviewRounds: number; cause?: InterruptionCause }
   | { 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
@@ -854,7 +929,10 @@ export {
   type AddressSeveritySource,
 };
 
-export interface UnitSession {
+/** How far the unit's lease segments have got (decision 0046, the renewable
+ *  lease): the segment's number, the renewals and dollars spent before it and
+ *  the continuation facts — a progress counter, nothing conversational. */
+export interface LeaseSegmentProgress {
   segment: number;
   renewalsSpent: number;
   spendUsd: number | null;
@@ -894,7 +972,7 @@ export interface UnitPipelineInput {
    *  session's spend so far, the sha it continues from and the previous
    *  segment's handoff. Every step name of a later segment is prefixed with
    *  it, so the Workflow's durable steps never collide across segments. */
-  session?: UnitSession;
+  session?: LeaseSegmentProgress;
   /** The instance's mark (agent-ship item 16): a generated one-unit plan — a
    *  `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. */
@@ -940,6 +1018,8 @@ type Phase =
        *  pushed: the pr-check recovers a pushed branch by opening its pull
        *  request; with nothing pushed the unit ends with the child's own reason. */
       dead?: "failed" | "interrupted";
+      /** What ended the dead child (issue 1876), for the `interrupted` ending's sentence. */
+      cause?: InterruptionCause;
       /** The dead child's record names a provider transient (`failure:
        *  provider_transient`, issue 1932): with nothing pushed, round 0 is
        *  re-run once instead of the unit aborting; a second transient in the
@@ -1085,14 +1165,17 @@ const loopOf = (s: UnitPipelineState): Loop => ({ maxRounds: s.input.caps.maxRou
  *  A review round `n` and the findings step that follows it share `n`; the
  *  module's positions are the loop's own. */
 function roundCarve(s: UnitPipelineState, round: RoundRef): Carve {
-  const kind = round.kind === "findings" ? "fix" : round.kind;
-  return carve(remainingMs(s), { kind, index: loopPosition(loopOf(s), kind, round.index) }, loopOf(s));
+  return carve(
+    remainingMs(s),
+    { kind: round.kind, index: loopPosition(loopOf(s), round.kind, round.index) },
+    loopOf(s),
+  );
 }
 
 /** The prefix every step of this pipeline is named under: the unit id, and for
  *  a renewal's segment the segment too (`U10/s2/…`), so the Workflow's durable
  *  step cache never hands segment two the answers of segment one. */
-export const stepPrefixOf = (unit: string, session: UnitSession | undefined): string =>
+export const stepPrefixOf = (unit: string, session: LeaseSegmentProgress | undefined): string =>
   session !== undefined && session.segment > 1 ? `${unit}/s${session.segment}` : unit;
 const stepPrefix = (s: UnitPipelineState) => stepPrefixOf(s.input.unit.id, s.input.session);
 const roundStep = (s: UnitPipelineState, round: RoundRef) =>
@@ -1623,19 +1706,29 @@ function enterChecks(s: UnitPipelineState, round: RoundRef, notes: CoordinatorNo
   };
 }
 
-/** The order the checks step reads a head in (record 0055, issue 1991):
- *  a failed check is the round's answer as soon as it is read, whatever else
- *  is still pending — with the flake rule spending its one re-run first when
- *  every failure is a suspect — and only a head with no failed check waits on
- *  the pending ones; a head with no check reported gets one chunk of grace;
- *  the rest is green. One function so the siblings that fold more outcomes
- *  into the step (a held ending, a transient round re-run) read the same order. */
+/** The checks step's decision table over the reviewed head's facts (record
+ *  0055; issues 1991 and 2063) — one function, read top to bottom, so every
+ *  sibling that folds more outcomes into the step (a held ending, a transient
+ *  round re-run) reads the same order:
+ *  (a) any failed check is the round's answer as soon as it is read, whatever
+ *      else is still pending — with the flake rule spending its one re-run
+ *      first when every failure is a suspect;
+ *  (d) no failure and the pull request a draft: the step waits for the ready
+ *      event — nothing can merge a draft and a fix round would change nothing;
+ *  (b) no failure and a check pending, queued, expected but not yet reported
+ *      (`expected`: a required check, or the repository's approve workflow
+ *      whose run does not exist yet), or GitHub unreadable: the head waits on
+ *      the settled event and is read again;
+ *  (—) no check reported at all: one chunk of grace, never more;
+ *  (c) every expected check reported green: the round proceeds with no wait. */
 function checksVerdict(
   checks: RoundChecks | undefined,
   p: { retried: boolean; graced: boolean },
+  draft?: boolean,
 ):
   | { kind: "retry"; names: string[] }
   | { kind: "failed"; failed: CheckFailure[] }
+  | { kind: "draft" }
   | { kind: "pending" }
   | { kind: "grace" }
   | { kind: "green" } {
@@ -1649,8 +1742,14 @@ function checksVerdict(
       return { kind: "retry", names: checks.failed.map((f) => f.name) };
     return { kind: "failed", failed: checks.failed };
   }
-  // GitHub unreadable answers as pending and is re-read at the chunk's end.
-  if (checks === undefined || checks.pending.length > 0) return { kind: "pending" };
+  // A draft outranks the waits: its checks may sit green forever, and only a
+  // person's "ready" changes anything — a red check above still gets its fix
+  // round, since that work stands whether or not the pull request is a draft.
+  if (draft === true) return { kind: "draft" };
+  // GitHub unreadable answers as pending and is re-read at the chunk's end;
+  // an expected check not yet reported (issue 2063) is pending the same way.
+  if (checks === undefined || checks.pending.length > 0 || (checks.expected?.length ?? 0) > 0)
+    return { kind: "pending" };
   // 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).
@@ -1673,6 +1772,7 @@ function settleChecks(
   p: Extract<Phase, { at: "checks" }>,
   checks: RoundChecks | undefined,
   retried?: boolean,
+  draft?: boolean,
 ): Transition {
   const { round } = p;
   const wait = (over: Partial<Extract<Phase, { at: "checks-wait" }>>): Transition => ({
@@ -1706,7 +1806,7 @@ function settleChecks(
     }
     return wait({ retried: true });
   }
-  const verdict = checksVerdict(checks, p);
+  const verdict = checksVerdict(checks, p, draft);
   switch (verdict.kind) {
     case "retry":
       return {
@@ -1731,6 +1831,21 @@ function settleChecks(
         );
       return enterRound(next, { index: round.index, kind: "findings" }, notes);
     }
+    case "draft":
+      // A draft pull request (issue 2063): the unit idles on the settled event
+      // — marking it ready starts the head's check suites, whose completion
+      // fires `checks-settled-<head>` — and the re-read continues through the
+      // table. Still a draft at the ask's end, the unit ends held naming the
+      // draft and the person's next step, never an exit with no cause.
+      if (s.clock - p.since >= p.waitMs)
+        return end(s, {
+          kind: "held",
+          cause: "draft",
+          ...(s.pr !== undefined ? { pr: s.pr } : {}),
+          round: p.round,
+          reviewRounds: s.reviewRounds,
+        });
+      return wait({});
     case "pending":
       // 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
@@ -1812,9 +1927,17 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
     // A dead child left nothing on the branch to recover: the unit ends with
     // the child's own reason — never the budget clip.
     if (phase.dead === "interrupted")
-      return end(s, { kind: "interrupted", round, runId: phase.runId, reviewRounds: s.reviewRounds }, [
-        roundNote(round, "aborted"),
-      ]);
+      return end(
+        s,
+        {
+          kind: "interrupted",
+          round,
+          runId: phase.runId,
+          reviewRounds: s.reviewRounds,
+          ...(phase.cause !== undefined ? { cause: phase.cause } : {}),
+        },
+        [roundNote(round, "aborted")],
+      );
     if (phase.dead === "failed") {
       // A provider transient with nothing pushed is not the child's failure
       // (issue 1932): the ledger row and the branch are untouched, so round 0
@@ -1832,7 +1955,7 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
         pr.unrecovered === "no_commits"
           ? `nothing heads \`${s.input.unit.branch}\`: no commits were pushed, so there was no work to recover`
           : pr.unrecovered === "no_base"
-            ? `\`${s.input.unit.branch}\` could not be given a pull request: the instance names no base branch to open it against, so whatever was pushed stays on the branch`
+            ? `\`${s.input.unit.branch}\` could not be given a pull request: the pipeline names no base branch to open it against, so whatever was pushed stays on the branch`
             : `the pr-check found no pull request heading \`${s.input.unit.branch}\`, so nothing was recovered`;
       return end(
         s,
@@ -1971,9 +2094,17 @@ function roundOnOpenPr(
       // ends with the child's own reason — the ship-restart note for a bot
       // roll, the failure for a failed run — never as the round's inaction.
       if (phase.dead === "interrupted")
-        return end(next, { kind: "interrupted", round, runId: phase.runId, reviewRounds: next.reviewRounds }, [
-          roundNote(round, "aborted"),
-        ]);
+        return end(
+          next,
+          {
+            kind: "interrupted",
+            round,
+            runId: phase.runId,
+            reviewRounds: next.reviewRounds,
+            ...(phase.cause !== undefined ? { cause: phase.cause } : {}),
+          },
+          [roundNote(round, "aborted")],
+        );
       if (phase.dead === "failed")
         return end(
           next,
@@ -2169,10 +2300,14 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
     case "read": {
       const r = ret as Extract<StepReturn, { type: "read-record" }>;
       if (!r.run.finished)
+        // `restartedAs` (issues 1903/1876): the child's container was replaced
+        // and it restarted from its request as a new run — the round carries on
+        // waiting on the successor, and the unit never ends over a resume that
+        // succeeded. The next wait and read follow the successor's id.
         return {
           state: {
             ...clocked,
-            phase: { at: "wait", round: p.round, runId: p.runId, n: p.n + 1, until: p.until },
+            phase: { at: "wait", round: p.round, runId: r.restartedAs ?? p.runId, n: p.n + 1, until: p.until },
           },
           notes: [],
         };
@@ -2192,17 +2327,35 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
           [roundNote(p.round, "stopped")],
         );
       if (r.run.status === "interrupted") {
+        const cause = r.run.interruption;
         // A dead CODING child may have pushed before the ledger closed it: the
         // pr-check recovers the branch. A review child has nothing on the
         // branch to recover, so its interruption still ends the unit at once.
         if (p.round.kind !== "review")
           return {
-            state: { ...clocked, phase: { at: "pr-check", round: p.round, runId: p.runId, dead: "interrupted" } },
+            state: {
+              ...clocked,
+              phase: {
+                at: "pr-check",
+                round: p.round,
+                runId: p.runId,
+                dead: "interrupted",
+                ...(cause !== undefined ? { cause } : {}),
+              },
+            },
             notes: [],
           };
-        return end(clocked, { kind: "interrupted", round: p.round, runId: p.runId, reviewRounds: s.reviewRounds }, [
-          roundNote(p.round, "aborted"),
-        ]);
+        return end(
+          clocked,
+          {
+            kind: "interrupted",
+            round: p.round,
+            runId: p.runId,
+            reviewRounds: s.reviewRounds,
+            ...(cause !== undefined ? { cause } : {}),
+          },
+          [roundNote(p.round, "aborted")],
+        );
       }
       return p.round.kind === "review"
         ? settleReview(clocked, p.round, r.run)
@@ -2212,7 +2365,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
       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);
+      return settleChecks(clocked, p, r.checks, r.retried, r.draft);
     }
     case "checks-wait":
       // The event fired or the chunk elapsed either way the head is read again.
@@ -2431,7 +2584,7 @@ export interface CommitChecksFacts {
  *  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.`;
+    return `⚠️ Approved but not merge-ready after ${rounds}: ${url} — the head conflicts with \`${base}\`: \`pulls rebase ${url}\` rebases it onto \`${base}\` (an unchanged patch carries the approval). 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.`;
@@ -2450,13 +2603,16 @@ function mergeReadyHeadline(rounds: string, url: string, base: string, facts: Me
 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. */
+  /** The level the report speaks at (routing-and-config item 28, record
+   *  0066). 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 only the
+   *  outcome is everyone's: ONE line in the user's words — `✅ Merge-ready
+   *  after 2 review rounds: <url>`, `Held: <the human-gated row>`, `Stopped`,
+   *  `Round cap reached: <counts>` — and the verdict, the findings left below
+   *  the gate, the declined ones, the remaining-gate sentence, the level in
+   *  force, the grant, the write-up pointer, the budget split, the re-issue
+   *  prompt and a segment boundary are `verbose` asides; the full detail
+   *  stays on the pull request, where the round routes put it. */
   verbosity: Verbosity = "verbose",
 ): string {
   const e = s.ending;
@@ -2495,44 +2651,62 @@ export function renderUnitReport(
   switch (e.kind) {
     case "merged":
       if (e.by === "other")
-        return `✅ Already merged: ${e.pr.url} (merge commit \`${e.sha.slice(0, 7)}\`, merged ${e.mergedAt}) — the pull request heading \`${s.input.unit.branch}\` was merged before this attempt reached it, by a person or by an earlier attempt of this plan; the runner merged nothing. The unit is done and its dependents start on a base that carries it.`;
+        return `✅ Already merged: ${e.pr.url} (merge commit \`${e.sha.slice(0, 7)}\`, merged ${e.mergedAt}) — the pull request heading \`${s.input.unit.branch}\` was merged before this pipeline reached it, by a person or by an earlier pipeline of this plan; the pipeline merged nothing. The unit is done and its dependents start on a base that carries it.`;
       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,
+        `✅ Merged after ${rounds}: ${e.pr.url} (squash \`${e.sha.slice(0, 7)}\`) — merged by the pipeline under \`plan:merge\`: the review approved at this head and the guards were green.`,
+        aside(verdictLine),
         aside(levelLine),
         aside(grantLine),
-        skippedLine,
-        declinedLine,
+        aside(skippedLine),
+        aside(declinedLine),
       ]
         .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.
-      return `✅ Already on \`${s.input.base}\`: the unit's scope landed before this attempt — ${e.landed.map((l) => `${l.what} (${l.where})`).join("; ")}. The coding child (run ${e.runId}) found it there and pushed nothing of its own: \`${s.input.unit.branch}\` has no commits over \`${s.input.base}\`, so there is no pull request to open or review. The unit is done and its dependents start on a base that carries it.`;
+      return `✅ Already on \`${s.input.base}\`: the unit's scope landed before this pipeline — ${e.landed.map((l) => `${l.what} (${l.where})`).join("; ")}. The coding child (run ${e.runId}) found it there and pushed nothing of its own: \`${s.input.unit.branch}\` has no commits over \`${s.input.base}\`, so there is no pull request to open or review. The unit is done and its dependents start on a base that carries it.`;
     case "merge_ready":
       return [
         // 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, s.input.base, facts),
-        verdictLine,
+        aside(verdictLine),
         aside(levelLine),
         aside(grantLine),
-        skippedLine,
-        declinedLine,
+        aside(skippedLine),
+        aside(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
         // as such, else the pull request's own auto-merge fact, else the gate.
-        facts?.merged
-          ? `Already merged: ${e.pr.url} (merge commit \`${facts.merged.sha.slice(0, 7)}\`, merged ${facts.merged.mergedAt}) — auto-merge or a person merged it after the approval; the runner merged nothing.`
-          : 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.",
+        // A `verbose` aside like the rest — the quiet thread copy is the
+        // headline alone (record 0066).
+        aside(
+          facts?.merged
+            ? `Already merged: ${e.pr.url} (merge commit \`${facts.merged.sha.slice(0, 7)}\`, merged ${facts.merged.mergedAt}) — auto-merge or a person merged it after the approval; the pipeline merged nothing.`
+            : facts?.autoMergeEnabled
+              ? "Auto-merge is on for this pull request: the approval merges it once checks pass."
+              : "Remaining gate: a person's merge — the pipeline merges only when the plan's `merge` setting says so, and ship never approves.",
+        ),
       ]
         .filter(Boolean)
         .join("\n");
     case "held": {
+      // The draft hold (issue 2063): the pull request is a draft, so nothing
+      // can merge and no fix round would change anything — the one line names
+      // the cause and the person's exact next step.
+      if (e.cause === "draft") {
+        const link = e.pr !== undefined ? ` — ${e.pr.url}` : "";
+        if (!shows(verbosity, "verbose")) return `⏸️ Held: draft — mark it ready to continue${link}`;
+        const draftReissue = s.input.generated
+          ? `To continue, mark it ready and re-issue \`agent:ship\` in this thread with only the PR URL${e.pr !== undefined ? ` (${e.pr.url})` : ""} — no new task text; the re-issued pipeline resumes at the review round.`
+          : `To continue, mark it ready; ${reissue.charAt(0).toLowerCase()}${reissue.slice(1)}`;
+        return join([
+          `⏸️ Held after ${rounds}${e.pr !== undefined ? `: ${e.pr.url}` : ""} — the pull request is a draft, so nothing can merge and no fix round would change anything.`,
+          draftReissue,
+        ]);
+      }
       // The person's next step is the report's whole point (issue 1990): the
       // human-gated rows are named with the reviewer's own words, and the
       // re-issue line says the attempt resumes at the review round — item 10's
@@ -2542,13 +2716,16 @@ export function renderUnitReport(
       // first (item 10), the very round this ending exists to avoid — so the
       // held case renders its own re-issue line instead of the shared one.
       const rows = e.findings.map((f) => `${f.id} (${f.severity}) — ${f.title}`).join("; ");
+      // The quiet copy is the ending in the user's words (record 0066): the
+      // held row named, the pull request linked, nothing about the machinery.
+      if (!shows(verbosity, "verbose")) return `⏸️ Held: ${rows}${e.pr !== undefined ? ` — ${e.pr.url}` : ""}`;
       const heldReissue = s.input.generated
         ? `To continue, re-issue \`agent:ship\` in this thread with only the PR URL${e.pr !== undefined ? ` (${e.pr.url})` : ""} — no new task text.`
         : reissue;
       return join([
         `⏸️ ${e.verdict === "approve" ? "Approved but held" : "Changes requested but held"} after ${rounds}${e.pr !== undefined ? `: ${e.pr.url}` : ""} — every finding of review round ${e.round.index} is human-gated, a receipt only a person can produce: ${rows}. No fix round was opened: a coding child cannot produce the receipt.`,
-        aside(levelLine),
-        `Next step: produce the receipt each finding names and post it on the pull request. ${heldReissue} The re-issued attempt resumes at the review round — no coding round runs first.`,
+        levelLine,
+        `Next step: produce the receipt each finding names and post it on the pull request. ${heldReissue} The re-issued pipeline resumes at the review round — no coding round runs first.`,
       ]);
     }
     case "merge_refused":
@@ -2558,40 +2735,56 @@ export function renderUnitReport(
       // `already_landed`) and moves on to the dependents. The generated
       // plan's line already says to re-issue with the PR URL, which takes the
       // same recognition path.
+      // The quiet copy: the outcome in the user's words with the person's
+      // remedy — the hand merge is what a person must act on (record 0066).
+      if (!shows(verbosity, "verbose")) return `⚠️ Not merged: ${e.reason} — ${e.pr.url}`;
       return join([
-        `⚠️ The review approved ${e.pr.url} but the runner did not merge it: ${e.reason}. A person decides what becomes of the pull request.`,
+        `⚠️ The review approved ${e.pr.url} but the pipeline did not merge it: ${e.reason}. A person decides what becomes of the pull request.`,
         s.input.generated
           ? reissue
           : `The approved work is on the branch: rebase or fix it, push, and merge it by hand. Then re-issue the plan naming the remaining units — a unit whose pull request has merged is recognized and not run again, and its dependents start from there.`,
       ]);
-    case "round_cap":
-      return join([
-        `🧢 Ship stopped at a cap: the ${e.maxRounds}-round cap — no approval after ${rounds}.${prLine}`,
-        splitReport(s),
-        reissue,
-      ]);
+    case "round_cap": {
+      // The quiet copy counts the last review's open findings, only the
+      // non-zero severities (record 0066): `Round cap reached: 2 blockers, 1 major`.
+      if (!shows(verbosity, "verbose")) {
+        const counts = severityCounts(s.findingsByRound[e.reviewRounds] ?? []);
+        return `🧢 Round cap reached${counts ? `: ${counts}` : ""}${prUrl !== undefined ? ` — ${prUrl}` : ""}`;
+      }
+      // The cap bounds fix rounds, never the terminal steps (issue 2023): an
+      // approval in the last allowed round still runs the checks step and the
+      // merge, so a round_cap after an approve means the checks (or the merge
+      // queue) failed at the approved head with no fix round left — and the
+      // report names those findings instead of claiming no approval landed.
+      const failedChecks = checkFindingsOf(s.findingsByRound[s.reviewRounds]);
+      const headline =
+        failedChecks.length > 0
+          ? `🧢 Ship stopped at a cap: the ${e.maxRounds}-round cap — the review of round ${e.reviewRounds} approved, but ${failedChecks.map((f) => `\`${f.id}\``).join(", ")} failed at the approved head and no fix round remains.${prLine}`
+          : `🧢 Ship stopped at a cap: the ${e.maxRounds}-round cap — no approval after ${rounds}.${prLine}`;
+      return join([headline, splitReport(s), reissue]);
+    }
     case "wall_clock_cap":
+      if (!shows(verbosity, "verbose")) return `🧢 Out of budget — no approval after ${rounds}.${prLine}`;
       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}`,
-        aside(budgetSplitLine(e.spent, s.input.caps.maxMinutes)),
+        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.`,
+        `⏳ 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 pipeline starts at the review round while the pull request still heads at the child's own last push.`,
         aside(budgetSplitLine(e.spent, s.input.caps.maxMinutes)),
-        reissue,
+        aside(reissue),
       ]);
     case "stopped":
+      if (!shows(verbosity, "verbose")) return `${e.mode === "hard" ? "⛔" : "⏹"} Stopped.${prLine}`;
       return join([
         `${e.mode === "hard" ? "⛔" : "⏹"} Ship stopped by operator (${e.mode} stop) after ${rounds}.${prLine}`,
-        aside(
-          writeUpPointer(
-            s,
-            e.round.kind,
-            e.round.kind === "review" ? s.reviewRunByRound[e.round.index] : s.lastCodingRunId,
-          ),
+        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."
@@ -2599,14 +2792,13 @@ export function renderUnitReport(
         reissue,
       ]);
     case "aborted":
+      if (!shows(verbosity, "verbose")) return `⚠️ Aborted after ${rounds}: ${e.reason}${prLine}`;
       return join([
         e.reason,
-        aside(
-          writeUpPointer(
-            s,
-            e.round?.kind ?? "coding",
-            e.round?.kind === "review" ? s.reviewRunByRound[e.round.index] : s.lastCodingRunId,
-          ),
+        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}.`,
@@ -2619,29 +2811,33 @@ export function renderUnitReport(
       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` : ""}.`,
+        `🔁 The unit's budget ran out with the unit unfinished — ${e.line}. A fresh ${s.input.caps.maxMinutes}-minute budget opens in this thread${e.from !== undefined ? ` from \`${e.from.slice(0, 7)}\`` : ""}, with the last run's write-up as its request; ${e.renewalsLeft} renewal${e.renewalsLeft === 1 ? "" : "s"} remain${e.spendUsd !== null ? `, $${e.spendUsd.toFixed(2)} spent so far` : ""}.`,
         aside(budgetSplitLine(e.spent, s.input.caps.maxMinutes)),
       ]);
     case "transient":
+      if (!shows(verbosity, "verbose"))
+        return `⚠️ Aborted after ${rounds}: the model provider failed twice; re-issue once it settles.${prLine}`;
       return join([
         `⚠️ The coding child of round ${e.round.index} (run ${e.runId}) died on a provider transient — a model-gateway 5xx, a cut stream or a gateway timeout past the harness's retry ladder — with nothing pushed, after the round was already re-run once for the same reason. The task itself was never the problem.`,
-        aside(writeUpPointer(s, e.round.kind, s.lastCodingRunId)),
+        writeUpPointer(s, e.round.kind, s.lastCodingRunId),
         `⚠️ Ship ended after ${rounds}; re-issue once the provider settles.`,
         reissue,
       ]);
     case "no_verdict":
+      if (!shows(verbosity, "verbose"))
+        return `⚠️ No verdict from review round ${e.round.index} — aborted after ${rounds}.${prLine}`;
       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.`,
-        aside(writeUpPointer(s, e.round.kind, s.reviewRunByRound[e.round.index])),
+        writeUpPointer(s, e.round.kind, s.reviewRunByRound[e.round.index]),
         `⚠️ Ship aborted after ${rounds}.`,
         reissue,
       ]);
     case "interrupted":
-      return shipInterruptedNote(prUrl);
+      return shipInterruptedNote(prUrl, e.cause);
     case "refused":
       return join([
         `🚫 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,
+        aside(reissue),
       ]);
     case "idle":
       // The old kind's sentence at this copy's level — the report is unchanged