@coreplane/switchboard 1.242.0 → 1.243.0

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

@@ -1,3 +1,9 @@
+import {
+  anthropicTokensCostUsd,
+  parseModelPrices,
+  type AnthropicTokens,
+  type ModelPriceTable,
+} from "./modelPricing.js";
 import { systemClock } from "./trace/clock.js";
 // Spend report: what a group of deployed pieces ("switchboard" = the bot
 // Worker + its containers, the resident/sandbox/memory Workers) costs per day,
@@ -68,6 +74,8 @@ export interface CostsConfig {
   /** Env var holding an Anthropic Admin API key (sk-ant-admin…). Optional feature. */
   anthropicAdminKeyEnv: string;
   groups: Record<string, CostGroupConfig>;
+  /** `costs.prices`: the operator's per-million rates by `<provider>/<model>`, over the Anthropic list (item 4b). */
+  prices: ModelPriceTable;
   /** The snapshot the page and the twins serve (src/core/costsSnapshot.ts). */
   snapshot: {
     /** Hours between two reads of the billing sources. */
@@ -155,6 +163,7 @@ export function parseCostsConfig(raw: unknown): CostsConfig | undefined {
     anthropicAdminKeyEnv:
       typeof r.anthropicAdminKeyEnv === "string" ? r.anthropicAdminKeyEnv : DEFAULT_ANTHROPIC_ADMIN_ENV,
     groups,
+    prices: parseModelPrices(r.prices),
     snapshot: snapshotConfig(r.snapshot),
   };
 }
@@ -691,82 +700,6 @@ export function buildCostReport(
   };
 }
 
-// ---- Anthropic list prices ----------------------------------------------------------------
-
-/** 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
-  );
-}
-
 // ---- range ----------------------------------------------------------------------------
 
 const DEFAULT_DAYS = 30;

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,7 @@
 // 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
@@ -26,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;
@@ -388,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. */
@@ -673,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
@@ -734,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;
@@ -745,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/runRecord.ts

@@ -209,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
@@ -225,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 {
@@ -465,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
@@ -577,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. */