@coreplane/switchboard 1.253.0 → 1.254.1

package/dist/assets/src/core/plane/decide.ts

@@ -0,0 +1,203 @@
+// The plane's decider (docs/reference/specs/orchestration-plane.md, the
+// decider items; record 0064, "Where it lives"): one pure function over a
+// closed event union and a closed effect union. The ledger object reads its
+// state, calls `decide` and commits the writes and the effects inside ONE
+// `transactionSync`, so a decision and its consequences land together or not
+// at all. Node-free by design, like `table.ts`: no clock, no io, no ids it
+// did not derive from its inputs — the same event over the same state is the
+// same answer, which is what the shadow comparison and the tests rest on.
+
+/** The three stages an ask is judged at (record 0064): the bot's admission
+ *  door, the plan runner's seed door, the resident's seat. this unit decides the
+ *  admission stage alone; the others' conditions arrive with their units. */
+export type PlaneStage = "admission" | "runner" | "resident";
+
+/** A queue condition: what must become true before the row may run. Each is
+ *  flipped by an event the plane already sees, never polled. The union grows
+ *  one member per stage as the later units land. */
+export type PlaneCondition = { kind: "thread_free"; threadKey: string; met: boolean };
+
+/** One queued ask: the `plane_queue` row. `position` counts the waiting rows
+ *  ahead of it on the same conditions when it queued — the number a person is
+ *  told, never recomputed for them. */
+export interface PlaneQueueRow {
+  runId: string;
+  requester: string;
+  threadKey: string;
+  stage: PlaneStage;
+  /** The stored request, replayed verbatim when the row is admitted (the transport unit). */
+  request: Record<string, unknown>;
+  conditions: PlaneCondition[];
+  position: number;
+  queuedAt: number;
+  state: "waiting" | "admitted" | "withdrawn";
+}
+
+/** What the decider knows: the queue and the threads with a live run. The
+ *  object builds it from its own tables inside the same transaction that
+ *  commits the answer. */
+export interface PlaneState {
+  queue: PlaneQueueRow[];
+  liveThreads: string[];
+}
+
+export function emptyPlaneState(): PlaneState {
+  return { queue: [], liveThreads: [] };
+}
+
+/** The closed event union. `ask`: may this run start now; `sealed`: a thread's
+ *  live run ended (the ledger's seal, the event that flips `thread_free`);
+ *  `withdraw`: the requester gave the wait up (`runs stop` on a queued id, the transport unit). */
+export interface PlaneAskEvent {
+  kind: "ask";
+  at: number;
+  runId: string;
+  requester: string;
+  threadKey: string;
+  stage: PlaneStage;
+  request: Record<string, unknown>;
+}
+export type PlaneEvent =
+  PlaneAskEvent | { kind: "sealed"; at: number; threadKey: string } | { kind: "withdraw"; at: number; runId: string };
+
+/** The closed effect union: what the bot is asked to do, offered on its
+ *  heartbeat and reclaim answers and acknowledged by id (`/plane/ack`). The
+ *  id is derived from the run, so a duplicate offer after a roll is the same
+ *  effect, acknowledged once. The transport unit adds execution; this one only shapes and stores. */
+export type PlaneEffect = {
+  id: string;
+  kind: "admit";
+  runId: string;
+  threadKey: string;
+  request: Record<string, unknown>;
+};
+
+/** What the object must persist beside the returned state — the decider names
+ *  the rows, the object owns the SQL, both inside one `transactionSync`. */
+export type PlaneWrite =
+  | { table: "plane_queue"; op: "put"; row: PlaneQueueRow }
+  | { table: "plane_queue"; op: "state"; runId: string; state: PlaneQueueRow["state"] }
+  | { table: "plane_effects"; op: "offer"; effect: PlaneEffect; at: number };
+
+/** The bot's own outcome for one dispatch, posted to `POST /plane/outcome`
+ *  under `plane.admission: shadow` (orchestration-plane item 8): `proceeded`, `refused:<code>` or
+ *  `fell_cold:<token>` — the ledger object logs the decider's word beside it.
+ *  `runId` is absent when the dispatch never minted one (a refusal). */
+export interface PlaneOutcomePost {
+  runId?: string;
+  requester: string;
+  threadKey: string;
+  stage: PlaneStage;
+  outcome: string;
+}
+
+/** How the bot answers an offered effect (orchestration-plane item 7): `done` and `skipped` close it,
+ *  `deferred` leaves it on the next heartbeat or reclaim answer. */
+export type PlaneAckOutcome = "done" | "skipped" | "deferred";
+
+export interface PlaneDecision {
+  state: PlaneState;
+  effects: PlaneEffect[];
+  writes: PlaneWrite[];
+}
+
+/** One event in, the next state out, with the writes and effects that carry
+ *  it — and nothing else: no transition, no writes (the state comes back as
+ *  given). Never throws: an event about a run or thread the state does not
+ *  know is a no-op, because the object replays outcomes from a bot whose view
+ *  can be older than the tables. */
+export function decide(state: PlaneState, event: PlaneEvent): PlaneDecision {
+  switch (event.kind) {
+    case "ask":
+      return onAsk(state, event);
+    case "sealed":
+      return onSealed(state, event);
+    case "withdraw":
+      return onWithdraw(state, event);
+  }
+}
+
+/** The shadow word for an ask the decider just judged (orchestration-plane item 8): `queued` when the
+ *  decision holds a waiting row for the run, `proceed` when it holds none —
+ *  what the object logs beside the bot's own outcome. */
+export function planeAskWordOf(decision: PlaneDecision, runId: string): "proceed" | "queued" {
+  const row = decision.state.queue.find((r) => r.runId === runId);
+  return row && row.state === "waiting" ? "queued" : "proceed";
+}
+
+function onAsk(state: PlaneState, event: PlaneAskEvent): PlaneDecision {
+  const threadLive = state.liveThreads.includes(event.threadKey);
+  if (!threadLive) return { state, effects: [], writes: [] };
+  const waitingAhead = state.queue.filter((r) => r.state === "waiting" && r.threadKey === event.threadKey).length;
+  const row: PlaneQueueRow = {
+    runId: event.runId,
+    requester: event.requester,
+    threadKey: event.threadKey,
+    stage: event.stage,
+    request: event.request,
+    conditions: [{ kind: "thread_free", threadKey: event.threadKey, met: false }],
+    position: waitingAhead + 1,
+    queuedAt: event.at,
+    state: "waiting",
+  };
+  return {
+    state: { ...state, queue: [...state.queue, row] },
+    effects: [],
+    writes: [{ table: "plane_queue", op: "put", row }],
+  };
+}
+
+function onSealed(state: PlaneState, event: { kind: "sealed"; at: number; threadKey: string }): PlaneDecision {
+  const liveThreads = state.liveThreads.filter((t) => t !== event.threadKey);
+  if (liveThreads.length === state.liveThreads.length && !hasWaiting(state, event.threadKey))
+    return { state, effects: [], writes: [] };
+  return walk({ ...state, liveThreads }, event.at);
+}
+
+function onWithdraw(state: PlaneState, event: { kind: "withdraw"; at: number; runId: string }): PlaneDecision {
+  const row = state.queue.find((r) => r.runId === event.runId && r.state === "waiting");
+  if (!row) return { state, effects: [], writes: [] };
+  const queue = state.queue.map((r) => (r === row ? { ...r, state: "withdrawn" as const } : r));
+  return {
+    state: { ...state, queue },
+    effects: [],
+    writes: [{ table: "plane_queue", op: "state", runId: event.runId, state: "withdrawn" }],
+  };
+}
+
+function hasWaiting(state: PlaneState, threadKey: string): boolean {
+  return state.queue.some((r) => r.state === "waiting" && r.threadKey === threadKey);
+}
+
+/** The queue walk (record 0064): oldest first, and the state is re-evaluated
+ *  after each admission — an admitted run's thread is live again, so a second
+ *  row on the same thread keeps waiting for the next seal. */
+function walk(state: PlaneState, at: number): PlaneDecision {
+  let next = state;
+  const effects: PlaneEffect[] = [];
+  const writes: PlaneWrite[] = [];
+  for (;;) {
+    const row = next.queue.find((r) => r.state === "waiting" && conditionsMet(next, r));
+    if (!row) break;
+    const admitted: PlaneQueueRow = { ...row, state: "admitted" };
+    const effect: PlaneEffect = {
+      id: `admit:${row.runId}`,
+      kind: "admit",
+      runId: row.runId,
+      threadKey: row.threadKey,
+      request: row.request,
+    };
+    next = {
+      queue: next.queue.map((r) => (r === row ? admitted : r)),
+      liveThreads: [...next.liveThreads, row.threadKey],
+    };
+    effects.push(effect);
+    writes.push({ table: "plane_queue", op: "state", runId: row.runId, state: "admitted" });
+    writes.push({ table: "plane_effects", op: "offer", effect, at });
+  }
+  return { state: next, effects, writes };
+}
+
+function conditionsMet(state: PlaneState, row: PlaneQueueRow): boolean {
+  return row.conditions.every((c) => !state.liveThreads.includes(c.threadKey));
+}

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

