catherd-cli 0.1.0

package/src/core/reply.ts

@@ -0,0 +1,54 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { ReplyStatus } from "../types.ts";
+
+const STATUS = /^STATUS:\s*(complete|partial|blocked|refused)\s*(?:—|–|-)\s*(.*)$/;
+
+/** Dirs never worth hashing, even under an owned path. */
+const SKIP = new Set(["node_modules", ".git", "dist", ".next", "coverage"]);
+
+export function parseReplyStatus(reply: string): { status: ReplyStatus | null; why: string | null } {
+  const last = reply.trimEnd().split("\n").at(-1)?.trim() ?? "";
+  const m = STATUS.exec(last);
+  return m ? { status: m[1] as ReplyStatus, why: (m[2] ?? "").trim() } : { status: null, why: null };
+}
+
+function hashFile(path: string): string {
+  return new Bun.CryptoHasher("sha1").update(readFileSync(path)).digest("hex");
+}
+
+/** Owned paths are matched literally: walked with node:fs, never interpreted as glob patterns. */
+function walk(root: string, dir: string, out: Map<string, string>): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walk(root, full, out);
+    else if (entry.isFile()) out.set(relative(root, full), hashFile(full));
+  }
+}
+
+export function snapshotOwned(repo: string, owned: string[]): Map<string, string> {
+  const m = new Map<string, string>();
+  for (const o of owned) {
+    const full = join(repo, o);
+    if (!existsSync(full)) {
+      m.set(o, "<absent>");
+      continue;
+    }
+    if (statSync(full).isDirectory()) walk(repo, full, m);
+    else m.set(o, hashFile(full));
+  }
+  return m;
+}
+
+export function changedSince(repo: string, before: Map<string, string>, owned: string[]): string[] {
+  const after = snapshotOwned(repo, owned);
+  const changed = new Set<string>();
+  for (const [p, h] of after) {
+    if (before.get(p) !== h && !(h === "<absent>" && !before.has(p))) changed.add(p);
+  }
+  for (const [p, h] of before) {
+    if (!after.has(p) && h !== "<absent>") changed.add(p);
+  }
+  return [...changed].sort();
+}

package/src/core/runstore.ts

