@coreplane/switchboard 1.248.0 → 1.249.1

package/dist/assets/src/core/modelRegistry.ts

@@ -0,0 +1,51 @@
+// The pi registry as the card's catalog (record 0052): the JSON files the
+// installed `@earendil-works/pi-ai` ships under `providers/data/`, keyed
+// catalog file → wire → model id. A block's `catalog` names the file consulted
+// for its cards (default, the block's own name when such a file exists; `none`
+// for no catalog); a card is looked up under the block's wire first (our
+// `openai-chat` is pi's `openai-completions`), then under any wire, since a
+// card of another wire still carries levels, window and price. Nothing here
+// knows a vendor or a model by name — and nothing here touches Node: this
+// module is the seam's types alone, reachable from the Workers' typechecks
+// through the run events' card type. The file-reading implementation is the
+// bot's ./installedModelRegistry.ts; tests hand an in-memory table.
+
+import type { Wire } from "./provider.js";
+
+/** One card as pi's registry files carry it (only the fields the bot reads). */
+export interface RegistryCard {
+  id?: string;
+  name?: string;
+  /** pi's own wire word (`anthropic-messages`, `openai-completions`, `openai-responses`). */
+  api?: string;
+  reasoning?: boolean;
+  /** Our tiers as pi spells them: `null` refuses a level, an absent tier is
+   *  not named (the card's reader applies pi's rule). */
+  thinkingLevelMap?: Record<string, string | null>;
+  input?: string[];
+  cost?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
+  contextWindow?: number;
+  maxTokens?: number;
+  compat?: Record<string, unknown>;
+}
+
+/** One registry file: pi's wire word → model id → card. */
+export type RegistryFile = Record<string, Record<string, RegistryCard>>;
+
+/** The catalog seam the card resolver reads (record 0052): a card by catalog
+ *  name and wire, or by any wire; a catalog that does not exist reads as no
+ *  card. The production implementation reads pi's installed files; tests hand
+ *  a table. */
+export interface ModelRegistry {
+  /** The card for `model` in `catalog`, under `wire` first then any wire. */
+  card(catalog: string | undefined, wire: Wire, model: string): RegistryCard | undefined;
+  /** The file named, or undefined when the catalog does not exist. */
+  file(catalog: string): RegistryFile | undefined;
+  /** Every catalog file name the library ships. */
+  names(): string[];
+}
+
+/** Our wire word as pi's registry spells it. */
+export function piWireOf(wire: Wire): string {
+  return wire === "openai-chat" ? "openai-completions" : wire;
+}

package/dist/assets/src/core/provider.ts

@@ -93,14 +93,117 @@ export interface Provider {
   complete(req: CompletionRequest): Promise<CompletionResult>;
 }
 
+/** The three wire shapes a provider block may declare (record 0052):
+ *  Anthropic's Messages API, OpenAI's Chat Completions and OpenAI's Responses
+ *  API. `openai-responses` is a declaration only in this slice — the proxy
+ *  still serves two routes (a later slice adds the third) — and a block that names it
+ *  keeps routing through the compatible shape until then. */
+export const WIRES = ["anthropic-messages", "openai-chat", "openai-responses"] as const;
+export type Wire = (typeof WIRES)[number];
+
+/** The legacy `type` words, as the wires they load as for one release. */
+export const WIRE_ALIASES: Readonly<Record<string, Wire>> = {
+  anthropic: "anthropic-messages",
+  "openai-compatible": "openai-chat",
+};
+
+/** One model's operator override under a block's `models.<id>` (record 0052,
+ *  the operator layer of the card). Every field is optional and wins over the
+ *  registry card and the wire defaults where it is set. */
+export interface ProviderModelOverride {
+  /** Our effort tiers → the wire's word, or null to refuse the tier. */
+  levels?: Record<string, string | null>;
+  /** The body field the output cap is spelled with on this model. */
+  capField?: string;
+  /** The model's context window in tokens. */
+  window?: number;
+  /** Which input kinds the model takes. */
+  inputs?: { image?: boolean; document?: boolean };
+  /** The model's cache rule. */
+  cache?: "automatic" | "markers" | "none" | "unknown";
+  /** USD per million tokens, by kind. */
+  price?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
+}
+
 export interface ProviderConfig {
+  /** The legacy wire word: `anthropic` or `openai-compatible` (record
+   *  0052). `wire` is the new spelling; `type` keeps loading as its alias for
+   *  one release. A block may declare either; validation derives the one it
+   *  did not. */
   type: "anthropic" | "openai-compatible";
+  /** The wire the block speaks (`anthropic-messages`, `openai-chat`,
+   *  `openai-responses`). Absent → derived from `type`. */
+  wire?: Wire;
+  /** The vendor whose models this block serves: a name (default, the block's
+   *  own) or `model`, which makes the block an aggregator whose vendor is the
+   *  model id's first segment. */
+  vendor?: string;
+  /** The pi registry file consulted for this block's cards (default, the
+   *  block's own name when such a file exists; `none` otherwise). */
+  catalog?: string;
+  /** Per-model operator overrides, keyed by the model id as the ref spells it. */
+  models?: Record<string, ProviderModelOverride>;
+  /** Extra body fields merged into every request on the wires whose adapter
+   *  takes one. Never a control: not decided, not noted, not in the matrix. */
+  passthrough?: Record<string, unknown>;
   /** Env var holding the API key (never put keys in config files). */
   apiKeyEnv?: string;
   /** Base URL for openai-compatible providers (e.g. http://localhost:11434/v1). */
   baseUrl?: string;
 }
 
