catherd-cli 0.2.1 → 1.1.0

package/src/mcp/dispatch.ts

@@ -1,154 +0,0 @@
-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)] });
-    },
-  );
-}

package/src/mcp/lane-tools.ts

@@ -1,200 +0,0 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative } from "node:path";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { appendRoute, CLIMB_REASONS, currentRoute, ID } from "../core/lanes.ts";
-import { appendLedger } from "../core/runstore.ts";
-import { budgetStatus, summarizeRun } from "../core/status.ts";
-import { runsRoot } from "../paths.ts";
-import { agentName } from "../profile/agents.ts";
-import { activeProfileName, loadProfile } from "../profile/profile.ts";
-import { loadCatalog } from "../routing/catalog.ts";
-import { askFinding, askSameDefect, nextRung, route as routeLane } from "../routing/route.ts";
-import { defaultLadder } from "../routing/select.ts";
-import { type Backend, type Catalog, ROLES, type Role, type RungId } from "../types.ts";
-import { json, text } from "./out.ts";
-import { backendOf, findRun, refreshState, runFile } from "./runs.ts";
-
-export function targetOf(c: Catalog, role: Role, rung: RungId): { backend: Backend; agent?: string } {
-  const backend = backendOf(c, rung);
-  return backend === "claude" ? { backend, agent: agentName(role, rung) } : { backend };
-}
-
-const cell = (s: string) => s.replace(/[|\n]/g, "/").replace(/\s+/g, " ").trim();
-
-/** git's short commit exists check: does `<commit>^{commit}` resolve in `repo`? */
-function commitExists(repo: string, commit: string): boolean {
-  return Bun.spawnSync(["git", "-C", repo, "cat-file", "-e", `${commit}^{commit}`]).success;
-}
-
-/** spec §11b: what past runs of this repo learned, one line per landed milestone that had something to say. */
-const knowledgeFile = (repo: string): string => join(runsRoot(repo), "knowledge.md");
-
-function appendKnowledge(repo: string, line: string): void {
-  const file = knowledgeFile(repo);
-  mkdirSync(dirname(file), { recursive: true });
-  appendFileSync(file, `${line}\n`);
-}
-
-export function registerLaneTools(server: McpServer): void {
-  server.registerTool(
-    "route",
-    {
-      description:
-        "The rung for a lane (decided by Jev from its lane file, lanes/<id>.md) or, without a lane file, for a role (the profile's default), with the ladder above it. A Claude rung comes with the agent to run it as.",
-      inputSchema: {
-        run: z.string(),
-        lane_file: z.string().optional(),
-        role: z.enum(ROLES).default("worker"),
-      },
-    },
-    async (a) => {
-      const run = findRun(a.run);
-      const profile = loadProfile(activeProfileName(run.meta.repo));
-      const catalog = loadCatalog();
-      if (!a.lane_file) {
-        const d = defaultLadder(profile, catalog, a.role);
-        return json({
-          role: a.role,
-          rung: d.rung,
-          ladder: d.ladder,
-          source: "default",
-          ...targetOf(catalog, a.role, d.rung),
-        });
-      }
-      const file = runFile(run, a.lane_file, "read");
-      const lane = basename(file, ".md");
-      if (!ID.test(lane) || relative(run.dir, file) !== join("lanes", `${lane}.md`)) {
-        throw new Error(`catherd: a lane file lives at lanes/<id>.md, not ${a.lane_file}`);
-      }
-      const d = await routeLane({
-        runDir: run.dir,
-        profile,
-        catalog,
-        role: a.role,
-        laneText: readFileSync(file, "utf8"),
-        budget: { spentFraction: budgetStatus(summarizeRun(run).totals, profile.budget)?.fraction ?? 0 },
-      });
-      appendRoute(run.dir, {
-        at: new Date().toISOString(),
-        lane,
-        role: a.role,
-        rung: d.rung,
-        ladder: d.ladder,
-        source: "route",
-        from: null,
-        reason: null,
-        kind: d.kind,
-        difficulty: d.difficulty,
-        jev: d.source,
-      });
-      return json({ lane, role: a.role, ...d, ...targetOf(catalog, a.role, d.rung) });
-    },
-  );
-
-  server.registerTool(
-    "climb",
-    {
-      description:
-        "Move a routed lane one rung up its ladder and record why. Returns the next rung, or top: true when there is none. Dispatch the lane again on a fresh thread.",
-      inputSchema: {
-        run: z.string(),
-        lane: z.string().regex(ID),
-        reason: z.enum(CLIMB_REASONS),
-        evidence: z.string().optional(),
-      },
-    },
-    async (a) => {
-      const run = findRun(a.run);
-      const cur = currentRoute(run.dir, a.lane);
-      if (!cur) throw new Error(`catherd: lane ${a.lane} was never routed; call route first`);
-      const next = nextRung(cur.ladder, cur.rung);
-      appendRoute(run.dir, {
-        ...cur,
-        at: new Date().toISOString(),
-        source: "climb",
-        from: cur.rung,
-        rung: next ?? cur.rung,
-        reason: a.evidence ? `${a.reason}: ${a.evidence}` : a.reason,
-      });
-      await refreshState(run, {
-        next: next
-          ? `dispatch ${a.lane} at ${next} on a fresh thread`
-          : `${a.lane} failed on its top rung: ask finding, then the architect or the report`,
-      });
-      if (!next) return json({ lane: a.lane, rung: cur.rung, top: true });
-      return json({ lane: a.lane, rung: next, top: false, ...targetOf(loadCatalog(), cur.role, next) });
-    },
-  );
-
-  server.registerTool(
-    "ask",
-    {
-      description:
-        "Ask Jev one fixed question. finding: state { lane_file, finding } → design | code | unclear. same-defect: state { before, after } → yes | no. Falls back to the default when Jev is unsure or down. Keep the state short, in English, and free of secrets.",
-      inputSchema: {
-        run: z.string(),
-        question: z.enum(["finding", "same-defect"]),
-        state: z.record(z.string(), z.string()),
-      },
-    },
-    async (a) => {
-      const run = findRun(a.run);
-      const need = (k: string) => {
-        const v = a.state[k];
-        if (!v) throw new Error(`catherd: ${a.question} needs state.${k}`);
-        return v;
-      };
-      if (a.question === "finding") {
-        const laneText = readFileSync(runFile(run, need("lane_file"), "read"), "utf8");
-        return json(await askFinding(run.dir, laneText, need("finding")));
-      }
-      return json(await askSameDefect(run.dir, need("before"), need("after")));
-    },
-  );
-
-  server.registerTool(
-    "land",
-    {
-      description:
-        "Record a landed milestone after you commit it: appends its ledger row and rewrites state.md with its evidence as the last check and the next step. learned, when given, is appended to this repo's knowledge.md (read_knowledge returns it) for the next run's architect to read.",
-      inputSchema: {
-        run: z.string(),
-        milestone: z.string().min(1),
-        what: z.string().min(1),
-        commit: z.string().regex(/^[0-9a-f]{7,40}$/),
-        evidence: z.string().min(1),
-        next: z.string().min(1),
-        learned: z.string().min(1).optional(),
-      },
-    },
-    async (a) => {
-      const run = findRun(a.run);
-      if (!commitExists(run.meta.repo, a.commit))
-        throw new Error(`catherd: no commit ${a.commit} in ${run.meta.repo}`);
-      const row = [a.milestone, a.what, a.commit, a.evidence].map(cell).join(" | ");
-      appendLedger(run.dir, row);
-      await refreshState(run, { lastCheck: cell(a.evidence), next: a.next });
-      if (a.learned) {
-        const date = new Date().toISOString().slice(0, 10);
-        appendKnowledge(run.meta.repo, `- ${date} ${run.meta.title} ${a.milestone}: ${cell(a.learned)}`);
-      }
-      return json({ ledger: row });
-    },
-  );
-
-  server.registerTool(
-    "read_knowledge",
-    {
-      description:
-        "What past runs of this repo learned, one line per landed milestone that said something (land's learned). Read it before an architect plans a new run.",
-      inputSchema: { repo: z.string().min(1) },
-    },
-    async (a) => {
-      const file = knowledgeFile(a.repo);
-      return text(
-        existsSync(file) ? readFileSync(file, "utf8") : "catherd: no knowledge recorded yet for this repo",
-      );
-    },
-  );
-}

