catherd-cli 0.2.1 → 1.1.0

package/src/adapters/opencode/index.ts

@@ -0,0 +1,333 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CatherdError } from "../../domain/errors.ts";
+import type { Rung } from "../../domain/ids.ts";
+import type { Access, RunStatus, Tokens } from "../../domain/record.ts";
+import {
+  type BackendAdapter,
+  compareVersions,
+  type DiscoveredModel,
+  type EventDelta,
+  extractVersion,
+  type FinishedRun,
+  type Outcome,
+  type Probe,
+  type RunRequest,
+  type SpawnPlan,
+  type Spent,
+} from "../backend.ts";
+import { scratchShell } from "../access.ts";
+import { jsonOf, runCli } from "../cli.ts";
+import { configDir } from "../../infra/paths.ts";
+import { discovered, readDiscovery } from "../discovery.ts";
+import { installAgents, isolatedConfigRoot, OPENCODE_AGENT, userConfigRoot } from "./agents.ts";
+import {
+  eventName,
+  foldOpencodeEvents,
+  isV1Error,
+  OPENCODE_LIMIT,
+  OPENCODE_LIMIT_TYPES,
+  OPENCODE_TOO_OLD,
+  opencodeTokens,
+  parseOpencodeLine,
+} from "./events.ts";
+
+/** Spec §6.3: v2 only (`@opencode/cli` 2.0.16 or newer). */
+const OPENCODE_MIN_VERSION = "2.0.16";
+export const OPENCODE_INSTALL = "curl -fsSL https://opencode.ai/v2/install | bash";
+/** Spec §6.3: discovery is limited to OpenCode Zen and Go. */
+const OPENCODE_PROVIDERS = ["opencode", "opencode-go"];
+const THREAD = /^ses_[A-Za-z0-9]{20,40}$/;
+const DAY_MS = 24 * 60 * 60_000;
+
+/** Limits for `opencode` queries; tests shorten them. */
+export const opencodeShell = { timeoutMs: 15_000, retryDelayMs: 1_500 };
+
+/** `opencode api <method> <path>`: the JSON the service answered, or null when it failed or said nothing. */
+async function opencodeApi(method: "GET" | "POST", path: string): Promise<Record<string, any> | null> {
+  const r = await runCli("opencode", ["api", method, path], opencodeShell);
+  const j = r?.ok ? jsonOf(r.out) : null;
+  return j && typeof j === "object" ? (j as Record<string, any>) : null;
+}
+
+/**
+ * An isolated worker's XDG_CONFIG_HOME holds only catherd's opencode config, and every process the worker
+ * starts inherits it: point catherd (`catherd lock`), gh and git back at the user's own config.
+ */
+function isolatedEnv(): Record<string, string> {
+  const user = userConfigRoot();
+  const env: Record<string, string> = {
+    XDG_CONFIG_HOME: isolatedConfigRoot(),
+    CATHERD_CONFIG_DIR: configDir(),
+  };
+  if (!process.env.GH_CONFIG_DIR) env.GH_CONFIG_DIR = join(user, "gh");
+  const gitXdg = join(user, "git", "config");
+  if (!process.env.GIT_CONFIG_GLOBAL && !existsSync(join(homedir(), ".gitconfig")) && existsSync(gitXdg))
+    env.GIT_CONFIG_GLOBAL = gitXdg;
+  return env;
+}
+
+function plan(r: RunRequest): SpawnPlan {
+  if (r.thread !== null && !THREAD.test(r.thread))
+    throw new CatherdError("E_ADMIT_THREAD", `"${r.thread}" is not an opencode session id`, {
+      fix: "pass the thread from the earlier RunRecord",
+    });
+  return {
+    cmd: "opencode",
+    args: [
+      "run",
+      "--format",
+      "json",
+      "--auto",
+      "--agent",
+      OPENCODE_AGENT[r.access],
+      "-m",
+      // "default" means the model's own default variant: no `#` (spec §5.1)
+      r.rung.effort === "default" ? r.rung.model : `${r.rung.model}#${r.rung.effort}`,
+      // v2's background service ignores the client's config env; a standalone server reads it
+      ...(r.isolated ? ["--standalone"] : []),
+      ...(r.thread === null ? [] : ["-s", r.thread]),
+    ],
+    env: r.isolated ? isolatedEnv() : {},
+    cwd: r.repo,
+    stdinPath: r.briefPath,
+  };
+}
+
+/**
+ * The Zen and Go models enabled in `repo`; without one, in the home directory, where v2 resolves a
+ * request that names no location (research §2.4).
+ */
+async function listModels(repo?: string): Promise<DiscoveredModel[]> {
+  const where = repo === undefined ? "" : `?${new URLSearchParams({ "location[directory]": repo })}`;
+  let data: Record<string, any>[] = [];
+  for (let attempt = 0; attempt < 2 && data.length === 0; attempt++) {
+    // the first listing after the service (re)starts can be empty (research §1.4)
+    if (attempt > 0) await Bun.sleep(opencodeShell.retryDelayMs);
+    const r = await opencodeApi("GET", `/api/model${where}`);
+    data = Array.isArray(r?.data) ? r.data : [];
+  }
+  return data
+    .filter(
+      (m) => OPENCODE_PROVIDERS.includes(m.providerID) && m.enabled !== false && typeof m.id === "string",
+    )
+    .map((m) => ({
+      id: `${m.providerID}/${m.id}`,
+      efforts: ((m.variants ?? []) as { id?: unknown }[])
+        .map((v) => v.id)
+        .filter((v): v is string => typeof v === "string"),
+      context: typeof m.limit?.context === "number" ? m.limit.context : null,
+      imageIn: Array.isArray(m.capabilities?.input) && m.capabilities.input.includes("image"),
+    }));
+}
+
+/**
+ * Spec §6.3: install the catherd agents, and refuse a Zen or Go model or variant opencode does not list
+ * in the repository (its config can enable or disable models), from a listing cached per repository.
+ */
+async function prepare(req: { rung: Rung; access: Access; isolated: boolean; repo: string }): Promise<void> {
+  const root = req.isolated ? isolatedConfigRoot() : userConfigRoot();
+  // the background service only sees a new agent file after a reload (verified on 2.0.16)
+  if (installAgents(root) && !req.isolated) await runCli("opencode", ["reload"], opencodeShell);
+  const { model, effort } = req.rung;
+  if (!OPENCODE_PROVIDERS.includes(model.split("/")[0] ?? "")) return;
+  const models = await discovered("opencode", () => listModels(req.repo), {
+    maxAgeMs: DAY_MS,
+    need: model,
+    repo: req.repo,
+  });
+  if (models.length === 0) return; // opencode listed nothing: let the run itself say what is wrong
+  const m = models.find((x) => x.id === model);
+  if (!m)
+    throw new CatherdError("E_BACKEND_MODEL_UNKNOWN", `opencode does not list ${model}`, {
+      fix: model.startsWith("opencode-go/")
+        ? "subscribe to OpenCode Go and run: opencode auth login opencode-go --method key"
+        : "run: opencode auth login opencode --method key, or pick a model catalog_query lists",
+    });
+  if (effort !== "default" && !m.efforts.includes(effort))
+    throw new CatherdError("E_BACKEND_MODEL_UNKNOWN", `${model} has no variant "${effort}"`, {
+      fix: `use one of: ${["default", ...m.efforts].join(", ")}`,
+    });
+}
+
+function finalize(run: FinishedRun): Outcome {
+  const f = foldOpencodeEvents(run.eventLines);
+  const stopped = run.exit.reason;
+  const tooOld = f.tooOld || OPENCODE_TOO_OLD.some((r) => r.test(run.stderr));
+  const status: RunStatus =
+    stopped === "cancelled"
+      ? "cancelled"
+      : stopped === "idle-timeout" || stopped === "wall-timeout"
+        ? "timeout"
+        : tooOld
+          ? "cli-too-old"
+          : f.limit
+            ? "limit"
+            : f.error !== null || run.exit.code !== 0
+              ? "failed"
+              : "ok";
+  const lastErr = run.stderr.trim().split("\n").at(-1) ?? "";
+  const message = f.declined
+    ? `permission rejected: ${f.declined}`
+    : (f.error?.message ?? (lastErr || `${stopped}, exit ${run.exit.code ?? run.exit.signal}`));
+  return {
+    status,
+    thread: f.thread ?? run.request.thread,
+    tokens: f.tokens,
+    costUsd: f.costUsd,
+    images: [],
+    error: status === "ok" ? null : { code: status, message },
+    reply: f.reply,
+  };
+}
+
+/** Spec §3.7: the tool opencode ran (a command, a file edit, another tool with its first argument) or its text. */
+function opencodeActivity(e: Record<string, any>): string | undefined {
+  if (e.type === "text" && typeof e.part?.text === "string") return e.part.text;
+  if (e.type !== "tool_use" || typeof e.part?.tool !== "string") return undefined;
+  const input = e.part.state?.input ?? {};
+  if (typeof input.command === "string") return `$ ${input.command}`;
+  const path = input.filePath ?? input.path;
+  if (/^(edit|write|patch)$/.test(e.part.tool) && typeof path === "string") return `edit ${path}`;
+  const first = Object.values(input).find((v) => typeof v === "string");
+  return `${e.part.tool}${typeof first === "string" ? ` ${first}` : ""}`;
+}
+
+function parse(line: string): EventDelta {
+  const e = parseOpencodeLine(line);
+  if (!e) return {};
+  const d: EventDelta = { lastEvent: eventName(e) };
+  const activity = opencodeActivity(e);
+  if (activity) d.activity = activity;
+  if (typeof e.sessionID === "string") d.thread = e.sessionID;
+  if (e.type === "step_finish") {
+    d.tokens = opencodeTokens(e.part?.tokens);
+    d.requestInput = d.tokens.input;
+    if (typeof e.part?.cost === "number") d.costUsd = e.part.cost;
+  }
+  if (e.type === "error") {
+    if (isV1Error(e)) d.tooOld = true;
+    else if (OPENCODE_LIMIT_TYPES.includes(e.error?.type)) d.limit = true;
+    d.failure = String(e.error?.message ?? e.error?.data?.message ?? "error");
+  }
+  return d;
+}
+
+/**
+ * A usage limit the latest assistant message is retrying on or failed with (v2 keeps `retry: {attempt, at,
+ * error}` on it), or null. Messages come newest first, after an `idle` marker once the session stopped;
+ * older messages keep their errors, so only the newest assistant message counts, and with `sinceMs` only
+ * if this run wrote it.
+ */
+function limitRetry(messages: unknown, sinceMs?: number): string | null {
+  if (!Array.isArray(messages)) return null;
+  const m = messages.find((x) => x?.type === "assistant") as Record<string, any> | undefined;
+  const err = m?.retry?.error ?? m?.error;
+  if (!OPENCODE_LIMIT_TYPES.includes(err?.type)) return null;
+  if (sinceMs !== undefined && !(m?.time?.created >= sinceMs)) return null;
+  return String(err.message ?? err.type);
+}
+
+const minus = (a: Tokens, b: Tokens): Tokens => ({
+  input: Math.max(0, a.input - b.input),
+  cached: Math.max(0, a.cached - b.cached),
+  output: Math.max(0, a.output - b.output),
+});
+
+/**
+ * Spec §6.3: totals from `GET /api/session/<id>` (the stream often drops its last step_finish), minus
+ * what earlier records on the session counted; a run stopped while retrying on a usage limit is a limit.
+ */
+async function settle(o: Outcome, run: FinishedRun, prior: Spent): Promise<Outcome> {
+  if (o.thread === null) return o;
+  let out = o;
+  const s = (await opencodeApi("GET", `/api/session/${o.thread}`))?.data;
+  if (s?.tokens)
+    out = {
+      ...out,
+      tokens: minus(opencodeTokens(s.tokens), prior.tokens),
+      costUsd: typeof s.cost === "number" ? Math.max(0, s.cost - prior.costUsd) : out.costUsd,
+    };
+  if (out.status === "timeout" || out.status === "failed") {
+    const messages = (await opencodeApi("GET", `/api/session/${o.thread}/message`))?.data;
+    const why = limitRetry(messages, run.startedAtMs);
+    if (why) out = { ...out, status: "limit", error: { code: "limit", message: why } };
+  }
+  return out;
+}
+
+/**
+ * Busy while the service lists the session as running, unless it is only waiting out a usage limit.
+ * Empty or failed API output counts as not busy (spec §6.3), so a hung run still times out.
+ */
+async function isBusy(thread: string, sinceMs?: number): Promise<boolean> {
+  const active = (await opencodeApi("GET", "/api/session/active"))?.data;
+  if (!active || typeof active !== "object" || !(thread in active)) return false;
+  const messages = (await opencodeApi("GET", `/api/session/${thread}/message`))?.data;
+  return Array.isArray(messages) && limitRetry(messages, sinceMs) === null;
+}
+
+/** Killing the v2 client does not stop its session; the service must be told (research §2.4). */
+async function interrupt(thread: string): Promise<void> {
+  await opencodeApi("POST", `/api/session/${thread}/interrupt`);
+}
+
+/** Spec §4.5: Go `X` → Zen `X` when Zen lists `X` with the same variant (in `repo`, when given). */
+function failoverFor(rung: Rung, repo?: string): Rung | null {
+  if (!rung.model.startsWith("opencode-go/")) return null;
+  const zen = `opencode/${rung.model.slice("opencode-go/".length)}`;
+  const m = readDiscovery("opencode", repo)?.models.find((x) => x.id === zen);
+  if (!m || (rung.effort !== "default" && !m.efforts.includes(rung.effort))) return null;
+  return { backend: "opencode", model: zen, effort: rung.effort };
+}
+
+async function probe(): Promise<Probe> {
+  const v = await runCli("opencode", ["--version"], opencodeShell);
+  if (!v)
+    return {
+      installed: false,
+      version: null,
+      versionOk: false,
+      loggedIn: null,
+      problems: [{ code: "E_BACKEND_MISSING", message: "opencode is not on PATH", fix: OPENCODE_INSTALL }],
+    };
+  const version = extractVersion(v.out);
+  const versionOk = version !== null && compareVersions(version, OPENCODE_MIN_VERSION) >= 0;
+  const auth = jsonOf((await runCli("opencode", ["auth", "list", "--format", "json"], opencodeShell))?.out);
+  // Not logged in is no problem: the free Zen models run without a key.
+  const loggedIn = Array.isArray(auth)
+    ? auth.some((p) => OPENCODE_PROVIDERS.includes(p?.id) && (p?.connections?.length ?? 0) > 0)
+    : null;
+  const problems: Probe["problems"] = [];
+  if (!versionOk)
+    problems.push({
+      code: "E_BACKEND_TOO_OLD",
+      message: version?.startsWith("1.")
+        ? `opencode ${version} is v1; catherd needs opencode v2 (${OPENCODE_MIN_VERSION} or newer)`
+        : `opencode ${version ?? "?"} is older than ${OPENCODE_MIN_VERSION}`,
+      fix: OPENCODE_INSTALL,
+    });
+  return { installed: true, version, versionOk, loggedIn, problems };
+}
+
+export const opencodeAdapter: BackendAdapter = {
+  id: "opencode",
+  minVersion: OPENCODE_MIN_VERSION,
+  probe,
+  listModels,
+  prepare,
+  plan,
+  parse,
+  finalize,
+  settle,
+  enforcement: { "read-only": "advisory", "workspace-write": "advisory", full: "advisory" },
+  errors: { limit: OPENCODE_LIMIT, tooOld: OPENCODE_TOO_OLD },
+  resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
+  interrupt: (thread) => interrupt(thread),
+  isBusy: (thread, _cwd, sinceMs) => isBusy(thread, sinceMs),
+  failoverFor,
+  graceAfterFinalMs: null,
+  // research 2026-09-25 §2.6: opencode has no OS sandbox; its shell runs with the user's own authority
+  accessShell: async () => scratchShell("an unsandboxed shell (opencode has no sandbox)", []),
+};