@@ -155,8 +155,19 @@ export interface ProviderConfig {
   apiKeyEnv?: string;
   /** Base URL for openai-compatible providers (e.g. http://localhost:11434/v1). */
   baseUrl?: string;
+  /** The invoice API the biller's daily tie-out reads (docs/reference/specs/costs.md
+   *  item 4d): Anthropic's cost report, OpenRouter's activity endpoint, or
+   *  OpenAI's organization costs. Requires `invoiceKeyEnv`. */
+  invoiceApi?: InvoiceApi;
+  /** Env var holding that API's key — an admin or management key, never the
+   *  block's inference key (`apiKeyEnv`). Requires `invoiceApi`. */
+  invoiceKeyEnv?: string;
 }
 
+/** The invoice APIs a provider block may name (`invoiceApi`). */
+export const INVOICE_APIS = ["anthropic-cost-report", "openrouter-activity", "openai-costs"] as const;
+export type InvoiceApi = (typeof INVOICE_APIS)[number];
+
 /** 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";

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

@@ -207,6 +207,13 @@ export type RunNoteKind =
    *  the summary names the branch. Published by the post-step, so a unit
    *  that ends without a pull request says why on the record and the card. */
   | "pr_not_opened"
+  /** A coding run's pull request was opened or edited, but its head moved
+   *  before the post-step's head pin and the second identity rewrite answered
+   *  `unreadable` (docs/reference/specs/agent-coding.md item 2, record 0062):
+   *  the open cannot be undone, so the summary names the reason the new tip's
+   *  identities could not be verified and the reply carries the same warning.
+   *  Published by the post-step. */
+  | "pr_head_unverified"
   /** A review run's post-step posted nothing to the pull request — a guard's
    *  refusal, an opt-out, no pull request resolved, GitHub's own error — and
    *  the summary names the pull request (when one was resolved) and the
@@ -275,6 +282,14 @@ export type RunNoteKind =
    *  there was nothing to push), so a re-issue starts from the partial work
    *  (docs/reference/specs/agent-ship.md item 8). */
   | "budget_salvage"