package/src/mcp/out.ts

@@ -1,6 +0,0 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-
-export const json = (v: unknown): CallToolResult => ({
-  content: [{ type: "text", text: JSON.stringify(v, null, 2) }],
-});
-export const text = (t: string): CallToolResult => ({ content: [{ type: "text", text: t }] });

package/src/mcp/preflight.ts

@@ -1,84 +0,0 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { fastCheckOf, ownedFilesOf } from "../core/lanes.ts";
-import { acquire, resolveSlots } from "../core/lock.ts";
-import { json } from "./out.ts";
-import { findRun } from "./runs.ts";
-
-const TAIL_LINES = 20;
-
-interface PreflightResult {
-  lane: string;
-  check: string;
-  pass: boolean;
-  skipped?: boolean;
-  tail: string[];
-}
-
-async function runCheck(cwd: string, check: string): Promise<{ pass: boolean; tail: string[] }> {
-  const proc = Bun.spawn(["sh", "-c", check], { cwd, stdout: "pipe", stderr: "pipe" });
-  const [out, err, code] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  const tail = `${out}${err}`
-    .split("\n")
-    .filter((l) => l.trim())
-    .slice(-TAIL_LINES);
-  return { pass: code === 0, tail };
-}
-
-export function registerPreflight(server: McpServer): void {
-  server.registerTool(
-    "preflight",
-    {
-      description:
-        "Runs each lane's fast check once, on the base tree, behind the machine-wide heavy-command lock, and reports pass/fail per lane with the tail of its output. Call it after the lane files exist and before dispatching any lane.",
-      inputSchema: { run: z.string() },
-    },
-    async (a) => {
-      const run = findRun(a.run);
-      const dir = join(run.dir, "lanes");
-      const files = existsSync(dir)
-        ? readdirSync(dir)
-            .filter((f) => f.endsWith(".md"))
-            .sort()
-        : [];
-      const held = await acquire(resolveSlots(), `preflight ${run.id}`);
-      try {
-        const results: PreflightResult[] = [];
-        for (const f of files) {
-          const lane = f.slice(0, -".md".length);
-          const text = readFileSync(join(dir, f), "utf8");
-          const check = fastCheckOf(text);
-          if (!check) {
-            results.push({ lane, check: "", pass: false, tail: [`lanes/${f} has no "Fast check:" line`] });
-            continue;
-          }
-          // A check on a file the lane itself creates cannot run on the base tree; that is expected.
-          const unborn = ownedFilesOf(text).filter(
-            (p) => check.includes(p) && !existsSync(join(run.meta.repo, p)),
-          );
-          if (unborn.length > 0) {
-            results.push({
-              lane,
-              check,
-              pass: true,
-              skipped: true,
-              tail: [`skipped: ${unborn.join(", ")} does not exist yet; the lane creates it`],
-            });
-            continue;
-          }
-          const r = await runCheck(run.meta.repo, check);
-          results.push({ lane, check, ...r });
-        }
-        return json({ results, allPass: results.every((r) => r.pass) });
-      } finally {
-        await held.release();
-      }
-    },
-  );
-}