+/** The wire a block speaks: its `wire` when declared, else its legacy `type`. */
+export function wireOf(block: Pick<ProviderConfig, "type" | "wire">): Wire {
+  return block.wire ?? WIRE_ALIASES[block.type] ?? "openai-chat";
+}
+
+/** One `<block>/<model>` ref read for the vendor it serves (record 0052):
+ *  the block, the model id as the ref spells it, the vendor, the vendor's own
+ *  id (the model id less a vendor prefix) and which layer named the vendor. */
+export interface VendorRef {
+  block: string;
+  model: string;
+  vendor: string;
+  vendorId: string;
+  vendorSource: "declared" | "model" | "block";
+}
+
+/** The one vendor parse (record 0052): `parseModelRef` is the only other parser of a
+ *  ref. A block that declares a vendor name uses it; a block that declares
+ *  `vendor: model`, or a model id that carries its own vendor prefix
+ *  (`openrouter/anthropic/claude-sonnet-5`), reads the vendor off the id's
+ *  first segment; otherwise the block's own name is the vendor. `catalog`
+ *  never enters: a block named unlike its catalog still serves the vendor the
+ *  declaration or the id names. */
+export function vendorOf(
+  ref: string,
+  blocks: Readonly<Record<string, Pick<ProviderConfig, "vendor">>> = {},
+): VendorRef {
+  const { provider: block, model } = parseModelRef(ref);
+  const declared = blocks[block]?.vendor;
+  const slash = model.indexOf("/");
+  if (declared !== undefined && declared !== "model") {
+    const prefix = `${declared}/`;
+    return {
+      block,
+      model,
+      vendor: declared,
+      vendorId: model.startsWith(prefix) ? model.slice(prefix.length) : model,
+      vendorSource: "declared",
+    };
+  }
+  if (slash > 0 && (declared === "model" || declared === undefined)) {
+    return {
+      block,
+      model,
+      vendor: model.slice(0, slash),
+      vendorId: model.slice(slash + 1),
+      vendorSource: "model",
+    };
+  }
+  return { block, model, vendor: block, vendorId: model, vendorSource: "block" };
+}
+
 /** The env var Anthropic's own SDK reads when an `anthropic` provider block names none. */
 export const ANTHROPIC_API_KEY_ENV = "ANTHROPIC_API_KEY";
 

package/dist/assets/src/core/refusal.ts

