catherd-cli 1.1.1 → 1.2.0

package/src/services/credentials.ts

@@ -0,0 +1,69 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { CatherdError, isCatherdError } from "../domain/errors.ts";
+import { log } from "../infra/log.ts";
+import { configDir } from "../infra/paths.ts";
+import { readVersioned, writeJsonAtomic } from "../infra/store.ts";
+
+// Spec §10.4 and 1.2 §9: `<config>/credentials.json`, mode 600, holds catherd's own keys: Jev's
+// (`typesafeApiKey`) and Artificial Analysis's (`artificialAnalysisApiKey`). The schema is a loose object,
+// so a key one catherd does not know survives another's rewrite.
+
+export const credentialsPath = (): string => join(configDir(), "credentials.json");
+
+const CredentialsSchema = z.looseObject({
+  schema: z.literal(1).default(1),
+  typesafeApiKey: z.string().optional(),
+  artificialAnalysisApiKey: z.string().optional(),
+});
+export type CredentialField = "typesafeApiKey" | "artificialAnalysisApiKey";
+
+/** How to repair a credentials file catherd cannot read: `init` alone refuses to overwrite it. */
+const credentialsFix = (): string =>
+  `delete ${credentialsPath()} and run catherd init, or write it as {"schema": 1, "typesafeApiKey": "<your key>"}`;
+const readCredentials = () =>
+  readVersioned(credentialsPath(), CredentialsSchema, 1, { fix: credentialsFix() });
+
+/** A key saved in credentials.json, or why that file cannot be read (unparsable, newer schema). */
+export function savedCredential(field: CredentialField): {
+  key: string | null;
+  problem: CatherdError | null;
+} {
+  if (!existsSync(credentialsPath())) return { key: null, problem: null };
+  try {
+    return { key: readCredentials()[field]?.trim() || null, problem: null };
+  } catch (e) {
+    return {
+      key: null,
+      problem: isCatherdError(e)
+        ? e
+        : new CatherdError("E_CONFIG_INVALID", String(e), { fix: credentialsFix() }),
+    };
+  }
+}
+
+/**
+ * Keeps every other credential, and the file at mode 600 (spec §10.4). A missing file starts empty; an
+ * unreadable or newer-schema one is refused (it throws) rather than overwritten.
+ */
+export function saveCredential(field: CredentialField, key: string): void {
+  const cur: z.infer<typeof CredentialsSchema> = existsSync(credentialsPath())
+    ? readCredentials()
+    : { schema: 1 };
+  writeJsonAtomic(credentialsPath(), { ...cur, schema: 1, [field]: key.trim() }, { mode: 0o600 });
+}
+
+/**
+ * Spec 1.2 §9: `ARTIFICIAL_ANALYSIS_API_KEY`, else the saved key; null when neither has one. The key is
+ * optional, so a credentials file that cannot be read means no key here; it is logged.
+ */
+export function aaKey(env: Record<string, string | undefined> = process.env): string | null {
+  const fromEnv = env.ARTIFICIAL_ANALYSIS_API_KEY?.trim();
+  if (fromEnv) return fromEnv;
+  const { key, problem } = savedCredential("artificialAnalysisApiKey");
+  if (problem) log("warn", "sources", { error: `no Artificial Analysis key: ${problem.message}` });
+  return key;
+}
+
+export const saveAaKey = (key: string): void => saveCredential("artificialAnalysisApiKey", key);

package/src/services/doctor-sources.ts

