catherd-cli 0.2.1 → 1.1.0

package/src/domain/catalog.ts

@@ -0,0 +1,262 @@
+import { z } from "zod";
+import { type Rung, parseRung } from "./ids.ts";
+import { DIFFICULTIES, type Difficulty, KINDS, type Kind } from "./lane.ts";
+import type { Role } from "./roles.ts";
+
+/** Spec §5.2: the scored dimensions, each on one named benchmark. */
+export const DIMS = ["repo_code", "terminal", "honesty"] as const;
+export type Dim = (typeof DIMS)[number];
+
+/**
+ * Spec §7.1 `billing` keys: a rung's backend, except that opencode's Go models (`opencode-go/…`) are billed
+ * apart from its Zen models (`opencode/…`).
+ */
+export const BILLING_KEYS = [
+  "codex",
+  "claude",
+  "claude-code",
+  "opencode-go",
+  "opencode",
+  "cursor",
+  "grok",
+] as const;
+export type BillingKey = (typeof BILLING_KEYS)[number];
+
+/** The keys a family's `on` map uses; the native `claude` pseudo-backend runs claude-code's model ids. */
+const MODEL_KEYS = ["codex", "claude-code", "opencode-go", "opencode", "cursor", "grok"] as const;
+type ModelKey = (typeof MODEL_KEYS)[number];
+
+export function billingKeyOf(r: Rung): BillingKey {
+  if (r.backend === "opencode" && r.model.startsWith("opencode-go/")) return "opencode-go";
+  return r.backend;
+}
+
+const modelKeyOf = (k: BillingKey): ModelKey => (k === "claude" ? "claude-code" : k);
+
+const BackendModelSchema = z.object({
+  id: z.string().min(1),
+  efforts: z.array(z.string().min(1)),
+  context: z.number().int().positive(),
+});
+
+/** `vendor` and `status` (current or legacy) stay in the data as documentation; nothing reads them. */
+const FamilySchema = z.looseObject({
+  id: z.string().min(1),
+  name: z.string(),
+  capabilities: z.object({ toolUse: z.boolean(), imageIn: z.boolean(), reasoning: z.boolean() }),
+  /** API list price, dollars per million tokens */
+  price: z.object({ input: z.number(), cached: z.number(), output: z.number() }),
+  /** chatgpt-plan: messages per 5 hours relative to GPT-6 Luna (spec §5.3) */
+  planWeight: z.number().positive().optional(),
+  /** claude-plan: billed as usage credits, not from the plan's limits */
+  meteredOnPlan: z.boolean().default(false),
+  on: z.partialRecord(z.enum(MODEL_KEYS), BackendModelSchema),
+  notes: z.record(z.string(), z.string()).default({}),
+});
+export type Family = z.infer<typeof FamilySchema>;
+
+/** `sources` (where the data came from) stays in the file as documentation; nothing reads it. */
+export const ModelsFileSchema = z.looseObject({
+  schema: z.literal(1),
+  version: z.string(),
+  backends: z.record(
+    z.string(),
+    z.looseObject({
+      imageGen: z.object({ tool: z.string(), requires: z.string(), source: z.string() }).optional(),
+    }),
+  ),
+  families: z.array(FamilySchema),
+});
+export type ModelsFile = z.infer<typeof ModelsFileSchema>;
+
+/** A canonical rung: `<canonical model id>#<effort>`, the key scores and treat-likes use. */
+export const CanonicalRung = z.string().regex(/^[^:#\s]+#[^#\s]+$/, "a canonical rung is model#effort");
+
+const ScoreSchema = z.object({
+  rung: CanonicalRung,
+  dim: z.enum(DIMS),
+  value: z.number(),
+  benchmark: z.string(),
+  version: z.string(),
+  url: z.url(),
+  date: z.iso.date(),
+  confidence: z.enum(["verified", "secondary", "inferred"]),
+  note: z.string().optional(),
+});
+export type Score = z.infer<typeof ScoreSchema>;
+
+const BarSchema = z.partialRecord(z.enum(DIMS), z.number());
+type Bars = Record<Kind, Record<Difficulty, Partial<Record<Dim, number>>>>;
+const BarsSchema = z.record(z.enum(KINDS), z.record(z.enum(DIFFICULTIES), BarSchema));
+
+/** `barsWhy` (the reasoning behind the bars) stays in the file as documentation; nothing reads it. */
+export const ScoresFileSchema = z.looseObject({
+  schema: z.literal(1),
+  version: z.string(),
+  benchmarks: z.record(z.enum(DIMS), z.object({ benchmark: z.string(), version: z.string() })),
+  scores: z.array(ScoreSchema),
+  treatLike: z.record(CanonicalRung, z.object({ like: CanonicalRung, note: z.string() })),
+  bars: BarsSchema,
+});
+export type ScoresFile = z.infer<typeof ScoresFileSchema>;
+
+/** `<config>/catalog.override.json` (spec §3.5): the user's treat-likes, scores and bars. */
+export const OverrideSchema = z.looseObject({
+  schema: z.literal(1).default(1),
+  treatLike: z.record(CanonicalRung, CanonicalRung).default({}),
+  scores: z.array(ScoreSchema).default([]),
+  bars: z.partialRecord(z.enum(KINDS), z.partialRecord(z.enum(DIFFICULTIES), BarSchema)).default({}),
+});
+export type Override = z.infer<typeof OverrideSchema>;
+
+interface Listed {
+  id: string;
+  efforts: string[];
+  context: number | null;
+  imageIn: boolean;
+}
+
+/** Everything routing reads, merged from the three layers plus the user's override and own timings. */
+export interface Catalog {
+  families: Family[];
+  backends: ModelsFile["backends"];
+  /** canonical rung → its best-sourced value per dimension (the override's win) */
+  scores: Record<string, Partial<Record<Dim, Score>>>;
+  treatLike: Record<string, { like: string; source: "shipped" | "user" }>;
+  bars: Bars;
+  /** per backend id, the last `listModels()`; absent when never listed */
+  listed: Record<string, { fetchedAt: string; models: Listed[] }>;
+  /** `<canonical rung>|<kind or *>` → median seconds, only with ≥ 5 samples (spec §5.2) */
+  secs: Record<string, number>;
+}
+
+const RANK: Record<Score["confidence"], number> = { verified: 0, secondary: 1, inferred: 2 };
+
+export function buildCatalog(o: {
+  models: ModelsFile;
+  scores: ScoresFile;
+  override?: Override;
+  listed?: Catalog["listed"];
+  secs?: Catalog["secs"];
+}): Catalog {
+  const scores: Catalog["scores"] = {};
+  const put = (s: Score, force: boolean) => {
+    const cur = (scores[s.rung] ??= {});
+    const had = cur[s.dim];
+    if (force || !had || RANK[s.confidence] < RANK[had.confidence]) cur[s.dim] = s;
+  };
+  for (const s of o.scores.scores) put(s, false);
+  for (const s of o.override?.scores ?? []) put(s, true);
+  const treatLike: Catalog["treatLike"] = {};
+  for (const [rung, t] of Object.entries(o.scores.treatLike))
+    treatLike[rung] = { like: t.like, source: "shipped" };
+  for (const [rung, like] of Object.entries(o.override?.treatLike ?? {}))
+    treatLike[rung] = { like, source: "user" };
+  const bars = structuredClone(o.scores.bars) as Bars;
+  for (const kind of KINDS)
+    for (const d of DIFFICULTIES) {
+      const bar = o.override?.bars[kind]?.[d];
+      if (bar) bars[kind][d] = bar;
+    }
+  return {
+    families: o.models.families,
+    backends: o.models.backends,
+    scores,
+    treatLike,
+    bars,
+    listed: o.listed ?? {},
+    secs: o.secs ?? {},
+  };
+}
+
+/** What the catalog knows about one `backend:model#effort` rung. */
+export interface RungInfo {
+  rung: string;
+  parsed: Rung;
+  key: BillingKey;
+  family: Family | null;
+  /** `<family id or backend model id>#<effort>`: the key scores, treat-likes and timings use */
+  canonical: string;
+  efforts: string[];
+  context: number | null;
+  /** true when the backend's last listing has it, false when that listing lacks it, null with no listing */
+  listed: boolean | null;
+}
+
+function familyOf(c: Catalog, r: Rung): Family | null {
+  const mk = modelKeyOf(billingKeyOf(r));
+  return c.families.find((f) => f.on[mk]?.id === r.model) ?? null;
+}
+
+/** The backend's listing; the native `claude` backend has none of its own: it runs claude-code's models. */
+const listingOf = (c: Catalog, backend: string) => c.listed[backend === "claude" ? "claude-code" : backend];
+
+/** A rung's catalog facts; `rung` must parse (E_ADMIT_RUNG otherwise). */
+export function rungInfo(c: Catalog, rung: string): RungInfo {
+  const parsed = parseRung(rung);
+  const key = billingKeyOf(parsed);
+  const family = familyOf(c, parsed);
+  const shipped = family?.on[modelKeyOf(key)];
+  const listing = listingOf(c, parsed.backend);
+  const found = listing?.models.find((m) => m.id === parsed.model);
+  return {
+    rung,
+    parsed,
+    key,
+    family,
+    canonical: `${family?.id ?? parsed.model}#${parsed.effort}`,
+    efforts: found?.efforts ?? shipped?.efforts ?? [],
+    context: found?.context ?? shipped?.context ?? null,
+    listed: listing && listing.models.length > 0 ? found !== undefined : null,
+  };
+}
+
+/** The rung's scores: its own, else those of the rung it is treated like. null when unscored. */
+export function scoresOf(
+  c: Catalog,
+  canonical: string,
+): { values: Partial<Record<Dim, number>>; records: Partial<Record<Dim, Score>>; via: string | null } | null {
+  const own = c.scores[canonical];
+  const via = own ? null : (c.treatLike[canonical]?.like ?? null);
+  const records = own ?? (via ? c.scores[via] : undefined);
+  if (!records || Object.keys(records).length === 0) return null;
+  const values: Partial<Record<Dim, number>> = {};
+  for (const d of DIMS) if (records[d]) values[d] = records[d].value;
+  return { values, records, via };
+}
+
+/** Spec §4 roles: what a rung must offer to be placed on a role. */
+export const ROLE_NEEDS: Record<Role, { toolUse?: true; imageIn?: true; imageGen?: true }> = {
+  architect: { toolUse: true },
+  verifier: { toolUse: true },
+  worker: { toolUse: true },
+  reviewer: { toolUse: true },
+  "ui-reviewer": { toolUse: true, imageIn: true },
+  artist: { imageGen: true },
+  writer: { toolUse: true },
+  researcher: { toolUse: true },
+};
+
+/**
+ * A listed model catherd has no family for can use tools (Zen and Go serve coding models) and reports
+ * its own image input; image generation is a backend capability (spec §5.2: Codex's tool).
+ */
+export function capableFor(c: Catalog, info: RungInfo, role: Role): boolean {
+  const need = ROLE_NEEDS[role];
+  const listedImage = listingOf(c, info.parsed.backend)?.models.find(
+    (m) => m.id === info.parsed.model,
+  )?.imageIn;
+  const caps = info.family?.capabilities ?? {
+    toolUse: true,
+    imageIn: listedImage ?? false,
+    reasoning: false,
+  };
+  if (need.toolUse && !caps.toolUse) return false;
+  if (need.imageIn && !caps.imageIn) return false;
+  if (need.imageGen && !c.backends[info.parsed.backend]?.imageGen) return false;
+  return true;
+}
+
+/** An effort the rung's model offers; `default` (no effort flag, spec §5.1) always is. */
+export const effortOffered = (info: RungInfo): boolean =>
+  info.parsed.effort === "default" || info.efforts.includes(info.parsed.effort);

package/src/domain/changes.ts

@@ -0,0 +1,52 @@
+import { overlaps } from "./lane.ts";
+
+/**
+ * `git status --porcelain=v1 -z` rows. A rename or copy (R/C in either column) carries its source path as
+ * the next token; both paths are reported, so moving a file out of a path counts as a change to it.
+ */
+export function parsePorcelainZ(out: string): { xy: string; path: string }[] {
+  const tokens = out.split("\0");
+  const rows: { xy: string; path: string }[] = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i] as string;
+    if (t.length < 4) continue;
+    const xy = t.slice(0, 2);
+    rows.push({ xy, path: t.slice(3) });
+    if (/[RC]/.test(xy)) {
+      const source = tokens[++i];
+      if (source) rows.push({ xy, path: source });
+    }
+  }
+  return rows;
+}
+
+/** Repo-relative path → a fingerprint of its dirty state (status, size, mtime); clean paths are absent. */
+export type Snapshot = Record<string, string>;
+
+/**
+ * The paths dirty after a run whose fingerprint differs from before it, so an edit to a file that was
+ * already dirty counts. A path that became clean (committed or reverted meanwhile) does not.
+ */
+export function changedPaths(before: Snapshot, after: Snapshot): string[] {
+  return Object.keys(after)
+    .filter((p) => before[p] !== after[p])
+    .sort();
+}
+
+/**
+ * Spec §4.4: `changedOwned` are the changes inside the lane's Owns; `violations` the ones outside it
+ * that no overlapping dispatch owns either. `strict` is false for a laneless dispatch that may write
+ * (it has no Owns to break), so it reports no violations.
+ */
+export function splitChanges(
+  changed: string[],
+  owns: string[],
+  others: string[],
+  strict: boolean,
+): { changedOwned: string[]; violations: string[] } {
+  const inside = (p: string, paths: string[]) => overlaps([p], paths).length > 0;
+  return {
+    changedOwned: changed.filter((p) => inside(p, owns)),
+    violations: strict ? changed.filter((p) => !inside(p, owns) && !inside(p, others)) : [],
+  };
+}

