@coreplane/switchboard 1.247.0 → 1.249.0

package/dist/assets/src/agents/registry.ts

@@ -2,7 +2,12 @@
 import type { Effort } from "../effort.js";
 import { BASH_TIMEOUT_MAX_MS } from "../execution/bashTimeout.js";
 import { ASKS, RUNAWAY_TURNS_PER_MINUTE, runawayTurnCap, type LoopPreset } from "../core/budgets.js";
-import { CONTRACT_HEADING, CONTRACT_SECTION_HEADINGS, PR_TITLE_GUARD } from "../core/ship/contract.js";
+import {
+  CONTRACT_HEADING,
+  CONTRACT_SECTION_HEADINGS,
+  PR_TITLE_GUARD,
+  TIMEOUT_ON_LONG_COMMANDS,
+} from "../core/ship/contract.js";
 // Which model runs it is resolved separately by the config layers, so any
 // agent can run on any configured provider/model.
 
@@ -183,7 +188,7 @@ const UNIT_CONTRACT = `UNIT CONTRACT: when your first user turn carries a \`${CO
 // it to the unit's board issue without a person writing it there. Both coding
 // prompts carry this verbatim, right after the contract paragraph, so the
 // sandbox and resident children read the same rule.
-const UNIT_HANDOFF = `UNIT HANDOFF: when your first user turn carries a \`${CONTRACT_HEADING}\` block, call the submit_handoff tool once, after submit_pr_description and before your final message, with the typed handoff — deviations: where you departed from the unit as written (from, to, why); followUps: what you found and did not do, and where it belongs (what, where); unproven: which of the unit's test scenarios or criteria you could not prove, and why (criterion, why). Switchboard records it on the run and posts it to the unit's board issue, where a person decides each row's disposition; you never edit the plan's ledger yourself. An empty handoff is submitted as three empty lists, never skipped — a missing handoff reads as an unfinished run, not as nothing to say. Without a \`${CONTRACT_HEADING}\` block, do not call it.`;
+const UNIT_HANDOFF = `UNIT HANDOFF: when your first user turn carries a \`${CONTRACT_HEADING}\` block, call the submit_handoff tool once, after submit_pr_description and before your final message, with the typed handoff — deviations: where you departed from the unit as written (from, to, why); followUps: what you found and did not do, and where it belongs (what, where); unproven: which of the unit's test scenarios or criteria you could not prove, and why (criterion, why); landed (optional): what of the unit was already on the base when you began, and the pull request or commit that carries it (what, where) — when the whole unit is already there, push nothing of your own and open no pull request; the handoff's landed rows end the unit done. Switchboard records it on the run and posts it to the unit's board issue, where a person decides each row's disposition; you never edit the plan's ledger yourself. An empty handoff is submitted as three empty lists, never skipped — a missing handoff reads as an unfinished run, not as nothing to say. Without a \`${CONTRACT_HEADING}\` block, do not call it.`;
 
 // What both execution images carry beyond git and the package managers
 // (docs/reference/specs/execution.md item 10), said in one sentence by every