package/src/adapters/registry.ts

@@ -0,0 +1,14 @@
+import type { BackendAdapter } from "./backend.ts";
+
+const adapters = new Map<string, BackendAdapter>();
+
+export function registerAdapter(a: BackendAdapter): void {
+  adapters.set(a.id, a);
+}
+
+export const adapterFor = (id: string): BackendAdapter | null => adapters.get(id) ?? null;
+
+/** Tests only: forget an adapter registered for the test. */
+export function unregisterAdapter(id: string): void {
+  adapters.delete(id);
+}

package/src/cli.ts

@@ -1,28 +1,168 @@
 #!/usr/bin/env bun
-import { readFileSync, realpathSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { defineCommand, runMain } from "citty";
-import { lockCommand } from "./core/lock.ts";
-import { mcpCommand } from "./mcp/commands.ts";
-import { catalogCommand } from "./routing/commands.ts";
-import { editorRun, initCommand, watchCommand } from "./tui/commands.ts";
-
-const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
-  version: string;
+import type { ArgsDef } from "citty";
+import { errorMessage } from "./domain/errors.ts";
+import { runtimeRefusal } from "./domain/runtime.ts";
+
+// Spec §3.1: refuse an old Bun before anything else loads.
+const refusal = runtimeRefusal(typeof Bun === "undefined" ? undefined : Bun.version);
+if (refusal) {
+  for (const line of refusal) console.error(line);
+  process.exit(1);
+}
+
+const { realpathSync } = await import("node:fs");
+const { fileURLToPath } = await import("node:url");
+const { defineCommand, renderUsage, runCommand } = await import("citty");
+const { CatherdError, isCatherdError } = await import("./domain/errors.ts");
+const { EXIT, exitCodeOf, printError, stripAnsi } = await import("./entry/cli-kit.ts");
+const { VERSION } = await import("./infra/version.ts");
+
+type Command = ReturnType<typeof defineCommand>;
+
+/** The dashboard's flags, typed as any command's args so `main` stays a plain `Command`. */
+const dashboardArgs: ArgsDef = {
+  plain: {
+    type: "boolean",
+    description: "the dashboard in ASCII without colour (NO_COLOR also drops colour)",
+  },
+  "reduced-motion": { type: "boolean", description: "the dashboard without animation" },
 };
 
-export const main = defineCommand({
-  meta: { name: "catherd", version: pkg.version, description: "Herds coding agents." },
+/**
+ * Spec §8. Every subcommand loads lazily, so `mcp`, `lock` and `_supervise` never load OpenTUI or React
+ * (spec §3.1); a bare `catherd` opens the TUI.
+ */
+export const main: Command = defineCommand({
+  meta: {
+    name: "catherd",
+    version: VERSION,
+    description: "Herds coding agents",
+  },
+  args: dashboardArgs,
   subCommands: {
-    lock: lockCommand,
-    catalog: catalogCommand,
-    mcp: mcpCommand,
-    init: initCommand,
-    watch: watchCommand,
+    init: () => import("./entry/init-command.ts").then((m) => m.initCommand),
+    status: () => import("./entry/runs-command.ts").then((m) => m.statusCommand),
+    watch: () => import("./entry/runs-command.ts").then((m) => m.watchCommand),
+    runs: () => import("./entry/runs-command.ts").then((m) => m.runsCommand),
+    profile: () => import("./entry/profile-command.ts").then((m) => m.profileCommand),
+    doctor: () => import("./entry/doctor-command.ts").then((m) => m.doctorCommand),
+    catalog: () => import("./entry/catalog-command.ts").then((m) => m.catalogCommand),
+    lock: () => import("./entry/lock-command.ts").then((m) => m.lockCommand),
+    "capture-fixtures": () =>
+      import("./entry/capture-fixtures-command.ts").then((m) => m.captureFixturesCommand),
+    mcp: () => import("./entry/mcp/command.ts").then((m) => m.mcpCommand),
+    _supervise: () => import("./entry/supervise-command.ts").then((m) => m.superviseCommand),
+  },
+  // citty runs this after any subcommand too; only a bare `catherd` loads and opens the dashboard
+  async run(ctx) {
+    if (!ctx.rawArgs.every((a) => a.startsWith("-"))) return;
+    await (await import("./entry/tui/run.tsx")).tuiRun(ctx);
   },
-  run: editorRun,
 });
 
+const resolve = async <T>(v: T | Promise<T> | (() => T | Promise<T>)): Promise<T> =>
+  typeof v === "function" ? await (v as () => T | Promise<T>)() : await v;
+
+/** The deepest command `argv` names and its parent: what `--help` and a usage error describe. */
+async function commandFor(argv: string[]): Promise<[Command, Command | undefined, string[]]> {
+  let cmd = main;
+  let parent: Command | undefined;
+  const path: string[] = [];
+  for (const a of argv) {
+    if (a.startsWith("-")) continue;
+    const subs = cmd.subCommands ? await resolve(cmd.subCommands) : undefined;
+    const next = subs?.[a];
+    if (!next) break;
+    parent = cmd;
+    cmd = (await resolve(next)) as Command;
+    path.push(a);
+  }
+  return [cmd, parent, path];
+}
+
+/** runCli takes `--verbose` before any command, so every command's help lists it. */
+const VERBOSE_ARG: ArgsDef = {
+  verbose: { type: "boolean", description: "log at debug level (CATHERD_LOG=debug)" },
+};
+
+/**
+ * `--help` for the command `path` names (spec §8): `catherd <path>` with the version at every depth, the
+ * usage line a command spells out itself, and no colour codes when piped or under NO_COLOR.
+ */
+async function helpText(cmd: Command, path: string[]): Promise<string> {
+  const shown = { ...cmd, args: { ...(await resolve(cmd.args ?? {})), ...VERBOSE_ARG } };
+  const parent = path.length
+    ? defineCommand({ meta: { name: ["catherd", ...path.slice(0, -1)].join(" "), version: VERSION } })
+    : undefined;
+  let text = await renderUsage(shown, parent);
+  const usage = path[0] === "lock" ? (await import("./entry/lock-command.ts")).LOCK_USAGE : undefined;
+  if (usage) text = text.replace(/^(\S*USAGE\S*) .*$/m, (_, head: string) => `${head} ${usage}`);
+  return process.stdout.isTTY && !process.env.NO_COLOR ? text : stripAnsi(text);
+}
+
+/** citty's "Unknown command x." worded as catherd's own messages: lower case, no full stop (audit N5). */
+const cittyWording = (m: string): string => `${m.charAt(0).toLowerCase()}${m.slice(1)}`.replace(/\.$/, "");
+
+const isCliError = (e: unknown): e is Error & { code: string } => e instanceof Error && e.name === "CLIError";
+
+/** Runs `catherd <argv>` and returns its exit code (spec §8). */
+export async function runCli(argv: string[]): Promise<number> {
+  // catherd's own flags are those before `--`; everything after belongs to the command `lock` runs
+  const dashdash = argv.indexOf("--");
+  const head = dashdash < 0 ? argv : argv.slice(0, dashdash);
+  if (head.includes("--verbose")) process.env.CATHERD_LOG = "debug";
+  const own = head.filter((a) => a !== "--verbose");
+  const rawArgs = [...own, ...(dashdash < 0 ? [] : argv.slice(dashdash))];
+  if (own.length === 1 && (own[0] === "--version" || own[0] === "-v")) {
+    console.log(VERSION);
+    return EXIT.ok;
+  }
+  if (own.includes("--help") || own.includes("-h")) {
+    const [cmd, , path] = await commandFor(own);
+    console.log(`${await helpText(cmd, path)}\n`);
+    return EXIT.ok;
+  }
+  const command = own.find((a) => !a.startsWith("-"));
+  // a bare `catherd` opens the dashboard, which takes only its own flags: a typo is not a terminal problem
+  const flag = (a: string) => (a.startsWith("--") ? (a.slice(2).split("=")[0] ?? "") : "");
+  // citty negates a boolean as `--no-<name>`
+  const known = (name: string) =>
+    Object.hasOwn(dashboardArgs, name) ||
+    (name.startsWith("no-") && dashboardArgs[name.slice(3)]?.type === "boolean");
+  const unknown = command === undefined ? own.find((a) => !known(flag(a))) : undefined;
+  if (unknown !== undefined) {
+    printError(new CatherdError("E_INPUT_INVALID", `unknown option ${unknown}`, { fix: "catherd --help" }));
+    return EXIT.usage;
+  }
+  // `lock` forwards signals to its command itself; everything else stops at once on Ctrl-C. The command is
+  // the first word that is not a flag: `catherd --plain lock -- …` is `lock` too.
+  if (command !== "lock") process.once("SIGINT", () => process.exit(EXIT.interrupted));
+  try {
+    await runCommand(main, { rawArgs });
+    return Number(process.exitCode ?? EXIT.ok);
+  } catch (e) {
+    if (isCliError(e)) {
+      const [, , path] = await commandFor(own);
+      printError(
+        new CatherdError("E_INPUT_INVALID", cittyWording(stripAnsi(e.message)), {
+          fix: `catherd ${[...path, "--help"].join(" ")}`,
+        }),
+      );
+      return EXIT.usage;
+    }
+    if (isCatherdError(e)) {
+      printError(e);
+      return exitCodeOf(e);
+    }
+    printError({
+      code: "E_IO_UNEXPECTED",
+      message: errorMessage(e),
+      fix: "this is a catherd bug: report it with this message and the output of the same command with --verbose",
+    });
+    return EXIT.error;
+  }
+}
+
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  void runMain(main);
+  process.exitCode = await runCli(process.argv.slice(2));
 }

package/src/domain/agents.ts

@@ -0,0 +1,60 @@
+import { parseRung, tryParseRung } from "./ids.ts";
+import { agentName, type Profile } from "./profile.ts";
+import type { Access } from "./record.ts";
+import { nativeDisallowedTools, rolePrompt } from "./role-prompts.ts";
+import { ROLES, type Role } from "./roles.ts";
+
+export interface AgentFile {
+  /** the agent's name, also its file name without `.md` */
+  name: string;
+  role: Role;
+  rung: string;
+  text: string;
+}
+
+/** One native subagent's file: Claude Code reads `name`, `model`, `effort` and the tool list. */
+export function renderAgent(o: {
+  profile: string;
+  role: Role;
+  rung: string;
+  access: Access;
+  version: string;
+}): string {
+  const { model, effort } = parseRung(o.rung);
+  return [
+    "---",
+    `name: ${agentName(o.profile, o.role, o.rung)}`,
+    `description: Internal ${o.role} role of the catherd orchestrator (profile ${o.profile}), on ${model}${effort === "default" ? "" : ` at ${effort} effort`}. Dispatched only by the catherd skill while a run is in flight. Never for a plain request, even one that names this role.`,
+    `model: ${model}`,
+    ...(effort === "default" ? [] : [`effort: ${effort}`]),
+    `disallowedTools: ${nativeDisallowedTools(o.access).join(", ")}`,
+    "---",
+    "",
+    rolePrompt(o.role, o.version),
+    "",
+  ].join("\n");
+}
+
+/**
+ * Spec §7.3: an agent file per enabled role and native `claude:` rung, counting a native stand-in for one
+ * of the role's rungs, since dispatch hands those to the orchestrator as an Agent to start.
+ */
+export function agentFiles(p: Profile, version: string): AgentFile[] {
+  const out = new Map<string, AgentFile>();
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    if (!rc.enabled) continue;
+    const rungs = [...rc.rungs, ...rc.rungs.flatMap((r) => p.failover[r] ?? [])];
+    for (const rung of rungs) {
+      if (tryParseRung(rung)?.backend !== "claude") continue;
+      const name = agentName(p.name, role, rung);
+      out.set(name, {
+        name,
+        role,
+        rung,
+        text: renderAgent({ profile: p.name, role, rung, access: rc.access, version }),
+      });
+    }
+  }
+  return [...out.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/domain/budget.ts

@@ -0,0 +1,45 @@
+export interface Budget {
+  minutes?: number;
+  tokens?: number;
+  usd?: number;
+}
+
+export interface Spend {
+  minutes: number;
+  tokens: number;
+  usd: number;
+}
+
+export interface BudgetStatus {
+  /** the highest spent/cap ratio over the caps the profile sets; ≥ 1 means spent */
+  fraction: number;
+  minutes?: { spent: number; cap: number };
+  tokens?: { spent: number; cap: number };
+  usd?: { spent: number; cap: number };
+}
+
+/** Spec §4.6: from this fraction on, `route` starts at the cheapest rung that clears the bar. */
+export const BUDGET_CHEAP_AT = 0.8;
+
+/** null when the profile sets no cap. */
+export function budgetStatus(spend: Spend, budget: Budget): BudgetStatus | null {
+  const b: BudgetStatus = { fraction: 0 };
+  let capped = false;
+  for (const key of ["minutes", "tokens", "usd"] as const) {
+    const cap = budget[key];
+    if (cap === undefined) continue;
+    capped = true;
+    const spent = spend[key];
+    b[key] = { spent, cap };
+    b.fraction = Math.max(b.fraction, cap > 0 ? spent / cap : spent > 0 ? 1 : 0);
+  }
+  return capped ? b : null;
+}
+
+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)}%)`;
+}