@@ -0,0 +1,181 @@
+// The refusal seam (docs/decisions/0054-a-refusal-the-person-caused-is-one-question-with-a-best-guess.md): every refusal the
+// bot makes is one `Refusal` value with a cause, produced by the stage that
+// cannot proceed and rendered in one place (`renderRefusal` in
+// dispatch/reply.ts). A code has exactly one cause, in one table — a code the
+// table does not know is a type error — so the trace, the run record and the
+// door report count refusals by the same names.
+import type { IncomingMessage } from "./types.js";
+
+/** Why the bot refused, in the record's three classes: a different sentence
+ *  from the person would work (`request`), the person may not (`policy`), or
+ *  the bot or a dependency cannot act now (`system`). */
+export type RefusalCause = "request" | "policy" | "system";
+
+/** The bot's best guess at what the person meant: the person's message with
+ *  the fix applied, the line as the person would type it, and the evidence
+ *  that names the match. Produced by a later unit of record 0054's plan;
+ *  carried here so the seam's
+ *  shape is complete from the first unit. */
+export interface Guess {
+  proposal: IncomingMessage;
+  line: string;
+  evidence: string;
+}
+
+/** One cause per code — the closed table `causeOf` reads. The codes are the
+ *  inventory's: the dispatch gates' `refuse(code)` outcomes, the click's four
+ *  `confirmation_*` codes, the two `elsewhere_*` reasons that never reached a
+ *  span before, the references step's eight reasons (request 2, policy 3,
+ *  system 3 — the appendix's split), and `uncaught` for the catch-all. */
+const CAUSE_OF = {
+  // the dispatch gates (dispatcher.ts `refuse(code)`)
+  agent_allowlist: "policy",
+  profile_bounded: "policy",
+  repo_not_visible: "policy",
+  repo_unverified: "system",
+  repo_not_onboarded: "request",
+  repo_access: "policy",
+  pr_head_unknown: "system",
+  branch_moved: "system",
+  coordinator_thread_live: "system",
+  live_agent_allowlist: "policy",
+  follow_up_refused: "request",
+  elsewhere_agent_allowlist: "policy",
+  elsewhere_follow_up_refused: "request",
+  which_branch: "request",
+  workspace_lost: "system",
+  ship_budget: "request",
+  setup_failed: "system",
+  // the click on a confirmation (confirm.ts)
+  confirmation_used: "request",
+  confirmation_expired: "request",
+  confirmation_foreign: "policy",
+  confirmation_unreadable: "system",
+  // the references step's eight reasons (record 0037: one sentence, eight codes)
+  reference_over_cap: "request",
+  reference_rate_limited: "request",
+  reference_guest: "policy",
+  reference_not_a_member: "policy",
+  reference_denied: "policy",
+  reference_timed_out: "system",
+  reference_never: "system",
+  reference_fetch_failed: "system",
+  // the catch-all: an uncaught throw in dispatch()
+  uncaught: "system",
+  // the ship preflight's nine results (record 0054's plan): the old
+  // `ship_preflight` code is kept as these codes' prefix, so a query on the
+  // old code still finds them; the sentence did not split with the code.
+  ship_preflight_channel: "system",
+  ship_preflight_permission: "policy",
+  ship_preflight_no_repo: "request",
+  ship_preflight_pr_unreachable: "system",
+  ship_preflight_pr_facts: "system",
+  ship_preflight_fork_head: "request",
+  ship_preflight_head_unknown: "system",
+  ship_preflight_closed_resume: "request",
+  ship_preflight_no_task: "request",
+  // the plan hand-off's fifteen sentences (two share `plan_history_unavailable`)
+  plan_base_unknown: "request",
+  plan_routed_seed: "request",
+  plan_id_invalid: "request",
+  plan_unreadable: "request",
+  plan_no_units: "request",
+  plan_units_unknown: "request",
+  plan_runner_state_unknown: "system",
+  plan_runner_live: "system",
+  plan_runner_state_unread: "system",
+  plan_units_merged: "request",
+  plan_history_unavailable: "system",
+  plan_runner_conflict: "system",
+  plan_instance_orphaned: "system",
+  plan_start_failed: "system",
+  // the directive and resolve parsers' thrown errors (A6 of the inventory)
+  directive_agent: "request",
+  directive_effort: "request",
+  directive_budget: "request",
+  directive_severity: "request",
+  directive_renewals: "request",
+  provider_unknown: "request",
+  // the model card's refusal (record 0052, model-proxy item 11): a control the
+  // resolved card does not take, named before any card or model call
+  model_card_refused: "request",
+  // a follow-up dropped because the run it was folded into was stopped
+  follow_up_dropped: "system",
+  // the typed-command codes (`InvokeErrorCode`): `chatErrorLine` renders these
+  // through the renderer's one line shape; the cause rides `CommandError`.
+  command_unauthorized: "policy",
+  command_invalid_input: "request",
+  command_not_found: "request",
+  command_conflict: "system",
+  command_unavailable: "system",
+  command_busy: "system",
+  command_internal: "system",
+  // the resident Worker's JSON errors, at the moment the bot receives them
+  // (record 0054): the cause is read from the Worker's `error` prefix.
+  resident_attach_rejected: "request",
+  resident_attach_failed: "system",
+} as const satisfies Record<string, RefusalCause>;
+
+/** Every code a refusal may carry. A new refusal site adds its code here with
+ *  its one cause; an unknown code does not compile. */
+export type RefusalCode = keyof typeof CAUSE_OF;
+
+/** The one cause of a code — exhaustive over the union above. */
+export function causeOf(code: RefusalCode): RefusalCause {
+  return CAUSE_OF[code];
+}
+
+/** Every code the table knows, for tests and reports. */
+export const REFUSAL_CODES: readonly RefusalCode[] = Object.keys(CAUSE_OF) as RefusalCode[];
+
+/** One refusal: the cause, the code, the sentence the person reads (built by
+ *  the producing site, byte-identical to what it said before the seam), the
+ *  best guess when the site holds one, and the way forward when the cause is
+ *  `policy` and the text does not already carry it. */
+export interface Refusal {
+  cause: RefusalCause;
+  code: RefusalCode;
+  text: string;
+  guess?: Guess;
+  wayForward?: string;
+}
+
+/** Build a `Refusal` for a code: the cause comes from the one table. */
+export function refusalOf(code: RefusalCode, text: string, extra?: Pick<Refusal, "guess" | "wayForward">): Refusal {
+  return { cause: causeOf(code), code, text, ...(extra ?? {}) };
+}
+
+/** The one line a `Refusal` reads as, shared by the async renderer and the
+ *  string-shaped surfaces (`chatErrorLine`): the producer's own text, plus the
+ *  way forward when the cause is `policy` and one was set apart. */
+export function refusalLine(refusal: Refusal): string {
+  if (refusal.cause === "policy" && refusal.wayForward) return `${refusal.text} ${refusal.wayForward}`;
+  return refusal.text;
+}
+
+/** A typed command's error code as a refusal code with its one cause. */
+export function commandRefusalCode(
+  code: "unauthorized" | "invalid_input" | "not_found" | "conflict" | "unavailable" | "busy" | "internal",
+): RefusalCode {
+  return `command_${code}`;
+}
+
+/** The cause the Worker's `error` prefix names (record 0054): a wrong or missing ref is
+ *  the person's to fix (`request`); everything else is the machinery's —
+ *  `op-unavailable` included: the Worker says it when its command table has no
+ *  entry for the op the bot sent, a version skew between bot and Worker, not a
+ *  sentence the person could reword. */
+export function residentErrorCause(error: string): RefusalCause {
+  const prefix = error.split(":", 1)[0]?.trim();
+  return prefix === "needs-ref" || prefix === "unknown-ref" ? "request" : "system";
+}
+
+/** A refusal as a throwable, for producers whose call shape is a throw. */
+export class RefusalError extends Error {
+  readonly refusal: Refusal;
+  constructor(refusal: Refusal) {
+    super(refusal.text);
+    this.name = "RefusalError";
+    this.refusal = refusal;
+  }
+}