@@ -233,7 +238,7 @@ Keep notes with the \`notes\` tool: one short document, replaced whole each time
 // project's most expensive checks first; the rule is the runner's to hold, not
 // a line every requester remembers to paste. Stack-agnostic on purpose — the
 // classes are by duration, the project's own scripts and CI say which is which.
-export const CHECKS_BY_COST = `CHECKS BY COST — push before the expensive ones. Every check you might run has a cost class: seconds (a formatter or a linter on the files you touched, one test file, a docs, link or spec check, the typecheck of one package) or minutes (the whole test suite, a build, a dependency install, an end-to-end or full verification). Know a command's class before you run it — from the project's own scripts and CI configuration, from how long it took last time, or by the class above when you have nothing better. Prove each change with the cheapest check that can prove it, matched to the change's scope: a documentation change gets the documentation checks, one module gets its own tests, a shared type gets the typecheck. As soon as the change exists and those checks pass, commit and push — the pushed branch is the deliverable, and an unpushed tree does not survive the run's end. Only then run the expensive checks, once, and fix forward with further commits and pushes. Never start an operation whose expected duration does not fit the time you have left minus what a commit, a push and the description need: push what there is and say plainly what is unverified instead. At the wind-down note, commit and push what compiles, say what does not, then answer. The description's validation names exactly what ran; what did not run is CI's to gate, and you say so.`;
+export const CHECKS_BY_COST = `CHECKS BY COST — push before the expensive ones. Every check you might run has a cost class: seconds (a formatter or a linter on the files you touched, one test file, a docs, link or spec check, the typecheck of one package) or minutes (the whole test suite, a build, a dependency install, an end-to-end or full verification). Know a command's class before you run it — from the project's own scripts and CI configuration, from how long it took last time, or by the class above when you have nothing better. Prove each change with the cheapest check that can prove it, matched to the change's scope: a documentation change gets the documentation checks, one module gets its own tests, a shared type gets the typecheck. As soon as the change exists and those checks pass, commit and push — the pushed branch is the deliverable, and an unpushed tree does not survive the run's end. Only then run the expensive checks, once, and fix forward with further commits and pushes. Never start an operation whose expected duration does not fit the time you have left minus what a commit, a push and the description need: push what there is and say plainly what is unverified instead. At the wind-down note, commit and push what compiles, say what does not, then answer. ${TIMEOUT_ON_LONG_COMMANDS} The description's validation names exactly what ran; what did not run is CI's to gate, and you say so.`;
 
 const CODING_SYSTEM = `You are Switchboard's coding agent, operating from a Slack request.
 
@@ -539,7 +544,7 @@ Your tools work without a workspace: the GitHub tools — \`github_repos\` (the
 
 ${statusCardRule('"Read the issue and its thread", "Post the comment"')} A one-step answer needs no checklist; post one when the request has steps the person would wait on.
 
-You cannot run commands, clone repositories, edit code, or review pull requests, and you cannot search the web. Other Switchboard agents can: for a code change or a pull request tell the user to re-send with \`agent:ship\` (it makes the change, opens the PR and loops review); for a PR review, \`agent:review\`; for a web-research question, \`agent:research\` (e.g. "\`agent:ship in acme/api: fix the failing login test\`", "\`agent:research compare X and Y\`"). Delete an issue only when the user explicitly asked to delete it (closing is an update).`;
+You cannot run commands, clone repositories, edit code, or review pull requests, and you cannot search the web. Other Switchboard agents can, and a plain message reaches them by itself: for a code change or a pull request, say what you found and that the change is not yours to make, and that asking for it in plain words in a new message — "in acme/api: fix the failing login test" — starts the agent that makes the change, opens the PR and loops review; the same for a PR review ("review <PR URL>") and a web-research question ("compare X and Y on the web"). Never hand back a command or an \`agent:…\` line for the person to type: describe the ask in their words. Delete an issue only when the user explicitly asked to delete it (closing is an update).`;
 
 // The explore agent (docs/reference/specs/agent-explore.md): a long, read-only
 // investigation — "run our CI locally and validate the claims", "how long does