+  /** A pi run's compaction failed for good — the provider refused the summary
+   *  (harness-pi.md item 7) — and the run loop treated it as a checkpoint
+   *  signal: the tracked changes were committed and pushed to the run's own
+   *  branch (a `pushed_head` event, `by: "salvage"`), or the note says plainly
+   *  that the tree held nothing, so a context that overflows before the
+   *  wind-down loses no work. The summary names the compaction failure.
+   *  Published by the run loop's hook, which the pi harness awaits. */
+  | "compaction_salvage"
   /** The loop's end found a tool call in flight and ended it, so the write-up
    *  keeps its allowance (decision 0046, unit seven; harness-pi item 6). The
    *  summary names the tools. Published by the harness beside the budget note. */
@@ -323,6 +338,7 @@ export const RUN_NOTE_KINDS = [
   "work_left_behind",
   "workspace_torn_down",
   "pr_not_opened",
+  "pr_head_unverified",
   "review_not_posted",
   "compacted",
   "harness_error",
@@ -333,6 +349,7 @@ export const RUN_NOTE_KINDS = [
   "tool_unnamed",
   "directory_reached",
   "budget_salvage",
+  "compaction_salvage",
   "stuck_loop",
   "decline_cascade",
 ] as const satisfies readonly RunNoteKind[];
@@ -345,7 +362,7 @@ void _everyKindListed;
  *  the message, the thread's sticky preset, the user or the channel scope's
  *  `agent`, `defaults.agent`, or the request router. The replay harness
  *  (`load route`) reads it to tell a requester's own choice from a fallback. */
-export type AgentSource = "directive" | "sticky" | "user" | "channel" | "default" | "route";
+export type AgentSource = "directive" | "sticky" | "user" | "channel" | "default" | "route" | "operator";
 
 /** How an operator asked a run to stop: `soft` — take no new steps and
  *  wrap up through the normal finale; `hard` — abort the in-flight call now, no
@@ -848,6 +865,10 @@ export type RunEvent =
        *  its own branches past the tree (docs/reference/specs/resident-repos.md
        *  item 16). Absent from an event a build before it recorded. */
       head?: string;
+      /** How many of the run's commits the identity rewrite re-authored before
+       *  the open (record 0062; docs/reference/specs/agent-coding.md item 2).
+       *  Absent when none were, and from an event a build before it recorded. */
+      rewritten?: number;
       seq?: number;
       at?: number;
     }