package/dist/assets/src/core/runEvents.ts

@@ -3,6 +3,7 @@
 // tsconfigs — importing prDescription.ts would drag zod into those graphs.
 import type { PrDescription, RenderedPointer } from "./prDescriptionTypes.js";
 import type { HarnessScope } from "./harness/scope.js";
+import type { ModelCard } from "./modelCard.js";
 
 /** The `pr_description` review artifact minus the event envelope
  *  (docs/reference/specs/reading-diff.md item 7). */
@@ -122,12 +123,24 @@ export type RunNoteKind =
    *  (docs/reference/specs/run-history.md item 37); the summary says how many calls were
    *  in flight at the kill and how each was settled. Published by the runner. */
   | "resumed"
+  /** A control was decided against the model card and is not native (record
+   *  0052): a fallback (`applied` differs from `asked`, `vouched` true) or
+   *  an unvouched send (`vouched` false). One note per degraded control,
+   *  published by the dispatcher before the first turn. `why` says what the
+   *  card could not vouch for; `summary` is the human line. */
+  | "control_degraded"
   /** What the run's session seed could not do (docs/reference/specs/session-log.md
    *  item 9): the log could not be read so the run seeds from the channel, the
    *  newest turn alone was over the seed budget, the previous run's end was
    *  unknown so no line since could be told apart. One note per reason,
    *  published by the dispatcher before the first turn. */
   | "seed"