@@ -562,9 +567,9 @@ THE DELIVERABLE IS A CLAIM TABLE. Turn the request into the claims it makes or a
 
 TIME. Your budget is up to two hours — less when a boundary or the request's \`budget:\` directive clipped it, which the runtime-config block above says — and the wrap-up warning tells you when to stop starting new checks. A single command is capped at ${BASH_TIMEOUT_MAX_MS / 60_000} minutes (pass the bash tool's \`timeoutMs\`, up to ${BASH_TIMEOUT_MAX_MS} ms, for a long one). A job that needs longer — a full suite, a build, a pipeline run — is started detached and polled across tool calls: \`setsid -f sh -c '<command> > /tmp/job.log 2>&1; echo $? > /tmp/job.exit'\`, then \`tail -n 40 /tmp/job.log\` and \`cat /tmp/job.exit\` on later calls (a plain background job dies with the command that started it; a \`setsid -f\` job outlives it). Batch commands into few tool calls; never explore file by file.
 
-READ-ONLY: NEVER open a pull request, and never commit or push — no branch, no \`gh pr create\`, no PR or issue write of any kind. You hold a read credential and your job is to find out, not to change. If the investigation shows a change is needed, say exactly what and where in your write-up and point the user at \`agent:ship\` (it makes the change, opens the PR and loops review).
+READ-ONLY: NEVER open a pull request, and never commit or push — no branch, no \`gh pr create\`, no PR or issue write of any kind. You hold a read credential and your job is to find out, not to change. If the investigation shows a change is needed, say exactly what and where in your write-up, and that asking for it in plain words in a new message ("in <owner/name>: <the change>") starts the agent that makes the change, opens the PR and loops review — never hand back a command or an \`agent:…\` line to type.
 
-You cannot attach or post files: your whole answer is text. Never say a file is attached or below — name its path in the workspace and describe it (what it shows, its size) instead; a person who needs the file itself asks \`agent:coding\`, which can attach.
+You cannot attach or post files: your whole answer is text. Never say a file is attached or below — name its path in the workspace and describe it (what it shows, its size) instead; a person who needs the file itself asks for it to be attached in a new message, which reaches a preset that can.
 
 ${statusCardRule('"Clone and install", "Time the full suite"')}
 

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

@@ -18,6 +18,10 @@
 
 export const MINUTE_MS = 60_000;
 
+/** Minutes → milliseconds, for a duration a request names in minutes (a drain's
+ *  length): the multiplication lives here so no other file holds it. */
+export const minutesToMs = (minutes: number): number => minutes * MINUTE_MS;
+
 /** One calendar day in milliseconds: the unit the daily cost and delivery ranges
  *  step by (`dayOf`, the day count of a range). A day is not a lease, but it is
  *  a duration, and every duration is read from this table rather than written
@@ -61,6 +65,26 @@ export const ATTACH_REQUEST_MIN_MS = 30_000;
  *  that opened the question stands. */
 export const HARNESS_PROBE_WAIT_MS = 5 * MINUTE_MS;
 
+/** The resident fleet drain (docs/decisions/0059; docs/reference/specs/resident-repos.md
+ *  item 69; docs/reference/specs/release-and-deploy.md item 31). A deploy closes
+ *  the fleet to new runs and waits for the runs in flight to end: `deployWaitMaxMs`
+ *  is that wait, past a coding child's whole lease (its ask plus its write-up),
+ *  the longest a run in flight can outlive the drain's start; the drain itself
+ *  lasts the wait plus `marginMinutes`, and the registry caps any drain at
+ *  `maxMinutes` so one nobody lifted is an hour and a half, not a day. A run
+ *  asked during a drain waits at its attach one `pollMs` at a time under its
+ *  own lease less `leaseReserveMs` (what the attach and the work after it
+ *  need), `waitMaxMs` with no lease to clip it. */
+export const DRAIN = {
+  pollMs: 30_000,
+  waitMaxMs: 60 * MINUTE_MS,
+  leaseReserveMs: 10 * MINUTE_MS,
+  deployWaitMaxMs: 60 * MINUTE_MS,
+  marginMinutes: 5,
+  maxMinutes: 90,
+  defaultMinutes: 60,
+} as const;
+
 /** The presets that run the tool loop, and the one pipeline preset. */
 export const LOOP_PRESETS = ["general", "coding", "review", "research", "explore", "conductor"] as const;
 export type LoopPreset = (typeof LOOP_PRESETS)[number];

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

@@ -233,9 +233,10 @@ export interface CoordinatorUnit {
   /** The unit's thread, once opened; a generated plan's is the requesting thread from the start. */
   threadKey?: string;
   sourceUrl?: string;
-  /** The unit's review thread, opened once beside the unit's thread: every
-   *  review round runs there (record 0034), so the review child's worktree is
-   *  readonly and its own and no round wipes the coding thread's. */
+  /** Retired (record 0055): a bot before it opened a review thread beside the
+   *  unit's and ran every review round there. A row that carries one keeps its
+   *  review rounds there; a new row never gets one — every child of the unit
+   *  runs in the unit's thread. */
   reviewThread?: { threadKey: string; sourceUrl?: string };
   /** The unit's board issue in the repository, when one titled by the unit id exists — the handoff's destination. */
   issue?: number;

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

@@ -307,16 +307,27 @@ function readRecordReturn(step: string, a: BotAnswer): StepReturn {
   };
 }
 
+/** The check runs a pr-check answer carries at the head (agent-ship item 9), shape-checked. */
+function isCommitChecks(v: unknown): v is { total: number; pending: string[]; failed: string[] } {
+  if (typeof v !== "object" || v === null) return false;
+  const c = v as Record<string, unknown>;
+  const names = (x: unknown) => Array.isArray(x) && x.every((n) => typeof n === "string");
+  return typeof c.total === "number" && names(c.pending) && names(c.failed);
+}
+
 function prCheckReturn(step: string, a: BotAnswer): StepReturn {
   const { ok, state, prNumber, url, headSha, sha, mergedAt, at } = a.body;
   if (ok === true && state === "none") {
-    const { unrecovered } = a.body;
+    const { unrecovered, aheadOfBase } = a.body;
     return {
       type: "pr-check",
       step,
       pr: {
         state: "none",
         ...(unrecovered === "no_commits" || unrecovered === "no_base" ? { unrecovered } : {}),
+        // The branch's commits over the base, when the bot could read them
+        // (agent-ship item 12): zero is the `already_landed` ending's fact.
+        ...(typeof aheadOfBase === "number" ? { aheadOfBase } : {}),
       },
       at,
     };
@@ -331,6 +342,7 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
         url,
         ...(typeof headSha === "string" ? { headSha } : {}),
         ...(typeof a.body.autoMergeEnabled === "boolean" ? { autoMergeEnabled: a.body.autoMergeEnabled } : {}),
+        ...(isCommitChecks(a.body.checks) ? { checks: a.body.checks } : {}),
       },
       at,
     };
@@ -561,13 +573,20 @@ async function runUnit(
               `${prefix}/end/pr-facts`,
               answerOf(
                 "pr-check",
-                await step.do(`${prefix}/end/pr-facts`, STEP_CONFIG, () => call(bot, "pr-check", tag)),
+                await step.do(`${prefix}/end/pr-facts`, STEP_CONFIG, () =>
+                  call(bot, "pr-check", { ...tag, checks: true }),
+                ),
               ),
             );
             if (check.type === "pr-check" && check.pr.state === "merged")
               endFacts = { merged: { sha: check.pr.sha, mergedAt: check.pr.mergedAt } };
-            else if (check.type === "pr-check" && check.pr.state === "open" && check.pr.autoMergeEnabled !== undefined)
-              endFacts = { autoMergeEnabled: check.pr.autoMergeEnabled };
+            else if (check.type === "pr-check" && check.pr.state === "open")
+              endFacts = {
+                ...(check.pr.autoMergeEnabled !== undefined ? { autoMergeEnabled: check.pr.autoMergeEnabled } : {}),
+                // The checks at the approved head (record 0055): the report's
+                // headline is a claim about them, never "merge-ready" over a red one.
+                ...(check.pr.checks !== undefined ? { checks: check.pr.checks } : {}),
+              };
           } catch {
             // the report simply omits the fact
           }
@@ -650,7 +669,9 @@ async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string):
       });
     }
     endings[next] = ending.kind;
-    cursor = settleUnit(graph, cursor, next, ending.kind === "merged" ? "done" : "failed");
+    // A unit is done for its dependents when the base carries its scope: the
+    // runner's merge, or a scope that had already landed before the attempt.
+    cursor = settleUnit(graph, cursor, next, isSettledDone(ending.kind) ? "done" : "failed");
   }
   // Blocked units, in the plan's order: each told its own ending, so the rows
   // and the summary say why it never ran. Every blocked unit's ending is known
@@ -669,15 +690,27 @@ async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string):
     await step.do(`${id}/end`, STEP_CONFIG, () => call(bot, "unit-end", body));
   }
   if (!cursorFinished(cursor)) throw new Error(`the plan's cursor did not finish: ${JSON.stringify(cursor.status)}`);