package/src/domain/cost.ts

@@ -0,0 +1,89 @@
+import type { BillingKey, Family } from "./catalog.ts";
+
+/** Spec §5.3: how the user pays for each billing key. */
+export const BILLING_MODES = ["chatgpt-plan", "claude-plan", "subscription", "metered"] as const;
+export type BillingMode = (typeof BILLING_MODES)[number];
+
+/** Spec §7.1's default `billing`: the owner's Codex/ChatGPT plan, Claude plan and OpenCode Go. */
+export const DEFAULT_BILLING: Record<BillingKey, BillingMode> = {
+  codex: "chatgpt-plan",
+  claude: "claude-plan",
+  "claude-code": "claude-plan",
+  "opencode-go": "subscription",
+  opencode: "metered",
+  cursor: "metered",
+  grok: "metered",
+};
+
+/**
+ * Tokens per task relative to `medium`, from GPT-6 Sol's published DeepSWE dollars per task
+ * (low 0.16, medium 0.38, high 0.64, xhigh 1.00, max 2.74; research 2026-09-25-models.md §3.1).
+ * `ultra` is `max` with parallel subagents: ×4 is catherd's estimate. An unknown variant counts as 1.
+ */
+const EFFORT_FACTOR: Record<string, number> = {
+  none: 0.3,
+  minimal: 0.3,
+  low: 0.4,
+  medium: 1,
+  default: 1,
+  high: 1.7,
+  xhigh: 2.6,
+  max: 7.2,
+  ultra: 28.8,
+};
+
+/** A reference task at medium effort: uncached input, cached input and output tokens (≈ $0.38 on Sol). */
+const REF_TASK = { input: 60_000, cached: 400_000, output: 18_000 };
+
+export const effortFactor = (effort: string): number => EFFORT_FACTOR[effort] ?? 1;
+
+/** Estimated list-price dollars for one task at `effort`. */
+export function taskUsd(price: Family["price"], effort: string): number {
+  const perTask =
+    REF_TASK.input * price.input + REF_TASK.cached * price.cached + REF_TASK.output * price.output;
+  return (perTask / 1_000_000) * effortFactor(effort);
+}
+
+/** One GPT-6 Luna task at medium, in list-price dollars: the unit of a chatgpt-plan weight of 1. */
+export const CHATGPT_UNIT_USD = 0.019;
+
+export interface Cost {
+  /** 0: paid from a subscription; 1: metered. Every tier-0 rung ranks before any tier-1 rung. */
+  tier: 0 | 1;
+  /** comparable across billing modes, in list-price dollars per task; null when unknown */
+  value: number | null;
+  mode: BillingMode;
+}
+
+/**
+ * Spec §5.3. Every mode yields list-price dollars per task, so plans compare with each other:
+ * chatgpt-plan scales the official quota weight (Luna 1, Sol 20, Astra 60) by the effort factor;
+ * claude-plan uses API prices as the proxy, with Fable metered (catherd cannot tell Pro from Max);
+ * Go's share of its monthly dollar limit is dollars / limit, which orders the same as dollars.
+ */
+export function costOf(family: Family | null, effort: string, mode: BillingMode): Cost {
+  if (!family) return { tier: mode === "metered" ? 1 : 0, value: null, mode };
+  const usd = taskUsd(family.price, effort);
+  switch (mode) {
+    case "chatgpt-plan":
+      return {
+        tier: 0,
+        value:
+          family.planWeight === undefined ? usd : family.planWeight * CHATGPT_UNIT_USD * effortFactor(effort),
+        mode,
+      };
+    case "claude-plan":
+      return { tier: family.meteredOnPlan ? 1 : 0, value: usd, mode };
+    case "subscription":
+      return { tier: 0, value: usd, mode };
+    case "metered":
+      return { tier: 1, value: usd, mode };
+  }
+}
+
+/** Cheaper first: tier, then value, an unknown value last. */
+export function compareCost(a: Cost, b: Cost): number {
+  if (a.tier !== b.tier) return a.tier - b.tier;
+  if (a.value === null || b.value === null) return (a.value === null ? 1 : 0) - (b.value === null ? 1 : 0);
+  return a.value - b.value;
+}