+  /** This run is a question's Yes (record 0054;
+   *  docs/reference/specs/run-history.md item 2): the stored proposal went
+   *  back through `dispatch()` as the requester, and the summary names the
+   *  question's refusal code. Published by the dispatcher before the first
+   *  turn. */
+  | "redispatch"
   /** A coding run pushed onto a branch that already heads an open PR without
    *  resubmitting the PR description, and the same run is being given one
    *  bounded extra model turn to submit it (docs/reference/specs/pr-description.md
@@ -217,6 +230,18 @@ export type RunNoteKind =
    *  item 7): the summary names the tool and the rule; the model read the same
    *  reason as the tool's result. Published by the bot's authorize route. */
   | "tool_refused"
+  /** OpenCode withdrew a pending ask before the gate's reply to it landed
+   *  (harness.md item 2): the server answered the reply 404 and its pending
+   *  asks no longer listed the ask — the gate refused a sibling call of the
+   *  same step, and at a reject the binary declines every other pending ask
+   *  (`packages/core/src/permission.ts:203-220` at the pinned v2.0.3) and
+   *  ends their step (measured in `opencode/testing/realDriver.test.ts`).
+   *  The summary names the call, the reply the gate had decided and the
+   *  sibling's refusal when the step has one (or says no refusal is on the
+   *  record). Information, not a failure: nothing ran that the gate did not
+   *  decide, the loop is not stopped, and the step ends by the server's word.
+   *  Published by the OpenCode bridge. */
+  | "ask_withdrawn"
   /** An OpenCode tool settled under a step this loop never saw start and the
    *  settle was set aside (harness.md item 13): an earlier execution's late
    *  result — the pinned binary's ordinary shape after a hung call's interrupt
@@ -269,7 +294,9 @@ export const RUN_NOTE_KINDS = [
   "mcp_unavailable",
   "follow_up",
   "resumed",
+  "control_degraded",
   "seed",
+  "redispatch",
   "description_turn",
   "verdict_turn",
   "cold_sandbox",
@@ -283,6 +310,7 @@ export const RUN_NOTE_KINDS = [
   "harness_error",
   "policy_refusal",
   "tool_refused",
+  "ask_withdrawn",
   "settle_set_aside",
   "tool_unnamed",
   "directory_reached",
@@ -389,6 +417,7 @@ export function isHeadMaterial(event: RunEvent): boolean {
         event.kind === "mcp_unavailable" ||
         event.kind === "spans_dropped" ||
         event.kind === "cold_sandbox" ||
+        event.kind === "control_degraded" ||
         event.kind === "ledger_untracked" ||
         event.kind === "rebind_refused"
       );
@@ -525,6 +554,14 @@ export type RunEvent =
       summary: string;
       mode?: StopMode;
       actor?: RunActor;
+      /** On a `control_degraded` note only (record 0052): which control,
+       *  the word asked, the word applied, whether a layer vouched for the
+       *  applied word, and what the card could not vouch for. */
+      control?: string;
+      asked?: string;
+      applied?: string;
+      vouched?: boolean;
+      why?: string;
       /** On a `spans_dropped` note only (docs/reference/specs/tracing.md): the runner-clock
        *  interval the dropped setup records covered — a `not recorded` loss. */
       from?: number;
@@ -624,6 +661,12 @@ export type RunEvent =
        *  written before the word was a scope setting. */
       harnessScope?: HarnessScope;
       effort?: string;
+      /** The model card this run resolved before its first call (record
+       *  0052): the wire, vendor, levels, cap field, window, inputs, cache rule
+       *  and price source, each with the layer that named it. Absent on a
+       *  command run and on a record written before the card existed.
+       *  Additive. */
+      card?: ModelCard;
       repo?: string;
       ref?: string;
       pr?: number;

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

