@coreplane/switchboard 1.260.2 → 1.260.4

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

@@ -59,6 +59,7 @@ import { parsePlanUnit, planUnitIds } from "./contract.js";
 import {
   carve,
   DEFAULT_GRANT,
+  IDLE_DAYS_MAX,
   loopPosition,
   MERGE_WAIT_ASK_MINUTES,
   MINUTE_MS,
@@ -136,11 +137,11 @@ export function shipInterruptedNote(prUrl?: string, cause?: InterruptionCause, i
   const stands = prUrl
     ? `Its work stands on GitHub: ${prUrl}.`
     : "Whatever it pushed stands on its pipeline branch; no PR was opened yet.";
-  const reissue = idle
-    ? "To continue, reply in this thread to continue."
+  const continuation = idle
+    ? "The next reply in this thread continues the unit."
     : 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.";
+      ? `The pipeline kept its task, branch and pull request; the next reply in this thread continues the review loop at ${prUrl}.`
+      : "The pipeline kept its task and branch; the next reply in this thread starts round 0 again on that branch.";
   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."
@@ -149,7 +150,7 @@ export function shipInterruptedNote(prUrl?: string, cause?: InterruptionCause, i
         : 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}`;
+  return `${opening} ${stands} ${continuation}`;
 }
 
 // ---- the plan graph --------------------------------------------------------------------------------
@@ -494,8 +495,10 @@ export type Brief =
       pr: number;
       headSha?: string;
       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 review round and the coding run that answered it. A
+       *  recovered posted verdict carries findings by value when no run row
+       *  belongs to this attempt. */
+      prior?: { reviewRunId?: string; codingRunId?: string; findings?: Finding[] };
       /** 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[];
@@ -504,7 +507,12 @@ export type Brief =
       kind: "findings";
       unit: string;
       pr: number;
-      reviewRunId: string;
+      /** The review run normally supplies the findings. An adopted attempt
+       *  can recover them from the last posted verdict marker instead. */
+      reviewRunId?: string;
+      findings?: Finding[];
+      /** Human replies that answered a parked finding, attributed at intake. */
+      answers?: 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[];
@@ -522,6 +530,20 @@ export interface PrRef {
   url: string;
 }
 
+/** A human-gated review question parked on its live unit. The review's typed
+ * findings and the pull request survive the wait; `reviewRunId` is absent when
+ * an adopted attempt recovered the question from GitHub's verdict marker. */
+export interface HumanGatePending {
+  pr: PrRef;
+  round: number;
+  findings: Finding[];
+  verdict: "approve" | "request_changes";
+  reviewRunId?: string;
+  headSha?: string;
+  /** When the verdict asked the question, for fencing older unit events. */
+  askedAt?: number;
+}
+
 /** What the coordinator asks for next. `step` is the Workflow step's name, and
  *  for a spawn the second half of the child's idempotency key. */
 export type CoordinatorAction =
@@ -577,6 +599,10 @@ export type ChildFacts =
   | {
       finished: true;
       status: RunStatus;
+      /** The terminal record time; fallback fence for an older review record. */
+      finishedAt?: number;
+      /** When the posted verdict became the person's question. */
+      reviewAskedAt?: number;
       finalReply?: string;
       /** A coding child's `pr_opened`. */
       pr?: { number: number; url: string; created: boolean };
@@ -659,6 +685,16 @@ export type PrCheck =
        *  read beside the checks on the ending's facts read, so a `merge_ready`
        *  report tells the person their merge is queued, never a direct one. */
       baseHasMergeQueue?: boolean;
+      /** A person's newest pull-request comment answered the last posted
+       * human-gated verdict. Entry starts its fix round before any review. */
+      humanGate?: {
+        round: number;
+        findings: Finding[];
+        verdict: "approve" | "request_changes";
+        answer: string;
+        author: string;
+        commentId: string;
+      };
     }
   | { state: "merged"; prNumber: number; url: string; sha: string; mergedAt: string };
 
@@ -793,12 +829,9 @@ export type UnitEnding =
    *  The unit is done and its dependents start on a base that carries it. */
   | { kind: "already_landed"; landed: HandoffLanded[]; round: RoundRef; runId: string; reviewRounds: number }
   | { kind: "merge_ready"; pr: PrRef; reviewRounds: number }
-  /** Every finding the round would act on is human-gated — a receipt only a
-   *  person can produce (issue 1990; the reviewer set the flag through
-   *  `submit_verdict`, agent-review item 5) — so a fix round could change
-   *  nothing: the unit ends held for a person, the ending carrying the
-   *  human-gated rows, and a re-issue with the pull request resumes at the
-   *  review round once the receipt is posted (item 10's resume path). */
+  /** The report nested inside a parked human-gated question. The unit never
+   *  publishes this as its terminal kind: `parkHumanGate` carries it under an
+   *  idle ending until a person's answer opens the fix round. */
   | {
       kind: "held";
       cause?: undefined;
@@ -938,6 +971,10 @@ export type UnitEnding =
       handoff?: Handoff;
       round?: RoundRef;
       reviewRounds: number;
+      /** A parked human-gated review is always an idle, independent of the
+       * optional idle policy. Its question is the unit's pending state. */
+      humanGate?: HumanGatePending;
+      parkDays?: number;
     };
 
 /** The kinds that idle: every ending but the ended ones — the unit is
@@ -945,10 +982,9 @@ export type UnitEnding =
  *  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. A gated or
- *  draft `held` never idles either — it waits only for a person's receipt at
- *  the pull request, which no thread reply can produce — but a blocked hold
- *  (issue 2086) waits for exactly the person's word the idle's wake carries,
- *  so it alone idles; `idleEnding` draws that line by cause. */
+ *  draft `held` never idles either. A blocked hold (issue 2086) follows the
+ *  configured idle policy; a human-gated hold takes `parkHumanGate` instead,
+ *  which always creates the pending idle question. */
 export type IdleWhy =
   Exclude<UnitEnding["kind"], "idle" | "merged" | "already_landed" | "merge_ready" | "refused"> | RenewalWhy;
 
@@ -1014,6 +1050,9 @@ export interface LeaseSegmentProgress {
   previousHandoff?: Handoff;
   /** Words that woke an idle segment, already attributed in arrival order. */
   texts?: string[];
+  /** The human-gated question those words answer. It resumes as a findings
+   * round before another review, without spending a renewal. */
+  humanGate?: HumanGatePending;
   /** A stopped segment reopens under the remainder of its cut lease. Each
    *  reopen gets a fresh attempt so its Workflow steps cannot replay the
    *  stopped attempt's cached answers. */
@@ -1165,6 +1204,8 @@ export interface UnitPipelineState {
    *  ids are unique within one round only. A disposition naming an id the review
    *  never issued is dropped at the match (`matchDispositions`). */
   readonly findingsByRound: Readonly<Record<number, Finding[]>>;
+  /** Human answers folded into a recovered/parked findings brief. */
+  readonly humanAnswersByRound: Readonly<Record<number, string[]>>;
   readonly dispositionsByRound: Readonly<Record<number, FindingDisposition[]>>;
   readonly reviewRunByRound: Readonly<Record<number, string>>;
   /** The coding run each round's findings step dispatched. */
@@ -1208,20 +1249,29 @@ export const BUSY_RETRY_MS = SHIP_WAIT.busyRetryMinutes * MIN;
 // ---- the unit pipeline: opening and the next action -----------------------------------------------
 
 export function openUnitPipeline(input: UnitPipelineInput, at: number): UnitPipelineState {
+  const pending = input.session?.humanGate;
   const base: UnitPipelineState = {
     input,
     startedAt: at,
     clock: at,
     phase: { at: "pre-check" },
-    reviewRounds: 0,
+    reviewRounds: pending?.round ?? 0,
     rebaseAttempts: 0,
     spentMs: { coding: 0, review: 0, waiting: 0 },
     spendUsd: input.session?.spendUsd ?? 0,
-    findingsByRound: {},
+    findingsByRound: pending ? { [pending.round]: pending.findings } : {},
+    humanAnswersByRound: pending && input.session?.texts !== undefined ? { [pending.round]: input.session.texts } : {},
     dispositionsByRound: {},
-    reviewRunByRound: {},
+    reviewRunByRound: pending?.reviewRunId !== undefined ? { [pending.round]: pending.reviewRunId } : {},
     findingsRunByRound: {},
+    ...(pending !== undefined
+      ? {
+          pr: pending.pr,
+          ...(pending.headSha !== undefined ? { lastReviewHead: pending.headSha } : {}),
+        }
+      : {}),
   };
+  if (pending !== undefined) return enterRound(base, { index: pending.round, kind: "findings" }).state;
   if (!input.resume) return base;
   const url = input.resume.url ?? `https://github.com/${input.repo}/pull/${input.resume.pr}`;
   const resumed: UnitPipelineState = {
@@ -1294,26 +1344,40 @@ function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
     return { kind: "rebase", unit, pr, headSha: s.lastReviewHead!, base: s.input.base };
   }
   if (round.kind === "findings") {
-    const checks = checkFindingsOf(s.findingsByRound[round.index]);
+    const issued = s.findingsByRound[round.index] ?? [];
+    const checks = checkFindingsOf(issued);
+    const reviewRunId = s.reviewRunByRound[round.index];
+    const answers = s.humanAnswersByRound[round.index];
     return {
       kind: "findings",
       unit,
       pr,
-      reviewRunId: s.reviewRunByRound[round.index]!,
+      ...(reviewRunId !== undefined ? { reviewRunId } : {}),
+      ...(reviewRunId === undefined || (answers !== undefined && answers.length > 0) ? { findings: issued } : {}),
+      ...(answers !== undefined && answers.length > 0 ? { answers } : {}),
       ...(checks.length > 0 ? { checks } : {}),
     };
   }
+  const priorFindings = s.findingsByRound[round.index - 1] ?? [];
   const priorReview = s.reviewRunByRound[round.index - 1];
   const priorCoding = s.findingsRunByRound[round.index - 1];
-  const priorChecks = checkFindingsOf(s.findingsByRound[round.index - 1]);
+  const priorChecks = checkFindingsOf(priorFindings);
   return {
     kind: "review",
     unit,
     pr,
     ...(s.lastReviewHead !== undefined ? { headSha: s.lastReviewHead } : {}),
     round: round.index,
-    ...(priorReview !== undefined
-      ? { prior: { reviewRunId: priorReview, ...(priorCoding !== undefined ? { codingRunId: priorCoding } : {}) } }
+    ...(priorReview !== undefined || (priorCoding !== undefined && priorFindings.length > 0)
+      ? {
+          prior: {
+            ...(priorReview !== undefined ? { reviewRunId: priorReview } : {}),
+            ...(priorReview === undefined || s.humanAnswersByRound[round.index - 1] !== undefined
+              ? { findings: priorFindings }
+              : {}),
+            ...(priorCoding !== undefined ? { codingRunId: priorCoding } : {}),
+          },
+        }
       : {}),
     ...(priorChecks.length > 0 ? { checks: priorChecks } : {}),
   };
@@ -1454,9 +1518,9 @@ function end(s: UnitPipelineState, ending: UnitEnding, notes: CoordinatorNote[]
 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;
-  // A gated or draft hold waits only for a person's receipt at the pull
-  // request — no thread reply can continue it — while a blocked hold (issue
-  // 2086) waits for exactly the person's word the wake carries, so it idles.
+  // A draft hold is not continued by a reply. A blocked hold (issue 2086)
+  // waits for the person's word. Human-gated questions bypass this mapping:
+  // `parkHumanGate` always parks them with their typed pending state.
   if (ending.kind === "held" && ending.cause !== "blocked") return undefined;
   const old = ending as Exclude<UnitEnding, { kind: "idle" | "merged" | "already_landed" | "merge_ready" | "refused" }>;
   const grant = s.input.grant ?? DEFAULT_GRANT;
@@ -1512,7 +1576,7 @@ const heldEnding = (
   round: RoundRef,
   findings: Finding[],
   verdict: "approve" | "request_changes",
-): UnitEnding => ({
+): Extract<UnitEnding, { kind: "held" }> => ({
   kind: "held",
   ...(s.pr !== undefined ? { pr: s.pr } : {}),
   round,
@@ -1521,6 +1585,48 @@ const heldEnding = (
   reviewRounds: s.reviewRounds,
 });
 
+/** A human-gated finding is a question, not a terminal hold. Park the live
+ * unit in record 0051's idle state regardless of the optional idle policy, so
+ * either a thread reply or a pull-request comment can become its fix brief. */
+function parkHumanGate(
+  s: UnitPipelineState,
+  round: RoundRef,
+  findings: Finding[],
+  verdict: "approve" | "request_changes",
+  askedAt: number,
+  notes: CoordinatorNote[],
+): Transition {
+  const held = heldEnding(s, round, findings, verdict);
+  const humanGate: HumanGatePending = {
+    pr: s.pr!,
+    round: round.index,
+    findings,
+    verdict,
+    ...(s.reviewRunByRound[round.index] !== undefined ? { reviewRunId: s.reviewRunByRound[round.index] } : {}),
+    ...(s.lastReviewHead !== undefined ? { headSha: s.lastReviewHead } : {}),
+    askedAt,
+  };
+  const grant = s.input.grant ?? DEFAULT_GRANT;
+  const ending: Extract<UnitEnding, { kind: "idle" }> = {
+    kind: "idle",
+    why: "held",
+    idled: held,
+    renewalsLeft: Math.max(0, grant.renewals - (s.input.session?.renewalsSpent ?? 0)),
+    ...(s.lastReviewHead !== undefined ? { from: s.lastReviewHead } : {}),
+    ...(s.lastCodingRunId !== undefined ? { runId: s.lastCodingRunId } : {}),
+    spendUsd: s.spendUsd,
+    ...(s.lastCodingHandoff !== undefined ? { handoff: s.lastCodingHandoff } : {}),
+    round,
+    reviewRounds: s.reviewRounds,
+    humanGate,
+    parkDays: IDLE_DAYS_MAX,
+  };
+  return {
+    state: { ...s, phase: ENDED, ending },
+    notes: [...notes, { type: "ended", ending }],
+  };
+}
+
 const roundNote = (round: RoundRef, outcome: ShipRoundOutcome): RoundNote => ({
   type: "round",
   index: round.index,
@@ -1564,10 +1670,11 @@ function enterRound(s: UnitPipelineState, round: RoundRef, notes: CoordinatorNot
   };
 }
 
-/** A rebase changed the approved patch, so review is mandatory even when
- *  the ordinary findings-round count is spent. The run's remaining lease is
- *  the bound: `enterRound` refuses when another review no longer fits. */
-function reviewAfterRebase(s: UnitPipelineState, notes: CoordinatorNote[] = []): Transition {
+/** A rebase changed the approved patch, or a person's answer enabled a
+ *  human-gated fix, so review is mandatory even when the ordinary findings-
+ *  round count is spent. The run's remaining lease is the bound: `enterRound`
+ *  refuses when another review no longer fits. */
+function mandatoryReview(s: UnitPipelineState, notes: CoordinatorNote[] = []): Transition {
   return enterRound(s, { index: s.reviewRounds + 1, kind: "review" }, notes);
 }
 
@@ -1634,18 +1741,21 @@ function settleCoding(
       [roundNote(round, "stopped")],
     );
   // A mechanical WIP push means the child did not declare the work ready for
-  // review. Keep the unit branch as the resumption point and abort this
-  // attempt; an ordinary push still takes the established recover-PR path.
-  if (facts.status === "failed" && checkpoint !== undefined) {
+  // review, whatever terminal status its own answer produced. Keep the unit
+  // branch as the resumption point and abort this attempt; an ordinary push
+  // still takes the established recover-PR path.
+  if (checkpoint !== undefined) {
     const cause =
       facts.failure?.kind === "provider_transient"
         ? "the model provider's transport retry budget was spent"
-        : "it failed before finishing";
+        : facts.status === "failed"
+          ? "it failed before finishing"
+          : "it ended before its work was ready for review";
     return end(
       next,
       {
         kind: "aborted",
-        reason: `⚠️ The coding child ended because ${cause}; the branch carries the interrupted work at \`${checkpoint.sha.slice(0, 7)}\` on \`${checkpoint.branch}\`. Re-issue the request to resume from it instead of starting over.`,
+        reason: `⚠️ The coding child ended because ${cause}; the branch carries the interrupted work at \`${checkpoint.sha.slice(0, 7)}\` on \`${checkpoint.branch}\`. The next reply in this thread resumes from that checkpoint instead of starting over.`,
         round,
         reviewRounds: next.reviewRounds,
       },
@@ -1766,9 +1876,10 @@ function settleReview(
           },
           notes,
         );
-      // Every gated finding is human-gated (issue 1990): a fix round could
-      // change nothing, so the unit ends held for a person instead.
-      if (allHumanGated(gated)) return end(next, heldEnding(next, round, gated, "approve"), notes);
+      // Every gated finding is human-gated: ask a person and park the live
+      // unit; an answer later opens the fix round with the question attached.
+      if (allHumanGated(gated))
+        return parkHumanGate(next, round, gated, "approve", facts.reviewAskedAt ?? facts.finishedAt ?? s.clock, notes);
       if (next.reviewRounds >= next.input.caps.maxRounds)
         return end(
           next,
@@ -1797,11 +1908,18 @@ function settleReview(
       },
       notes,
     );
-  // Every finding of the round is human-gated (issue 1990): no fix round can
-  // change anything, so the unit ends held for a person's receipt instead of
-  // spending a coding child — or the round cap — on it.
+  // Every finding of the round is human-gated: no fix round can change
+  // anything yet, so park the live unit for a person's answer before asking
+  // the round cap.
   if (allHumanGated(verdict.findings ?? []))
-    return end(next, heldEnding(next, round, verdict.findings ?? [], "request_changes"), notes);
+    return parkHumanGate(
+      next,
+      round,
+      verdict.findings ?? [],
+      "request_changes",
+      facts.reviewAskedAt ?? facts.finishedAt ?? s.clock,
+      notes,
+    );
   if (next.reviewRounds >= next.input.caps.maxRounds)
     return end(
       next,
@@ -2303,12 +2421,14 @@ function roundOnOpenPr(
         },
         [roundNote(round, "aborted")],
       );
-    return reviewAfterRebase({ ...next, lastReviewHead: pushed }, [roundNote(round, "pr_opened")]);
+    return mandatoryReview({ ...next, lastReviewHead: pushed }, [roundNote(round, "pr_opened")]);
   }
+  const hasHumanAnswer = round.kind === "findings" && (s.humanAnswersByRound[round.index]?.length ?? 0) > 0;
   if (round.kind === "findings") {
     // Nothing repushed → nothing to re-review, unless every finding of the
     // last review was declined on the record: that re-review verifies the
-    // arguments and may concede.
+    // arguments and may concede. A person's answer is itself new evidence for
+    // the mandatory re-review, even when accepting it changes no code.
     const codingHead = normalizeHead(head);
     const reviewedAt = normalizeHead(s.lastReviewHead);
     if (codingHead !== undefined && reviewedAt !== undefined && sameCommit(codingHead, reviewedAt)) {
@@ -2339,27 +2459,30 @@ function roundOnOpenPr(
           },
           [roundNote(round, "aborted")],
         );
-      const findings = s.findingsByRound[round.index] ?? [];
-      const dispositions = s.dispositionsByRound[round.index] ?? [];
-      const allDeclined =
-        findings.length > 0 &&
-        findings.every((f) => dispositions.find((d) => d.findingId === f.id)?.disposition === "declined");
-      if (!allDeclined)
-        return end(
-          next,
-          {
-            kind: "aborted",
-            reason: `⚠️ Round ${round.index}'s findings step produced no new head — the branch still sits at \`${codingHead.slice(0, 7)}\`, the commit the review already read, and not every finding was declined on the record, so there is nothing new to re-review.`,
-            round,
-            reviewRounds: next.reviewRounds,
-          },
-          [roundNote(round, "aborted")],
-        );
+      if (!hasHumanAnswer) {
+        const findings = s.findingsByRound[round.index] ?? [];
+        const dispositions = s.dispositionsByRound[round.index] ?? [];
+        const allDeclined =
+          findings.length > 0 &&
+          findings.every((f) => dispositions.find((d) => d.findingId === f.id)?.disposition === "declined");
+        if (!allDeclined)
+          return end(
+            next,
+            {
+              kind: "aborted",
+              reason: `⚠️ Round ${round.index}'s findings step produced no new head — the branch still sits at \`${codingHead.slice(0, 7)}\`, the commit the review already read, and not every finding was declined on the record, so there is nothing new to re-review.`,
+              round,
+              reviewRounds: next.reviewRounds,
+            },
+            [roundNote(round, "aborted")],
+          );
+      }
     }
   }
-  return nextReview({ ...next, ...(head !== undefined ? { lastReviewHead: head } : {}) }, [
-    roundNote(round, "pr_opened"),
-  ]);
+  const reviewed: UnitPipelineState = { ...next, ...(head !== undefined ? { lastReviewHead: head } : {}) };
+  const notes = [roundNote(round, "pr_opened")];
+  if (hasHumanAnswer) return mandatoryReview(reviewed, notes);
+  return nextReview(reviewed, notes);
 }
 
 /** Move the clock and charge the elapsed time to the budget's bucket: a phase
@@ -2421,6 +2544,20 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
             pr: { number: r.pr.prNumber, url: r.pr.url },
             lastReviewHead: entryHead,
           };
+          const answered = r.pr.humanGate;
+          if (answered !== undefined) {
+            const round = Math.max(1, answered.round);
+            const withAnswer: UnitPipelineState = {
+              ...adopted,
+              reviewRounds: round,
+              findingsByRound: { ...adopted.findingsByRound, [round]: answered.findings },
+              humanAnswersByRound: {
+                ...adopted.humanAnswersByRound,
+                [round]: [`${answered.author}: ${answered.answer}`],
+              },
+            };
+            return enterRound(withAnswer, { index: round, kind: "findings" });
+          }
           const checks = r.pr.checks;
           const green =
             checks !== undefined && checks.total > 0 && checks.failed.length === 0 && checks.pending.length === 0;
@@ -2733,7 +2870,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
           reviewRounds: s.reviewRounds,
         });
       const rebased: UnitPipelineState = { ...clocked, lastReviewHead: r.headSha };
-      if (r.outcome === "changed") return reviewAfterRebase(rebased);
+      if (r.outcome === "changed") return mandatoryReview(rebased);
       return enterChecks(rebased, { index: s.reviewRounds, kind: "review" }, []);
     }
     case "merge-wait":
@@ -2785,7 +2922,7 @@ function dispositionFor(s: UnitPipelineState, finding: Finding, round: number):
 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}`;
+  const at = base !== undefined ? `${base.replace(/\/+$/, "")}/${encodeURIComponent(runId)}` : `the 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}).`;
 }
 
@@ -2899,9 +3036,9 @@ export function renderUnitReport(
   // The re-issue line keys on the instance's mark, never on who merges: a
   // generated plan is re-issued with the request's own text, a seeded one by
   // its plan path — and a seeded plan can be a person's merge too.
-  const reissue = s.input.generated
-    ? `To continue, re-issue \`agent:ship\` in this thread with the same text${prUrl ? ` and include the PR URL (${prUrl})` : " — include the PR URL if a PR exists"}.`
-    : `The unit's dependents in this plan stay blocked; the unit runs again when the plan is re-issued.`;
+  const continuation = s.input.generated
+    ? `The pipeline kept this unit's task and branch; the next reply in this thread continues it${prUrl ? ` from the open pull request (${prUrl})` : " from the branch head"}.`
+    : `The unit's dependents in this plan stay blocked; the next run of this plan recognizes the unit's branch and pull request.`;
   const declined = [...(s.dispositionsByRound[e.reviewRounds - 1] ?? [])].filter((d) => d.disposition === "declined");
   const declinedLine = `Declined findings: ${declined.length > 0 ? declined.map((d) => `${d.findingId}${d.note ? ` — ${d.note}` : ""}`).join("; ") : "none"}`;
   const verdictLine = `Verdict: LGTM${s.lastVerdictSummary ? ` — ${s.lastVerdictSummary}` : ""}`;
@@ -2926,7 +3063,7 @@ export function renderUnitReport(
   const checkpointLine = (checkpoint: { branch: string; sha: string } | undefined) =>
     checkpoint === undefined
       ? undefined
-      : `The branch carries the interrupted work at \`${checkpoint.sha.slice(0, 7)}\` on \`${checkpoint.branch}\`; re-issue to resume from it instead of starting over.`;
+      : `The branch carries the interrupted work at \`${checkpoint.sha.slice(0, 7)}\` on \`${checkpoint.branch}\`; the next reply in this thread resumes from it instead of starting over.`;
   switch (e.kind) {
     case "merged":
       if (e.by === "other")
@@ -2982,13 +3119,13 @@ export function renderUnitReport(
       // 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)}`;
+        if (!shows(verbosity, "verbose")) return `⏸️ Held: draft — GitHub still marks the pull request as draft${link}`;
+        const draftContinuation = s.input.generated
+          ? `The pipeline kept the task, branch and pull request${e.pr !== undefined ? ` (${e.pr.url})` : ""}; after GitHub marks it ready, the next reply in this thread resumes at the review round.`
+          : `The unit stays held while GitHub marks the pull request as a draft; ${continuation.charAt(0).toLowerCase()}${continuation.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,
+          draftContinuation,
         ]);
       }
       // The blocked hold (issue 2086): the coding child concluded its round
@@ -3001,28 +3138,19 @@ export function renderUnitReport(
         return join([
           `⏸️ Held after ${rounds}: the coding child of round ${e.round.index} concluded its round blocked instead of opening a pull request — ${e.reason}.${prLine}`,
           writeUpPointer(s, e.round.kind, e.runId),
-          `No renewal was spent and no second coding child ran — a concluded round is not renewed (a renewal continues a budget that ran out mid-work). Next step: your word in this thread — answer what the child raised, and the unit continues from there. ${reissue}`,
+          `No renewal was spent and no second coding child ran — a concluded round is not renewed (a renewal continues a budget that ran out mid-work). The child's answer remains the thread's open question; the next reply is treated as its answer. ${continuation}`,
         ]);
       }
-      // 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
-      // resume path — once the receipt stands on the pull request. That path
-      // fires only when the invocation carries NO new task text: re-issuing
-      // with the task would ADOPT the pull request and run a coding round
-      // 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.
+      // A human-gated row is a question to a person. The enclosing idle keeps
+      // this unit live; either answer surface wakes a fix round carrying both
+      // the typed finding and the attributed answer.
       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;
+      if (!shows(verbosity, "verbose"))
+        return `⏸️ Waiting for you: ${rows}${e.pr !== undefined ? ` — ${e.pr.url}` : ""}`;
       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.`,
+        `⏸️ Waiting for a person 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}. The unit stays live; no unanswered fix round was opened.`,
         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.`,
+        `The next reply in this unit thread or authorized pull request comment becomes the fix round's answer; review then runs again.`,
       ]);
     }
     case "merge_refused":
@@ -3038,8 +3166,8 @@ export function renderUnitReport(
       return join([
         `⚠️ 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.`,
+          ? continuation
+          : "The approved work remains on the branch. This is a bug: the pipeline has no automatic recovery for this refused merge, so the unit's dependents remain blocked.",
       ]);
     case "round_cap": {
       // The quiet copy counts the last review's open findings, only the
@@ -3058,7 +3186,7 @@ export function renderUnitReport(
         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]);
+      return join([headline, splitReport(s), continuation]);
     }
     case "wall_clock_cap":
       if (!shows(verbosity, "verbose")) return `🧢 Out of budget — no approval after ${rounds}.${prLine}`;
@@ -3066,13 +3194,13 @@ export function renderUnitReport(
         `🧢 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),
         splitReport(s),
-        reissue,
+        continuation,
       ]);
     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 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)),
-        aside(reissue),
+        aside(continuation),
       ]);
     case "stopped":
       if (!shows(verbosity, "verbose"))
@@ -3088,7 +3216,7 @@ export function renderUnitReport(
         e.postedReview
           ? "ℹ️ A changes-requested review was posted this round before the stop — its findings stand on the PR."
           : undefined,
-        s.input.idleDays && s.input.idleDays > 0 ? "Next step: reply in this thread to continue." : reissue,
+        continuation,
       ]);
     case "aborted":
       if (!shows(verbosity, "verbose")) return `⚠️ Aborted after ${rounds}: ${e.reason}${prLine}`;
@@ -3101,7 +3229,7 @@ export function renderUnitReport(
         ),
         e.renewal !== undefined ? `🔁 Not renewed: ${e.renewal.line}.` : undefined,
         `⚠️ Ship aborted after ${rounds}.`,
-        reissue,
+        continuation,
       ]);
     case "continued":
       // A segment boundary is the runner continuing — an acknowledgement, verbose
@@ -3111,18 +3239,18 @@ export function renderUnitReport(
       return join([
         writeUpPointer(s, e.round.kind, e.runId),
         s.input.idleDays && s.input.idleDays > 0
-          ? `🔁 The unit's budget ran out with the unit unfinished — ${e.line}. Next step: reply in this thread to continue; ${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}. The next reply in this thread continues it; ${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 `⚠️ Aborted after ${rounds}: this is a bug — the model provider failed twice and no automatic retry remains.${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.`,
         writeUpPointer(s, e.round.kind, s.lastCodingRunId),
-        `⚠️ Ship ended after ${rounds}; re-issue once the provider settles.`,
-        reissue,
+        `⚠️ This is a bug: ship ended after ${rounds} because its automatic provider retry was spent.`,
+        continuation,
       ]);
     case "no_verdict":
       if (!shows(verbosity, "verbose"))
@@ -3131,7 +3259,7 @@ export function renderUnitReport(
         `⚠️ 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]),
         `⚠️ Ship aborted after ${rounds}.`,
-        reissue,
+        continuation,
       ]);
     case "interrupted":
       return join([shipInterruptedNote(prUrl, e.cause, (s.input.idleDays ?? 0) > 0), checkpointLine(e.checkpoint)]);
@@ -3140,7 +3268,7 @@ export function renderUnitReport(
     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.`,
-        aside(reissue),
+        aside(continuation),
       ]);
     case "idle":
       // The old kind's sentence at this copy's level — the report is unchanged