package/src/domain/errors.ts

@@ -0,0 +1,60 @@
+export type ErrorCode =
+  | "E_CONFIG_INVALID"
+  | "E_CONFIG_NEWER_SCHEMA"
+  | "E_CONFIG_KEYBIND"
+  | "E_BACKEND_MISSING"
+  | "E_BACKEND_TOO_OLD"
+  | "E_BACKEND_NOT_LOGGED_IN"
+  | "E_BACKEND_MODEL_UNKNOWN"
+  | "E_RUN_NOT_FOUND"
+  | "E_RUN_CORRUPT"
+  | "E_RUN_BUDGET"
+  | "E_RUN_COMMIT"
+  | "E_RUN_NOT_LIVE"
+  | "E_ADMIT_RUNG"
+  | "E_ADMIT_DUPLICATE"
+  | "E_ADMIT_OVERLAP"
+  | "E_ADMIT_ID"
+  | "E_ADMIT_THREAD"
+  | "E_LANE_INVALID"
+  | "E_LAND_GATE"
+  | "E_CLIMB_DESIGN"
+  | "E_JEV_KEY"
+  | "E_JEV_NETWORK"
+  | "E_JEV_RESPONSE"
+  | "E_IO_LOCK"
+  | "E_IO_WRITE"
+  | "E_IO_PATH"
+  | "E_IO_UNEXPECTED"
+  | "E_INPUT_INVALID"
+  | "E_RUNTIME_TOO_OLD";
+
+/**
+ * How to get a newer catherd. `bunx catherd-cli@latest` alone opens the newest one's dashboard and upgrades
+ * nothing that is installed (audit N12).
+ */
+export const UPGRADE = "bun add -g catherd-cli@latest (or run bunx catherd-cli@latest <command>)";
+
+/** Every failure catherd reports: a stable code, a message, and the exact action that fixes it. */
+export class CatherdError extends Error {
+  readonly code: ErrorCode;
+  readonly fix: string | undefined;
+
+  constructor(code: ErrorCode, message: string, opts: { fix?: string; cause?: unknown } = {}) {
+    super(message, opts.cause === undefined ? undefined : { cause: opts.cause });
+    this.name = "CatherdError";
+    this.code = code;
+    this.fix = opts.fix;
+  }
+
+  toJSON(): { code: ErrorCode; message: string; fix?: string } {
+    return this.fix === undefined
+      ? { code: this.code, message: this.message }
+      : { code: this.code, message: this.message, fix: this.fix };
+  }
+}
+
+export const isCatherdError = (e: unknown): e is CatherdError => e instanceof CatherdError;
+
+/** The message of anything thrown: an Error's message, else the value as a string. */
+export const errorMessage = (e: unknown): string => (e instanceof Error ? e.message : String(e));