@@ -30,7 +30,7 @@
 // arrive in the input rather than from the agent registry.
 
 import type { ShipRoundOutcome } from "../runEvents.js";
-import type { Handoff } from "./handoff.js";
+import type { Handoff, HandoffLanded } from "./handoff.js";
 import { progressOf, renderRenewal, renewalDecision, type PushedHeadFact, type RenewalDecision } from "./renewal.js";
 import type { RunStatus } from "../runRecord.js";
 import { normalizeHead, sameCommit } from "../reviewedHead.js";
@@ -504,8 +504,21 @@ export type PrCheck =
        *  the base and the head) or `no_base` (the instance names no base to
        *  open against, so no create was tried). Absent on a plain check. */
       unrecovered?: "no_commits" | "no_base";
+      /** On a plain check: the branch's commits over the base as GitHub
+       *  compares them, when the bot could read them. Zero beside a handoff
+       *  naming where the scope landed is the `already_landed` ending
+       *  (agent-ship item 12); absent, the fact is unknown and never claimed. */
+      aheadOfBase?: number;
+    }
+  | {
+      state: "open";
+      prNumber: number;
+      url: string;
+      headSha?: string;
+      autoMergeEnabled?: boolean;
+      /** The check runs at the head, when the read asked for them (the ending's facts). */
+      checks?: CommitChecksFacts;
     }
-  | { state: "open"; prNumber: number; url: string; headSha?: string; autoMergeEnabled?: boolean }
   | { state: "merged"; prNumber: number; url: string; sha: string; mergedAt: string };
 
 /** What a step answered. Every bot answer carries `at`, the bot's clock — the machine's time. */
@@ -536,6 +549,11 @@ export type StepReturn =
 export type UnitEnding =
   | { kind: "merged"; by: "runner"; pr: PrRef; sha: string; reviewRounds: number }
   | { kind: "merged"; by: "other"; pr: PrRef; sha: string; mergedAt: string; reviewRounds: number }
+  /** Round 0 found the unit's scope already on the base (agent-ship item 12):
+   *  the coding child's handoff names where it landed and the branch has no
+   *  commits over the base, so there is no pull request to open or review.
+   *  The unit is done and its dependents start on a base that carries it. */
+  | { kind: "already_landed"; landed: HandoffLanded[]; round: RoundRef; runId: string; reviewRounds: number }
   | { kind: "merge_ready"; pr: PrRef; reviewRounds: number }
   | { kind: "merge_refused"; pr: PrRef; reason: string; reviewRounds: number }
   | { kind: "round_cap"; maxRounds: number; reviewRounds: number }
@@ -1268,15 +1286,26 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
         [roundNote(round, "aborted")],
       );
     }