package/src/mcp/run-tools.ts

@@ -1,121 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { ID } from "../core/lanes.ts";
-import { createRun, listRuns, readRunRecords, rolePaths } from "../core/runstore.ts";
-import { formatSummary, summarizeRun } from "../core/status.ts";
-import { jevKey } from "../routing/jev.ts";
-import { json, text } from "./out.ts";
-import { findRun, refreshState, runFile } from "./runs.ts";
-
-const CAP_LINES = 250;
-const CAP_CHARS = 20_000;
-
-export function capReply(reply: string, path: string): string {
-  const lines = reply.split("\n");
-  const head = lines.length > CAP_LINES ? lines.slice(0, CAP_LINES).join("\n") : reply;
-  if (head === reply && reply.length <= CAP_CHARS) return reply;
-  return `${head.slice(0, CAP_CHARS)}\n[capped: the full reply is ${path}]`;
-}
-
-/** git's toplevel for `repo`, or null when it is not inside a git repository. */
-function gitToplevel(repo: string): string | null {
-  const proc = Bun.spawnSync(["git", "-C", repo, "rev-parse", "--show-toplevel"], {
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  return proc.success ? proc.stdout.toString("utf8").trim() : null;
-}
-
-export function registerRunTools(server: McpServer): void {
-  server.registerTool(
-    "run_start",
-    {
-      description:
-        "Start a catherd run for a git repository: creates its run folder (outside the repo) and state.md. Returns the run id and the folder.",
-      inputSchema: {
-        repo: z.string().min(1),
-        title: z.string().min(1),
-        a_lines: z.array(z.string().min(1)).min(1),
-      },
-    },
-    async ({ repo, title, a_lines }) => {
-      if (!jevKey()) throw new Error("catherd: no Jev key. Run `bunx catherd-cli init` in a terminal first.");
-      const top = gitToplevel(repo);
-      if (!top) throw new Error(`catherd: ${repo} is not inside a git repository`);
-      const run = createRun(top, title, a_lines);
-      return json({ run: run.id, dir: run.dir });
-    },
-  );
-
-  server.registerTool(
-    "write_run_file",
-    {
-      description:
-        "Write a file inside a run folder: plan.md, lanes/Mx.Ly.md, a dossier or notes. The path is relative to the run folder; catherd's own files are refused.",
-      inputSchema: { run: z.string(), path: z.string().min(1), content: z.string() },
-    },
-    async (a) => {
-      const file = runFile(findRun(a.run), a.path, "write");
-      mkdirSync(dirname(file), { recursive: true });
-      writeFileSync(file, a.content);
-      return json({ path: file, bytes: Buffer.byteLength(a.content) });
-    },
-  );
-
-  server.registerTool(
-    "read_run_file",
-    {
-      description: "Read a file inside a run folder. The path is relative to the run folder.",
-      inputSchema: { run: z.string(), path: z.string().min(1) },
-    },
-    async (a) => text(readFileSync(runFile(findRun(a.run), a.path, "read"), "utf8")),
-  );
-
-  server.registerTool(
-    "status",
-    {
-      description:
-        "One screen on a run: the state.md tail, live roles with their age, totals, Jev fallbacks and the harness cost. Without a run: every run with live roles, else the newest run.",
-      inputSchema: { run: z.string().optional() },
-    },
-    async (a) => {
-      if (a.run) return text(formatSummary(summarizeRun(findRun(a.run))));
-      const runs = listRuns();
-      if (runs.length === 0) return text("catherd: no runs yet");
-      const all = runs.map(summarizeRun);
-      const live = all.filter((s) => s.live.length > 0);
-      return text((live.length ? live : all.slice(0, 1)).map(formatSummary).join("\n\n"));
-    },
-  );
-
-  server.registerTool(
-    "result",
-    {
-      description: "A role's latest reply, capped, and its RESULT record.",
-      inputSchema: { run: z.string(), name: z.string().regex(ID) },
-    },
-    async (a) => {
-      const run = findRun(a.run);
-      const p = rolePaths(run.dir, a.name);
-      const reply = existsSync(p.out) ? readFileSync(p.out, "utf8") : "";
-      const record = readRunRecords(run.dir).findLast((r) => r.name === a.name) ?? null;
-      return json({ reply: capReply(reply, p.out), record });
-    },
-  );
-
-  server.registerTool(
-    "set_next",
-    {
-      description:
-        "Record the run's next step, the last line of state.md: when pausing, or when the plan changes. dispatch, climb and land write state.md themselves.",
-      inputSchema: { run: z.string(), next: z.string().min(1) },
-    },
-    async (a) => {
-      const run = findRun(a.run);
-      await refreshState(run, { next: a.next });
-      return text(readFileSync(join(run.dir, "state.md"), "utf8"));
-    },
-  );
-}

package/src/mcp/runs.ts

@@ -1,118 +0,0 @@
-import { existsSync, lstatSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { ID } from "../core/lanes.ts";
-import { listRuns, readLive, type Run, writeState } from "../core/runstore.ts";
-import { modelOf } from "../routing/catalog.ts";
-import { type Backend, type Catalog, type RungId, splitRung, type StateSnapshot } from "../types.ts";
-
-export function findRun(id: string): Run {
-  if (!ID.test(id)) throw new Error(`catherd: bad run id "${id}"`);
-  const run = listRuns().find((r) => r.id === id);
-  if (!run) throw new Error(`catherd: no run "${id}"; status() lists the runs`);
-  return run;
-}
-
-const SERVER_OWNED = [
-  "meta.json",
-  "state.md",
-  "state.json",
-  "ledger.md",
-  "runs.jsonl",
-  "jev.jsonl",
-  "routes.jsonl",
-  "harness.jsonl",
-];
-
-const present = (p: string) => {
-  try {
-    lstatSync(p);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-/** The absolute path of `path` inside the run folder. Throws when it, or a symlink on the way, leaves the folder. */
-export function runFile(run: Run, path: string, mode: "read" | "write"): string {
-  const full = resolve(run.dir, path);
-  const rel = relative(run.dir, full);
-  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || resolve(run.dir, rel) !== full) {
-    throw new Error(`catherd: "${path}" is outside the run folder`);
-  }
-  if (mode === "write" && (SERVER_OWNED.includes(rel) || rel.startsWith(`roles${sep}`))) {
-    throw new Error(`catherd: ${rel} is written by catherd itself`);
-  }
-  let probe = full;
-  while (!present(probe)) probe = dirname(probe);
-  const root = realpathSync(run.dir);
-  const real = realpathSync(probe);
-  if (real !== root && !real.startsWith(`${root}${sep}`)) {
-    throw new Error(`catherd: "${path}" resolves outside the run folder`);
-  }
-  return full;
-}
-
-interface StateNotes {
-  next: string;
-  lastCheck: string | null;
-}
-
-const notesFile = (run: Run) => join(run.dir, "state.json");
-
-function readNotes(run: Run): StateNotes {
-  if (!existsSync(notesFile(run))) return { next: "plan the milestones", lastCheck: null };
-  return JSON.parse(readFileSync(notesFile(run), "utf8")) as StateNotes;
-}
-
-/** git output, or "" on any failure (no repo, git missing, non-zero exit). */
-function git(cwd: string, ...args: string[]): string {
-  try {
-    const proc = Bun.spawnSync(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
-    return proc.success ? (proc.stdout?.toString("utf8") ?? "") : "";
-  } catch {
-    return "";
-  }
-}
-
-export async function refreshState(
-  run: Run,
-  o: { starting?: StateSnapshot["running"][number]; next?: string; lastCheck?: string } = {},
-): Promise<void> {
-  const notes = readNotes(run);
-  if (o.next !== undefined) notes.next = o.next;
-  if (o.lastCheck !== undefined) notes.lastCheck = o.lastCheck;
-  writeFileSync(notesFile(run), `${JSON.stringify(notes)}\n`);
-
-  const live = readLive(run.dir);
-  const running: StateSnapshot["running"] = live.map((m) => ({
-    name: m.name,
-    rung: m.rung,
-    thread: m.thread,
-    brief: `roles/${m.name}${m.thread ? ".fix" : ""}.md`,
-    since: m.startedAt.slice(11, 16),
-  }));
-  if (o.starting && !running.some((r) => r.name === o.starting?.name)) running.push(o.starting);
-
-  const head = git(run.meta.repo, "rev-parse", "--short", "HEAD").trim() || "none";
-  const porcelain = git(run.meta.repo, "status", "--porcelain", "--untracked-files=all");
-  const dirty = porcelain
-    .split("\n")
-    .filter((l) => l.trim())
-    .map((l) => l.slice(3))
-    .map((path) => ({ path, owner: live.find((m) => m.ownedFiles.includes(path))?.name ?? null }));
-
-  const waiting = running.map((r) => r.name);
-  writeState(run.dir, {
-    head,
-    dirty,
-    running,
-    lastCheck: notes.lastCheck,
-    next: waiting.length ? `wait for ${waiting.join(", ")}; then ${notes.next}` : notes.next,
-  });
-}
-
-export function backendOf(c: Catalog, rung: RungId): Backend {
-  const { model } = splitRung(rung);
-  // ponytail: an opencode model the catalog does not list is recognised by its provider/ prefix
-  return modelOf(c, model)?.backend ?? (model.includes("/") ? "opencode" : "codex");
-}