catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/domain/scorecard.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+import { CatherdError } from "./errors.ts";
+
+export const SCORECARD_TASKS = [
+  "raqam-myanmar",
+  "catherd-findings",
+  "sanitell-payment-3",
+  "injected-lao",
+] as const;
+export type ScorecardTaskId = (typeof SCORECARD_TASKS)[number];
+export const INJECTED_TASK: ScorecardTaskId = "injected-lao";
+
+/** The spec's "no worse than 1.5", read as the four tasks' summed wall-clock within 10 % (plan 28, ruling 6). */
+export const WALL_TOLERANCE = 0.1;
+
+const text = z.string().min(1);
+
+export const ScorecardTaskSchema = z.strictObject({
+  schema: z.literal(1),
+  id: z.enum(SCORECARD_TASKS),
+  title: text,
+  goal: text,
+  source: text.nullable(),
+  commit: z.string().regex(/^[0-9a-f]{40}$/),
+  plan: z.union([z.strictObject({ file: text }), z.strictObject({ repoPath: text })]),
+  inject: z
+    .strictObject({
+      message: text,
+      edits: z.array(z.strictObject({ path: text, find: text, replace: z.string() })).min(1),
+    })
+    .nullable()
+    .default(null),
+  limits: z.number().int().min(0).default(0),
+  setup: z.array(text).default([]),
+  acceptance: text,
+  acceptanceTimeoutMin: z.number().int().positive(),
+  acceptFiles: z.array(z.strictObject({ from: text, to: text })).default([]),
+  prompt: z.string().includes("{plan}"),
+});
+export type ScorecardTask = z.infer<typeof ScorecardTaskSchema>;
+
+export interface Interventions {
+  parks: number;
+  answers: number;
+  takeovers: number;
+  manualDispatches: number;
+  pauses: number;
+  superseded: number;
+  chat: number;
+  /** the owner's cancel requests (a daemon run) */
+  cancels: number;
+  /** the owner's plan approvals, not a plan given as input (a daemon run) */
+  approvals: number;
+  total: number;
+}
+
+export interface QuotaRow {
+  backend: string;
+  runs: number;
+  input: number;
+  cached: number;
+  output: number;
+  limits: number;
+}
+
+export interface TaskScore {
+  task: ScorecardTaskId;
+  run: string;
+  catherdVersion: string;
+  startCommit: string;
+  head: string | null;
+  milestones: string[];
+  landed: string[];
+  finished: boolean;
+  interventions: Interventions;
+  reviewRounds: number;
+  lanes: { total: number; landed: number; climbs: number };
+  wallMinutes: number;
+  pausedMinutes: number;
+  quota: { backends: QuotaRow[]; claudeAgentTokens: number };
+  acceptance: { passed: boolean; code: number | null; timedOut: boolean; tail: string[] };
+  firstTry: boolean;
+  injected: { limits: number; standInOk: boolean } | null;
+  recordedAt: string;
+}
+
+export interface ScorecardFile {
+  schema: 1;
+  label: string;
+  tasks: Partial<Record<ScorecardTaskId, TaskScore>>;
+}
+
+export const ScorecardFileSchema = z.looseObject({
+  schema: z.literal(1),
+  label: z.string(),
+  tasks: z.record(z.string(), z.unknown()),
+});
+
+const count = z.number().int().min(0);
+
+/** The fields `passBar` and the comparison table read; the rest of a row is carried untouched. */
+const TaskScoreRowSchema = z.looseObject({
+  catherdVersion: z.string(),
+  finished: z.boolean(),
+  interventions: z.looseObject({
+    parks: count,
+    answers: count,
+    takeovers: count,
+    manualDispatches: count,
+    pauses: count,
+    superseded: count,
+    chat: count,
+    total: count,
+  }),
+  reviewRounds: count,
+  wallMinutes: z.number().min(0),
+  quota: z.looseObject({
+    backends: z.array(z.looseObject({ input: z.number().min(0), output: z.number().min(0) })),
+  }),
+  firstTry: z.boolean(),
+  injected: z.looseObject({ limits: count, standInOk: z.boolean() }).nullable(),
+});
+
+/** Checks every row `passBar` consumes; a malformed one fails naming the label, the task and the field. */
+export function assertScorecardRows(f: z.infer<typeof ScorecardFileSchema>, file: string): ScorecardFile {
+  for (const [task, row] of Object.entries(f.tasks)) {
+    const r = TaskScoreRowSchema.safeParse(row);
+    const issue = r.success ? null : r.error.issues[0];
+    const field = issue ? issue.path.join(".") || "row" : null;
+    if (!(SCORECARD_TASKS as readonly string[]).includes(task) || issue)
+      throw new CatherdError(
+        "E_INPUT_INVALID",
+        `scorecard ${f.label} (${file}): ${task}: ${field ?? "unknown task"}: ${issue?.message ?? "not one of the four tasks"}`,
+        { fix: `fix or delete ${file}, then record the task again` },
+      );
+  }
+  return f as unknown as ScorecardFile;
+}
+
+export function assertLabel(label: string): string {
+  if (!/^[a-z0-9][a-z0-9.-]{0,40}$/.test(label)) {
+    throw new CatherdError("E_INPUT_INVALID", `\`${label}\` is not a scorecard label`, {
+      fix: "a version or plan name: 1.5.0, plan-29, 2.0.0-beta.1",
+    });
+  }
+  return label;
+}
+
+/** Answers are shown, not added: each one closes a park that is already counted. */
+export function interventionTotal(i: Omit<Interventions, "total">): number {
+  return (
+    i.parks + i.takeovers + i.manualDispatches + i.pauses + i.superseded + i.chat + i.cancels + i.approvals
+  );
+}
+
+/** The injected task recovered by itself: a limit hit, a stand-in that ended ok, and nobody stepped in. */
+export function recovered(s: TaskScore): boolean {
+  return (
+    s.injected !== null &&
+    s.injected.limits > 0 &&
+    s.injected.standInOk &&
+    s.finished &&
+    s.interventions.total === 0
+  );
+}
+
+export interface Verdict {
+  pass: boolean;
+  failures: string[];
+  wall: { now: number; baseline: number | null };
+}
+
+const sumWall = (f: ScorecardFile): number =>
+  SCORECARD_TASKS.reduce((n, t) => n + (f.tasks[t]?.wallMinutes ?? 0), 0);
+
+/** The spec's pass bar. Quota, review rounds and the first try are reported, never gated. */
+export function passBar(current: ScorecardFile, baseline: ScorecardFile | null): Verdict {
+  const failures: string[] = [];
+  for (const t of SCORECARD_TASKS) {
+    const s = current.tasks[t];
+    if (!s) failures.push(`${t}: not recorded`);
+    else if (!s.finished) failures.push(`${t}: not finished`);
+    else if (s.interventions.total > 0) failures.push(`${t}: ${s.interventions.total} intervention(s)`);
+  }
+  const injected = current.tasks[INJECTED_TASK];
+  if (injected && !recovered(injected)) failures.push(`${INJECTED_TASK}: did not recover by itself`);
+  const now = sumWall(current);
+  const full = baseline !== null && SCORECARD_TASKS.every((t) => baseline.tasks[t] !== undefined);
+  const base = full ? sumWall(baseline) : null;
+  if (base === null) failures.push("no full baseline to compare wall-clock against");
+  else if (now > base * (1 + WALL_TOLERANCE)) {
+    failures.push(
+      `wall-clock ${Math.round(now)} min against the baseline's ${Math.round(base)} min (more than 10 % slower)`,
+    );
+  }
+  return { pass: failures.length === 0, failures, wall: { now, baseline: base } };
+}