package/src/domain/failover.ts

@@ -0,0 +1,119 @@
+import { billingKeyOf, type Catalog, DIMS, type Dim, rungInfo, scoresOf } from "./catalog.ts";
+import { type BillingMode, compareCost, type Cost, costOf, DEFAULT_BILLING } from "./cost.ts";
+import { type Rung, tryParseRung } from "./ids.ts";
+import { DIFFICULTIES, KINDS } from "./lane.ts";
+
+/**
+ * Spec §7.1 and §4.5: a stand-in on the same quota would be out of quota too. The billing key names the
+ * quota, except that the native `claude` path and headless `claude-code` both draw on the Claude plan.
+ */
+export const quotaOf = (r: Rung): string => (billingKeyOf(r) === "claude" ? "claude-code" : billingKeyOf(r));
+
+/** Whether a rung draws on the Claude plan (native `claude:` or headless `claude-code:`). */
+export function claudeBilled(rung: string): boolean {
+  const r = tryParseRung(rung);
+  return r !== null && quotaOf(r) === "claude-code";
+}
+
+/** A rung's scores by dim, its own or borrowed through a treat-like; null when unscored or not a rung. */
+export function valuesOf(c: Catalog, rung: string): Partial<Record<Dim, number>> | null {
+  try {
+    return scoresOf(c, rungInfo(c, rung).canonical)?.values ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** The dims used by the routing bars (kind × difficulty) the rung clears: what makes it fit its lanes. */
+export function barDims(c: Catalog, rung: string): Dim[] {
+  const v = valuesOf(c, rung);
+  if (!v) return [];
+  const used = new Set<Dim>();
+  for (const kind of KINDS)
+    for (const d of DIFFICULTIES) {
+      const bar = Object.entries(c.bars[kind][d]).filter(([, min]) => min !== undefined) as [Dim, number][];
+      if (bar.every(([dim, min]) => (v[dim] ?? Number.NEGATIVE_INFINITY) >= min))
+        for (const [dim] of bar) used.add(dim);
+    }
+  return DIMS.filter((d) => used.has(d));
+}
+
+/**
+ * Spec 1.1 §11: the dims, among those the rung's bars use, on which `standIn` scores below `rung` (a
+ * missing score counts as below). Empty means the stand-in clears every bar the rung clears, at least as
+ * well: no downgrade.
+ */
+export function downgradeDims(c: Catalog, rung: string, standIn: string): Dim[] {
+  const a = valuesOf(c, rung);
+  if (!a) return [];
+  const b = valuesOf(c, standIn) ?? {};
+  return barDims(c, rung).filter((d) => (b[d] ?? Number.NEGATIVE_INFINITY) < (a[d] as number));
+}
+
+/**
+ * Spec 1.1 §11 "the ladder goes down": the dims both rungs are scored on where `upper` (the later rung)
+ * scores below `lower`, when it scores above it on none of them. Empty when it does not go down.
+ */
+export function ladderDropDims(c: Catalog, lower: string, upper: string): Dim[] {
+  const a = valuesOf(c, lower);
+  const b = valuesOf(c, upper);
+  if (!a || !b) return [];
+  const shared = DIMS.filter((d) => a[d] !== undefined && b[d] !== undefined);
+  if (shared.some((d) => (b[d] as number) > (a[d] as number))) return [];
+  return shared.filter((d) => (b[d] as number) < (a[d] as number));
+}
+
+const costFor = (c: Catalog, billing: Partial<Record<string, BillingMode>>, rung: string): Cost => {
+  const info = rungInfo(c, rung);
+  return costOf(info.family, info.parsed.effort, billing[info.key] ?? DEFAULT_BILLING[info.key]);
+};
+
+/**
+ * Spec 1.1 §11: the rungs of `pool` that can stand in for `rung`, best first. A stand-in is on another
+ * quota, scored, paid from a plan or subscription under `billing` (a metered one spends money nobody chose
+ * to), startable by `dispatch` (not a native `claude:` subagent), and no downgrade on the rung's bar dims.
+ * Claude-billed stand-ins rank last, then the cheapest first.
+ */
+export function rankStandIns(
+  c: Catalog,
+  billing: Partial<Record<string, BillingMode>>,
+  rung: string,
+  pool: readonly string[],
+): string[] {
+  const from = tryParseRung(rung);
+  if (!from) return [];
+  const fits = [...new Set(pool)].filter((x) => {
+    const r = tryParseRung(x);
+    if (!r || r.backend === "claude" || quotaOf(r) === quotaOf(from) || !valuesOf(c, x)) return false;
+    if (costFor(c, billing, x).tier === 1) return false;
+    return downgradeDims(c, rung, x).length === 0;
+  });
+  return fits.sort(
+    (a, b) =>
+      Number(claudeBilled(a)) - Number(claudeBilled(b)) ||
+      compareCost(costFor(c, billing, a), costFor(c, billing, b)) ||
+      a.localeCompare(b),
+  );
+}
+
+/** How a family's `on` key or a model id's prefix maps to the backend that runs it. */
+const BACKEND_OF_KEY: Record<string, string> = { "opencode-go": "opencode" };
+
+/**
+ * Every rung the catalog knows how to name: each shipped family's model on each backend at each effort,
+ * each listed model at each effort, and each treat-like whose model is an opencode id (`opencode-go/…`,
+ * `opencode/…`), such as the shipped Kimi K3 stand-in. Sorted, without duplicates.
+ */
+export function catalogRungs(c: Catalog): string[] {
+  const out = new Set<string>();
+  for (const f of c.families)
+    for (const [key, m] of Object.entries(f.on)) {
+      if (!m) continue;
+      for (const e of m.efforts) out.add(`${BACKEND_OF_KEY[key] ?? key}:${m.id}#${e}`);
+    }
+  for (const [backend, l] of Object.entries(c.listed))
+    for (const m of l.models) for (const e of m.efforts) out.add(`${backend}:${m.id}#${e}`);
+  for (const canonical of Object.keys(c.treatLike))
+    if (/^opencode(-go)?\//.test(canonical)) out.add(`opencode:${canonical}`);
+  return [...out].sort();
+}

package/src/domain/hints.ts

@@ -0,0 +1,22 @@
+import type { RunRecord } from "./record.ts";
+
+/** Spec §4.4: what the orchestrator does next, read off one finished record. `dir` is the dispatch folder, relative to the run. */
+export function dispatchHints(r: RunRecord, owns: string[], dir: string): string[] {
+  const h: string[] = [];
+  if (r.status === "limit") h.push(`limit: ${r.backend} hit a usage limit on ${r.rung}`);
+  if (r.status === "cli-too-old") h.push(`cli-too-old: ${r.error?.message ?? `upgrade ${r.backend}`}`);
+  if (r.status === "failed") h.push(`failed: read ${dir}/stderr`);
+  if (r.gitUnavailable) h.push("git-unavailable: changed files unknown");
+  if (r.replyStatus === "refused" || r.replyStatus === "blocked") h.push(`climb: ${r.replyStatus}`);
+  else if (
+    r.status === "ok" &&
+    !r.gitUnavailable &&
+    r.access !== "read-only" &&
+    owns.length > 0 &&
+    r.changedOwned.length === 0
+  )
+    h.push("climb: unchanged");
+  if (r.violations.length > 0) h.push(`violation: ${r.violations.join(", ")}`);
+  if (r.threadHeavy) h.push("thread-heavy");
+  return h;
+}