@coreplane/switchboard 1.260.1 → 1.260.3

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,
@@ -458,7 +459,7 @@ export function cursorFinished(cursor: PlanCursor): boolean {
  *  findings dispatched into the unit thread as `agent:coding`, so the coding
  *  session there continues with them (record 0034). Never a `fix` child briefed
  *  from the review. */
-export type RoundKind = "coding" | "review" | "findings";
+export type RoundKind = "coding" | "review" | "findings" | "rebase";
 export interface RoundRef {
   /** Round 0 is the coding round; review round n and its findings step share n. */
   index: number;
@@ -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,10 +507,22 @@ 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[];
+    }
+  | {
+      kind: "rebase";
+      unit: string;
+      pr: number;
+      headSha: string;
+      base: string;
     };
 
 export interface PrRef {
@@ -515,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 =
@@ -549,6 +578,9 @@ export type CoordinatorAction =
    *  the queue's outcome (merged, still queued, or removed with the reason)
    *  instead of attempting the squash. */
   | { type: "merge"; step: string; prNumber: number; headSha: string; queued?: true }
+  /** Rung one of an approved head's rebase: git first. A conflict alone buys
+   *  the runner's coding round; a clean changed patch returns to review. */
+  | { type: "rebase"; 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; `refire`
@@ -567,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 };
@@ -649,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 };
 
@@ -678,7 +724,15 @@ export type StepReturn =
   | { type: "merge"; step: string; outcome: "merged"; by: "other"; sha: string; mergedAt: string; at: number }
   /** The door enqueued the pull request (or found it still queued), or the
    *  queue removed it — the reason is the queue's own (issue 2011). */
-  | { type: "merge"; step: string; outcome: "pending" | "refused" | "enqueued" | "removed"; reason: string; at: number }
+  | {
+      type: "merge";
+      step: string;
+      outcome: "pending" | "refused" | "conflict" | "enqueued" | "removed";
+      reason: string;
+      at: number;
+    }
+  | { type: "rebase"; step: string; outcome: "carried" | "changed"; headSha: string; at: number }
+  | { type: "rebase"; step: string; outcome: "conflict" | "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). Effect
    *  asks answer `retried` or `refired` instead; false still spends that one
@@ -775,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;
@@ -920,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
@@ -927,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;
 
@@ -996,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. */
@@ -1090,6 +1147,7 @@ type Phase =
    *  only through a merge queue (issue 2011) — so every later ask reads the
    *  queue's outcome instead of attempting the squash again. */
   | { at: "merge"; pr: PrRef; headSha: string; n: number; since: number; waitMs: number; queued?: true }
+  | { at: "rebase"; pr: PrRef; headSha: string; n: number }
   | { at: "merge-wait"; pr: PrRef; headSha: string; n: number; since: number; waitMs: number; queued?: true }
   /** 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.
@@ -1135,6 +1193,9 @@ export interface UnitPipelineState {
   readonly phase: Phase;
   /** Review rounds started so far. */
   readonly reviewRounds: number;
+  /** Approved-head rebases attempted in this run. Each fresh conflict may buy
+   *  one fix round; the run's remaining lease, not pull-request lifetime, is the bound. */
+  readonly rebaseAttempts: number;
   readonly pr?: PrRef;
   readonly lastReviewHead?: string;
   readonly lastVerdictSummary?: string;
@@ -1143,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. */
@@ -1186,19 +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 = {
@@ -1230,11 +1303,8 @@ 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 {
-  return carve(
-    remainingMs(s),
-    { kind: round.kind, index: loopPosition(loopOf(s), round.kind, round.index) },
-    loopOf(s),
-  );
+  const kind = round.kind === "rebase" ? "findings" : round.kind;
+  return carve(remainingMs(s), { kind, index: loopPosition(loopOf(s), kind, round.index) }, loopOf(s));
 }
 
 /** The prefix every step of this pipeline is named under: the unit id, a
@@ -1270,27 +1340,44 @@ function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
     };
   }
   const pr = s.pr!.number;
+  if (round.kind === "rebase") {
+    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 } : {}),
   };
@@ -1380,6 +1467,13 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         headSha: p.headSha,
         ...(p.queued === true ? { queued: true as const } : {}),
       };
+    case "rebase":
+      return {
+        type: "rebase",
+        step: `${unit}/rebase/${p.n}`,
+        prNumber: p.pr.number,
+        headSha: p.headSha,
+      };
     case "merge-wait":
       return {
         type: "wait-checks",
@@ -1424,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;
@@ -1482,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,
@@ -1491,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,
@@ -1534,6 +1670,14 @@ function enterRound(s: UnitPipelineState, round: RoundRef, notes: CoordinatorNot
   };
 }
 
+/** 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);
+}
+
 /** The next review round, or the round cap. */
 function nextReview(s: UnitPipelineState, notes: CoordinatorNote[] = []): Transition {
   if (s.reviewRounds >= s.input.caps.maxRounds)
@@ -1597,13 +1741,16 @@ 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,
       {
@@ -1729,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,
@@ -1760,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,
@@ -1987,6 +2142,21 @@ function settleChecks(
   }
 }
 
+/** Re-enter the approved head's rebase step. The attempt count belongs to
+ *  this run, not to the pull request: every later base move is a fresh
+ *  conflict, while the one pipeline lease remains the hard bound. */
+export function reenterApprovedRebase(s: UnitPipelineState): UnitPipelineState {
+  if (s.pr === undefined || s.lastReviewHead === undefined)
+    throw new Error("an approved rebase needs the pull request and reviewed head");
+  const { ending: _ending, ...open } = s;
+  const n = s.rebaseAttempts + 1;
+  return {
+    ...open,
+    rebaseAttempts: n,
+    phase: { at: "rebase", pr: s.pr, headSha: s.lastReviewHead, n },
+  };
+}
+
 /** 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 {
@@ -2237,10 +2407,28 @@ function roundOnOpenPr(
   const { round } = phase;
   const head = pr.headSha ?? phase.childHead;
   const next: UnitPipelineState = { ...s, pr: { number: pr.prNumber, url: pr.url } };
+  if (round.kind === "rebase") {
+    const pushed = normalizeHead(head);
+    const approved = normalizeHead(s.lastReviewHead);
+    if (pushed === undefined || (approved !== undefined && sameCommit(pushed, approved)))
+      return end(
+        next,
+        {
+          kind: "aborted",
+          reason: `⚠️ Rebase round ${round.attempt ?? 1} left the approved head unchanged, so the conflict still has no resolution to review.`,
+          round,
+          reviewRounds: next.reviewRounds,
+        },
+        [roundNote(round, "aborted")],
+      );
+    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)) {
@@ -2271,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
@@ -2353,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;
@@ -2577,6 +2782,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
               reviewRounds: s.reviewRounds,
             })
           : end(clocked, { kind: "merged", by: "runner", pr: p.pr, sha: r.sha, reviewRounds: s.reviewRounds });
+      if (r.outcome === "conflict") return { state: reenterApprovedRebase(clocked), notes: [] };
       if (r.outcome === "refused")
         return end(clocked, { kind: "merge_refused", pr: p.pr, reason: r.reason, reviewRounds: s.reviewRounds });
       if (r.outcome === "removed") {
@@ -2641,6 +2847,32 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
             : [],
       };
     }
+    case "rebase": {
+      const r = ret as Extract<StepReturn, { type: "rebase" }>;
+      if (r.outcome === "refused")
+        return end(clocked, {
+          kind: "merge_refused",
+          pr: p.pr,
+          reason: r.reason,
+          reviewRounds: s.reviewRounds,
+        });
+      if (r.outcome === "conflict")
+        return enterRound(clocked, {
+          index: s.reviewRounds,
+          kind: "rebase",
+          attempt: p.n,
+        });
+      if (!("headSha" in r))
+        return end(clocked, {
+          kind: "merge_refused",
+          pr: p.pr,
+          reason: "the rebase resolver returned no head",
+          reviewRounds: s.reviewRounds,
+        });
+      const rebased: UnitPipelineState = { ...clocked, lastReviewHead: r.headSha };
+      if (r.outcome === "changed") return mandatoryReview(rebased);
+      return enterChecks(rebased, { index: s.reviewRounds, kind: "review" }, []);
+    }
     case "merge-wait":
       return {
         state: {
@@ -2764,7 +2996,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}\`: \`pulls rebase ${url}\` rebases it onto \`${base}\` (an unchanged patch carries the approval). The approved work stands.`;
+    return `⚠️ Approved but not merge-ready after ${rounds}: ${url} — the head conflicts with \`${base}\`; the pipeline runner owns the rebase (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.`;
@@ -2909,25 +3141,16 @@ export function renderUnitReport(
           `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}`,
         ]);
       }
-      // 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.`,
+        `Reply in this unit thread or comment on the pull request with the receipt. The answer and finding become the fix round's brief, then review runs again.`,
       ]);
     }
     case "merge_refused":