package/src/domain/select.ts

@@ -1,136 +1,293 @@
-import {
-  type Catalog,
-  capableFor,
-  type Dim,
-  effortOffered,
-  type RungInfo,
-  rungInfo,
-  scoresOf,
-} from "./catalog.ts";
+import { type Bars, barOf, percentilesOf } from "./bars.ts";
+import { type Catalog, capableFor, effortOffered, type RungInfo, rungInfo } from "./catalog.ts";
 import { type BillingMode, type Cost, compareCost, costOf, DEFAULT_BILLING } from "./cost.ts";
 import { CatherdError } from "./errors.ts";
-import { DIFFICULTIES, type Difficulty, type Kind } from "./lane.ts";
-import type { Role } from "./roles.ts";
+import { quotaOf } from "./failover.ts";
+import { type EffortWord, effortRank, tryParseRung } from "./ids.ts";
+import { DIFFICULTIES, type Difficulty } from "./lane.ts";
+import { ROLES, type Role } from "./roles.ts";
 
 /** What routing reads from a profile for one role. */
 export interface RoutingProfile {
   objective: "cost" | "speed";
   billing: Partial<Record<string, BillingMode>>;
   role: { enabled: boolean; rungs: string[]; defaultRung?: string };
+  /**
+   * spec 1.5 plan 24: the run's dispatches so far per quota (`quotaOf`), the headroom a tie between rungs of
+   * equal intelligence is broken on; absent, every quota counts 0 and the candidates' order breaks it
+   */
+  usage?: Partial<Record<string, number>>;
+  /** `<backend>:<model>` → the highest effort routing may start (plan 33); a rung above it is skipped */
+  maxEffort?: Readonly<Record<string, string>>;
+  /** this role's bar percentiles over the profile's, laid over the shipped ones (`percentilesOf`) */
+  bars?: Bars;
+}
+
+/** What a start check reads of a profile: `ProfileView` and the resolved `Profile` both satisfy it. */
+export interface ProfileLike {
+  objective: "cost" | "speed";
+  billing: Partial<Record<string, BillingMode>>;
+  roles: Partial<Record<Role, { enabled: boolean; rungs: string[]; defaultRung?: string }>>;
+  maxEffort?: Readonly<Record<string, string>>;
+}
+
+/** Spec 2.0 decision 22: the roles that write code. The worker runs repo_code, terminal and ui lanes and every fix round. */
+export const CODING_ROLES: readonly Role[] = ["worker"];
+/** A coding role never runs below this effort, whatever the objective or the budget. */
+export const CODING_FLOOR: EffortWord = "medium";
+
+/**
+ * False for a rung above its model's `maxEffort`, or below `CODING_FLOOR` for a coding role. A rung that does not
+ * parse, one whose effort is no effort word (`default`), and a ceiling that is no effort word all allow it.
+ */
+export function effortAllowed(
+  maxEffort: Readonly<Record<string, string>>,
+  role: Role,
+  rung: string,
+): boolean {
+  const r = tryParseRung(rung);
+  const rank = r ? effortRank(r.effort) : -1;
+  if (!r || rank < 0) return true;
+  if (CODING_ROLES.includes(role) && rank < effortRank(CODING_FLOOR)) return false;
+  const cap = effortRank(maxEffort[`${r.backend}:${r.model}`] ?? "");
+  return cap < 0 || rank <= cap;
 }
 
 export interface Candidate {
   rung: string;
   info: RungInfo;
-  scores: Partial<Record<Dim, number>>;
+  intelligence: number;
   cost: Cost;
-  /** median seconds over the user's own runs (≥ 5 samples), else null */
-  secs: number | null;
+  /** the pair's tokens per second; null when Slopalytics has none */
+  speed: number | null;
 }
 
 export interface Pick {
   rung: string;
   ladder: string[];
+  /** no rung clears the difficulty's bar (`no rung clears hard (bar 47.1); best is …`) */
+  noClear?: string;
+  /** spec 1.5 plan 24: rungs of equal intelligence competed for the start, and how the tie was broken */
+  tie?: string;
+}
+
+/** The enabled roles, in `ROLES` order, that the catalog can place no rung for. */
+export function rolesWithoutRung(c: Catalog, v: ProfileLike): Role[] {
+  return ROLES.filter((role) => {
+    const r = v.roles[role];
+    return (
+      r?.enabled === true &&
+      candidates(
+        c,
+        {
+          objective: v.objective,
+          billing: v.billing,
+          role: r,
+          ...(v.maxEffort ? { maxEffort: v.maxEffort } : {}),
+        },
+        role,
+      ).length === 0
+    );
+  });
 }
 
 const byNull = (a: number | null, b: number | null) =>
   a === null || b === null ? (a === null ? 1 : 0) - (b === null ? 1 : 0) : a - b;
 