-  const settled = (kind: string) => kind === "merged" || kind === "merge_ready";
   return {
     instance: instanceId,
     ...(plan.planId !== undefined ? { planId: plan.planId } : {}),
     units: endings,
-    outcome: cursor.order.every((id) => settled(endings[id] ?? "")) ? "completed" : "failed",
+    outcome: cursor.order.every((id) => isSettledOutcome(endings[id] ?? "")) ? "completed" : "failed",
   };
 }
 
+/** The endings whose unit's scope is on the base, so its dependents run on a
+ *  base that carries it (agent-ship item 12): the runner's merge, a merge found
+ *  already made, or a scope that had landed before the attempt. */
+function isSettledDone(kind: string): boolean {
+  return kind === "merged" || kind === "already_landed";
+}
+
+/** The endings a plan closes ✅ over: every `isSettledDone` one, plus
+ *  merge-ready — the work stands and a person's merge is the only gate left. */
+function isSettledOutcome(kind: string): boolean {
+  return isSettledDone(kind) || kind === "merge_ready";
+}
+
 /** The Workflow's body. The finish is asked on every path — as `failed`, best
  *  effort, when the walk threw — and the cause is rethrown, so the instance's
  *  own status says what happened and the parent's record exists either way. */

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

@@ -0,0 +1,348 @@
+// The model card (record 0052): the resolved description of one
+// `<block>/<model>` for one run — the wire, the vendor, the effort levels, the
+// output-cap field, the window, the input kinds, the cache rule and the price
+// source — layered operator over registry over wire defaults, each field with
+// the layer that named it. `decideControls` then answers, before the first
+// call, whether each control is native, degraded with a reason, or refused.
+//
+// Node-free on purpose: the resolver reads a `CardRegistry` seam, never pi's
+// files, so the memory Worker's build can carry this leaf. The production
+// catalog lives in ./modelRegistry.ts.
+
+import { EFFORT_LEVELS, type Effort } from "../effort.js";
+import { vendorOf, wireOf, type ProviderConfig, type Wire } from "./provider.js";
+import type { RegistryCard } from "./modelRegistry.js";
+
+/** Which layer named a field: the operator's block, the registry card, or the
+ *  wire's structural default (the one place a vendor's name may appear). */
+export type Provenance = "operator" | "registry" | "wire";
+
+/** One tier's wire word and how the card arrived at it: `named` when the
+ *  layer names this tier itself (its own wire word, whatever the spelling —
+ *  `LOW`, `default` — or pi's rule for an unlisted low/medium/high), false
+ *  when the word is a lower tier's, reached by pi's fallback rule. */
+export interface LevelWord {
+  word: string;
+  named: boolean;
+}
+
+/** The card's levels: each of our tiers → the wire's word with its standing,
+ *  or `refused`; or `unknown` as a whole (no layer names this model's levels). */
+export type LevelMap = Record<Effort, LevelWord | "refused"> | "unknown";
+export type InputSupport = boolean | "unknown";
+export type CacheRule = "automatic" | "markers" | "none" | "unknown";
+
+export interface CardPrice {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+export interface ModelCard {
+  ref: string;
+  block: string;
+  model: string;
+  vendor: string;
+  wire: Wire;
+  levels: LevelMap;
+  /** The body field the output cap is spelled with on this model's wire. */
+  capField: string;
+  window: number;
+  inputs: { image: InputSupport; document: InputSupport };
+  cache: CacheRule;
+  /** The rate card when a layer names one; the meter applies it in a later slice. */
+  price?: CardPrice;
+  provenance: Record<"levels" | "capField" | "window" | "inputs" | "cache" | "price", Provenance>;
+}
+
+/** The catalog seam `resolveModelCard` reads — pi's registry behind
+ *  ./modelRegistry.ts in production, a table in tests. */
+export interface CardRegistry {
+  card(catalog: string | undefined, wire: Wire, model: string): RegistryCard | undefined;
+}
+
+/** The output-cap field each wire spells the cap with, unvouched. */
+const WIRE_CAP_FIELD: Readonly<Record<Wire, string>> = {
+  "anthropic-messages": "max_tokens",
+  "openai-chat": "max_completion_tokens",
+  "openai-responses": "max_output_tokens",
+};
+
+/** pi's own default for a `models.json` card without a window: compacting
+ *  early beats overflowing a window no layer can vouch for. */
+export const UNKNOWN_WINDOW = 128_000;
+
+/** The vendor-keyed cache table, the wire defaults' one vendor-name table
+ *  (record 0052): the vendors whose caches are automatic, and Anthropic, whose
+ *  cache needs explicit markers. A vendor not here is `unknown`. */
+const VENDOR_CACHE: Readonly<Record<string, CacheRule>> = {
+  anthropic: "markers",
+  openai: "automatic",
+  deepseek: "automatic",
+  groq: "automatic",
+  moonshot: "automatic",
+  moonshotai: "automatic",
+  grok: "automatic",
+  xai: "automatic",
+  gemini: "automatic",
+  google: "automatic",
+};
+
+/** The highest tier below `tier` the map names (pi's fallback rule), or
+ *  undefined when it names none. */
+function highestNamedBelow(map: Record<string, string | null> | undefined, tier: Effort): string | undefined {
+  const at = EFFORT_LEVELS.indexOf(tier);
+  for (let i = at - 1; i >= 0; i--) {
+    const word = map?.[EFFORT_LEVELS[i]!];
+    if (typeof word === "string") return word;
+  }
+  return undefined;
+}
+
+/** A registry or operator level map read by pi's rule: `null` refuses a tier;
+ *  `low`, `medium`, `high` are native unless null; `xhigh` and `max` are
+ *  native only when named, else the highest named tier below them (refused
+ *  when none is named). `reasoning: false` refuses every tier. */
+function levelMapOf(map: Record<string, string | null> | undefined, reasoning: boolean | undefined): LevelMap {
+  const out = {} as Record<Effort, LevelWord | "refused">;
+  for (const tier of EFFORT_LEVELS) {
+    if (reasoning === false) {
+      out[tier] = "refused";
+      continue;
+    }
+    const word = map?.[tier];
+    if (word === null) out[tier] = "refused";
+    else if (typeof word === "string") out[tier] = { word, named: true };
+    else if (tier === "low" || tier === "medium" || tier === "high") out[tier] = { word: tier, named: true };
+    else {
+      const below = highestNamedBelow(map, tier);
+      out[tier] = below === undefined ? "refused" : { word: below, named: false };
+    }
+  }
+  return out;
+}
+
+function priceOf(
+  raw: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number } | undefined,
+): CardPrice | undefined {
+  if (!raw) return undefined;
+  const { input, output, cacheRead, cacheWrite } = raw;
+  if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined)
+    return undefined;
+  return { input, output, cacheRead, cacheWrite };
+}
+
+/**
+ * One run's card: the operator's `models.<id>` override over the registry card
+ * the block's `catalog` names over the wire's structural defaults, each field
+ * carrying the layer that named it (record 0052). The block must exist —
+ * the dispatcher checks it first — and a ref the block does not cover still
+ * resolves, from the wire defaults, saying so.
+ */
+export function resolveModelCard(
+  ref: string,
+  blocks: Readonly<Record<string, ProviderConfig>>,
+  registry: CardRegistry,
+): ModelCard {
+  const vendor = vendorOf(ref, blocks);
+  const block = blocks[vendor.block];
+  const wire = block ? wireOf(block) : "openai-chat";
+  const override = block?.models?.[vendor.model];
+  const card: RegistryCard | undefined = registry.card(block?.catalog ?? vendor.block, wire, vendor.model);
+
+  const levels: LevelMap =
+    override?.levels !== undefined
+      ? levelMapOf(override.levels, undefined)
+      : card?.thinkingLevelMap !== undefined || card?.reasoning !== undefined
+        ? levelMapOf(card?.thinkingLevelMap, card?.reasoning)
+        : "unknown";
+  const levelsProvenance: Provenance =
+    override?.levels !== undefined ? "operator" : levels === "unknown" ? "wire" : "registry";
+
+  const capField = override?.capField ?? (card?.compat?.maxTokensField as string | undefined) ?? WIRE_CAP_FIELD[wire];
+  const capProvenance: Provenance =
+    override?.capField !== undefined ? "operator" : card?.compat?.maxTokensField !== undefined ? "registry" : "wire";
+
+  const window = override?.window ?? card?.contextWindow ?? UNKNOWN_WINDOW;
+  const windowProvenance: Provenance =
+    override?.window !== undefined ? "operator" : card?.contextWindow !== undefined ? "registry" : "wire";
+
+  const image: InputSupport =
+    override?.inputs?.image ?? (card?.input !== undefined ? card.input.includes("image") : "unknown");
+  const document: InputSupport = override?.inputs?.document ?? "unknown";
+  const inputsProvenance: Provenance =
+    override?.inputs !== undefined ? "operator" : card?.input !== undefined ? "registry" : "wire";
+
+  const cache = override?.cache ?? VENDOR_CACHE[vendor.vendor] ?? "unknown";
+  const cacheProvenance: Provenance = override?.cache !== undefined ? "operator" : "wire";
+
+  const price = priceOf(override?.price) ?? priceOf(card?.cost);
+  const priceProvenance: Provenance =
+    priceOf(override?.price) !== undefined ? "operator" : price !== undefined ? "registry" : "wire";
+
+  return {
+    ref,
+    block: vendor.block,
+    model: vendor.model,
+    vendor: vendor.vendor,
+    wire,
+    levels,
+    capField,
+    window,
+    inputs: { image, document },
+    cache,
+    ...(price ? { price } : {}),
+    provenance: {
+      levels: levelsProvenance,
+      capField: capProvenance,
+      window: windowProvenance,
+      inputs: inputsProvenance,
+      cache: cacheProvenance,
+      price: priceProvenance,
+    },
+  };
+}
+
+/** What the request asks of the model's controls, for `decideControls`. */
+export interface AskedControls {
+  effort?: Effort;
+  images?: number;
+  documents?: number;
+}
+
+export type ControlName = "effort" | "cap" | "inputs" | "window" | "cache";
+
+/** One control's decision before the first call (record 0052): `native`
+ *  (the wire's own word goes out, vouched for by a layer), `degraded` (the
+ *  card cannot vouch — a fallback with `applied` differing from `asked`, or an
+ *  unvouched send with `vouched: false`), or `refused` (the run never starts). */
+export interface ControlDecision {
+  control: ControlName;
+  outcome: "native" | "degraded" | "refused";
+  asked?: string;
+  applied?: string;
+  vouched: boolean;
+  why: string;
+}
+
+/** Every control decided against the card (record 0052). A control the request does
+ *  not ask about is not decided at all — no note, no refusal. The output cap
+ *  and the window are always decided: every run sends one and compacts
+ *  somewhere. */
+export function decideControls(card: ModelCard, asked: AskedControls): ControlDecision[] {
+  const decisions: ControlDecision[] = [];
+
+  if (asked.effort !== undefined) {
+    const tier = asked.effort;
+    if (card.levels === "unknown") {
+      decisions.push({
+        control: "effort",
+        outcome: "degraded",
+        asked: tier,
+        applied: tier,
+        vouched: false,
+        why: `no layer names ${card.model}'s levels; the word goes out unvouched`,
+      });
+    } else {
+      const level = card.levels[tier];
+      if (level === "refused") {
+        decisions.push({
+          control: "effort",
+          outcome: "refused",
+          asked: tier,
+          vouched: false,
+          why: `${card.model} does not take effort "${tier}"`,
+        });
+      } else if (level.named) {
+        decisions.push({
+          control: "effort",
+          outcome: "native",
+          asked: tier,
+          applied: level.word,
+          vouched: true,
+          why: "",
+        });
+      } else {
+        decisions.push({
+          control: "effort",
+          outcome: "degraded",
+          asked: tier,
+          applied: level.word,
+          vouched: true,
+          why: `${card.model} does not take effort "${tier}"; the highest named tier below it is "${level.word}"`,
+        });
+      }
+    }
+  }
+
+  const capVouched = card.provenance.capField !== "wire";
+  decisions.push({
+    control: "cap",
+    outcome: capVouched ? "native" : "degraded",
+    applied: card.capField,
+    vouched: capVouched,
+    why: capVouched ? "" : `no layer names the cap field; the cap goes out as ${card.capField} unvouched`,
+  });
+
+  const images = asked.images ?? 0;
+  const documents = asked.documents ?? 0;
+  if (images > 0) {
+    if (card.inputs.image === true)
+      decisions.push({
+        control: "inputs",
+        outcome: "native",
+        asked: "image",
+        applied: "image",
+        vouched: true,
+        why: "",
+      });
+    else if (card.inputs.image === false)
+      decisions.push({
+        control: "inputs",
+        outcome: "refused",
+        asked: "image",
+        vouched: false,
+        why: `${card.model} takes no images`,
+      });
+    else
+      decisions.push({
+        control: "inputs",
+        outcome: "degraded",
+        asked: "image",
+        applied: "image",
+        vouched: false,
+        why: `no layer names ${card.model}'s image support; the image goes out unvouched`,
+      });
+  }
+  if (documents > 0) {
+    decisions.push({
+      control: "inputs",
+      outcome: "degraded",
+      asked: "document",
+      applied: "text",
+      vouched: false,
+      why: "documents reach a provider as a text stub until the harness carries files",
+    });
+  }
+
+  const windowVouched = card.provenance.window !== "wire";
+  decisions.push({
+    control: "window",
+    outcome: windowVouched ? "native" : "degraded",
+    applied: String(card.window),
+    vouched: windowVouched,
+    why: windowVouched ? "" : `no layer names the window; compacting at ${card.window}`,
+  });
+
+  const cacheNative = card.cache !== "unknown";
+  decisions.push({
+    control: "cache",
+    outcome: cacheNative ? "native" : "degraded",
+    applied: card.cache,
+    vouched: cacheNative,
+    why: cacheNative ? "" : `no layer names ${card.model}'s cache rule`,
+  });
+
+  return decisions;
+}

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

@@ -1,3 +1,4 @@
+import { parseModelRef } from "./provider.js";
 import type { ModelUsage, RunUsage } from "./runUsage.js";
 
 // The price of a model's tokens (docs/reference/specs/costs.md): one table
@@ -110,9 +111,14 @@ export function parseModelPrices(raw: unknown): ModelPriceTable {
     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`);
+    let shaped: boolean;
+    try {
+      const parsed = parseModelRef(ref);
+      shaped = parsed.provider !== "" && parsed.model !== "";
+    } catch {
+      shaped = false;
+    }
+    if (!shaped) 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`,
@@ -160,8 +166,11 @@ 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);
+/** `anthropic/claude-fable-5` → `claude-fable-5`: the spans name the provider, the price
+ *  table the model. The list fallback drops the provider prefix alone (costs.md item 4b),
+ *  so an aggregator's vendor-prefixed ref (`openrouter/anthropic/claude-…`) stays a list
+ *  miss — reported unpriced, never silently billed at another provider's rate. */
+export const modelIdOf = (ref: string): string => (ref.includes("/") ? parseModelRef(ref).model : 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`

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;
+}