-    // Round 0 ended without a pull request: the segment is over with the unit
-    // unfinished, and the grant decides whether the next opens (decision
-    // 0046, Renewal). Progress is read off the child's record — a head pushed
-    // to the unit's branch since the segment started, or a handoff that moved —
-    // never off its words; the decision then asks the grant's count, the cap
-    // and the fit, in that order, and a refusal names the clause. A plain
-    // abort keeps its old shape when nothing was pushed under a grant of zero:
-    // a clarifying question is not a stop to explain.
     if (round.index === 0) {
+      // The scope already landed (agent-ship item 12): the child's handoff
+      // names where, and the branch carries no commits over the base — two
+      // facts off the record and GitHub, never the child's prose alone. There
+      // is nothing to open, review or renew: the unit is done. Either fact
+      // missing (a handoff that names no landing, commits on the branch, a
+      // compare the bot could not read) leaves the round-0 ending below.
+      const landed = phase.childHandoff?.landed ?? [];
+      if (landed.length > 0 && pr.aheadOfBase === 0)
+        return end(s, { kind: "already_landed", landed, round, runId: phase.runId, reviewRounds: s.reviewRounds }, [
+          roundNote(round, "completed"),
+        ]);
+      // Round 0 ended without a pull request: the segment is over with the unit
+      // unfinished, and the grant decides whether the next opens (decision
+      // 0046, Renewal). Progress is read off the child's record — a head pushed
+      // to the unit's branch since the segment started, or a handoff that moved —
+      // never off its words; the decision then asks the grant's count, the cap
+      // and the fit, in that order, and a refusal names the clause. A plain
+      // abort keeps its old shape when nothing was pushed under a grant of zero:
+      // a clarifying question is not a stop to explain.
       const grant = s.input.grant ?? DEFAULT_GRANT;
       const session = s.input.session;
       const progress = progressOf({
@@ -1656,6 +1685,30 @@ function splitReport(s: UnitPipelineState): string {
 export interface MergeReadyFacts {
   autoMergeEnabled?: boolean;
   merged?: { sha: string; mergedAt: string };
+  /** The check runs at the approved head as the merge door reads them (record 0055). */
+  checks?: CommitChecksFacts;
+}
+
+/** The check runs at one commit: how many, which still run, which failed. */
+export interface CommitChecksFacts {
+  total: number;
+  pending: string[];
+  failed: string[];
+}
+
+/** The merge-ready report's headline is a claim about the approved head
+ *  (record 0055): a failed check is never called merge-ready, a pending one
+ *  is named, green is said, and without the fact the line is unchanged. */
+function mergeReadyHeadline(rounds: string, url: string, checks: CommitChecksFacts | undefined): string {
+  if (checks === undefined) return `✅ Merge-ready after ${rounds}: ${url}`;
+  if (checks.failed.length > 0) {
+    const pending = checks.pending.length > 0 ? `; pending: ${checks.pending.join(", ")}` : "";
+    return `⚠️ Approved but not merge-ready after ${rounds}: ${url} — CI is red at the approved head: ${checks.failed.join(", ")}${pending}. Fix it and re-review, or rerun a flake; the runner calls a head merge-ready only over green checks.`;
+  }
+  if (checks.pending.length > 0)
+    return `✅ Approved after ${rounds}: ${url} — checks pending at the approved head: ${checks.pending.join(", ")}; merge-ready once they pass.`;
+  if (checks.total === 0) return `✅ Merge-ready after ${rounds}: ${url} — no check reported at the approved head.`;
+  return `✅ Merge-ready after ${rounds}: ${url} — ${checks.total} check${checks.total === 1 ? "" : "s"} green at the approved head.`;
 }
 
 export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts): string {
@@ -1703,9 +1756,16 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
         ...(skippedLine ? [skippedLine] : []),
         declinedLine,
       ].join("\n");
+    case "already_landed":
+      // No compare link, no renewal line, no re-issue prompt: there was
+      // nothing to ship, so none of them has a question to answer.
+      return `✅ Already on \`${s.input.base}\`: the unit's scope landed before this attempt — ${e.landed.map((l) => `${l.what} (${l.where})`).join("; ")}. The coding child (run ${e.runId}) found it there and pushed nothing of its own: \`${s.input.unit.branch}\` has no commits over \`${s.input.base}\`, so there is no pull request to open or review. The unit is done and its dependents start on a base that carries it.`;
     case "merge_ready":
       return [
-        `✅ Merge-ready after ${rounds}: ${e.pr.url}`,
+        // A merge that already happened outranks the checks: there is no head left to gate.
+        facts?.merged
+          ? `✅ Merge-ready after ${rounds}: ${e.pr.url}`
+          : mergeReadyHeadline(rounds, e.pr.url, facts?.checks),
         verdictLine,
         levelLine,
         grantLine,
@@ -1721,9 +1781,17 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
             : "Remaining gate: a person's merge — the runner merges only when the instance's `merge` field says runner, and ship never approves.",
       ].join("\n");
     case "merge_refused":
+      // The approved work is on the branch, so the remedy is a person's hand
+      // merge, never a re-run: a seeded plan re-issued afterwards finds the
+      // merged pull request (the pre-check's `merged` by other, or
+      // `already_landed`) and moves on to the dependents. The generated
+      // plan's line already says to re-issue with the PR URL, which takes the
+      // same recognition path.
       return join([
         `⚠️ The review approved ${e.pr.url} but the runner did not merge it: ${e.reason}. A person decides what becomes of the pull request.`,
-        reissue,
+        s.input.generated
+          ? reissue
+          : `The approved work is on the branch: rebase or fix it, push, and merge it by hand. Then re-issue the plan naming the remaining units — a unit whose pull request has merged is recognized and not run again, and its dependents start from there.`,
       ]);
     case "round_cap":
       return join([