-function secsOf(c: Catalog, canonical: string, kind: Kind | null): number | null {
-  return c.secs[`${canonical}|${kind ?? "*"}`] ?? c.secs[`${canonical}|*`] ?? null;
-}
-
 /**
- * The role's enabled rungs that the catalog can place: parseable, offered by their model, listed by
- * the backend when it has a listing, capable for the role, and scored (their own or a treat-like).
- * Ordered by cost (spec §5.3), or by measured speed with cost breaking ties; with fewer than 5
- * samples a rung has no speed, and cost orders it, which within a model is effort order.
+ * The role's enabled rungs that the catalog can place: parseable, indexed, offered by their model, listed by
+ * the backend when it has a listing, and capable for the role. Ordered by cost (spec §5.3), or by speed with
+ * cost breaking ties; the profile's ladder order breaks every remaining tie (spec 1.5 plan 24), so equal rungs
+ * start in the order the user wrote.
  */
-export function candidates(c: Catalog, p: RoutingProfile, role: Role, kind: Kind | null = null): Candidate[] {
+export function candidates(c: Catalog, p: RoutingProfile, role: Role): Candidate[] {
   if (!p.role.enabled) return [];
   const out: Candidate[] = [];
-  for (const rung of new Set(p.role.rungs)) {
+  const order = [...new Set(p.role.rungs)];
+  for (const rung of order) {
+    if (!effortAllowed(p.maxEffort ?? {}, role, rung)) continue;
     let info: RungInfo;
     try {
       info = rungInfo(c, rung);
     } catch {
       continue;
     }
-    if (!effortOffered(info) || info.listed === false || !capableFor(c, info, role)) continue;
-    const s = scoresOf(c, info.canonical);
-    if (!s) continue;
+    if (!info.pair || !effortOffered(info) || info.listed === false || !capableFor(c, info, role)) continue;
     const mode = p.billing[info.key] ?? DEFAULT_BILLING[info.key];
     out.push({
       rung,
       info,
-      scores: s.values,
-      cost: costOf(info.family, info.parsed.effort, mode),
-      secs: secsOf(c, info.canonical, kind),
+      intelligence: info.pair.intelligence,
+      cost: costOf(info.family, info.pair, info.parsed.effort, mode),
+      speed: info.pair.speed,
     });
   }
-  const cost = (a: Candidate, b: Candidate) => compareCost(a.cost, b.cost) || byNull(a.secs, b.secs);
-  const speed = (a: Candidate, b: Candidate) => byNull(a.secs, b.secs) || compareCost(a.cost, b.cost);
+  const written = (a: Candidate, b: Candidate) => order.indexOf(a.rung) - order.indexOf(b.rung);
+  const cost = (a: Candidate, b: Candidate) => compareCost(a.cost, b.cost) || written(a, b);
+  // fastest first, a pair with no speed last
+  const speed = (a: Candidate, b: Candidate) =>
+    byNull(a.speed === null ? null : -a.speed, b.speed === null ? null : -b.speed) ||
+    compareCost(a.cost, b.cost) ||
+    written(a, b);
   return out.sort(p.objective === "speed" ? speed : cost);
 }
 
-export function clearsBar(c: Catalog, cand: Candidate, kind: Kind, difficulty: Difficulty): boolean {
-  return Object.entries(c.bars[kind][difficulty]).every(
-    ([dim, min]) => min === undefined || (cand.scores[dim as Dim] ?? Number.NEGATIVE_INFINITY) >= min,
-  );
-}
+export const clearsBar = (cand: Candidate, bar: number): boolean => cand.intelligence >= bar;
 
 function noRung(role: Role): CatherdError {
-  return new CatherdError("E_CONFIG_INVALID", `role "${role}" has no enabled, capable, scored rung`, {
-    fix: "run profile_validate, then enable a scored rung or map one with catherd catalog treat-like",
+  return new CatherdError("E_CONFIG_INVALID", `role "${role}" has no enabled, capable, indexed rung`, {
+    fix: `pick indexed pairs: catherd catalog list --role ${role}`,
   });
 }
 
+/** Spec 1.5 plan 24: how many of `rungs` (a run's dispatched rungs) drew on each quota. */
+export function quotaUsage(rungs: readonly string[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const rung of rungs) {
+    const r = tryParseRung(rung);
+    if (r) out[quotaOf(r)] = (out[quotaOf(r)] ?? 0) + 1;
+  }
+  return out;
+}
+
+/** Equal intelligence: a tie for the start. */
+const same = (a: Candidate, b: Candidate): boolean => a.intelligence === b.intelligence;
+
+const quota = (x: Candidate): string => quotaOf(x.info.parsed);
+
 /**
- * The role's default rung and every candidate above it (the whole list when it has no default), in cost
- * order under either objective: speed order would put slower, not stronger, rungs above the default.
+ * Spec 1.5 plan 24: when rungs on other quotas are exactly as intelligent as `start`, the start goes to the
+ * quota with the most headroom (the fewest of the run's dispatches so far), the candidates' order (cost, then
+ * the profile's ladder order) breaking an equal count. `tie` says what decided. Rungs of one quota that tie
+ * are no tie (cost already orders them), nor is a rung of another cost tier.
+ */
+function breakTie(
+  start: Candidate,
+  order: Candidate[],
+  usage: Partial<Record<string, number>>,
+): { start: Candidate; tie?: string } {
+  // a metered rung never wins a tie over a plan's: headroom is free only within the start's cost tier
+  const rivals = order.filter(
+    (x) => x !== start && quota(x) !== quota(start) && x.cost.tier === start.cost.tier && same(x, start),
+  );
+  if (rivals.length === 0) return { start };
+  const used = (x: Candidate) => usage[quota(x)] ?? 0;
+  const tied = [start, ...rivals];
+  const pick = [...tied].sort((a, b) => used(a) - used(b))[0] as Candidate;
+  const others = tied.filter((x) => x !== pick).map((x) => x.rung);
+  const counts = [...new Set(tied.map(quota))].map((q) => `${q} ${usage[q] ?? 0}`).join(", ");
+  const why = tied.every((x) => used(x) === used(pick))
+    ? `equal headroom (${used(pick)} dispatches each); the profile's ladder order and cost decided`
+    : `${quota(pick)} has the most headroom (dispatches in this run: ${counts})`;
+  return {
+    start: pick,
+    tie: `tie on intelligence with ${others.join(", ")}: started on ${pick.rung}; ${why}`,
+  };
+}
+
+/**
+ * Spec 1.5 plan 24, "climb ladders only go up": the start (after a tie on equal intelligence goes to the quota
+ * with the most headroom), then, in `order`'s order, every other candidate at least as intelligent as the last
+ * rung kept. A stronger rung is on the ladder wherever cost puts it, and one weaker than the rung before it
+ * never is, so a climb never lands on a rung below the one it leaves.
+ */
+function ladderFrom(first: Candidate, order: Candidate[], usage: Partial<Record<string, number>> = {}): Pick {
+  const { start, tie } = breakTie(first, order, usage);
+  const kept = [start];
+  for (const x of order)
+    if (x !== start && x.intelligence >= (kept.at(-1) as Candidate).intelligence) kept.push(x);
+  return { rung: start.rung, ladder: kept.map((x) => x.rung), ...(tie ? { tie } : {}) };
+}
+
+/**
+ * The role's default rung and every candidate at least as intelligent (the whole list when it has no default),
+ * in cost order under either objective: speed order would put faster, not stronger, rungs above the default.
  */
 export function defaultLadder(c: Catalog, p: RoutingProfile, role: Role): Pick {
-  const all = candidates(c, { ...p, objective: "cost" }, role).map((x) => x.rung);
+  const all = candidates(c, { ...p, objective: "cost" }, role);
   if (all.length === 0) throw noRung(role);
-  const i = Math.max(0, all.indexOf(p.role.defaultRung ?? ""));
-  return { rung: all[i] as string, ladder: all.slice(i) };
+  const start = all.find((x) => x.rung === p.role.defaultRung) ?? (all[0] as Candidate);
+  return ladderFrom(start, all, p.usage);
 }
 
 /**
- * The role's default difficulty for a kind: the hardest difficulty whose bar the role's default rung clears
- * (`build` when it clears none, or is no candidate: never `copy`, whose start is the cheapest rung, below
- * what the `default` source would pick). A route sure of the kind but not the difficulty starts there.
+ * The role's default difficulty: the hardest difficulty whose bar the role's default rung clears (`build` when
+ * it clears none, or is no candidate: never `copy`, whose start is the cheapest rung). A route sure of the
+ * lane but not its difficulty starts there.
  */
-export function defaultDifficulty(c: Catalog, p: RoutingProfile, role: Role, kind: Kind): Difficulty {
+export function defaultDifficulty(c: Catalog, p: RoutingProfile, role: Role): Difficulty {
   const start = defaultLadder(c, p, role).rung;
-  const cand = candidates(c, p, role, kind).find((x) => x.rung === start);
-  const cleared = cand ? DIFFICULTIES.filter((d) => clearsBar(c, cand, kind, d)) : [];
+  const cand = candidates(c, p, role).find((x) => x.rung === start);
+  const at = percentilesOf(p);
+  const cleared = cand ? DIFFICULTIES.filter((d) => clearsBar(cand, barOf(c, d, at))) : [];
   return cleared.at(-1) ?? "build";
 }
 
 /**
- * Under `objective: "speed"` the objective picks only the start (the fastest bar-clearing rung); the
- * ladder above it is the other bar-clearing rungs at least as strong on the kind's primary dimension,
- * weakest first, cost breaking ties, so a lane never climbs onto a weaker rung. Ported from 0.x.
+ * Under `objective: "speed"` the objective picks only the start (the fastest rung that clears the bar); the
+ * ladder above it is the other rungs at least as intelligent, least intelligent first, cost breaking ties, so a
+ * lane never climbs onto a weaker rung.
+ */
+function speedLadder(start: Candidate, all: Candidate[], p: RoutingProfile): Pick {
+  const order = [...all].sort((a, b) => a.intelligence - b.intelligence || compareCost(a.cost, b.cost));
+  return ladderFrom(start, order, p.usage);
+}
+
+/**
+ * Spec 1.5 plan 24: when no rung clears a bar, the most intelligent one (the candidates' order breaking a tie).
+ */
+const bestOf = (all: Candidate[]): Candidate =>
+  [...all].sort((a, b) => b.intelligence - a.intelligence)[0] as Candidate;
+
+/** `no rung clears hard (bar 47.1); best is codex:gpt-6-sol#xhigh (44.2)`, and where a raised start came from. */
+export function noClearLine(all: Candidate[], bar: number, d: Difficulty, raisedFrom?: Difficulty): string {
+  const best = bestOf(all);
+  return `no rung clears ${d} (bar ${bar.toFixed(1)}); best is ${best.rung} (${best.intelligence.toFixed(1)})${raisedFrom ? `; started at ${raisedFrom}'s start` : ""}`;
+}
+
+/**
+ * Spec §5.4: the start rung and ladder for a lane of this difficulty. The start is the first rung in objective
+ * order that clears the bar (under speed the fastest one with a speed, else the cheapest). When none does, it is
+ * the default rung, raised to an easier difficulty's start when that one is at least as intelligent (spec 1.5
+ * plan 24: `logic` starts no lower than `build`), and `noClear` says so. The ladder above the start only goes up.
  */
-function speedLadder(clearing: Candidate[], kind: Kind): Pick {
-  const start = clearing[0] as Candidate;
-  const dim: Dim = kind === "terminal" ? "terminal" : "repo_code";
-  const strength = (x: Candidate) => x.scores[dim] ?? Number.NEGATIVE_INFINITY;
-  const rest = clearing
-    .filter((x) => x !== start && strength(x) >= strength(start))
-    .sort((a, b) => strength(a) - strength(b) || compareCost(a.cost, b.cost));
-  return { rung: start.rung, ladder: [start, ...rest].map((x) => x.rung) };
-}
-
-/** Spec §5.4: the start rung and ladder for a lane of this kind and difficulty (0.x `select`). */
-export function select(c: Catalog, p: RoutingProfile, role: Role, kind: Kind, difficulty: Difficulty): Pick {
-  const all = candidates(c, p, role, kind);
+export function select(c: Catalog, p: RoutingProfile, role: Role, difficulty: Difficulty): Pick {
+  const all = candidates(c, p, role);
   if (all.length === 0) throw noRung(role);
-  if (all.length === 1) return { rung: all[0]?.rung as string, ladder: [all[0]?.rung as string] };
-  const clearing = all.filter((x) => clearsBar(c, x, kind, difficulty));
-  if (clearing.length === 0) return defaultLadder(c, p, role);
-  return p.objective === "speed"
-    ? speedLadder(clearing, kind)
-    : { rung: clearing[0]?.rung as string, ladder: clearing.map((x) => x.rung) };
+  const at = percentilesOf(p);
+  const bar = barOf(c, difficulty, at);
+  if (all.length === 1) {
+    const only = all[0] as Candidate;
+    const one = { rung: only.rung, ladder: [only.rung] };
+    return clearsBar(only, bar) ? one : { ...one, noClear: noClearLine(all, bar, difficulty) };
+  }
+  const byCost = p.objective === "speed" ? candidates(c, { ...p, objective: "cost" }, role) : all;
+  if (p.objective === "speed") {
+    // the fastest clearing pair that has a speed, else the cheapest clearing one
+    const rung = (
+      all.find((x) => x.speed !== null && clearsBar(x, bar)) ?? byCost.find((x) => clearsBar(x, bar))
+    )?.rung;
+    const first = all.find((x) => x.rung === rung);
+    if (first) return speedLadder(first, all, p);
+  } else {
+    const first = all.find((x) => clearsBar(x, bar));
+    if (first) return ladderFrom(first, all, p.usage);
+  }
+  const fallback = defaultLadder(c, p, role).rung;
+  const base = byCost.find((x) => x.rung === fallback) ?? (byCost[0] as Candidate);
+  let start = base;
+  let raisedFrom: Difficulty | undefined;
+  for (const easier of DIFFICULTIES.slice(0, DIFFICULTIES.indexOf(difficulty)).reverse()) {
+    const s = byCost.find((x) => clearsBar(x, barOf(c, easier, at)));
+    if (!s) continue;
+    if (s.intelligence >= start.intelligence) {
+      start = s;
+      if (s !== base) raisedFrom = easier;
+    }
+    break;
+  }
+  return {
+    ...ladderFrom(start, byCost, p.usage),
+    noClear: noClearLine(all, bar, difficulty, raisedFrom),
+  };
 }

package/src/domain/slopalytics.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { CatherdError } from "./errors.ts";
+
+/** One model at one effort, as the Slopalytics proxy indexes it: its intelligence and the facts that come with it. */
+export interface SlopRecord {
+  family: string;
+  effort: string;
+  intelligence: number;
+  inputPrice: number | null;
+  outputPrice: number | null;
+  speed: number | null;
+  context: number | null;
+}
+
+const RecordSchema = z.object({
+  family: z.string(),
+  effort: z.string(),
+  intelligence: z.number(),
+  inputPrice: z.number().nullable(),
+  outputPrice: z.number().nullable(),
+  speed: z.number().nullable(),
+  context: z.number().nullable(),
+});
+
+/** `<data>/slopalytics.json`: the last good answer, when it was fetched and checked, and the last failure. */
+export const IndexFileSchema = z.looseObject({
+  schema: z.literal(1),
+  checkedAt: z.iso.datetime(),
+  fetchedAt: z.string().nullable(),
+  error: z.object({ at: z.string(), message: z.string() }).nullable(),
+  models: z.array(RecordSchema),
+});
+export type IndexFile = z.infer<typeof IndexFileSchema>;
+
+/** A finite number or a finite numeric string (the proxy sends some prices as strings), else null. */
+const num = (v: unknown): number | null => {
+  const n = typeof v === "string" && v.trim() !== "" ? Number(v) : v;
+  return typeof n === "number" && Number.isFinite(n) ? n : null;
+};
+
+/** The proxy's answer as the records catherd ranks on: only a record with a positive intelligence is a pair. */
+export function parseProxy(body: unknown): { fetchedAt: string | null; models: SlopRecord[] } {
+  const b = body as { fetchedAt?: unknown; models?: unknown } | null;
+  if (typeof b !== "object" || b === null || !Array.isArray(b.models))
+    throw new CatherdError("E_INPUT_INVALID", "Slopalytics answered without a models list");
+  const models: SlopRecord[] = [];
+  for (const raw of b.models) {
+    const r = (raw ?? {}) as Record<string, unknown>;
+    const intelligence = num(r.intelligence);
+    if (typeof r.family !== "string" || !r.family) continue;
+    if (typeof r.effort !== "string" || !r.effort) continue;
+    if (intelligence === null || intelligence <= 0) continue;
+    const context = num(r.context);
+    models.push({
+      family: r.family,
+      effort: r.effort,
+      intelligence,
+      inputPrice: num(r.inputPrice),
+      outputPrice: num(r.outputPrice),
+      speed: num(r.speed),
+      context: context !== null && Number.isInteger(context) && context > 0 ? context : null,
+    });
+  }
+  return { fetchedAt: typeof b.fetchedAt === "string" ? b.fetchedAt : null, models };
+}
+
+/** A model's Slopalytics family key: its provider dropped, lower case, dots as dashes (`gpt-6.1-sol` → `gpt-6-1-sol`). */
+export const slopKey = (model: string): string =>
+  model
+    .slice(model.lastIndexOf("/") + 1)
+    .toLowerCase()
+    .replaceAll(".", "-");

package/src/domain/state.ts

@@ -16,6 +16,8 @@ export interface StateView {
   dirty: { path: string; owner: string | null }[];
   running: { name: string; rung: string; thread: string | null; since: string; brief: string }[];
   lastCheck: string | null;
+  /** spec 1.5 "Pinned per run": what changed since the pin; dispatch keeps the pinned values */
+  pinChanges?: string[];
   next: string;
   /** spec 1.1 §10: the protocol's next step, derived from the run's files; always the last line */
   protocol: string;
@@ -40,6 +42,9 @@ export function renderState(s: StateView): string {
       : ["- none"]),
     "",
     `Last check: ${s.lastCheck ?? "none"}`,
+    ...(s.pinChanges?.length
+      ? [`Pinned: ${s.pinChanges.join("; ")} (dispatch keeps the pinned values; run_pin re-pins)`]
+      : []),
     "",
     // 1.1: no tool waits; each running role's record arrives as a catherd message
     `Next: ${waiting.length ? `running ${waiting.join(", ")} (results arrive as catherd messages; peek to check); then ${s.next}` : s.next}`,