@@ -0,0 +1,163 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { dataDir, runsRoot } from "../paths.ts";
+import type { Role, RungId, RunMeta, RunRecord, StateSnapshot } from "../types.ts";
+
+export interface Run {
+  dir: string;
+  id: string;
+  meta: RunMeta;
+}
+
+/** Dirs under the data root that are catherd's own, not a repo's runs. */
+const NOT_REPOS = new Set(["locks", "codex-home", "opencode-home"]);
+
+const slug = (s: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 40) || "run";
+
+const stamp = (d: Date) => d.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+
+export function createRun(repo: string, title: string, aLines: string[]): Run {
+  const now = new Date();
+  const id = `${stamp(now)}-${slug(title)}`;
+  const dir = join(runsRoot(repo), id);
+  mkdirSync(join(dir, "lanes"), { recursive: true });
+  mkdirSync(join(dir, "roles"), { recursive: true });
+  mkdirSync(join(dir, "shots"), { recursive: true });
+  const meta: RunMeta = { id, repo, title, aLines, createdAt: now.toISOString() };
+  writeFileSync(join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`);
+  writeFileSync(join(dir, "ledger.md"), "milestone | what | commit | minutes | evidence\n");
+  writeFileSync(join(dir, "state.md"), `# ${title}\n\n${aLines.join("\n")}\n\nNext: plan the milestones\n`);
+  return { dir, id, meta };
+}
+
+export function openRun(repo: string, id: string): Run {
+  const dir = join(runsRoot(repo), id);
+  const meta = JSON.parse(readFileSync(join(dir, "meta.json"), "utf8")) as RunMeta;
+  return { dir, id, meta };
+}
+
+export function listRuns(): Run[] {
+  const root = dataDir();
+  if (!existsSync(root)) return [];
+  const runs: Run[] = [];
+  for (const repo of readdirSync(root, { withFileTypes: true })) {
+    if (!repo.isDirectory() || NOT_REPOS.has(repo.name)) continue;
+    for (const run of readdirSync(join(root, repo.name), { withFileTypes: true })) {
+      const dir = join(root, repo.name, run.name);
+      if (!run.isDirectory() || !existsSync(join(dir, "meta.json"))) continue;
+      const meta = JSON.parse(readFileSync(join(dir, "meta.json"), "utf8")) as RunMeta;
+      runs.push({ dir, id: meta.id, meta });
+    }
+  }
+  return runs.sort((a, b) => b.meta.createdAt.localeCompare(a.meta.createdAt));
+}
+
+export function rolePaths(dir: string, name: string) {
+  const base = join(dir, "roles", name);
+  return {
+    brief: `${base}.md`,
+    fix: `${base}.fix.md`,
+    out: `${base}.out`,
+    jsonl: `${base}.jsonl`,
+    err: `${base}.err`,
+  };
+}
+
+/** Moves the latest round's out/jsonl/err to <name>.r<k>.* so the new round starts clean. */
+export function rotateRound(dir: string, name: string): void {
+  const p = rolePaths(dir, name);
+  const current = [p.out, p.jsonl, p.err].filter((f) => existsSync(f));
+  if (current.length === 0) return;
+  let k = 1;
+  while (["out", "jsonl", "err"].some((x) => existsSync(join(dir, "roles", `${name}.r${k}.${x}`)))) k++;
+  for (const x of ["out", "jsonl", "err"] as const) {
+    if (existsSync(p[x])) renameSync(p[x], join(dir, "roles", `${name}.r${k}.${x}`));
+  }
+}
+
+export function appendJsonl(file: string, value: unknown): void {
+  appendFileSync(file, `${JSON.stringify(value)}\n`);
+}
+
+export function readJsonl<T>(file: string): T[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((l) => l.trim())
+    .map((l) => JSON.parse(l) as T);
+}
+
+export const appendRunRecord = (dir: string, r: RunRecord) => appendJsonl(join(dir, "runs.jsonl"), r);
+export const readRunRecords = (dir: string) => readJsonl<RunRecord>(join(dir, "runs.jsonl"));
+
+export function writeState(dir: string, s: StateSnapshot): void {
+  const lines = [
+    `HEAD ${s.head}`,
+    "",
+    "Dirty:",
+    ...(s.dirty.length ? s.dirty.map((d) => `- ${d.path}${d.owner ? ` (${d.owner})` : ""}`) : ["- none"]),
+    "",
+    "Running:",
+    ...(s.running.length
+      ? s.running.map(
+          (r) => `- ${r.name} · ${r.rung} · thread ${r.thread ?? "new"} · since ${r.since} · ${r.brief}`,
+        )
+      : ["- none"]),
+    "",
+    `Last check: ${s.lastCheck ?? "none"}`,
+    "",
+    `Next: ${s.next}`,
+  ];
+  const title = readFileSync(join(dir, "state.md"), "utf8").split("\n")[0] ?? "# run";
+  writeFileSync(join(dir, "state.md"), `${title}\n\n${lines.join("\n")}\n`);
+}
+
+export function appendLedger(dir: string, row: string): void {
+  appendFileSync(join(dir, "ledger.md"), `${row}\n`);
+}
+
+export interface LiveMarker {
+  name: string;
+  role: Role;
+  backend: "codex" | "opencode";
+  rung: RungId;
+  pid: number;
+  thread: string | null;
+  startedAt: string;
+  cwd: string;
+  ownedFiles: string[];
+  isolated: boolean;
+  before: Record<string, string>;
+}
+
+const livePath = (dir: string, name: string) => join(dir, "roles", `${name}.live.json`);
+
+export function writeLive(dir: string, m: LiveMarker): void {
+  writeFileSync(livePath(dir, m.name), JSON.stringify(m));
+}
+
+export function clearLive(dir: string, name: string): void {
+  rmSync(livePath(dir, name), { force: true });
+}
+
+export function readLive(dir: string): LiveMarker[] {
+  const roles = join(dir, "roles");
+  if (!existsSync(roles)) return [];
+  return readdirSync(roles)
+    .filter((f) => f.endsWith(".live.json"))
+    .map((f) => JSON.parse(readFileSync(join(roles, f), "utf8")) as LiveMarker);
+}

package/src/core/spawn.ts

@@ -0,0 +1,89 @@
+import { closeSync, existsSync, openSync, readFileSync } from "node:fs";
+
+export interface ChildOpts {
+  cwd: string;
+  env: Record<string, string | undefined>;
+  /** file to feed on stdin; stdin is /dev/null without it */
+  stdinFile?: string;
+  stdoutFile: string;
+  stderrFile: string;
+  /** called with each batch of new stdout lines, every pollMs */
+  onLines?: (lines: string[]) => void;
+  pollMs?: number;
+  /** called every tickMs while the child runs */
+  onTick?: () => void;
+  tickMs?: number;
+  /** called once, right after the child starts */
+  onSpawn?: (c: { pid: number; kill: () => void }) => void;
+}
+
+export interface ChildResult {
+  code: number | null;
+  pid: number | null;
+  signal: NodeJS.Signals | null;
+}
+
+export function readLines(file: string): string[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((l) => l.trim());
+}
+
+/** Kills the whole process group a detached child leads (pgid === pid on POSIX). */
+function killGroup(pid: number): void {
+  try {
+    process.kill(-pid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      // already gone
+    }
+  }
+}
+
+/**
+ * The child gets raw file descriptors, not a pipe through this process, so no stream passes
+ * through catherd: with `detached: true` it starts its own process group (POSIX `setsid()`),
+ * outlives catherd, and `reconcileLive` reads its files after a restart.
+ */
+export async function runChild(cmd: string, args: string[], o: ChildOpts): Promise<ChildResult> {
+  if (!Bun.which(cmd, { PATH: o.env?.PATH ?? process.env.PATH ?? "" })) {
+    throw new Error(`catherd: ${cmd} is not on PATH; install it, or untick its models in the profile`);
+  }
+  const stdin = o.stdinFile ? openSync(o.stdinFile, "r") : "ignore";
+  const stdout = openSync(o.stdoutFile, "w");
+  const stderr = openSync(o.stderrFile, "w");
+  const proc = Bun.spawn([cmd, ...args], {
+    cwd: o.cwd,
+    env: o.env,
+    stdin,
+    stdout,
+    stderr,
+    detached: true,
+  });
+  for (const fd of [stdin, stdout, stderr]) if (typeof fd === "number") closeSync(fd);
+  const pid = proc.pid;
+  if (pid) o.onSpawn?.({ pid, kill: () => killGroup(pid) });
+  let seen = 0;
+  const drain = () => {
+    const lines = readLines(o.stdoutFile);
+    if (lines.length > seen) {
+      o.onLines?.(lines.slice(seen));
+      seen = lines.length;
+    }
+  };
+  const poll = o.onLines ? setInterval(drain, o.pollMs ?? 1000) : null;
+  const tick = o.onTick ? setInterval(o.onTick, o.tickMs ?? 60_000) : null;
+  let code: number | null;
+  try {
+    code = await proc.exited;
+  } finally {
+    if (poll) clearInterval(poll);
+    if (tick) clearInterval(tick);
+  }
+  if (o.onLines) drain();
+  if (!pid) throw new Error(`catherd: could not start ${cmd}`);
+  return { code, pid, signal: proc.signalCode ?? null };
+}

package/src/core/status.ts

@@ -0,0 +1,193 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { activeProfileName, loadProfile } from "../profile/profile.ts";
+import type { Profile, Role, RungId, Tokens } from "../types.ts";
+import { formatHarness, type HarnessCost, harnessCosts } from "./harness.ts";
+import { readRoutes } from "./lanes.ts";
+import { reconcileLive } from "./reconcile.ts";
+import { listRuns, readJsonl, readRunRecords, type Run } from "./runstore.ts";
+
+export type RunTotals = {
+  runs: number;
+  ok: number;
+  notOk: string[];
+  secs: number;
+  tokens: Tokens;
+  costUsd: number;
+};
+
+export interface RunSummary {
+  id: string;
+  title: string;
+  repo: string;
+  stateTail: string[];
+  live: { name: string; rung: RungId; secs: number; pid: number }[];
+  totals: RunTotals;
+  jev: { decisions: number; fallbacks: number };
+  milestones: string[];
+  harness: HarnessCost[];
+  /** spec §11b: this run's spend against the active profile's budget, or null with no budget set */
+  budget: BudgetStatus | null;
+}
+
+export interface BudgetStatus {
+  /** the highest spent/cap ratio across the caps the profile set; ≥ 1 means exhausted */
+  fraction: number;
+  minutes?: { spent: number; cap: number };
+  tokens?: { spent: number; cap: number };
+  usd?: { spent: number; cap: number };
+}
+
+export function budgetStatus(totals: RunTotals, budget: Profile["budget"] | undefined): BudgetStatus | null {
+  if (!budget) return null;
+  const b: BudgetStatus = { fraction: 0 };
+  const consider = (spent: number, cap: number | undefined, key: "minutes" | "tokens" | "usd") => {
+    if (cap === undefined) return;
+    b[key] = { spent, cap };
+    b.fraction = Math.max(b.fraction, cap > 0 ? spent / cap : spent > 0 ? 1 : 0);
+  };
+  consider(totals.secs / 60, budget.minutes, "minutes");
+  consider(totals.tokens.input + totals.tokens.output, budget.tokens, "tokens");
+  consider(totals.costUsd, budget.usd, "usd");
+  return b;
+}
+
+export function formatBudget(b: BudgetStatus): string {
+  const parts: string[] = [];
+  if (b.minutes) parts.push(`${Math.round(b.minutes.spent)}/${b.minutes.cap} min`);
+  if (b.tokens) parts.push(`${b.tokens.spent}/${b.tokens.cap} tokens`);
+  if (b.usd) parts.push(`$${b.usd.spent.toFixed(2)}/$${b.usd.cap.toFixed(2)}`);
+  return `${parts.join(" · ")} (${Math.round(b.fraction * 100)}%)`;
+}
+
+/** The active profile's budget for this run's repo, or undefined when there is none or the profile fails to load. */
+function budgetFor(run: Run): Profile["budget"] | undefined {
+  try {
+    return loadProfile(activeProfileName(run.meta.repo)).budget;
+  } catch {
+    return undefined;
+  }
+}
+
+const lines = (file: string) =>
+  existsSync(file)
+    ? readFileSync(file, "utf8")
+        .split("\n")
+        .filter((l) => l.trim())
+    : [];
+
+export function summarizeRun(run: Run): RunSummary {
+  const { stillRunning } = reconcileLive(run.dir);
+  const recs = readRunRecords(run.dir);
+  const jev = readJsonl<{ source?: string }>(join(run.dir, "jev.jsonl"));
+  const now = Date.now();
+  const totals: RunTotals = {
+    runs: recs.length,
+    ok: recs.filter((r) => r.status === "ok").length,
+    notOk: recs.filter((r) => r.status !== "ok").map((r) => `${r.name} (${r.status})`),
+    secs: recs.reduce((n, r) => n + r.secs, 0),
+    tokens: {
+      input: recs.reduce((n, r) => n + r.tokens.input, 0),
+      cached: recs.reduce((n, r) => n + r.tokens.cached, 0),
+      output: recs.reduce((n, r) => n + r.tokens.output, 0),
+    },
+    costUsd: recs.reduce((n, r) => n + (r.costUsd ?? 0), 0),
+  };
+  return {
+    id: run.id,
+    title: run.meta.title,
+    repo: run.meta.repo,
+    stateTail: lines(join(run.dir, "state.md")).slice(-3),
+    live: stillRunning.map((m) => ({
+      name: m.name,
+      rung: m.rung,
+      secs: Math.round((now - Date.parse(m.startedAt)) / 1000),
+      pid: m.pid,
+    })),
+    totals,
+    jev: { decisions: jev.length, fallbacks: jev.filter((j) => j.source === "default").length },
+    milestones: lines(join(run.dir, "ledger.md")).slice(1),
+    harness: harnessCosts(listRuns().map((r) => r.dir)),
+    budget: budgetStatus(totals, budgetFor(run)),
+  };
+}
+
+const mmss = (s: number) =>
+  `${String(Math.floor(s / 60)).padStart(2, "0")}:${String(s % 60).padStart(2, "0")}`;
+
+export function formatSummary(s: RunSummary): string {
+  const t = s.totals;
+  return [
+    `== ${s.title} · ${s.id}`,
+    ...s.stateTail,
+    "-- running",
+    ...(s.live.length ? s.live.map((l) => `  ${l.name}  ${l.rung}  ${mmss(l.secs)}`) : ["  none"]),
+    `-- done  ${t.runs} runs · ${t.ok} ok · ${Math.round(t.secs / 60)} min · ${t.tokens.input} in / ${t.tokens.output} out tokens · $${t.costUsd.toFixed(2)}${t.notOk.length ? ` · not ok: ${t.notOk.join(", ")}` : ""}`,
+    `-- jev  ${s.jev.decisions} decisions · ${s.jev.fallbacks} fell back to default`,
+    ...(s.harness.length
+      ? s.harness.map((h) => `-- harness  ${formatHarness(h)}`)
+      : ["-- harness  no data yet"]),
+    ...(s.budget ? [`-- budget  ${formatBudget(s.budget)}`] : []),
+    ...(s.milestones.length ? ["-- landed", ...s.milestones.map((m) => `  ${m}`)] : []),
+  ].join("\n");
+}
+
+export interface RungStats {
+  role: Role;
+  rung: RungId;
+  runs: number;
+  ok: number;
+  refusals: number;
+  climbsFrom: number;
+  secs: number;
+  tokens: Tokens;
+}
+
+export function runsSummary(
+  f: { run?: string; repo?: string; role?: Role; sinceDays?: number } = {},
+): RungStats[] {
+  const since = f.sinceDays ? Date.now() - f.sinceDays * 86_400_000 : 0;
+  const runs = listRuns().filter(
+    (r) =>
+      (!f.run || r.id === f.run) &&
+      (!f.repo || r.meta.repo === f.repo) &&
+      Date.parse(r.meta.createdAt) >= since,
+  );
+  const stats = new Map<string, RungStats>();
+  const at = (role: Role, rung: RungId): RungStats => {
+    const key = `${role} ${rung}`;
+    let s = stats.get(key);
+    if (!s) {
+      s = {
+        role,
+        rung,
+        runs: 0,
+        ok: 0,
+        refusals: 0,
+        climbsFrom: 0,
+        secs: 0,
+        tokens: { input: 0, cached: 0, output: 0 },
+      };
+      stats.set(key, s);
+    }
+    return s;
+  };
+  for (const run of runs) {
+    for (const r of readRunRecords(run.dir)) {
+      if (f.role && r.role !== f.role) continue;
+      const s = at(r.role, r.rung);
+      s.runs++;
+      if (r.status === "ok") s.ok++;
+      if (r.replyStatus === "refused" || r.replyStatus === "blocked") s.refusals++;
+      s.secs += r.secs;
+      s.tokens.input += r.tokens.input;
+      s.tokens.cached += r.tokens.cached;
+      s.tokens.output += r.tokens.output;
+    }
+    for (const c of readRoutes(run.dir)) {
+      if (c.source !== "climb" || !c.from || (f.role && c.role !== f.role)) continue;
+      at(c.role, c.from).climbsFrom++;
+    }
+  }
+  return [...stats.values()].sort((a, b) => a.role.localeCompare(b.role) || a.rung.localeCompare(b.rung));
+}

package/src/files.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+// This module sits one level below the package root as src/files.ts, and catherd ships with no
+// build step, so one relative URL finds shipped files both in tests and after install alike.
+export const assetPath = (rel: string): string => fileURLToPath(new URL(`../${rel}`, import.meta.url));
+
+export function readJsonFile<T>(schema: z.ZodType<T>, file: string): T {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    throw new Error(`catherd: ${file} is not readable JSON: ${(e as Error).message}`);
+  }
+  const r = schema.safeParse(raw);
+  if (!r.success) throw new Error(`catherd: ${file} is invalid:\n${z.prettifyError(r.error)}`);
+  return r.data;
+}

