@coreplane/switchboard 1.241.0 → 1.243.0

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

@@ -0,0 +1,212 @@
+import type { ModelUsage, RunUsage } from "./runUsage.js";
+
+// The price of a model's tokens (docs/reference/specs/costs.md): one table
+// serves every dollar of token arithmetic — the open day's estimate from
+// Anthropic's hourly usage report and the by-user report's run tokens. The
+// list prices are Anthropic's, keyed by family and copied from the pricing
+// page; re-check them when the page moves.
+
+/** USD per million tokens of one kind, one model family. */
+export interface AnthropicModelPrice {
+  input: number;
+  output: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+  cacheRead: number;
+}
+
+/** Anthropic list prices per model family (platform.claude.com/docs/en/about-claude/pricing;
+ *  re-check when it moves). Keyed by the family id the usage report spells — a dated
+ *  release (`claude-haiku-4-5-20251001`) resolves to its family through
+ *  `anthropicPriceOf`. Only what the estimate needs: the open day priced at
+ *  the rate it will bill at; the cost report remains the invoice. */
+export const ANTHROPIC_PRICES: Record<string, AnthropicModelPrice> = {
+  "claude-fable-5-1": { input: 10, output: 50, cacheWrite5m: 12.5, cacheWrite1h: 20, cacheRead: 0.25 },
+  "claude-mythos-5-1": { input: 10, output: 50, cacheWrite5m: 12.5, cacheWrite1h: 20, cacheRead: 0.25 },
+  "claude-fable-5": { input: 10, output: 50, cacheWrite5m: 12.5, cacheWrite1h: 20, cacheRead: 1 },
+  "claude-mythos-5": { input: 10, output: 50, cacheWrite5m: 12.5, cacheWrite1h: 20, cacheRead: 1 },
+  "claude-opus-5": { input: 5, output: 25, cacheWrite5m: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+  "claude-opus-4-8": { input: 5, output: 25, cacheWrite5m: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+  "claude-opus-4-7": { input: 5, output: 25, cacheWrite5m: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+  "claude-opus-4-6": { input: 5, output: 25, cacheWrite5m: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+  "claude-opus-4-5": { input: 5, output: 25, cacheWrite5m: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+  "claude-opus-4-1": { input: 15, output: 75, cacheWrite5m: 18.75, cacheWrite1h: 30, cacheRead: 1.5 },
+  "claude-opus-4": { input: 15, output: 75, cacheWrite5m: 18.75, cacheWrite1h: 30, cacheRead: 1.5 },
+  "claude-sonnet-5": { input: 2, output: 10, cacheWrite5m: 2.5, cacheWrite1h: 4, cacheRead: 0.2 },
+  "claude-sonnet-4-6": { input: 3, output: 15, cacheWrite5m: 3.75, cacheWrite1h: 6, cacheRead: 0.3 },
+  "claude-sonnet-4-5": { input: 3, output: 15, cacheWrite5m: 3.75, cacheWrite1h: 6, cacheRead: 0.3 },
+  "claude-sonnet-4": { input: 3, output: 15, cacheWrite5m: 3.75, cacheWrite1h: 6, cacheRead: 0.3 },
+  "claude-haiku-4-5": { input: 1, output: 5, cacheWrite5m: 1.25, cacheWrite1h: 2, cacheRead: 0.1 },
+  "claude-haiku-3-5": { input: 0.8, output: 4, cacheWrite5m: 1, cacheWrite1h: 1.6, cacheRead: 0.08 },
+};
+
+const DATED_RELEASE_SUFFIX = /^-\d{8}$/;
+
+/** The family prices of a model id: the id itself, or the id less a dated
+ *  release suffix (`-YYYYMMDD`). Nothing else counts as "the same family" —
+ *  `claude-fable-5-1` is not `claude-fable-5` with a suffix, and its cache
+ *  reads bill differently. Unknown → undefined, never a guess. */
+export function anthropicPriceOf(modelId: string): AnthropicModelPrice | undefined {
+  const exact = ANTHROPIC_PRICES[modelId];
+  if (exact) return exact;
+  for (const family of Object.keys(ANTHROPIC_PRICES)) {
+    if (modelId.startsWith(family) && DATED_RELEASE_SUFFIX.test(modelId.slice(family.length)))
+      return ANTHROPIC_PRICES[family];
+  }
+  return undefined;
+}
+
+/** Token counts of one usage-report row, in the report's own kinds. */
+export interface AnthropicTokens {
+  uncachedInput: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+}
+
+/** What those tokens cost at the family's list prices; undefined for a model
+ *  the table does not know (the caller reports the tokens, never $0). */
+export function anthropicTokensCostUsd(modelId: string, t: AnthropicTokens): number | undefined {
+  const p = anthropicPriceOf(modelId);
+  if (!p) return undefined;
+  return (
+    (t.uncachedInput * p.input +
+      t.output * p.output +
+      t.cacheRead * p.cacheRead +
+      t.cacheWrite5m * p.cacheWrite5m +
+      t.cacheWrite1h * p.cacheWrite1h) /
+    1_000_000
+  );
+}
+
+// ---- the operator's table: `costs.prices` over the list (costs.md item 4b) --------------
+
+/** USD per million tokens of each kind a run's spans count, for one `<provider>/<model>` ref. */
+export interface ModelPrice {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** `costs.prices`: the exact ref as the spans name it → its rates. */
+export type ModelPriceTable = Readonly<Record<string, ModelPrice>>;
+
+/** No table configured: the list alone prices. */
+export const NO_PRICES: ModelPriceTable = Object.freeze({});
+
+const PRICE_KINDS = ["input", "output", "cacheRead", "cacheWrite"] as const;
+
+const isRate = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v) && v >= 0;
+
+/** `costs.prices` as config spells it. Absent → the empty table. A key is a
+ *  `<provider>/<model>` ref; a value names all four kinds as finite dollars per
+ *  million ≥ 0 (a kind left out would price at $0 in silence); anything else
+ *  is refused by name. */
+export function parseModelPrices(raw: unknown): ModelPriceTable {
+  if (raw === undefined || raw === null) return NO_PRICES;
+  if (typeof raw !== "object" || Array.isArray(raw))
+    throw new Error("costs.prices must be a mapping of <provider>/<model> → rates");
+  const out: Record<string, ModelPrice> = {};
+  for (const [ref, value] of Object.entries(raw as Record<string, unknown>)) {
+    const slash = ref.indexOf("/");
+    if (slash <= 0 || slash === ref.length - 1)
+      throw new Error(`costs.prices.${ref} must be keyed <provider>/<model>, the ref a run's spans name`);
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+      throw new Error(
+        `costs.prices.${ref} must be a mapping of { input, output, cacheRead, cacheWrite } in USD per million tokens`,
+      );
+    const v = value as Record<string, unknown>;
+    const price: Partial<ModelPrice> = {};
+    for (const kind of PRICE_KINDS) {
+      if (!isRate(v[kind]))
+        throw new Error(`costs.prices.${ref}.${kind} must be a finite number of USD per million tokens, 0 or more`);
+      price[kind] = v[kind];
+    }
+    out[ref] = price as ModelPrice;
+  }
+  return out;
+}
+
+/** The price of a ref: the configured table first (the exact ref), else the
+ *  Anthropic list by family after the provider prefix is dropped — cache
+ *  writes at the 5-minute rate, the one cache-write count a span carries —
+ *  and undefined for a model neither knows (the caller reports the tokens,
+ *  never $0). */
+export function modelPriceOf(ref: string, prices: ModelPriceTable = NO_PRICES): ModelPrice | undefined {
+  const configured = prices[ref];
+  if (configured) return configured;
+  const list = anthropicPriceOf(modelIdOf(ref));
+  if (!list) return undefined;
+  return { input: list.input, output: list.output, cacheRead: list.cacheRead, cacheWrite: list.cacheWrite5m };
+}
+
+/** What a model's counted tokens cost at a price, USD. */
+export function modelUsageUsd(m: ModelUsage, p: ModelPrice): number {
+  return (
+    (m.inputTokens * p.input +
+      m.outputTokens * p.output +
+      m.cacheReadTokens * p.cacheRead +
+      m.cacheWriteTokens * p.cacheWrite) /
+    1_000_000
+  );
+}
+
+// ---- a run's tokens, priced -----------------------------------------------------------
+
+/** One model's tokens, priced; `usd` is null for a model the price table does not know. */
+export interface PricedModelUsage extends ModelUsage {
+  usd: number | null;
+}
+
+/** `anthropic/claude-fable-5` → `claude-fable-5`: the spans name the provider, the price table the model. */
+export const modelIdOf = (ref: string): string => (ref.includes("/") ? ref.slice(ref.indexOf("/") + 1) : ref);
+
+/** A run's dollars as every surface prints them (costs.md item 4c): cents from a
+ *  dollar up (`$1.24`), a tenth of a cent below that (`$0.038`), and `<$0.001`
+ *  under that — a run that spent anything never reads as `$0.000`; `$0.00` is a
+ *  run with no turns and nothing else. */
+export function formatUsd(usd: number): string {
+  if (usd === 0) return "$0.00";
+  if (usd < 0.001) return "<$0.001";
+  return `$${usd.toFixed(usd >= 1 ? 2 : 3)}`;
+}
+
+/** What one run cost (costs.md item 4c): the dollars when every model it ran
+ *  on has a price, null when one has none — a total that left a model's tokens
+ *  out would understate the run — and $0 for a run with no turns at all.
+ *  `byModel` says which model was unpriced. */
+export interface RunCost {
+  usd: number | null;
+  byModel: Record<string, PricedModelUsage>;
+}
+
+export function runCostOf(usage: RunUsage, prices: ModelPriceTable = NO_PRICES): RunCost {
+  const priced = llmUsdOfUsage(usage, prices);
+  const unpriced = Object.values(priced.byModel).some((m) => m.usd === null);
+  return { usd: unpriced ? null : priced.usd, byModel: priced.byModel };
+}
+
+/** A usage priced through the table (`modelPriceOf`): dollars for the models a
+ *  price is known for, and the tokens of the ones it is not (never $0 in silence). */
+export function llmUsdOfUsage(
+  usage: RunUsage,
+  prices: ModelPriceTable = NO_PRICES,
+): {
+  usd: number;
+  unpricedTokens: number;
+  byModel: Record<string, PricedModelUsage>;
+} {
+  let usd = 0;
+  let unpricedTokens = 0;
+  const byModel: Record<string, PricedModelUsage> = {};
+  for (const [ref, m] of Object.entries(usage.byModel)) {
+    const price = modelPriceOf(ref, prices);
+    const priced = price ? modelUsageUsd(m, price) : undefined;
+    if (priced === undefined) unpricedTokens += m.inputTokens + m.outputTokens + m.cacheReadTokens + m.cacheWriteTokens;
+    else usd += priced;
+    byModel[ref] = { ...m, usd: priced ?? null };
+  }
+  return { usd, unpricedTokens, byModel };
+}

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

@@ -6,49 +6,54 @@
 // types and enforces (via its annotated parse return) that the zod output
 // stays assignable to them. Add a field here first, then to the schema.
 
-/** A hunk the reader is pointed at: a path + inclusive 1-based line range in
- *  the PR head. The sha is NOT stored here — it is supplied at render time. */
-export interface TourAnchor {
+/** The lines a pointer sends the reader to: a path + inclusive 1-based line
+ *  range in the PR head. The sha is NOT stored here — it is supplied at render
+ *  time. */
+export interface PrAnchor {
   path: string;
   from: number;
   to: number;
 }
 
-/** One Tour step, reader-first: heading (what the change is), the explanation,
- *  an optional "look for" pointer, then the code. */
-export interface TourStep {
-  title: string;
-  description: string;
-  lookFor?: string;
-  anchor: TourAnchor;
+/** One row of the map's "Where to look": a linked label, one sentence, an
+ *  optional risk (rendered as ⚠), and the lines the label links to. */
+export interface Pointer {
+  label: string;
+  text: string;
+  risk?: string;
+  anchor: PrAnchor;
 }
 
-/** A Tour anchor with the sha its permalink was rendered at — what a reader
- *  gets back from a rendered body (or from a submitted object at the head it
- *  was rendered for), so a surface can tell whether the anchors are at the
- *  head it is looking at. */
-export interface RenderedTourAnchor extends TourAnchor {
+/** An anchor with the sha its permalink was rendered at — what a reader gets
+ *  back from a rendered body (or from a submitted object at the head it was
+ *  rendered for), so a surface can tell whether the pointers are at the head
+ *  it is looking at. */
+export interface RenderedPrAnchor extends PrAnchor {
   sha: string;
 }
 
-/** A Tour step whose anchor carries its render sha. Assignable to `TourStep`. */
-export interface RenderedTourStep extends TourStep {
-  anchor: RenderedTourAnchor;
+/** A pointer whose anchor carries its render sha. Assignable to `Pointer`. */
+export interface RenderedPointer extends Pointer {
+  anchor: RenderedPrAnchor;
 }
 
+/** The PR description as data (docs/decisions/0050): the map above the fold
+ *  (tldr, why, pointers, feedbackWanted, risk, verified), every field capped
+ *  so the map's size does not grow with the diff, and the collapsed half
+ *  (decisions, validation, agentNotes) below it. */
 export interface PrDescription {
   /** The PR title's single source. Metadata for the PR's own title field —
    *  never rendered into the body (GitHub shows the title itself). */
   title: string;
   tldr: string;
-  whatWhy: string;
-  tour: TourStep[];
-  /** Every touched file the Tour steps did not cover, one line each. */
-  remaining: { path: string; note: string }[];
+  why: string;
+  pointers: Pointer[];
+  feedbackWanted: string;
+  risk: string;
+  verified: string;
   decisions: { title: string; rationale: string }[];
-  risks: string;
   validation: {
-    summary?: string;
     criteria: { criterion: string; proof: string }[];
   };
+  agentNotes?: string;
 }

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

@@ -163,6 +163,13 @@ export function formatFinding(f: Finding): string {
   return `[${f.severity}] ${f.id} ${location} — ${f.title}`;
 }
 
+/** One compact disposition line — `id: fixed|declined[ — note]` — the coding
+ *  side's answer to a finding, as ship's re-review turn and the thread's
+ *  artifacts block both render it. */
+export function formatDisposition(d: FindingDisposition): string {
+  return `${d.findingId}: ${d.disposition}${d.note ? ` — ${d.note}` : ""}`;
+}
+
 /**
  * Build the body posted to GitHub: the deterministic verdict line, the
  * compact findings list (when present), a blank line, then the model's

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

@@ -1,7 +1,8 @@
 // Types only, and from the zod-free module deliberately: this file is part of
 // the node-free contract the memory Worker and web app compile with their own
 // tsconfigs — importing prDescription.ts would drag zod into those graphs.
-import type { PrDescription, RenderedTourStep } from "./prDescriptionTypes.js";
+import type { PrDescription, RenderedPointer } from "./prDescriptionTypes.js";
+import type { HarnessScope } from "./harness/scope.js";
 
 /** The `pr_description` review artifact minus the event envelope
  *  (docs/reference/specs/reading-diff.md item 7). */
@@ -25,8 +26,11 @@ export interface PrDescriptionArtifact {
   /** The body as rendered (submitted) or as GitHub holds it (parsed), capped. */
   body: string;
   tldr?: string;
-  tour: RenderedTourStep[];
-  remaining: { path: string; note: string }[];
+  why?: string;
+  /** The map's "Where to look", each anchor stamped with the sha its permalink
+   *  was rendered at. (A record written under the previous contract carries
+   *  this array as `tour`; the line parser accepts either name.) */
+  pointers: RenderedPointer[];
   decisions: { title: string; rationale: string }[];
   /** Nothing missing or malformed — always true for `submitted`. */
   complete: boolean;
@@ -97,6 +101,11 @@ export type RunNoteKind =
   /** The PR head moved while a review ran and the same run is re-reviewing at
    *  the new head (agent-review.md item 12). Published by the dispatcher. */
   | "head_moved"
+  /** The run loop threw and the run finishes `failed`: the summary is the
+   *  error's message, redacted and capped, so the run page says why a failed
+   *  run failed even when the reply is never delivered (run-history.md).
+   *  Published by the run loop's catch, before the finish. */
+  | "run_failed"
   /** An MCP server configured for this agent did not answer discovery
    *  (docs/reference/specs/mcp-tools.md item 8); the run proceeds without its tools. One
    *  note per server, published by the dispatcher before the first turn. */
@@ -187,6 +196,11 @@ 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"
+  /** A ship coding child's budget ended with work still in the tree: the run
+   *  loop committed and pushed it to the unit's branch (or says plainly that
+   *  there was nothing to push), so a re-issue starts from the partial work
+   *  (docs/reference/specs/agent-ship.md item 8). */
+  | "budget_salvage"
   /** The native loop's stuck-loop guard: the same tool call failed identically
    *  six times in a row and the run was forced into its write-up. Written by
    *  no loop since that loop's deletion; a record from before it may carry it. */
@@ -205,6 +219,7 @@ export const RUN_NOTE_KINDS = [
   "stopped",
   "spans_dropped",
   "head_moved",
+  "run_failed",
   "mcp_unavailable",
   "follow_up",
   "resumed",
@@ -220,6 +235,7 @@ export const RUN_NOTE_KINDS = [
   "harness_error",
   "policy_refusal",
   "tool_refused",
+  "budget_salvage",
   "stuck_loop",
 ] as const satisfies readonly RunNoteKind[];
 type _EveryKindListed = [RunNoteKind] extends [(typeof RUN_NOTE_KINDS)[number]] ? true : never;
@@ -375,6 +391,13 @@ export type RouteInputObject2 = { readonly [key: string]: RouteInputLeafOrList |
 export type RouteInputObject3 = { readonly [key: string]: RouteInputLeafOrList | RouteInputObject2 };
 export type RouteInputValue = RouteInputLeafOrList | RouteInputObject3;
 
+/** How a door decision about a state change ended (docs/decisions/0044-a-routed-write-is-confirmed-in-proportion-to-its-blast-radius.md):
+ *  `hand_back` — the router bound a state-changing command and the door answered
+ *  the line to paste, nothing invoked; `pasted` — the typed line that followed
+ *  a hand-back in its thread, with the same receipt, ran. A routed read
+ *  carries no outcome: it is not a decision about a state change. */
+export type RouteOutcome = "hand_back" | "pasted";
+
 export type RunEvent =
   /** `callId` is the provider's tool_use id — the explicit pair key between a
    *  call and its result (live-view item 13); the runner stamps it on both. */
@@ -519,9 +542,15 @@ export type RunEvent =
       /** The request's trace id (docs/reference/specs/tracing.md), once the root exists. */
       traceId?: string;
       /** The harness the run is driven by (`Harness.name`; docs/reference/specs/harness.md
-       *  item 8): `pi` today. Absent on a command run, which starts no process,
+       *  items 8 and 10): the word the scopes resolved for the preset, `pi`
+       *  when none named it. Absent on a command run, which starts no process,
        *  and on a record written before the seam existed. Additive. */
       harness?: string;
+      /** Whose word put the run on that harness (item 10): the requester's own
+       *  scope, the channel's, or the deployment's top-level block. Absent when
+       *  no scope named the preset — the roster's default — and on records
+       *  written before the word was a scope setting. */
+      harnessScope?: HarnessScope;
       effort?: string;
       repo?: string;
       ref?: string;
@@ -654,6 +683,14 @@ export type RunEvent =
       seq?: number;
       at?: number;
     }
+  /** The run's lease as the harness started it (docs/reference/specs/run-history.md
+   *  item 2; decision 0046): when the wall clock began, when the lease ends,
+   *  and when the loop ends — the lease's end less the write-up and the
+   *  post-step the lease holds back — so a record says how long the run had
+   *  and where its loop was cut. Published by the harness once, at the first
+   *  start of the loop; a resumed run carries the original. Head material,
+   *  like `run_meta`. Additive: unknown → ignored. */
+  | { type: "lease"; startedAt: number; endsAt: number; loopEndsAt: number; seq?: number; at?: number }
   /** The coordinator tag as a fact of the run (docs/reference/specs/run-history.md
    *  item 48a): the instance the run is a child of, the unit its idempotency
    *  key named, and the base branch its pull request targets — published by
@@ -715,7 +752,11 @@ export type RunEvent =
    *  (`command`), `command` the id the model called, `input` the bound input
    *  (redacted, each value capped) and `receipt` the chat form the reply led
    *  with (`routed: <chat form>`, redacted and capped at `ROUTE_RECEIPT_CAP`);
-   *  how the invoke ended is the run's own status and `answer`. */
+   *  how the invoke ended is the run's own status and `answer`. A door
+   *  decision about a state change (record 0044) is a command run too, with
+   *  `outcome` saying which: a hand-back invoked nothing and its `answer` is
+   *  the line to paste; a paste is the typed line that followed, whatever its
+   *  command, `handBackRunId` naming the hand-back's record. */
   | {
       type: "route";
       preset: string;
@@ -726,6 +767,8 @@ export type RunEvent =
       command?: string;
       input?: { readonly [key: string]: RouteInputValue };
       receipt?: string;
+      outcome?: RouteOutcome;
+      handBackRunId?: string;
       seq?: number;
       at?: number;
     }

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

@@ -425,7 +425,8 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
       ev.type === "review_posted" ||
       ev.type === "ship_round" ||
       ev.type === "route" ||
-      ev.type === "reference"
+      ev.type === "reference" ||
+      ev.type === "lease"
     ) {
       sideFactEvents++;
       return;

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

@@ -56,6 +56,8 @@ export interface LiveRunMeta {
   /** The bound credential behind the person (authorization.md item 15): a
    *  resume or restart dispatches under ITS grants again, never the person's. */
   authenticatedAs?: string;
+  /** The app that relayed the request for the person (authorization.md item 14): a resume or restart keeps app ∩ person at the gates. */
+  postedBy?: string;
   effort?: string;
   ref?: string;
   headSha?: string;

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

@@ -109,6 +109,9 @@ export interface RunRecord {
   receivedAt?: number;
   sealedAt?: number;
   replyOk?: boolean;
+  /** Why a `replyOk: false` reply was not delivered (e.g. "no channel to deliver
+   *  to", run-history.md item 38). Absent when the reply was delivered or none was made. */
+  replyNote?: string;
   stepCount?: number;
   schema?: number;
   status: RunStatus;
@@ -206,6 +209,10 @@ export interface RunRecord {
    *  (docs/reference/specs/resident-repos.md item 29) — read off the record,
    *  never off the reply's text. */
   pr?: RunPullRequest;
+  /** The run's lease as the harness started it (item 2; decision 0046): the
+   *  `lease` event, folded at the assembly. Present only on a run whose
+   *  harness started a loop; a record written before the event lacks it. */
+  lease?: RunLease;
   /** What the run cost in tokens, per model, summed from its `model.turn`
    *  spans at finish (`usageOfEvents`; docs/reference/specs/costs.md, cost by user).
    *  Every record written since carries it (zero turns included); one written
@@ -222,6 +229,24 @@ export interface RunPullRequest {
   head?: string;
 }
 
+/** A run's lease as the record names it (item 2): when the wall clock
+ *  began, when the lease ends, and where the loop was cut so the write-up
+ *  and the post-step run inside it. */
+export interface RunLease {
+  startedAt: number;
+  endsAt: number;
+  loopEndsAt: number;
+}
+
+/** The lease a run's events say its harness started — the first `lease`
+ *  event; a resumed run's later generations publish none — or nothing. */
+export function leaseOfEvents(events: readonly RunEvent[]): RunLease | undefined {
+  for (const e of events) {
+    if (e.type === "lease") return { startedAt: e.startedAt, endsAt: e.endsAt, loopEndsAt: e.loopEndsAt };
+  }
+  return undefined;
+}
+
 /** The pull request a run's events say it opened or edited — the last
  *  `pr_opened` wins, as an edit after an open names the same PR — or nothing. */
 export function prOfEvents(events: readonly RunEvent[]): RunPullRequest | undefined {
@@ -462,6 +487,10 @@ export interface RunListOptions {
   /** The runs one run spawned or that continue a thread it opened
    *  (`RunRecord.parentRunId`, item 46) — a conductor's children as one listing. */
   parentRunId?: string;
+  /** The runs that name one pull request (`namesPullRequest`, item 58): the
+   *  coding runs whose post-step opened or edited it and the review runs that
+   *  posted to it — the findings ledger's runs as one listing. */
+  pr?: { repo: string; number: number };
   /** What the ACTOR may see (authorization): the store predicate compiled
    *  from the policy, pushed down so no surface loads rows and filters after.
    *  Absent = no visibility constraint — only a caller that has already decided
@@ -574,6 +603,27 @@ export function matchesVisibility(
   }
 }
 
+/** The pull request number a stored row names (item 58): the one its coding
+ *  post-step opened or edited (`pr`), else the one its review posted to
+ *  (`reviewPost.target`). Undefined for a run that named none — a review whose
+ *  post was skipped included. The Worker's `pr_number` column is this value,
+ *  written at `put` and backfilled from `summary_json` with the same rule. */
+export function pullRequestNumberOf(row: Pick<RunListItem, "pr" | "reviewPost">): number | undefined {
+  if (row.pr !== undefined) return row.pr.number;
+  if (row.reviewPost?.posted) return row.reviewPost.target.number;
+  return undefined;
+}
+
+/** The one truth table for `RunListOptions.pr`: the row's repository is the
+ *  pull request's and the number it names is the pull request's. The Worker
+ *  applies the same test in SQL (`repo = ? AND pr_number = ?`). */
+export function namesPullRequest(
+  row: Pick<RunListItem, "repo" | "pr" | "reviewPost">,
+  pr: { repo: string; number: number },
+): boolean {
+  return row.repo === pr.repo && pullRequestNumberOf(row) === pr.number;
+}
+
 /** The list order (`finishedAt` desc, `id` desc) as a cursor predicate: true
  *  when `row` comes strictly after the cursor. Shared by `selectListItems`;
  *  the Worker applies the same predicate in SQL. */
@@ -783,6 +833,7 @@ export function isRunRecord(v: unknown): v is RunRecord {
     if (r[key] !== undefined && !isFiniteNumber(r[key])) return false;
   }
   if (r.replyOk !== undefined && typeof r.replyOk !== "boolean") return false;
+  if (r.replyNote !== undefined && typeof r.replyNote !== "string") return false;
   for (const key of ["stepCount", "schema"] as const) {
     if (r[key] !== undefined && (!isFiniteNumber(r[key]) || !Number.isInteger(r[key]) || (r[key] as number) < 0))
       return false;