catherd-cli 0.2.1 → 1.1.0

package/src/domain/record.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+export const ACCESS = ["read-only", "workspace-write", "full"] as const;
+export type Access = (typeof ACCESS)[number];
+
+const RUN_STATUSES = ["ok", "failed", "limit", "cli-too-old", "timeout", "cancelled"] as const;
+export type RunStatus = (typeof RUN_STATUSES)[number];
+
+const REPLY_STATUSES = ["complete", "partial", "blocked", "refused"] as const;
+export type ReplyStatus = (typeof REPLY_STATUSES)[number];
+
+export interface Tokens {
+  input: number;
+  cached: number;
+  output: number;
+}
+export const ZERO_TOKENS: Readonly<Tokens> = Object.freeze({ input: 0, cached: 0, output: 0 });
+
+/** Spec §7: a thread past this many input tokens is spent; its next piece starts fresh. */
+export const THREAD_HEAVY_INPUT = 8_000_000;
+
+/** How a supervised worker ended, as the supervisor records it in exit.json. */
+export const EXIT_REASONS = [
+  "exited",
+  "after-final",
+  "idle-timeout",
+  "wall-timeout",
+  "cancelled",
+  "lost",
+] as const;
+export type ExitReason = (typeof EXIT_REASONS)[number];
+export interface ExitInfo {
+  code: number | null;
+  signal: string | null;
+  reason: ExitReason;
+  endedAt: string;
+}
+
+const TokensSchema = z.object({ input: z.number(), cached: z.number(), output: z.number() });
+
+export const RunRecordSchema = z.looseObject({
+  schema: z.literal(1),
+  runId: z.string(),
+  dispatchId: z.string(),
+  name: z.string(),
+  role: z.string(),
+  lane: z.string().nullable(),
+  backend: z.string(),
+  rung: z.string(),
+  attempt: z.number().int().min(1),
+  failoverFrom: z.string().nullable(),
+  thread: z.string().nullable(),
+  status: z.enum(RUN_STATUSES),
+  startedAt: z.string(),
+  endedAt: z.string(),
+  secs: z.number(),
+  exitCode: z.number().nullable(),
+  signal: z.string().nullable(),
+  cliVersion: z.string().nullable(),
+  tokens: TokensSchema,
+  costUsd: z.number().nullable(),
+  changedOwned: z.array(z.string()),
+  violations: z.array(z.string()),
+  /** true when git failed at finalize: changedOwned and violations are then unknown, not empty */
+  gitUnavailable: z.boolean().optional(),
+  replyStatus: z.enum(REPLY_STATUSES).nullable(),
+  replyWhy: z.string().nullable(),
+  threadHeavy: z.boolean(),
+  access: z.enum(ACCESS),
+  isolated: z.boolean(),
+  images: z.array(z.string()),
+  error: z.object({ code: z.string(), message: z.string() }).nullable(),
+  replyPath: z.string(),
+  /** the Claude Code session that dispatched it, copied from admit.json (spec §3.3); absent before 1.1 */
+  sessionId: z.string().optional(),
+});
+export type RunRecord = z.infer<typeof RunRecordSchema>;
+
+const STATUS_LINE = /^STATUS:\s*(complete|partial|blocked|refused)\s*(?:—|–|-)\s*(.*)$/;
+
+/** The role's claim about its own work: the reply's last line, `STATUS: <s> — <why>`. */
+export function parseReplyStatus(reply: string): { status: ReplyStatus | null; why: string | null } {
+  const last = reply.trimEnd().split("\n").at(-1)?.trim() ?? "";
+  const m = STATUS_LINE.exec(last);
+  return m ? { status: m[1] as ReplyStatus, why: (m[2] ?? "").trim() } : { status: null, why: null };
+}

package/src/{profile → domain}/role-prompts.ts

@@ -1,8 +1,8 @@
-import type { Role } from "../types.ts";
-import { VERSION } from "../version.ts";
+import type { Access } from "./record.ts";
+import type { Role } from "./roles.ts";
 