@@ -0,0 +1,76 @@
+import type { Profile } from "../domain/profile.ts";
+import { type StandInToConfirm, standInsToConfirm } from "../domain/profile-rules.ts";
+import { loadCatalog } from "./catalog-service.ts";
+import type { Check } from "./doctor-checks.ts";
+import { runnableBackends } from "./profile-store.ts";
+import { sourcesStatus, TTL_MS } from "./source-sync.ts";
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+
+/** An age as doctor prints it: minutes under an hour, hours under two days, else days. */
+export function ageText(ms: number): string {
+  if (ms < HOUR) return `${Math.max(1, Math.round(ms / 60_000))} min`;
+  if (ms < 2 * DAY) return `${Math.round(ms / HOUR)} h`;
+  return `${Math.round(ms / DAY)} d`;
+}
+
+/** Spec 1.2 §6.1, §9: the stand-ins to confirm across `profiles`, one per canonical rung. */
+export function standInsToConfirmIn(profiles: Profile[]): StandInToConfirm[] {
+  if (profiles.length === 0) return [];
+  const c = loadCatalog({ timings: false });
+  const seen = new Map<string, StandInToConfirm>();
+  for (const p of profiles)
+    for (const x of standInsToConfirm(p, c, runnableBackends()))
+      if (!seen.has(x.canonical)) seen.set(x.canonical, x);
+  return [...seen.values()];
+}
+
+/** `gpt-5.6-terra#high (repo_code, terminal, honesty)`, the rung and the dimensions a stand-in fills. */
+const confirmText = (xs: StandInToConfirm[]): string =>
+  `stand-ins to confirm: ${xs.map((x) => `${x.canonical} (${x.dims.map((d) => d.dim).join(", ")})`).join(", ")}`;
+
+/**
+ * Spec 1.2 §9: the `sources` row: each source's age and last error, whether an Artificial Analysis key is
+ * set, its requests left today (`x-ratelimit-remaining` of its last answer), and the linked profiles'
+ * stand-ins to confirm (`confirm`, spec 1.2 §6.1). `info` before the first sync (routing uses the shipped
+ * scores); a warning when a source fails or has not been fetched for two TTLs (a day), since background
+ * syncs would have refreshed it. It reads the sync's state only: no request.
+ */
+export function sourcesCheck(now = Date.now(), confirm: StandInToConfirm[] = []): Check {
+  const s = sourcesStatus();
+  const shown = s.sources.filter((x) => x.source !== "artificial-analysis" || s.aaKey);
+  const keyless = s.sources.filter((x) => x.source !== "artificial-analysis");
+  const sameDay =
+    s.rateLimitAt !== null && s.rateLimitAt.slice(0, 10) === new Date(now).toISOString().slice(0, 10);
+  const left =
+    s.rateLimitRemaining === null
+      ? ""
+      : sameDay
+        ? `, ${s.rateLimitRemaining} requests left today`
+        : `, ${s.rateLimitRemaining} requests left on ${s.rateLimitAt?.slice(0, 10)}`;
+  const aa = `${s.aaKey ? `Artificial Analysis key set${left}` : "no Artificial Analysis key"}${confirm.length ? `; ${confirmText(confirm)}` : ""}`;
+  const base = { id: "sources", label: "sources" };
+  if (keyless.every((x) => x.fetchedAt === null && x.error === null))
+    return {
+      ...base,
+      state: "info",
+      word: "not synced",
+      detail: `routing uses the shipped scores; ${aa}`,
+      fix: "catherd catalog sync",
+    };
+  const parts = shown.map(
+    (x) =>
+      `${x.source} ${x.fetchedAt ? ageText(now - Date.parse(x.fetchedAt)) : "never"}${x.error ? ` (${x.error})` : ""}`,
+  );
+  const failing = shown.some((x) => x.error !== null);
+  const stale = keyless.some((x) => x.fetchedAt === null || now - Date.parse(x.fetchedAt) > 2 * TTL_MS);
+  const warn = failing || stale;
+  return {
+    ...base,
+    state: warn ? "warn" : "ok",
+    word: failing ? "failing" : stale ? "stale" : "fresh",
+    detail: `${parts.join(", ")}; ${aa}`,
+    ...(warn ? { fix: "catherd catalog sync --force" } : {}),
+  };
+}

package/src/services/doctor.ts

@@ -9,6 +9,7 @@ import { linkedProfiles } from "./agent-links.ts";
 import { accessChecks } from "./doctor-access.ts";
 import { backendChecks, usedBackends } from "./doctor-backends.ts";
 import { type PushProbe, pushCheck } from "./doctor-push.ts";