package/src/mcp/commands.ts

@@ -0,0 +1,7 @@
+import { defineCommand } from "citty";
+import { startMcpServer } from "./server.ts";
+
+export const mcpCommand = defineCommand({
+  meta: { name: "mcp", description: "Run the catherd MCP server over stdio" },
+  run: () => startMcpServer(),
+});

package/src/mcp/dispatch.ts

@@ -0,0 +1,154 @@
+import { writeFileSync } from "node:fs";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { type DispatchOpts, runCodex } from "../core/codex.ts";
+import { recordHarness } from "../core/harness.ts";
+import { ID, ownedFilesOf, readLane } from "../core/lanes.ts";
+import { runOpencode } from "../core/opencode.ts";
+import { reconcileLive } from "../core/reconcile.ts";
+import { readLive, rolePaths } from "../core/runstore.ts";
+import { budgetStatus, formatBudget, summarizeRun } from "../core/status.ts";
+import { agentName } from "../profile/agents.ts";
+import { activeProfileName, loadProfile } from "../profile/profile.ts";
+import { loadCatalog } from "../routing/catalog.ts";
+import { ROLES, type RunRecord } from "../types.ts";
+import { json } from "./out.ts";
+import { backendOf, findRun, refreshState } from "./runs.ts";
+
+export function dispatchHints(r: RunRecord, owned: string[]): string[] {
+  const h: string[] = [];
+  if (r.status === "limit")
+    h.push(`limit: ${r.backend} hit a usage limit; the run is paused, report it and push`);
+  if (r.status === "cli-too-old")
+    h.push(`cli-too-old: tell the user to upgrade ${r.backend}: ${r.error ?? ""}`.trim());
+  if (r.status === "failed") h.push(`failed: read roles/${r.name}.err before a retry`);
+  if (r.replyStatus === "refused" || r.replyStatus === "blocked") h.push(`climb: ${r.replyStatus}`);
+  else if (r.status === "ok" && owned.length > 0 && r.changedOwned.length === 0) h.push("climb: unchanged");
+  if (r.threadHeavy) h.push("thread-heavy: its next piece starts on a fresh thread");
+  return h;
+}
+
+export function registerDispatch(server: McpServer): void {
+  server.registerTool(
+    "dispatch",
+    {
+      description:
+        "Run one Codex or opencode role and return its RESULT record and hints when it finishes. The brief is the text itself; catherd writes it to roles/<name>.md, or roles/<name>.fix.md when resuming a thread. With lane, the lane file's Owns: line gives the owned files, and a lane overlapping a running one is refused. Call it from the main thread.",
+      inputSchema: {
+        run: z.string(),
+        role: z.enum(ROLES),
+        name: z.string().regex(ID),
+        brief: z.string().min(1),
+        rung: z.string().min(3),
+        thread: z.string().optional(),
+        lane: z.string().regex(ID).optional(),
+        next: z.string().optional(),
+      },
+    },
+    async (a, extra) => {
+      const run = findRun(a.run);
+      reconcileLive(run.dir);
+      const catalog = loadCatalog();
+      const backend = backendOf(catalog, a.rung);
+      if (backend === "claude") {
+        throw new Error(
+          `catherd: ${a.rung} is a Claude rung. Run it as Agent(subagent_type: "${agentName(a.role, a.rung)}") instead.`,
+        );
+      }
+      const profile = loadProfile(activeProfileName(run.meta.repo));
+      // spec §11b: at 100% of the run budget, refuse rather than start another role that might overrun it.
+      const budget = budgetStatus(summarizeRun(run).totals, profile.budget);
+      if (budget && budget.fraction >= 1) {
+        throw new Error(
+          `catherd: run budget exhausted (${formatBudget(budget)}); ask the user before continuing`,
+        );
+      }
+      const owned = a.lane ? ownedFilesOf(readLane(run.dir, a.lane)) : [];
+      if (a.lane && owned.length === 0) throw new Error(`catherd: lanes/${a.lane}.md has no "Owns:" line`);
+      const live = readLive(run.dir);
+      if (live.some((m) => m.name === a.name)) throw new Error(`catherd: ${a.name} is already running`);
+      for (const m of live) {
+        const shared = m.ownedFiles.filter((f) => owned.includes(f));
+        if (shared.length) {
+          throw new Error(
+            `catherd: ${a.name} owns ${shared.join(", ")}, which running ${m.name} owns; dispatch it after that one`,
+          );
+        }
+      }
+
+      const p = rolePaths(run.dir, a.name);
+      writeFileSync(a.thread ? p.fix : p.brief, a.brief);
+      await refreshState(run, {
+        starting: {
+          name: a.name,
+          rung: a.rung,
+          thread: a.thread ?? null,
+          brief: `roles/${a.name}${a.thread ? ".fix" : ""}.md`,
+          since: new Date().toISOString().slice(11, 16),
+        },
+        ...(a.next ? { next: a.next } : {}),
+      });
+
+      const token = extra._meta?.progressToken;
+      let tick = 0;
+      const runOne = (
+        rung: string,
+        thread: string | undefined,
+        rb: "codex" | "opencode",
+      ): Promise<RunRecord> => {
+        const o: DispatchOpts = {
+          runDir: run.dir,
+          name: a.name,
+          role: a.role,
+          rung,
+          cwd: run.meta.repo,
+          thread,
+          ownedFiles: owned,
+          isolated: profile.harness[rb].isolated,
+          onProgress:
+            token === undefined
+              ? undefined
+              : (pr) => {
+                  void extra.sendNotification({
+                    method: "notifications/progress",
+                    params: {
+                      progressToken: token,
+                      progress: ++tick,
+                      message: `${a.name} · ${rung} · ${pr.secs}s${pr.lastEvent ? ` · ${pr.lastEvent}` : ""}`,
+                    },
+                  });
+                },
+        };
+        return rb === "codex" ? runCodex(o) : runOpencode(o);
+      };
+
+      let record = await runOne(a.rung, a.thread, backend);
+      if (!a.thread) recordHarness(run.dir, record);
+
+      // spec §11b: a limit result re-dispatches on the profile's failover stand-in for this rung.
+      const hints: string[] = [];
+      const failoverTo = profile.failover?.[a.rung];
+      if (record.status === "limit" && failoverTo) {
+        const toBackend = backendOf(catalog, failoverTo);
+        if (toBackend === "claude") {
+          hints.push(
+            `limit: ${a.rung} hit a usage limit; its failover ${failoverTo} is a Claude rung — run it as Agent(subagent_type: "${agentName(a.role, failoverTo)}")`,
+          );
+        } else {
+          const failedRung = record.rung;
+          record = await runOne(failoverTo, undefined, toBackend);
+          if (!a.thread) recordHarness(run.dir, record);
+          hints.push(`limit: ${a.role} ${failedRung} hit a usage limit; failed over to ${failoverTo}`);
+        }
+      }
+
+      await refreshState(
+        run,
+        record.status === "limit"
+          ? { next: `paused: ${record.backend} usage limit; resume when the user says so` }
+          : {},
+      );
+      return json({ record, hints: [...hints, ...dispatchHints(record, owned)] });
+    },
+  );
+}