-const READ_ONLY = ["Write", "Edit", "NotebookEdit", "Agent"];
-const WRITES = ["Agent"];
+// The role prompts of the native Claude subagents, ported from 0.x (spec D9). Headless backends get the
+// same text from the orchestrator's briefs; only native agents carry it in their agent file.
 
 const RUN_FILES =
   "The run folder is outside the project. Read and write it only through the catherd MCP tools read_run_file and write_run_file (in the tool list as mcp__plugin_catherd_catherd__read_run_file and mcp__plugin_catherd_catherd__write_run_file), with the run id the orchestrator gave you. Paths are relative to the run folder.";
@@ -15,6 +15,8 @@ const architect = [
   "",
   `Start from the dossier. Open a project file yourself only to settle a decision the dossier leaves open, and read each file once. Bash is for inspection only. Change nothing in the project. ${RUN_FILES}`,
   "",
+  "When the acceptance lines include plan: <path>[, <path>…], the user already has a plan and there is no dossier. Translate it, do not design: each plan task becomes lanes, each merge request or phase a milestone with its full check. Copy the plan's decisions into plan.md and the lane files, and decide only what the plan leaves undecided.",
+  "",
   "Write plan.md with exactly these parts, in this order:",
   "",
   "1. Decisions D1…Dn: each one is a choice, the alternative you rejected, and one line on why. Cover only choices where two reasonable engineers would differ.",
@@ -22,20 +24,22 @@ const architect = [
   "3. Lanes inside each milestone, M1.L1…: each lane gives",
   "   - the files it owns (two lanes of one milestone never share a file);",
   "   - what changes, stated as behavior plus the exact signatures and data shapes it introduces;",
-  "   - its fast check: the targeted command a worker reruns while it works, seconds to a minute or two.",
+  "   - its fast check: the command a worker reruns while it works, seconds to a minute or two: its targeted tests plus the linter, and the type check when the project has one, scoped to the packages the lane owns.",
   "",
   "   Every lane of a milestone runs at the same time, so split for width: more small lanes beat one long one.",
   "4. Speed: if the full check takes more than about five minutes, name why and make speeding it up (parallel tests, one shared fixture, fewer real-time waits) a lane of the first milestone.",
   "5. Edge cases the tests must pin, one line each.",
   "6. Out of scope: what no worker may touch.",
   "",
-  "Then write one file per lane, lanes/Mx.Ly.md. It is everything that worker needs and nothing else: the lane's section, the decisions and edge cases it relies on (copied, not referenced), and the out-of-scope lines. A worker reads its lane file, never plan.md. Its first three lines are exactly:",
+  "Then write one file per lane, lanes/Mx.Ly.md. It is everything that worker needs and nothing else: the lane's section, the decisions and edge cases it relies on (copied, not referenced), and the out-of-scope lines. A worker reads its lane file, never plan.md. Its first five lines are exactly:",
   "",
   "    # Mx.Ly — <one line>",
   "    Owns: <repo-relative paths, comma-separated>",
   "    Fast check: <command>",
+  "    Kind: repo_code|terminal|ui|prose|research",
+  "    Difficulty: copy|build|logic|hard",
   "",
-  "catherd reads the Owns: line to keep two running lanes off the same file, and to tell a refusal (owned files unchanged) from work.",
+  "catherd reads the Owns: line to keep two running lanes off the same file, and to tell a refusal (owned files unchanged) from work. It reads Kind: and Difficulty: to pick the lane's model when its router is unsure.",
   "",
   "Signatures, data shapes and test case names are yours. Function bodies are the worker's. A plan that contains the implementation turns the worker into a typist and spends the most expensive model on typing.",
   "",
@@ -49,7 +53,11 @@ const architect = [
 const verifier = [
   "You verify work you did not write. You get the acceptance lines, the check command and how to run the thing. You do not get the author's account of it, and you should not look for one.",
   "",
-  "1. Run the check command once. Report its exit code and the failing lines.",
+  "1. Run the check command once. Report its exit code and the failing lines. When the check has several gate items (suites, lint, builds, a boot check):",
+  "   - Before each item, call the catherd MCP tool gate_check (mcp__plugin_catherd_catherd__gate_check) with the run id, the milestone you verify (M1, as your brief names it), the item, its command and the repo paths it depends on. When it answers carried: true, do not run the item: report it as carried over from its commit. It also tells the orchestrator which step you are on.",
+  "   - After an item passes, call gate_pass (mcp__plugin_catherd_catherd__gate_pass) with the same item, command and paths, and the evidence.",
+  "   - Run independent items side by side, each heavy one wrapped in catherd lock, which queues them within the machine's slots.",
+  "   - Build each commit's images once, and reuse them for the boot check and the acceptance suite.",
   "2. Exercise every acceptance line through the real entry point: the CLI, the HTTP route, the page. Read source only to find that entry point. When a line needs data or files, build them in a temporary directory outside the project.",
   "3. Read the diff (git diff plus untracked files) for bugs the acceptance lines miss: wrong edge behavior, dead code, leftovers.",
   "",
@@ -58,19 +66,21 @@ const verifier = [
   "Return, in this order:",
   "- VERDICT: PASS or VERDICT: FAIL on the first line.",
   "- One line per acceptance line: A<n> PASS|FAIL, the command you ran and the decisive output.",
+  "- One line per gate item: PASS|FAIL, or carried over from <commit>.",
   "- Bugs outside the acceptance lines: file:line, what happens, the input that triggers it.",
   "- What you could not check, and why.",
 ].join("\n");
 
-const worker = [
-  "You are a worker in a catherd run. The orchestrator's message is your brief: the acceptance lines, the lane file to read, the files you own and the files you must not touch, and your fast check.",
-  "",
-  `Read your lane file first. ${RUN_FILES} If the project has a CLAUDE.md or AGENTS.md, follow it.`,
-  "",
-  `Change only the files you own. Run your fast check until it passes. Run the full suite only if the brief says so, and wrap any full build or full test suite in: bunx catherd-cli@${VERSION} lock -- <command>. Other lanes share this machine.`,
-  "",
-  REPLY,
-].join("\n");
+const worker = (version: string) =>
+  [
+    "You are a worker in a catherd run. The orchestrator's message is your brief: the acceptance lines, the lane file to read, the files you own and the files you must not touch, and your fast check.",
+    "",
+    `Read your lane file first. ${RUN_FILES} If the project has a CLAUDE.md or AGENTS.md, follow it.`,
+    "",
+    `Change only the files you own. Run your fast check until it passes. Run the full suite only if the brief says so, and wrap any full build or full test suite in: bunx catherd-cli@${version} lock -- <command>. Other lanes share this machine.`,
+    "",
+    REPLY,
+  ].join("\n");
 
 const reviewer = [
   "You review a milestone's diff that you did not write. The brief gives the acceptance lines and the changed files; read new files in full. Change nothing in the project.",
@@ -113,18 +123,56 @@ const writer = [
 const researcher = [
   "You answer a factual question about the code, or map it for a dossier. Change nothing in the project. Give file:line for every claim.",
   "",
-  `A dossier lists: the files and folders involved, one line each on what they hold; the existing patterns the work should copy, by path; the build, test and run commands, with how long the full suite takes; the symbols the change will call or alter, with their signatures; the project rules (CLAUDE.md, AGENTS.md, conventions) that bind this work; and risks: shared files, generated code, slow or flaky tests. It may run to 200 lines. Write it with write_run_file to the path the brief names, and reply with that path. ${RUN_FILES}`,
+  `A dossier lists: the files and folders involved, one line each on what they hold; the existing patterns the work should copy, by path; the build, test and run commands, with how long the full suite takes when the docs, the CI config or a log say so (never run the suite to find out; write "unknown" instead); the lint and type-check commands, and how to scope each to one package; the symbols the change will call or alter, with their signatures; the project rules (CLAUDE.md, AGENTS.md, conventions) that bind this work; and risks: shared files, generated code, slow or flaky tests. It may run to 200 lines. Write it with write_run_file to the path the brief names, and reply with that path. ${RUN_FILES}`,
   "",
   "For a single question, reply in at most 15 lines. The last line of your reply is: STATUS: complete|partial|blocked|refused — <one line why>",
 ].join("\n");
 
-export const ROLE_PROMPTS: Record<Role, { disallowedTools: string[]; body: string }> = {
-  architect: { disallowedTools: READ_ONLY, body: architect },
-  verifier: { disallowedTools: READ_ONLY, body: verifier },
-  worker: { disallowedTools: WRITES, body: worker },
-  reviewer: { disallowedTools: READ_ONLY, body: reviewer },
-  "ui-reviewer": { disallowedTools: READ_ONLY, body: uiReviewer },
-  artist: { disallowedTools: WRITES, body: artist },
-  writer: { disallowedTools: WRITES, body: writer },
-  researcher: { disallowedTools: READ_ONLY, body: researcher },
+const BODIES: Record<Role, (version: string) => string> = {
+  architect: () => architect,
+  verifier: () => verifier,
+  worker,
+  reviewer: () => reviewer,
+  "ui-reviewer": () => uiReviewer,
+  artist: () => artist,
+  writer: () => writer,
+  researcher: () => researcher,
 };
+
+const STATUS_LINE =
+  "The last line of your reply is: STATUS: complete|partial|blocked|refused — <one line why>";
+
+/**
+ * Spec 1.1 §6: the reply contract `dispatch` appends to every brief it writes, the tail of the role's
+ * prompt: reply length and the STATUS line. The architect and the verifier keep their own reply shapes.
+ */
+const CONTRACTS: Record<Role, string> = {
+  architect: `Reply briefly: the milestones, each with its lanes as Mx.Ly — one line — owned files, and the full-check command. ${STATUS_LINE}`,
+  verifier: `The first line of your reply is VERDICT: PASS or VERDICT: FAIL. ${STATUS_LINE}`,
+  worker: REPLY,
+  reviewer: REPLY,
+  "ui-reviewer": REPLY,
+  artist: REPLY,
+  writer: REPLY,
+  researcher: `For a single question, reply in at most 15 lines. ${STATUS_LINE}`,
+};
+
+export const replyContract = (role: Role): string => CONTRACTS[role];
+
+/** `brief` with the role's reply contract as its last paragraph, once: a brief that already ends with it is kept. */
+export function withReplyContract(role: Role, brief: string): string {
+  const contract = CONTRACTS[role];
+  const body = brief.trimEnd();
+  return body.endsWith(contract) ? `${body}\n` : `${body}\n\n${contract}\n`;
+}
+
+/** The role's prompt; the worker's names the catherd version whose `lock` it must use. */
+export const rolePrompt = (role: Role, version: string): string => BODIES[role](version);
+
+/**
+ * Spec D10 for native subagents, whose only lever is the agent file's tool list: read-only drops the
+ * editing tools (its Bash stays, for inspection, so enforcement is advisory); every role drops Agent,
+ * so a role never spawns its own subagents.
+ */
+export const nativeDisallowedTools = (access: Access): string[] =>
+  access === "read-only" ? ["Write", "Edit", "NotebookEdit", "Agent"] : ["Agent"];

package/src/domain/roles.ts

@@ -0,0 +1,25 @@
+import type { Access } from "./record.ts";
+
+export const ROLES = [
+  "architect",
+  "verifier",
+  "worker",
+  "reviewer",
+  "ui-reviewer",
+  "artist",
+  "writer",
+  "researcher",
+] as const;
+export type Role = (typeof ROLES)[number];
+
+/** Spec §7.1: the access mode a role runs with unless its profile says otherwise. */
+export const DEFAULT_ACCESS: Record<Role, Access> = {
+  architect: "read-only",
+  reviewer: "read-only",
+  researcher: "read-only",
+  worker: "workspace-write",
+  writer: "workspace-write",
+  artist: "workspace-write",
+  verifier: "full",
+  "ui-reviewer": "full",
+};

package/src/domain/route.ts

@@ -0,0 +1,126 @@
+import type { Difficulty, Kind } from "./lane.ts";
+import type { Role } from "./roles.ts";
+
+export const CLIMB_REASONS = [
+  "check-failed-twice",
+  "blocker",
+  "same-defect",
+  "refused",
+  "blocked",
+  "unchanged",
+] as const;
+export type ClimbReason = (typeof CLIMB_REASONS)[number];
+
+/**
+ * Spec §5.4: where a lane's kind and difficulty came from. `jev-kind`: Jev was sure of the kind only, and the
+ * difficulty came from the lane's `Difficulty:` line, else from the role's default rung.
+ */
+export type RouteSource = "jev" | "jev-kind" | "lane" | "default";
+
+/** What Jev said about a lane, kept with its route for outcomes.jsonl (spec §5.6). */
+export interface RouteJev {
+  pKind: number | null;
+  pA: number | null;
+  pB: number | null;
+  nouls: Record<string, number>;
+}
+
+/** One row of routes.jsonl: a lane's route, or one climb of it. The last row of a lane is its current route. */
+export interface RouteRow {
+  at: string;
+  lane: string;
+  role: Role;
+  rung: string;
+  ladder: string[];
+  source: "route" | "climb";
+  decidedBy: RouteSource;
+  from: string | null;
+  reason: string | null;
+  kind: Kind | null;
+  difficulty: Difficulty | null;
+  /** route rows: the Jev question set asked (null when Jev was not asked) and its probabilities */
+  questionSet?: string | null;
+  jev?: RouteJev | null;
+  /** climb rows: the climb was caused by the environment, not the rung's capability (spec §5.6) */
+  env?: boolean;
+}
+
+export function nextRung(ladder: string[], current: string): string | null {
+  const i = ladder.indexOf(current);
+  return i >= 0 && i < ladder.length - 1 ? (ladder[i + 1] as string) : null;
+}
+
+export const currentRoute = (rows: RouteRow[], lane: string): RouteRow | null =>
+  rows.findLast((r) => r.lane === lane) ?? null;
+
+/**
+ * The lane's route in force at `at`: its last row stamped at or before that time; null when the lane
+ * had no row by then (or `at` is not a time). Rows without a parseable `at` are skipped.
+ */
+export function routeAt(rows: RouteRow[], lane: string, at: string): RouteRow | null {
+  const t = Date.parse(at);
+  if (Number.isNaN(t)) return null;
+  return rows.findLast((r) => r.lane === lane && Date.parse(r.at) <= t) ?? null;
+}
+
+/**
+ * One outcomes.jsonl row (spec §5.6): how a routed lane ended, for calibrating Jev's route rule.
+ * A lane can get several rows (a top-rung failure later landed, a milestone landed again):
+ * the last row per lane wins; read them through `latestOutcomes`.
+ */
+export interface OutcomeRow {
+  at: string;
+  lane: string;
+  questionSet: string | null;
+  jevProbs: RouteJev | null;
+  source: RouteSource;
+  startRung: string;
+  finalRung: string;
+  climbs: { from: string; to: string; reason: string; env: boolean }[];
+  /** true when the lane landed, false when it ended open (a climb past its top rung) */
+  landed: boolean;
+  /** landed with no climb the rung itself caused */
+  start_ok: boolean;
+  /** the ladder index it landed on; null when it ended open (censored) */
+  min_ok_index: number | null;
+  /** some climb was the environment's fault: calibration leaves this lane out */
+  envCaused: boolean;
+}
+
+/** The lane's outcome from its routes.jsonl rows since its last route; null when it was never routed. */
+export function laneOutcome(rows: RouteRow[], lane: string, landed: boolean, at: string): OutcomeRow | null {
+  const mine = rows.filter((r) => r.lane === lane);
+  const i = mine.findLastIndex((r) => r.source === "route");
+  const start = mine[i];
+  if (!start) return null;
+  // every climb row counts for start_ok and envCaused, including a no-op past the top rung (from === rung),
+  // which only drops out of the listed climbs
+  const allClimbs = mine
+    .slice(i + 1)
+    .filter((r) => r.source === "climb" && r.from !== null)
+    .map((r) => ({ from: r.from as string, to: r.rung, reason: r.reason ?? "", env: r.env === true }));
+  const climbs = allClimbs.filter((c) => c.from !== c.to);
+  const finalRung = mine.at(-1)?.rung ?? start.rung;
+  const idx = start.ladder.indexOf(finalRung);
+  return {
+    at,
+    lane,
+    questionSet: start.questionSet ?? null,
+    jevProbs: start.jev ?? null,
+    source: start.decidedBy,
+    startRung: start.rung,
+    finalRung,
+    climbs,
+    landed,
+    start_ok: landed && allClimbs.every((c) => c.env),
+    min_ok_index: landed && idx >= 0 ? idx : null,
+    envCaused: allClimbs.some((c) => c.env),
+  };
+}
+
+/** Spec §5.6: one row per lane, the last one written (last row per lane wins), in first-seen lane order. */
+export function latestOutcomes(rows: OutcomeRow[]): OutcomeRow[] {
+  const byLane = new Map<string, OutcomeRow>();
+  for (const r of rows) byLane.set(r.lane, r);
+  return [...byLane.values()];
+}

package/src/domain/runtime.ts

@@ -0,0 +1,21 @@
+/** Spec §3.1 and D6: catherd runs on Bun 1.4.0 or newer. */
+export const MIN_BUN = "1.4.0";
+
+const parts = (v: string) => (/^(\d+)\.(\d+)\.(\d+)/.exec(v)?.slice(1) ?? ["0", "0", "0"]).map(Number);
+
+export function bunTooOld(version: string): boolean {
+  const a = parts(version);
+  const b = parts(MIN_BUN);
+  for (let i = 0; i < 3; i++)
+    if ((a[i] as number) !== (b[i] as number)) return (a[i] as number) < (b[i] as number);
+  return false;
+}
+
+/** The two lines to print, and exit 1 on, when this Bun is too old; null when it is new enough. */
+export function runtimeRefusal(version: string | undefined): string[] | null {
+  if (version !== undefined && !bunTooOld(version)) return null;
+  return [
+    `error E_RUNTIME_TOO_OLD: catherd needs Bun ${MIN_BUN} or newer; this is ${version ? `Bun ${version}` : "not Bun"}`,
+    "fix: bun upgrade (or install Bun: curl -fsSL https://bun.sh/install | bash)",
+  ];
+}

package/src/domain/sanitize.ts

@@ -0,0 +1,29 @@
+import { replaceSecrets, scrubKeyShapes } from "./secrets.ts";
+
+/** What to strip from a captured stream: exact secret values, and paths to replace with a stable name. */
+export interface Scrub {
+  secrets: string[];
+  paths: { from: string; to: string }[];
+}
+
+const EMAIL = /[\w.%+-]+@[\w-]+(?:\.[\w-]+)*\.[A-Za-z]{2,}/g;
+
+const longestFirst = <T>(xs: T[], len: (x: T) => number) => [...xs].sort((a, b) => len(b) - len(a));
+
+/**
+ * Spec §11.8: a capture keeps no secret and no home path. Secrets (8+ chars) and key-shaped strings
+ * (domain/secrets.ts) become `<redacted>`, emails `<email>`, and each path its stable name, longest
+ * path first so a repo inside the home directory reads `<repo>`, not `~/…`.
+ */
+export function sanitize(text: string, s: Scrub): string {
+  // a captured stream is JSONL: a secret with a quote, a backslash or a control character is escaped there
+  const forms = s.secrets.flatMap((x) => [x, JSON.stringify(x).slice(1, -1)]);
+  let out = scrubKeyShapes(replaceSecrets(text, forms, "<redacted>"), "<redacted>");
+  out = out.replace(EMAIL, "<email>");
+  for (const p of longestFirst(
+    s.paths.filter((x) => x.from.length > 1),
+    (x) => x.from.length,
+  ))
+    out = out.split(p.from).join(p.to);
+  return out;
+}

package/src/domain/secrets.ts

@@ -0,0 +1,57 @@
+// Spec §10.4 and §11.8: the one rule for what is a secret. The log redactor (infra/log.ts), fixture
+// capture (domain/sanitize.ts) and Jev's lane state (domain/jev.ts) all scrub with it; each picks its mark.
+
+/** Env names whose values are credentials: the word may sit anywhere (OPENAI_API_KEY_2, GH_TOKEN_FILE). */
+const SECRET_NAME = /KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i;
+/** A literal secret shorter than this is never scrubbed: it would blank ordinary words. */
+export const MIN_SECRET = 8;
+
+export const isSecretName = (name: string): boolean => SECRET_NAME.test(name);
+
+const longestFirst = (xs: string[]): string[] => [...new Set(xs)].sort((a, b) => b.length - a.length);
+
+/** The values of env vars whose names say they hold a credential: 8+ characters, once each, longest first. */
+export function secretEnvValues(env: Record<string, string | undefined>): string[] {
+  return longestFirst(
+    Object.entries(env)
+      .filter(([k, v]) => v !== undefined && v.length >= MIN_SECRET && isSecretName(k))
+      .map(([, v]) => v as string),
+  );
+}
+
+/** `text` with each literal secret of 8+ characters replaced by `mark`, the longest first. */
+export function replaceSecrets(text: string, secrets: string[], mark: string): string {
+  let out = text;
+  for (const s of longestFirst(secrets.filter((x) => x.length >= MIN_SECRET))) out = out.split(s).join(mark);
+  return out;
+}
+
+/** Strings shaped like a key wherever they appear, and the part kept before the mark ("Bearer ", a URL's user). */
+const KEY_SHAPES: [RegExp, string][] = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, ""],
+  [/sk-ant-[\w-]{10,}/g, ""],
+  [/\bsk-[\w-]{16,}/g, ""],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}/g, ""],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, ""],
+  [/\bAKIA[0-9A-Z]{16}\b/g, ""],
+  [/\bxox[abpr]-[A-Za-z0-9-]{10,}/g, ""],
+  [/\b(Bearer\s+)[\w.~+/=-]{10,}/gi, "$1"],
+  [/(\b[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s:@/]+:)[^\s@/]+(?=@)/g, "$1"],
+];
+
+/** `text` with every key-shaped string replaced by `mark` (which must not contain `$`). */
+export function scrubKeyShapes(text: string, mark: string): string {
+  let out = text;
+  for (const [re, keep] of KEY_SHAPES) out = out.replace(re, `${keep}${mark}`);
+  return out;
+}
+
+/**
+ * `api_key = value` and the like, keeping the name. Jev's state only: on a captured stream or a log row
+ * it would also blank counts such as `max_tokens: 100000`.
+ */
+const ASSIGNMENT =
+  /\b([A-Za-z0-9_]*(?:api[_-]?key|token|secret|password)[A-Za-z0-9_]*)\s*[:=]\s*["']?[^\s"']{6,}/gi;
+
+export const scrubSecretAssignments = (text: string, mark: string): string =>
+  text.replace(ASSIGNMENT, `$1=${mark}`);

package/src/domain/select.ts

@@ -0,0 +1,136 @@
+import {
+  type Catalog,
+  capableFor,
+  type Dim,
+  effortOffered,
+  type RungInfo,
+  rungInfo,
+  scoresOf,
+} 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";
+
+/** 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 };
+}
+
+export interface Candidate {
+  rung: string;
+  info: RungInfo;
+  scores: Partial<Record<Dim, number>>;
+  cost: Cost;
+  /** median seconds over the user's own runs (≥ 5 samples), else null */
+  secs: number | null;
+}
+
+export interface Pick {
+  rung: string;
+  ladder: string[];
+}
+
+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.
+ */
+export function candidates(c: Catalog, p: RoutingProfile, role: Role, kind: Kind | null = null): Candidate[] {
+  if (!p.role.enabled) return [];
+  const out: Candidate[] = [];
+  for (const rung of new Set(p.role.rungs)) {
+    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;
+    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),
+    });
+  }
+  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);
+  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,
+  );
+}
+
+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",
+  });
+}
+
+/**
+ * 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.
+ */
+export function defaultLadder(c: Catalog, p: RoutingProfile, role: Role): Pick {
+  const all = candidates(c, { ...p, objective: "cost" }, role).map((x) => x.rung);
+  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) };
+}
+
+/**
+ * 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.
+ */
+export function defaultDifficulty(c: Catalog, p: RoutingProfile, role: Role, kind: Kind): 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)) : [];
+  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.
+ */
+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);
+  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) };
+}