@coreplane/switchboard 1.254.1 → 1.255.0

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

@@ -404,6 +404,11 @@ export interface RoundRef {
   /** Round 0 is the coding round; review round n and its findings step share n. */
   index: number;
   kind: RoundKind;
+  /** The round's attempt when it was re-run (agent-ship item 9, issue 1932):
+   *  2 for round 0's one re-run after a provider transient with nothing
+   *  pushed. Absent on a first attempt; suffixes the round's step names so the
+   *  Workflow's durable cache never hands the re-run the dead attempt's answers. */
+  attempt?: number;
 }
 export type ChildPreset = "coding" | "review";
 
@@ -480,7 +485,10 @@ export type CoordinatorAction =
        *  over a record fact written minutes earlier. */
       pr?: number;
     }
-  | { type: "merge"; step: string; prNumber: number; headSha: string }
+  /** `queued`: the pull request is in the base's merge queue — the bot reads
+   *  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 }
   /** Read the check runs at the reviewed head (record 0055, the round verdict):
    *  the merge door's own reading, folded into the round. `retry` names the
    *  failed checks whose one flake re-run the machine is spending: the bot
@@ -524,6 +532,10 @@ export type ChildFacts =
       leaseStartedAt?: number;
       costUsd?: number | null;
       handoffLists?: Handoff;
+      /** The failure by name off a `failed` run's record (run-history item 57):
+       *  `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 heads the unit's branch on GitHub: nothing, an open pull request, or —
@@ -580,14 +592,22 @@ export type StepReturn =
   | { type: "spawn"; step: string; outcome: "busy"; runId?: string; at: number }
   | { type: "spawn"; step: string; outcome: "refused"; refusal: string; message?: string; at: number }
   | { type: "spawn"; step: string; outcome: "failed"; reason: string; at: number }
+  // The hosted parent's hard stop landed (record 0060; issue 1924): the bot
+  // refuses the spawn over the instance row's stop mark, and the unit ends
+  // `stopped` — nothing more is run.
+  | { type: "spawn"; step: string; outcome: "stopped"; at: number }
   | { type: "wait"; step: string; outcome: "event" | "timeout" }
-  | { type: "read-record"; step: string; run: ChildFacts; at: number }
+  // `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 }
   | { 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
   // fired, or a person merged — so the runner merged nothing (`by: other`).
   | { type: "merge"; step: string; outcome: "merged"; by: "other"; sha: string; mergedAt: string; at: number }
-  | { type: "merge"; step: string; outcome: "pending" | "refused"; reason: string; at: number }
+  /** The 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 }
   /** The checks read at the reviewed head; `checks` absent means GitHub could
    *  not be read, which the machine treats as pending (record 0055). A retry
    *  ask answers `retried` instead: whether the bot dispatched the re-run —
@@ -629,6 +649,20 @@ export function checkFinding(f: CheckFailure): Finding {
   };
 }
 
+/** A merge-queue removal as a finding of the round (issue 2011): the queue's
+ *  reason — a failing check inside the queue, a conflict — rides the findings
+ *  brief exactly as a red check does, severity `blocking` so the level in
+ *  force always counts it, and a fix round follows. */
+export function queueRemovalFinding(reason: string): Finding {
+  return {
+    id: "check:merge-queue",
+    severity: "blocking",
+    file: "merge queue",
+    title: `removed from the merge queue — ${reason}`,
+    check: true,
+  };
+}
+
 /** The check findings of a review round: the rows the checks step appended to
  *  the round's findings, told apart by provenance — the `check` flag only
  *  `checkFinding` sets, never the id: a reviewer's id is a free string, and a
@@ -653,6 +687,20 @@ 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). */
+  | {
+      kind: "held";
+      pr?: PrRef;
+      round: RoundRef;
+      findings: Finding[];
+      verdict: "approve" | "request_changes";
+      reviewRounds: number;
+    }
   | { kind: "merge_refused"; pr: PrRef; reason: string; reviewRounds: number }
   | { kind: "round_cap"; maxRounds: number; reviewRounds: number }
   | {
@@ -710,6 +758,14 @@ export type UnitEnding =
       spent: ShipBudgetSpent;
     }
   | { kind: "no_verdict"; round: RoundRef; reviewRounds: number; finalReply?: string }