@@ -1027,6 +1048,11 @@ export type RunEvent =
       proposal?: string;
       refusalCause?: string;
       refusalText?: string;
+      /** A refusal the seam itself produced (a non-decision answer, a wrong
+       *  tool, a transport failure) — never the model's decision: under `on`
+       *  the dispatcher falls back to the readers' route for that event, this
+       *  event recorded on the run that then runs. */
+      fallback?: true;
       intake?: { verdict: string; reason: string };
       latencyMs?: number;
       outputTokens?: number;

package/dist/assets/src/core/runLedger/transcript.ts

@@ -125,8 +125,24 @@ export interface AssembledCompaction {
 }
 
 export type AssembledTranscript =
-  | { complete: true; turns: number; messages: ChatMessage[]; compactions: AssembledCompaction[] }
-  | { complete: false; turns: number; messages: ChatMessage[]; compactions: AssembledCompaction[]; gap: string };
+  | {
+      complete: true;
+      turns: number;
+      messages: ChatMessage[];
+      compactions: AssembledCompaction[];
+      /** Each message's author (`StoredPart.actor`), aligned with `messages`;
+       *  present only when at least one row carries one — the verifier selects
+       *  the author's own turns by it (record 0057). */
+      actors?: (string | undefined)[];
+    }
+  | {
+      complete: false;
+      turns: number;
+      messages: ChatMessage[];
+      compactions: AssembledCompaction[];
+      actors?: (string | undefined)[];
+      gap: string;
+    };
 
 /** Rows (any order) → the turns, contiguous from `base` (a log index; 0 for a
  *  run's own object), as a conversation counted from 0. `turns` counts every
@@ -150,6 +166,8 @@ export function assembleTranscript(
   }
   const messages: ChatMessage[] = [];
   const compactions: AssembledCompaction[] = [];
+  const actorList: (string | undefined)[] = [];
+  const actorsOrNone = () => (actorList.some((a) => a !== undefined) ? { actors: actorList } : {});
   /** The `messages` index each turn index landed at (a compaction row lands nowhere). */
   const messageIndexOf = new Map<number, number>();
   const gap = (why: string): AssembledTranscript => ({
@@ -157,6 +175,7 @@ export function assembleTranscript(
     turns: messages.length + compactions.length,
     messages,
     compactions,
+    ...actorsOrNone(),
     gap: why,
   });
   const turnCount = byTurn.size === 0 ? 0 : Math.max(...byTurn.keys()) + 1;
@@ -187,11 +206,12 @@ export function assembleTranscript(
     }
     messageIndexOf.set(idx, messages.length);
     messages.push({ role: role ?? "user", content });
+    actorList.push(first && !("compaction" in first) ? first.actor : undefined);
   }
   for (const c of compactions) {
     if (c.entry.keptFrom === undefined) continue;
     const kept = messageIndexOf.get(c.entry.keptFrom - base);
     if (kept !== undefined) c.keptBefore = kept;
   }