+import { sourcesCheck, standInsToConfirmIn } from "./doctor-sources.ts";
 import {
   agentsCheck,
   type Check,
@@ -190,6 +191,15 @@ export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
     }
   }
 
+  // spec 1.2 §9: the public sources' ages and errors, the Artificial Analysis key, and the active and linked
+  // profiles' stand-ins to confirm
+  const mine = [...(active ? [active] : []), ...profiles.filter((p) => p.name !== active?.name)];
+  checks.push(
+    guarded("sources", "sources", "catherd catalog sync --force", () =>
+      sourcesCheck(Date.now(), standInsToConfirmIn(mine)),
+    ),
+  );
+
   checks.push(pluginCheck(d.version));
 
   checks.push(

package/src/services/jev-service.ts

@@ -1,7 +1,5 @@
-import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { z } from "zod";
-import { CatherdError, isCatherdError } from "../domain/errors.ts";
+import type { CatherdError } from "../domain/errors.ts";
 import type { RouteSource } from "../domain/route.ts";
 import {
   canonicalJson,
@@ -17,45 +15,28 @@ import {
 import { assetPath } from "../infra/assets.ts";
 import { type JevTransport, jevRequest } from "../infra/jev-client.ts";
 import { addSecret, log } from "../infra/log.ts";
-import { configDir } from "../infra/paths.ts";
-import { appendJsonl, ensureJsonlHeader, readJsonl, readVersioned, writeJsonAtomic } from "../infra/store.ts";
+import { appendJsonl, ensureJsonlHeader, readJsonl, readVersioned } from "../infra/store.ts";
+import { aaKey, credentialsPath, saveCredential, savedCredential } from "./credentials.ts";
+
+export { credentialsPath };
 
 let file: JevFile | null = null;
 /** catalog/jev.json: the question sets and their rules (spec §5.5). */
 export const jevQuestions = (): JevFile =>
   (file ??= readVersioned(assetPath("catalog/jev.json"), JevFileSchema, 1));
 
-export const credentialsPath = (): string => join(configDir(), "credentials.json");
-const CredentialsSchema = z.looseObject({
-  schema: z.literal(1).default(1),
-  typesafeApiKey: z.string().optional(),
-});
-
-/** Registers the saved Jev key with the redactor, for a process that reads logs without ever calling Jev. */
+/**
+ * Registers the saved keys (Jev's and Artificial Analysis's) with the redactor, for a process that reads
+ * logs without ever using them.
+ */
 export function registerSavedSecrets(): void {
   addSecret(jevKey());
+  addSecret(aaKey());
 }
 
-/** How to repair a credentials file catherd cannot read: `init` alone refuses to overwrite it. */
-const credentialsFix = (): string =>
-  `delete ${credentialsPath()} and run catherd init, or write it as {"schema": 1, "typesafeApiKey": "<your key>"}`;
-const readCredentials = () =>
-  readVersioned(credentialsPath(), CredentialsSchema, 1, { fix: credentialsFix() });
-
 /** The key saved in credentials.json, or why that file cannot be read (unparsable, newer schema). */
-export function savedJevKey(): { key: string | null; problem: CatherdError | null } {
-  if (!existsSync(credentialsPath())) return { key: null, problem: null };
-  try {
-    return { key: readCredentials().typesafeApiKey?.trim() || null, problem: null };
-  } catch (e) {
-    return {
-      key: null,
-      problem: isCatherdError(e)
-        ? e
-        : new CatherdError("E_CONFIG_INVALID", String(e), { fix: credentialsFix() }),
-    };
-  }
-}
+export const savedJevKey = (): { key: string | null; problem: CatherdError | null } =>
+  savedCredential("typesafeApiKey");
 
 /**
  * Spec §5.5: `TYPESAFE_API_KEY`, else `<config>/credentials.json`; null when neither has one. Jev is
@@ -70,16 +51,8 @@ export function jevKey(): string | null {
   return key;
 }
 
-/**
- * Keeps any other credential, and the file at mode 600 (spec §10.4). A missing file starts empty; an
- * unreadable or newer-schema one is refused (it throws) rather than overwritten.
- */
-export function saveJevKey(key: string): void {
-  const cur: z.infer<typeof CredentialsSchema> = existsSync(credentialsPath())
-    ? readCredentials()
-    : { schema: 1 };
-  writeJsonAtomic(credentialsPath(), { ...cur, schema: 1, typesafeApiKey: key.trim() }, { mode: 0o600 });
-}
+/** Saves the Jev key in credentials.json, keeping every other credential (`saveCredential`). */
+export const saveJevKey = (key: string): void => saveCredential("typesafeApiKey", key);
 
 /** A key works when Jev lists its models: no inference, and no dependence on a question set. */
 export async function testJevKey(key: string, o: JevTransport = {}): Promise<boolean> {

package/src/services/ports.ts

@@ -1,3 +1,4 @@
+import type { Provenance } from "./provenance.ts";
 import type { Budget } from "../domain/budget.ts";
 import type { SessionEnv } from "../infra/claude-session.ts";
 import type { BillingMode } from "../domain/cost.ts";
@@ -8,6 +9,7 @@ import type { Role } from "../domain/roles.ts";
 import type { Change, ProfilePatch } from "../domain/profile.ts";
 import type { Issue } from "../domain/profile-rules.ts";
 import type { RouteJev, RouteSource } from "../domain/route.ts";
+import type { SyncReport } from "./source-sync.ts";
 
 /** What the run lifecycle reads from a profile. Rungs are `backend:model#effort`; a role's in ladder order. */
 export interface ProfileView {
@@ -86,6 +88,8 @@ export interface RouteAnswer {
   /** the Jev question set asked, and its summed probabilities, for outcomes.jsonl (spec §5.6) */
   questionSet: string | null;
   jev: RouteJev | null;
+  /** spec 1.2 §5.3, §8: the chosen rung's thresholds, values, sources, facts and run evidence */
+  provenance?: Provenance;
 }
 
 export type { Verdict };
@@ -132,4 +136,6 @@ export interface Deps {
   /** the Claude Code session this process serves (spec §3.3), from its environment; null outside one */
   session: SessionEnv | null;
   now: () => number;
+  /** spec 1.2 §3.2 `catalog_sync`; default: the real sync (tests inject one that never reaches the network) */
+  sync?: (o: { force: boolean }) => Promise<SyncReport>;
 }

package/src/services/profile-service.ts

@@ -15,7 +15,7 @@ import {
   type ProfilePatch,
   resolveProfile,
 } from "../domain/profile.ts";
-import { type Validation, validateProfile } from "../domain/profile-rules.ts";
+import { repairs, type Validation, validateProfile } from "../domain/profile-rules.ts";
 import { ROLES } from "../domain/roles.ts";
 import { withFileLockSync } from "../infra/filelock.ts";
 import { configDir } from "../infra/paths.ts";
@@ -85,10 +85,12 @@ const unsaved = (v: Validation): Saved => ({
 export const CHANGED_ON_DISK = "profile";
 
 /**
- * Spec §7.3 `patch` (profile_set, `catherd profile set`): validates first and writes nothing when invalid.
- * A profile that does not exist yet starts from the default profile. With `expect` (the profile as a
- * preview read it), it writes nothing when the profile under the lock is no longer that one: the patch
- * would land on values the preview never showed.
+ * Spec §7.3 `patch` (profile_set, `catherd profile set`, the TUI's save): validates first and writes
+ * nothing when invalid, unless the save repairs the profile (spec 1.2 §6.2): it removes at least one error
+ * the stored profile had and adds none. Then it saves, and the result's `errors` are those still open. A
+ * profile that does not exist yet starts from the default profile. With `expect` (the profile as a preview
+ * read it), it writes nothing when the profile under the lock is no longer that one: the patch would land on
+ * values the preview never showed.
  */
 export function patchProfile(
   name: string | undefined,
@@ -112,7 +114,7 @@ export function patchProfile(
     const after = applyPatch(before, patch);
     const resolved = resolveProfile(after, n);
     const v = validate(after, n);
-    if (v.errors.length) return unsaved(v);
+    if (v.errors.length && !repairs(profileExists(n) ? validate(before, n) : null, v)) return unsaved(v);
     const diff = diffProfiles(resolveProfile(before, n), resolved);
     return { saved: true, ...v, diff, ...saveAndLink(n, after) };
   });

package/src/services/provenance.ts

@@ -0,0 +1,115 @@
+import { type Catalog, type Confidence, DIMS, type Dim, rungInfo, scoresOf } from "../domain/catalog.ts";
+import { type BillingMode, type Cost, costOf, DEFAULT_BILLING } from "../domain/cost.ts";
+import type { Difficulty, Kind } from "../domain/lane.ts";
+import { type EvidenceTable, evidenceLine, evidenceOf } from "./run-evidence.ts";
+
+/** Spec 1.2 §5.3: one value routing uses for a rung, with where it came from. */
+export interface ValueUsed {
+  dim: Dim;
+  value: number;
+  confidence: Confidence;
+  /** the source a synced value came from; `shipped` for a hand-typed one, `override` for the user's */
+  source: string;
+  benchmark: string;
+  date: string;
+  url: string;
+  /** catherd's guess for this rung: lent by a treat-like or an inferred stand-in (spec 1.2 §6.1) */
+  inferred: boolean;
+  /** the rung the value belongs to, when it is not this one */
+  from: string | null;
+}
+
+/** Spec 1.2 §5.3: one threshold of the lane's bar, the value used against it, and whether it clears. */
+export interface Threshold {
+  dim: Dim;
+  min: number;
+  used: ValueUsed | null;
+  clears: boolean;
+  /** where the default threshold came from (`barsWhy`) */
+  why: string | null;
+}
+
+/** Spec 1.2 §5.3, §8: what `route` reports about the rung it chose. */
+export interface Provenance {
+  rung: string;
+  canonical: string;
+  /** the lane's bar, threshold by threshold; empty when the route read no bar (the default rung) */
+  thresholds: Threshold[];
+  /** every value the rung has */
+  values: ValueUsed[];
+  /** facts that never carry a bar (spec 1.2 §4.1): `<source>.<field>` → value */
+  speed: Record<string, number>;
+  cost: Cost;
+  /** spec 1.2 §8: its runs for the lane's kind (or every kind) and over every kind; never used for routing */
+  evidence: { kind: string | null; all: string | null };
+}
+
+/** Spec 1.2 §5.3: each value a canonical rung has, with its confidence and source, borrowed ones marked. */
+export function valuesUsed(c: Catalog, canonical: string): ValueUsed[] {
+  const s = scoresOf(c, canonical);
+  if (!s) return [];
+  return DIMS.flatMap((dim) => {
+    const r = s.records[dim];
+    if (!r) return [];
+    const from = s.borrowed.includes(dim) ? s.via : (s.standIns[dim] ?? null);
+    return [
+      {
+        dim,
+        value: r.value,
+        confidence: r.confidence,
+        source: r.source ?? "shipped",
+        benchmark: `${r.benchmark} ${r.version}`,
+        date: r.date,
+        url: r.url,
+        inferred: from !== null,
+        from,
+      },
+    ];
+  });
+}
+
+/** Spec 1.2 §5.3: the chosen rung's thresholds for the lane's kind and difficulty, its values and facts. */
+export function provenanceOf(
+  c: Catalog,
+  rung: string,
+  kind: Kind | null,
+  difficulty: Difficulty | null,
+  billing: Partial<Record<string, BillingMode>>,
+  evidence: EvidenceTable,
+): Provenance {
+  const info = rungInfo(c, rung);
+  const values = valuesUsed(c, info.canonical);
+  const bar = kind && difficulty ? c.bars[kind][difficulty] : {};
+  const thresholds: Threshold[] = DIMS.flatMap((dim) => {
+    const min = bar[dim];
+    if (min === undefined || !kind || !difficulty) return [];
+    const used = values.find((v) => v.dim === dim) ?? null;
+    return [
+      {
+        dim,
+        min,
+        used,
+        clears: used !== null && used.value >= min,
+        why: c.barsWhy[dim]?.[difficulty] ?? null,
+      },
+    ];
+  });
+  return {
+    rung,
+    canonical: info.canonical,
+    thresholds,
+    values,
+    speed: info.family?.speed ?? {},
+    cost: costOf(info.family, info.parsed.effort, billing[info.key] ?? DEFAULT_BILLING[info.key]),
+    evidence: {
+      kind: evidenceLine(evidenceOf(evidence, info.canonical, kind)),
+      all: evidenceLine(evidenceOf(evidence, info.canonical)),
+    },
+  };
+}
+
+/** A value as one line: `repo_code 66.6 (adjacent, shipped DeepSWE 1.1, 2026-09-22)`, marking a guess. */
+export function valueWords(v: ValueUsed): string {
+  const lent = v.inferred ? `, inferred from ${v.from}` : "";
+  return `${v.dim} ${v.value} (${v.confidence}, ${v.source} ${v.benchmark}, ${v.date}${lent})`;
+}

package/src/services/routing-service.ts

@@ -24,6 +24,8 @@ import { log } from "../infra/log.ts";
 import { catalogQuery, freshenDiscovery, loadCatalog } from "./catalog-service.ts";
 import { type Asked, askJev, type JevOpts, jevQuestions, logJev } from "./jev-service.ts";
 import type { ProfileView, RouteAnswer, RouteRequest, RoutingPort, Verdict } from "./ports.ts";
+import { provenanceOf } from "./provenance.ts";
+import { runEvidence } from "./run-evidence.ts";
 
 function routingProfile(v: ProfileView, role: Role, spentFraction: number): RoutingProfile {
   const rc = v.roles[role];
@@ -87,8 +89,10 @@ async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
   await freshenWithin(p.role.rungs, req.repo, o.discoveryBudgetMs ?? DISCOVERY_BUDGET_MS);
   const c = loadCatalog({ repo: req.repo });
   const fallback = () => defaultLadder(c, p, req.role);
-  if (req.laneText === null || candidates(c, p, req.role).length <= 1)
-    return answer(fallback(), "default", null, null, null, null);
+  if (req.laneText === null || candidates(c, p, req.role).length <= 1) {
+    const out = answer(fallback(), "default", null, null, null, null);
+    return { ...out, provenance: provenanceOf(c, out.rung, null, null, p.billing, runEvidence(c)) };
+  }
   const lane = parseLaneHeader(req.laneText);
   let asked: Asked | null = null;
   let judged: ReturnType<typeof judgeRoute> | null = null;
@@ -120,6 +124,7 @@ async function route(req: RouteRequest, o: RoutingOpts): Promise<RouteAnswer> {
         ? answer(select(c, p, req.role, kind, lane.difficulty), "lane", kind, lane.difficulty, asked, jev)
         : answer(fallback(), "default", null, null, asked, jev);
   }
+  out.provenance = provenanceOf(c, out.rung, out.kind, out.difficulty, p.billing, runEvidence(c));
   if (asked) {
     logJev(req.runDir, {
       ...asked.meta,

package/src/services/run-evidence.ts

@@ -0,0 +1,86 @@
+import { type Catalog, rungInfo } from "../domain/catalog.ts";
+import type { Kind } from "../domain/lane.ts";
+import { routeAt } from "../domain/route.ts";
+import { replyVerdict } from "./milestones.ts";
+import { listRuns, readAgentRuns, readRecords, readRoutes } from "./run-store.ts";
+
+/** Spec 1.2 §8: what catherd's own runs say about a rung, for one kind or every kind (`*`). */
+export interface Evidence {
+  /** lanes routed to it, or climbed onto it */
+  lanes: number;
+  /** lanes that climbed off it */
+  climbed: number;
+  partial: number;
+  blocked: number;
+  refused: number;
+  /** verifier FAILs it gave, as a verifier (plan 14 Ruling 15) */
+  fails: number;
+}
+
+/** `<canonical rung>|<kind or *>` → its evidence. Shown by route, catalog list and the TUI; never routes. */
+export type EvidenceTable = Record<string, Evidence>;
+
+const VERDICT_FAIL = /^VERDICT: FAIL\b/;
+const zero = (): Evidence => ({ lanes: 0, climbed: 0, partial: 0, blocked: 0, refused: 0, fails: 0 });
+
+/**
+ * Spec 1.2 §8: for each rung and kind, from the run records of every repo on this machine: the lanes routed or
+ * climbed onto it, the climbs off it, its `partial`, `blocked` and `refused` replies (under the kind its lane
+ * was routed as when the dispatch started), and the verifier FAILs it gave. Every count also goes under `*`.
+ * It never changes scores, bars or routing (1.3's, once there is data).
+ */
+export function runEvidence(c: Catalog): EvidenceTable {
+  const out: EvidenceTable = {};
+  const canonicalOf = (rung: string): string | null => {
+    try {
+      return rungInfo(c, rung).canonical;
+    } catch {
+      return null;
+    }
+  };
+  const bump = (rung: string, kind: Kind | null, field: keyof Evidence) => {
+    const canonical = canonicalOf(rung);
+    if (!canonical) return;
+    for (const k of kind ? [kind, "*"] : ["*"]) (out[`${canonical}|${k}`] ??= zero())[field] += 1;
+  };
+  for (const run of listRuns().runs) {
+    const routes = readRoutes(run);
+    // a lane counts once per rung it was on, under the kind of the row that put it there
+    const seen = new Set<string>();
+    for (const r of routes) {
+      const key = `${r.lane} ${r.rung} ${r.kind ?? "*"}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        bump(r.rung, r.kind, "lanes");
+      }
+      if (r.source === "climb" && r.from && r.from !== r.rung) bump(r.from, r.kind, "climbed");
+    }
+    for (const rec of readRecords(run).records) {
+      const kind = rec.lane ? (routeAt(routes, rec.lane, rec.startedAt)?.kind ?? null) : null;
+      if (rec.replyStatus === "partial" || rec.replyStatus === "blocked" || rec.replyStatus === "refused")
+        bump(rec.rung, kind, rec.replyStatus);
+      if (rec.role === "verifier" && rec.status === "ok" && VERDICT_FAIL.test(replyVerdict(run, rec) ?? ""))
+        bump(rec.rung, null, "fails");
+    }
+    for (const a of readAgentRuns(run))
+      if (a.role === "verifier" && a.status === "failed") bump(a.rung, null, "fails");
+  }
+  return out;
+}
+
+/** A rung's evidence for `kind`, else over every kind; null when catherd never ran it. */
+export function evidenceOf(t: EvidenceTable, canonical: string, kind: Kind | null = null): Evidence | null {
+  return (kind ? t[`${canonical}|${kind}`] : undefined) ?? t[`${canonical}|*`] ?? null;
+}
+
+/** Spec 1.2 §8's words: "12 lanes, 2 climbed, 1 partial"; null when there is nothing to say. */
+export function evidenceLine(e: Evidence | null): string | null {
+  if (!e) return null;
+  const parts = [`${e.lanes} ${e.lanes === 1 ? "lane" : "lanes"}`];
+  if (e.climbed) parts.push(`${e.climbed} climbed`);
+  if (e.partial) parts.push(`${e.partial} partial`);
+  if (e.blocked) parts.push(`${e.blocked} blocked`);
+  if (e.refused) parts.push(`${e.refused} refused`);
+  if (e.fails) parts.push(`${e.fails} verifier ${e.fails === 1 ? "FAIL" : "FAILs"}`);
+  return parts.join(", ");
+}