+  /** Round 0's coding child died on a provider transient — a model-gateway
+   *  5xx, a cut stream, a gateway timeout, past the harness's retry ladder —
+   *  with nothing pushed, TWICE: the first such death re-ran the round once
+   *  (the ledger row and the branch untouched, a re-run costs only minutes),
+   *  and the second is the ending (agent-ship item 9, issue 1932). Named
+   *  `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: "refused"; refusal: string; message?: string; round: RoundRef; reviewRounds: number }
   /** The unit idles instead of ending (record 0051): with the resolved
@@ -737,18 +793,24 @@ export type UnitEnding =
       reviewRounds: number;
     };
 
-/** The kinds that idle: every ending but the four ended ones — the unit is
+/** The kinds that idle: every ending but the ended ones — the unit is
  *  unfinished (a cap, a stop, an abort, a refused merge, a segment's end) and
- *  a reply could continue it. `merged`, `already_landed`, `merge_ready` and
- *  `refused` never idle: the first two are done, merge-ready waits only for a
- *  person's merge, and a refused child would be refused again. */
-export type IdleWhy = Exclude<UnitEnding["kind"], "idle" | "merged" | "already_landed" | "merge_ready" | "refused">;
+ *  a reply could continue it. `merged`, `already_landed`, `merge_ready`,
+ *  `held` and `refused` never idle: the first two are done, merge-ready waits
+ *  only for a person's merge, held waits only for a person's receipt (a fix
+ *  round could change nothing, so nothing here can continue it), and a
+ *  refused child would be refused again. */
+export type IdleWhy = Exclude<
+  UnitEnding["kind"],
+  "idle" | "merged" | "already_landed" | "merge_ready" | "held" | "refused"
+>;
 
 const NEVER_IDLES: ReadonlySet<UnitEnding["kind"]> = new Set([
   "idle",
   "merged",
   "already_landed",
   "merge_ready",
+  "held",
   "refused",
 ]);
 
@@ -878,9 +940,17 @@ 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";
+      /** 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
+       *  same round is the `transient` ending. */
+      transient?: true;
     }
-  | { at: "merge"; pr: PrRef; headSha: string; n: number; since: number; waitMs: number }
-  | { at: "merge-wait"; pr: PrRef; headSha: string; n: number; since: number; waitMs: number }
+  /** `queued`: the door enqueued the pull request — the base takes changes
+   *  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: "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.
    *  `graced`: a head with no check reported has had its one-chunk grace;
@@ -1025,7 +1095,8 @@ function roundCarve(s: UnitPipelineState, round: RoundRef): Carve {
 export const stepPrefixOf = (unit: string, session: UnitSession | 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) => `${stepPrefix(s)}/${round.index}/${round.kind}`;
+const roundStep = (s: UnitPipelineState, round: RoundRef) =>
+  `${stepPrefix(s)}/${round.index}/${round.kind}${round.attempt !== undefined ? `/a${round.attempt}` : ""}`;
 
 function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
   const unit = s.input.unit.id;
@@ -1149,7 +1220,13 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         timeoutMs: Math.max(MIN, Math.min(MERGE_WAIT_CHUNK_MS, p.waitMs - (s.clock - p.since))),
       };
     case "merge":
-      return { type: "merge", step: `${unit}/merge/${p.n}`, prNumber: p.pr.number, headSha: p.headSha };
+      return {
+        type: "merge",
+        step: `${unit}/merge/${p.n}`,
+        prNumber: p.pr.number,
+        headSha: p.headSha,
+        ...(p.queued === true ? { queued: true as const } : {}),
+      };
     case "merge-wait":
       return {
         type: "wait-checks",
@@ -1194,7 +1271,10 @@ 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;
-  const old = ending as Exclude<UnitEnding, { kind: "idle" | "merged" | "already_landed" | "merge_ready" | "refused" }>;
+  const old = ending as Exclude<
+    UnitEnding,
+    { kind: "idle" | "merged" | "already_landed" | "merge_ready" | "held" | "refused" }
+  >;
   const grant = s.input.grant ?? DEFAULT_GRANT;
   // Unspent: an idle spends no renewal — the wake's segment does (this plan's
   // fifth unit) — so the row says what the grant still holds.
@@ -1234,6 +1314,29 @@ function idleEnding(s: UnitPipelineState, ending: UnitEnding): Extract<UnitEndin
 /** A gated finding as the gate note names it: `F1 (minor)`. */
 const gateLabel = (f: Finding): string => `${f.id} (${f.severity})`;
 