-  return { complete: true, turns: messages.length + compactions.length, messages, compactions };
+  return { complete: true, turns: messages.length + compactions.length, messages, compactions, ...actorsOrNone() };
 }

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

@@ -14,6 +14,7 @@ import {
   type ReviewVerdict,
 } from "./reviewVerdict.js";
 import { IDEMPOTENCY_KEY_PATTERN, INSTANCE_ID_PATTERN } from "./coordinator/contract.js";
+import { isPipelineSummaryShape, type PipelineSummary } from "./pipelineStanding.js";
 import {
   FRICTION_CATEGORIES,
   type CategoryTotals,
@@ -215,6 +216,15 @@ export interface RunRecord {
    *  coordinator tag. Present only on a ship run whose hand-off succeeded;
    *  a record written before the event has none. */
   instanceId?: string;
+  /** The pipeline's standing (record 0065): the fold of the run's own
+   *  `ship_round`/`ship_unit` events, summarized at the seal so the stored row
+   *  reads it without the events. Present only on a run that published ship
+   *  facts; a record written before the field carries none and reads as today. */
+  pipeline?: PipelineSummary;
+  /** A ship pipeline's parent run (record 0060; record 0065): `RunMeta.hosted`
+   *  carried onto the record at the seal, so a history reader draws the run as
+   *  a pipeline. Absent on every other run and on older records. */
+  hosted?: true;
   /** Where the run's conversation started (item 52): `channel` — its own
    *  thread's history, as for every run a person, a schedule or a coordinator
    *  started — or `parent` — a spawned child seeded from its parent's text
@@ -985,6 +995,11 @@ export function isRunRecord(v: unknown): v is RunRecord {
   // The instance a ship run's hand-off created (record 0051 R2; item 2).
   if (r.instanceId !== undefined && (typeof r.instanceId !== "string" || !INSTANCE_ID_PATTERN.test(r.instanceId)))
     return false;
+  // The pipeline's standing and the hosted marker (record 0065): the summary
+  // is checked for shape — an older reader accepts a newer record — and the
+  // marker, like `provisional`, is the literal `true` or absent.
+  if (r.pipeline !== undefined && !isPipelineSummaryShape(r.pipeline)) return false;
+  if (r.hosted !== undefined && r.hosted !== true) return false;
   if (typeof r.channelId !== "string" || typeof r.userId !== "string" || typeof r.threadKey !== "string") return false;
   if (r.relayedBy !== undefined && typeof r.relayedBy !== "string") return false;
   if (r.authenticatedAs !== undefined && typeof r.authenticatedAs !== "string") return false;

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

@@ -31,6 +31,11 @@ export interface ModelUsage {
    *  a record whose turns predate the meter row (the price table then prices
    *  the tokens, costs.md item 4b). */
   usd?: number | null;
+  /** The model's BYOK aggregator fees summed from its turns' `feeUsd` attrs —
+   *  the share of `usd` that is the aggregator's own charge, what the biller's
+   *  invoice tie-out compares against its `usage` column (costs.md item 4d).
+   *  Absent when no turn carried one. */
+  feeUsd?: number;
   /** The distinct `priceSource` words the turns carried, sorted — what the
    *  by-model view names as the source. Absent when no turn carried one. */
   priceSources?: string[];
@@ -59,12 +64,24 @@ export function usageOfEvents(events: readonly RunEvent[]): RunUsage {
   const usage = emptyUsage();
   // The meter row per model (model-proxy item 6): the turns' own dollars and
   // sources. `usd` sums only when every turn that counted tokens carried one —
-  // a turn that counted none (an upstream error, a retry the harness's SDK
-  // spent, a stream broken before its usage) has nothing a sum could leave
-  // out, so it never turns the model unpriced; a model none of whose turns
-  // carried price attrs stays without the fields (a record from before the
-  // meter row — the table prices it, costs.md item 4b).
-  const priced = new Map<string, { usd: number; pricedTurns: number; tokenTurns: number; sources: Set<string> }>();
+  // the token-counting turns that lack a figure are counted directly
+  // (`unpricedTokenTurns`), so a priced zero-token turn can never stand in for
+  // an unpriced one; a turn that counted none (an upstream error, a retry the
+  // harness's SDK spent, a stream broken before its usage) has nothing a sum
+  // could leave out, so it never turns the model unpriced; a model none of
+  // whose turns carried price attrs stays without the fields (a record from
+  // before the meter row — the table prices it, costs.md item 4b).
+  const priced = new Map<
+    string,
+    {
+      usd: number;
+      feeUsd: number;
+      feeTurns: number;
+      pricedTurns: number;
+      unpricedTokenTurns: number;
+      sources: Set<string>;
+    }
+  >();
   for (const e of events) {
     if (e.type !== "span_end" || e.name !== MODEL_TURN) continue;
     const attrs = (e.attrs ?? {}) as Record<string, unknown>;
@@ -87,19 +104,31 @@ export function usageOfEvents(events: readonly RunEvent[]): RunUsage {
     usage.turns += 1;
     const hasUsd = typeof attrs.usd === "number" && Number.isFinite(attrs.usd);
     const hasSource = typeof attrs.priceSource === "string" && attrs.priceSource !== "";
-    const p = priced.get(model) ?? { usd: 0, pricedTurns: 0, tokenTurns: 0, sources: new Set<string>() };
-    if (counted > 0) p.tokenTurns += 1;
+    const p = priced.get(model) ?? {
+      usd: 0,
+      feeUsd: 0,
+      feeTurns: 0,
+      pricedTurns: 0,
+      unpricedTokenTurns: 0,
+      sources: new Set<string>(),
+    };
+    if (counted > 0 && !hasUsd) p.unpricedTokenTurns += 1;
     if (hasUsd) {
       p.usd += attrs.usd as number;
       p.pricedTurns += 1;
     }
+    if (typeof attrs.feeUsd === "number" && Number.isFinite(attrs.feeUsd)) {
+      p.feeUsd += attrs.feeUsd;
+      p.feeTurns += 1;
+    }
     if (hasSource) p.sources.add(attrs.priceSource as string);
     priced.set(model, p);
   }
   for (const [model, p] of priced) {
     if (p.pricedTurns === 0 && p.sources.size === 0) continue;
     const m = usage.byModel[model]!;
-    m.usd = p.pricedTurns >= p.tokenTurns ? p.usd : null;
+    m.usd = p.unpricedTokenTurns > 0 ? null : p.usd;
+    if (p.feeTurns > 0) m.feeUsd = p.feeUsd;
     if (p.sources.size > 0) m.priceSources = [...p.sources].sort();
   }
   return usage;
@@ -128,6 +157,8 @@ export function addUsage(a: RunUsage, b: RunUsage): RunUsage {
       const usd = foldUsd(acc.usd, m.usd);
       if (usd === undefined) delete acc.usd;
       else acc.usd = usd;
+      // A side without a fee spent none — a fee of nothing, never an unknown.
+      if (acc.feeUsd !== undefined || m.feeUsd !== undefined) acc.feeUsd = (acc.feeUsd ?? 0) + (m.feeUsd ?? 0);
       const sources = new Set([...(acc.priceSources ?? []), ...(m.priceSources ?? [])]);
       if (sources.size > 0) acc.priceSources = [...sources].sort();
     }
@@ -145,6 +176,7 @@ const isModelUsage = (v: unknown): v is ModelUsage => {
   )
     return false;
   if (m.usd !== undefined && m.usd !== null && typeof m.usd !== "number") return false;
+  if (m.feeUsd !== undefined && typeof m.feeUsd !== "number") return false;
   return (
     m.priceSources === undefined ||
     (Array.isArray(m.priceSources) && m.priceSources.every((s) => typeof s === "string"))

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

@@ -461,6 +461,12 @@ export type CoordinatorAction =
   | {
       type: "pr-check";
       step: string;
+      /** The unit-start's pre-check (issue 1689): the bot reads the entry facts
+       *  beside the listing — the branch's own tip, whether its approval
+       *  stands at the head, and the checks there — so a re-issued plan's
+       *  unit resumes at review, or at the merge decision, never at coding
+       *  over an already-shipped pull request. */
+      entry?: true;
       /** Set after a coding child died: the bot opens the pull request from the
        *  pushed branch itself (title from the unit, body from this run's
        *  submitted description when the record holds one) instead of answering
@@ -545,6 +551,15 @@ export type PrCheck =
       prNumber: number;
       url: string;
       headSha?: string;
+      /** The unit branch's own tip, read beside the listing on the entry check
+       *  (issue 1689): the listing's `headSha` can lag a force-push, so the
+       *  machine resumes at review only when the pull request heads the
+       *  branch's actual tip — a head behind the branch is round 0's. */
+      branchHead?: string;
+      /** Whether an approving review by the bot stands at the head (the entry
+       *  check, issue 1689): with green checks the attempt resumes straight at
+       *  the merge decision instead of a review round. */
+      approved?: boolean;
       autoMergeEnabled?: boolean;
       /** The check runs at the head, when the read asked for them (the ending's facts). */
       checks?: CommitChecksFacts;
@@ -1081,7 +1096,7 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
   const p = s.phase;
   switch (p.at) {
     case "pre-check":
-      return { type: "pr-check", step: `${unit}/pr-check` };
+      return { type: "pr-check", step: `${unit}/pr-check`, entry: true };
     case "branch":
       return { type: "branch", step: `${unit}/branch`, branch: s.input.unit.branch, from: s.input.base };
     case "spawn": {
@@ -1859,19 +1874,40 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
       // by the coding child and adopted at the round's own pr-check.
       const r = ret as Extract<StepReturn, { type: "pr-check" }>;
       if (r.pr.state === "merged") return foundMerged(clocked, r.pr);
-      // The open pull request still heads at the child's own last push (the
-      // previous attempt ended `review_pending`): nothing to code, so the
-      // attempt adopts it and starts at the review round — never a fresh
-      // coding round on an already-shipped pull request.
+      // The open pull request still heads the branch — its head is the
+      // branch's own tip (the entry facts, issue 1689) or the child's own last
+      // push (the previous attempt ended `review_pending`, the row's
+      // `lastPush`): nothing to code, so the attempt adopts it and starts at
+      // the review round — never a fresh coding round on an already-shipped
+      // pull request. Approved at that very head with green checks, there is
+      // nothing to review either: the attempt resumes straight at the merge
+      // decision — `merge_ready` for a person, the merge door under
+      // `merge: runner`, which re-verifies the approval and the checks itself.
       if (r.pr.state === "open") {
         const head = normalizeHead(r.pr.headSha);
+        const branchHead = normalizeHead(r.pr.branchHead);
         const lastPush = normalizeHead(s.input.lastPush);
-        if (head !== undefined && lastPush !== undefined && sameCommit(head, lastPush))
-          return nextReview({
+        const atBranchHead = head !== undefined && branchHead !== undefined && sameCommit(head, branchHead);
+        const atLastPush = head !== undefined && lastPush !== undefined && sameCommit(head, lastPush);
+        if (atBranchHead || atLastPush) {
+          // The entry facts — the approval and the checks — were read at the
+          // branch's own tip when GitHub answered it (`branchHead`, the
+          // fresher read of the same head ref), else at the listing's sha.
+          // The resume pins the review — and the merge decision — at that
+          // same head, so the approved+green shortcut never fires at a stale
+          // listing sha the facts do not describe.
+          const entryHead = branchHead ?? head;
+          const adopted: UnitPipelineState = {
             ...clocked,
             pr: { number: r.pr.prNumber, url: r.pr.url },
-            lastReviewHead: head,
-          });
+            lastReviewHead: entryHead,
+          };
+          const checks = r.pr.checks;
+          const green =
+            checks !== undefined && checks.total > 0 && checks.failed.length === 0 && checks.pending.length === 0;
+          if (r.pr.approved === true && green) return approveOutcome(adopted, []);
+          return nextReview(adopted);
+        }
       }
       return { state: { ...clocked, phase: { at: "branch" } }, notes: [] };
     }