+/** The held decision (issue 1990): the findings the round would act on — the
+ *  gated set on an approve, every finding on a request_changes — are all
+ *  human-gated, read off the reviewer's own flag and never prose. One
+ *  actionable finding beside a human-gated one keeps the fix round: the
+ *  dispositions cover the human-gated row like any other (declined, with the
+ *  person named). An empty set decides nothing. */
+const allHumanGated = (findings: readonly Finding[]): boolean =>
+  findings.length > 0 && findings.every((f) => f.humanGated === true);
+
+const heldEnding = (
+  s: UnitPipelineState,
+  round: RoundRef,
+  findings: Finding[],
+  verdict: "approve" | "request_changes",
+): UnitEnding => ({
+  kind: "held",
+  ...(s.pr !== undefined ? { pr: s.pr } : {}),
+  round,
+  findings,
+  verdict,
+  reviewRounds: s.reviewRounds,
+});
+
 const roundNote = (round: RoundRef, outcome: ShipRoundOutcome): RoundNote => ({
   type: "round",
   index: round.index,
@@ -1332,7 +1435,19 @@ function settleCoding(
   // request (agent-ship items 10 and 15), and only a branch with
   // nothing on it ends the unit with the child's own reason.
   if (facts.status === "failed")
-    return { state: { ...next, phase: { at: "pr-check", round, runId, dead: "failed" } }, notes: [] };
+    return {
+      state: {
+        ...next,
+        phase: {
+          at: "pr-check",
+          round,
+          runId,
+          dead: "failed",
+          ...(facts.failure?.kind === "provider_transient" ? { transient: true as const } : {}),
+        },
+      },
+      notes: [],
+    };
   next = {
     ...next,
     phase: {
@@ -1429,6 +1544,9 @@ 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);
       if (next.reviewRounds >= next.input.caps.maxRounds)
         return end(
           next,
@@ -1457,6 +1575,11 @@ 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.
+  if (allHumanGated(verdict.findings ?? []))
+    return end(next, heldEnding(next, round, verdict.findings ?? [], "request_changes"), notes);
   if (next.reviewRounds >= next.input.caps.maxRounds)
     return end(
       next,
@@ -1500,14 +1623,51 @@ 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. */
+function checksVerdict(
+  checks: RoundChecks | undefined,
+  p: { retried: boolean; graced: boolean },
+):
+  | { kind: "retry"; names: string[] }
+  | { kind: "failed"; failed: CheckFailure[] }
+  | { kind: "pending" }
+  | { kind: "grace" }
+  | { kind: "green" } {
+  if (checks !== undefined && checks.failed.length > 0) {
+    // The flake rule (record 0055): a suspected flake — a test timeout or
+    // runner stall on a shard whose test files the pull request's changed
+    // paths never touch — is re-run once before it becomes a finding. One
+    // real failure among them makes the round's answer already known, so the
+    // re-run is spent only when every failure is a suspect.
+    if (!p.retried && checks.failed.every((f) => f.flakeSuspect === true))
+      return { 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" };
+  // No check reported at the head: one chunk of grace — the first check starts
+  // within minutes where CI exists — then the round proceeds, so a repository
+  // without CI costs one chunk per round and never idles (record 0055).
+  if (checks.total === 0 && !p.graced) return { kind: "grace" };
+  return { kind: "green" };
+}
+
 /** What the checks step answered, folded into the round (record 0055). Pure
  *  over the phase: a retry ask waits for the head to settle and reads again;
- *  an unreadable or pending head waits a chunk inside the step's ask and then
+ *  a failed check becomes a check finding under a round note of its own and
+ *  the findings step runs as for any changes-requested round — never
+ *  merge_ready, never the merge door — as soon as it is read, whatever else
+ *  is still pending (issue 1991); only a head with no failed check waits a
+ *  chunk inside the step's ask on what is unreadable or pending and then
  *  proceeds — the ending's facts read names what is still pending; a head with
- *  no check reported waits one chunk of grace and never more; a failed check
- *  becomes a check finding under a round note of its own and the findings step
- *  runs as for any changes-requested round — never merge_ready, never the
- *  merge door; a green head proceeds with no wait added. */
+ *  no check reported waits one chunk of grace and never more; a green head
+ *  proceeds with no wait added. */
 function settleChecks(
   s: UnitPipelineState,
   p: Extract<Phase, { at: "checks" }>,
@@ -1546,48 +1706,43 @@ function settleChecks(
     }
     return wait({ retried: true });
   }
-  // GitHub unreadable answers as pending and is re-read at the chunk's end
-  // (record 0055); a head still pending or unreadable at the ask's end
-  // proceeds — the ending's facts read names what is still pending, and the
-  // merge door (under `merge: runner`) is the guard that never merges over it.
-  if (checks === undefined || checks.pending.length > 0) {
-    if (s.clock - p.since >= p.waitMs) return approveOutcome(s, []);
-    return wait({});
-  }
-  if (checks.failed.length > 0) {
-    // The flake rule (record 0055): a suspected flake — a test timeout or
-    // runner stall on a shard whose test files the pull request's changed
-    // paths never touch — is re-run once before it becomes a finding. One
-    // real failure among them makes the round's answer already known, so the
-    // re-run is spent only when every failure is a suspect.
-    if (!p.retried && checks.failed.every((f) => f.flakeSuspect === true))
+  const verdict = checksVerdict(checks, p);
+  switch (verdict.kind) {
+    case "retry":
       return {
-        state: { ...s, phase: { ...p, n: p.n + 1, retry: checks.failed.map((f) => f.name) } },
+        state: { ...s, phase: { ...p, n: p.n + 1, retry: verdict.names } },
         notes: [],
       };
-    const findings = [...(s.findingsByRound[round.index] ?? []), ...checks.failed.map(checkFinding)];
-    const next: UnitPipelineState = {
-      ...s,
-      findingsByRound: { ...s.findingsByRound, [round.index]: findings },
-    };
-    // The failed checks get a round note of their own (record 0055) — never
-    // the parser-mismatch gate — and the findings step runs as for any
-    // changes-requested round: dispositions, a fix round, a re-review.
-    const notes: CoordinatorNote[] = [roundNote(round, "checks_failed")];
-    if (next.reviewRounds >= next.input.caps.maxRounds)
-      return end(
-        next,
-        { kind: "round_cap", maxRounds: next.input.caps.maxRounds, reviewRounds: next.reviewRounds },
-        notes,
-      );
-    return enterRound(next, { index: round.index, kind: "findings" }, notes);
+    case "failed": {
+      const findings = [...(s.findingsByRound[round.index] ?? []), ...verdict.failed.map(checkFinding)];
+      const next: UnitPipelineState = {
+        ...s,
+        findingsByRound: { ...s.findingsByRound, [round.index]: findings },
+      };
+      // The failed checks get a round note of their own (record 0055) — never
+      // the parser-mismatch gate — and the findings step runs as for any
+      // changes-requested round: dispositions, a fix round, a re-review.
+      const notes: CoordinatorNote[] = [roundNote(round, "checks_failed")];
+      if (next.reviewRounds >= next.input.caps.maxRounds)
+        return end(
+          next,
+          { kind: "round_cap", maxRounds: next.input.caps.maxRounds, reviewRounds: next.reviewRounds },
+          notes,
+        );
+      return enterRound(next, { index: round.index, kind: "findings" }, notes);
+    }
+    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
+      // (under `merge: runner`) is the guard that never merges over it.
+      if (s.clock - p.since >= p.waitMs) return approveOutcome(s, []);
+      return wait({});
+    case "grace":
+      return wait({ graced: true });
+    case "green":
+      // Green (or none reported after the grace): today's path, no wait added.
+      return approveOutcome(s, []);
   }
-  // No check reported at the head: one chunk of grace — the first check starts
-  // within minutes where CI exists — then the round proceeds, so a repository
-  // without CI costs one chunk per round and never idles (record 0055).
-  if (checks.total === 0 && !p.graced) return wait({ graced: true });
-  // Green (or none reported after the grace): today's path, no wait added.
-  return approveOutcome(s, []);
 }
 
 /** An approve past the checks read: merge_ready for a person, the merge door
@@ -1661,6 +1816,16 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
         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
+      // is re-run once — a fresh attempt under fresh step names — and only a
+      // second transient in the same round is the ending, named `transient`.
+      if (phase.transient && round.kind === "coding" && pr.unrecovered === "no_commits") {
+        if ((round.attempt ?? 1) < 2) return enterRound(s, { ...round, attempt: 2 }, [roundNote(round, "transient")]);
+        return end(s, { kind: "transient", round, runId: phase.runId, reviewRounds: s.reviewRounds }, [
+          roundNote(round, "transient"),
+        ]);
+      }
       // The abort repeats the bot's reason for recovering nothing, and claims
       // no more than the answer carried.
       const why =
@@ -1967,6 +2132,12 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
             round: p.round,
             reviewRounds: s.reviewRounds,
           });
+        case "stopped":
+          // The hosted parent's hard stop (record 0060; issue 1924): the spawn
+          // was refused over the stop mark, so the unit ends stopped here.
+          return end(clocked, { kind: "stopped", mode: "hard", round: p.round, reviewRounds: s.reviewRounds }, [
+            roundNote(p.round, "stopped"),
+          ]);
         case "failed":
           return end(clocked, {
             kind: "aborted",
@@ -2005,6 +2176,21 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
           },
           notes: [],
         };
+      // The hosted parent's hard stop landed while this child ran (record 0060;
+      // issue 1924): the unit ends stopped as the child ends, whatever the
+      // child's own status — the runner runs nothing more of it.
+      if (r.stopped === true)
+        return end(
+          clocked,
+          {
+            kind: "stopped",
+            mode: "hard",
+            round: p.round,
+            reviewRounds: s.reviewRounds,
+            ...(r.run.finalReply !== undefined ? { finalReply: r.run.finalReply } : {}),
+          },
+          [roundNote(p.round, "stopped")],
+        );
       if (r.run.status === "interrupted") {
         // 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
@@ -2064,27 +2250,81 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
           : end(clocked, { kind: "merged", by: "runner", pr: p.pr, sha: r.sha, reviewRounds: s.reviewRounds });
       if (r.outcome === "refused")
         return end(clocked, { kind: "merge_refused", pr: p.pr, reason: r.reason, reviewRounds: s.reviewRounds });
+      if (r.outcome === "removed") {
+        // The queue removed the pull request — a failing check in the queue, a
+        // conflict: the removal reason becomes a finding of the round, like a
+        // red check does through the checks step, and a fix round follows
+        // (issue 2011). With no review run to brief the fix from (a resume
+        // straight at the merge decision) a person decides, the refusal
+        // carrying the queue's own reason.
+        const round: RoundRef = { index: s.reviewRounds, kind: "findings" };
+        if (s.reviewRunByRound[round.index] === undefined)
+          return end(clocked, {
+            kind: "merge_refused",
+            pr: p.pr,
+            reason: `the merge queue removed the pull request: ${r.reason}`,
+            reviewRounds: s.reviewRounds,
+          });
+        const findings = [...(s.findingsByRound[round.index] ?? []), queueRemovalFinding(r.reason)];
+        const next: UnitPipelineState = {
+          ...clocked,
+          findingsByRound: { ...s.findingsByRound, [round.index]: findings },
+        };
+        const notes: CoordinatorNote[] = [roundNote(round, "dequeued")];
+        if (next.reviewRounds >= next.input.caps.maxRounds)
+          return end(
+            next,
+            { kind: "round_cap", maxRounds: next.input.caps.maxRounds, reviewRounds: next.reviewRounds },
+            notes,
+          );
+        return enterRound(next, round, notes);
+      }
       const waited = r.at - p.since;
       if (waited >= p.waitMs)
         return end(clocked, {
           kind: "merge_refused",
           pr: p.pr,
-          reason: `still pending after ${Math.round(waited / MIN)} minutes (${r.reason})`,
+          reason:
+            r.outcome === "enqueued"
+              ? `still in the merge queue after ${Math.round(waited / MIN)} minutes (${r.reason}) — the queue merges it on its own; a re-issued plan finds it merged`
+              : `still pending after ${Math.round(waited / MIN)} minutes (${r.reason})`,
           reviewRounds: s.reviewRounds,
         });
+      // `enqueued` waits like `pending`, marked so every later ask reads the
+      // queue's outcome; the boundary is noted once, when the queue takes it.
+      const queued = r.outcome === "enqueued" ? true : p.queued;
       return {
         state: {
           ...clocked,
-          phase: { at: "merge-wait", pr: p.pr, headSha: p.headSha, n: p.n, since: p.since, waitMs: p.waitMs },
+          phase: {
+            at: "merge-wait",
+            pr: p.pr,
+            headSha: p.headSha,
+            n: p.n,
+            since: p.since,
+            waitMs: p.waitMs,
+            ...(queued === true ? { queued: true as const } : {}),
+          },
         },
-        notes: [],
+        notes:
+          r.outcome === "enqueued" && p.queued !== true
+            ? [roundNote({ index: s.reviewRounds, kind: "review" }, "enqueued")]
+            : [],
       };
     }
     case "merge-wait":
       return {
         state: {
           ...s,
-          phase: { at: "merge", pr: p.pr, headSha: p.headSha, n: p.n + 1, since: p.since, waitMs: p.waitMs },
+          phase: {
+            at: "merge",
+            pr: p.pr,
+            headSha: p.headSha,
+            n: p.n + 1,
+            since: p.since,
+            waitMs: p.waitMs,
+            ...(p.queued === true ? { queued: true as const } : {}),
+          },
         },
         notes: [],
       };
@@ -2292,6 +2532,25 @@ export function renderUnitReport(
       ]
         .filter(Boolean)
         .join("\n");
+    case "held": {
+      // 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.
+      const rows = e.findings.map((f) => `${f.id} (${f.severity}) — ${f.title}`).join("; ");
+      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.`,
+      ]);
+    }
     case "merge_refused":
       // The approved work is on the branch, so the remedy is a person's hand
       // merge, never a re-run: a seeded plan re-issued afterwards finds the
@@ -2363,6 +2622,13 @@ export function renderUnitReport(
         `🔁 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` : ""}.`,
         aside(budgetSplitLine(e.spent, s.input.caps.maxMinutes)),
       ]);
+    case "transient":
+      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)),
+        `⚠️ Ship ended after ${rounds}; re-issue once the provider settles.`,
+        reissue,
+      ]);
     case "no_verdict":
       return join([
         `⚠️ Review round ${e.round.index} ended without a submitted verdict (budget, refusal, or stop) — ship never converts that into a request for changes, so no findings step ran.`,

package/dist/assets/src/core/trace/workerTrace.ts

@@ -54,6 +54,9 @@ export function shimRoute(pathname: string): string | undefined {
   if (pathname.startsWith("/admin/")) return "admin";
   // The artifact copy (deploy/cloudflare/artifactsCopy.ts): the shim's own route, a 1 GB stream.
   if (pathname === "/artifacts/copy") return "artifacts";
+  // The plane's effect push (record 0064): the state Worker's service-binding
+  // call, bearer-gated by the shim and forwarded to the container.
+  if (pathname === "/plane/effects") return "plane";
   // The model proxy's three routes (docs/reference/specs/model-proxy.md): a bounded
   // request per model call, forwarded to the container like everything else.
   if (pathname === "/v1/messages" || pathname === "/v1/chat/completions" || pathname === "/v1/responses")