catherd-cli 1.0.0 → 1.1.1

package/src/adapters/backend.ts

@@ -2,7 +2,7 @@ import type { ErrorCode } from "../domain/errors.ts";
 import type { ADAPTER_IDS, Rung } from "../domain/ids.ts";
 import type { BillingMode } from "../domain/cost.ts";
 import type { Access, ExitInfo, RunStatus, Tokens } from "../domain/record.ts";
-
+import type { CliResult } from "./cli.ts";
 type AdapterId = (typeof ADAPTER_IDS)[number];
 
 export interface Probe {
@@ -18,6 +18,14 @@ export interface Probe {
   problems: { code: ErrorCode; message: string; fix: string }[];
 }
 
+/** A worker's shell for doctor's probes: `run` is `sh -c <script> _ <args…>`; `close` removes its scratch dir. */
+export interface AccessShell {
+  /** how it runs, for the doctor rows: "codex sandbox", "an unsandboxed shell" */
+  how: string;
+  run(script: string, args: string[]): Promise<CliResult | null>;
+  close(): void;
+}
+
 export interface DiscoveredModel {
   id: string;
   efforts: string[];
@@ -28,6 +36,8 @@ export interface DiscoveredModel {
 export interface RunRequest {
   rung: Rung;
   access: Access;
+  /** spec §5: a workspace-write role's network and loopback grants; false only when the profile says `network: false` */
+  network?: boolean;
   thread: string | null;
   isolated: boolean;
   repo: string;
@@ -56,6 +66,11 @@ export interface EventDelta {
   requestInput?: number;
   costUsd?: number;
   lastEvent?: string;
+  /**
+   * what the worker is doing, in words, when the line says (spec §3.7 `peek`): a command (`$ bun test`), a file
+   * edit (`edit src/a.ts`) or a message line
+   */
+  activity?: string;
   failure?: string;
   limit?: boolean;
   tooOld?: boolean;
@@ -120,10 +135,10 @@ export interface BackendAdapter {
   /** Spec §4.5: this backend's own stand-in for a rung on a usage limit, when the profile names none. */
   failoverFor?(rung: Rung, repo?: string): Rung | null;
   /**
-   * Spec §10.3: whether a workspace-write worker of this backend can write `dir` (the heavy-lock dir, so
-   * `catherd lock` works inside it); null when it cannot be tested on this machine.
+   * Spec §5 and §12: a shell that runs a command the way this backend's workspace-write worker runs one,
+   * with the grants the worker gets, for doctor's access probes; a string says why it cannot be tested here.
    */
-  canWrite?(dir: string): Promise<{ ok: boolean; fix?: string } | null>;
+  accessShell?(o: { network: boolean }): Promise<AccessShell | string>;
   /** Spec §10.3: why this backend's isolation is weak; doctor warns when a profile uses it. */
   isolationNote?: string;
   graceAfterFinalMs: number | null;

package/src/adapters/claude-code/index.ts

@@ -2,6 +2,7 @@ import { CatherdError } from "../../domain/errors.ts";
 import type { Rung } from "../../domain/ids.ts";
 import type { Access, RunStatus } from "../../domain/record.ts";
 import {
+  type AccessShell,
   type BackendAdapter,
   compareVersions,
   type EventDelta,
@@ -12,6 +13,10 @@ import {
   type RunRequest,
   type SpawnPlan,
 } from "../backend.ts";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { claudeHome } from "../../infra/paths.ts";
+import { dockerSocket, scratchShell, writableRoots } from "../access.ts";
 import { jsonOf, runCli } from "../cli.ts";
 import {
   CLAUDE_LIMIT,
@@ -60,6 +65,75 @@ export const CLAUDE_ACCESS: Record<Access, string[]> = {
   full: ["--permission-mode", "bypassPermissions"],
 };
 
+/**
+ * Spec §5 for headless Claude Code. Its Bash runs unsandboxed unless the user turned Claude Code's own
+ * sandbox on (`sandbox.enabled`); then these settings, merged over the user's, add the lock and temp dirs,
+ * loopback binds, the Docker socket and `docker` itself (which cannot run inside that sandbox). Outbound
+ * domains stay the user's `sandbox.network.allowedDomains`: doctor's `access:claude-code` row says when
+ * the registry is not among them. `network: false` drops the network grants and the web tools (and with
+ * them Docker: the socket and `docker *` are network grants) and sets `allowLocalBinding: false`, so the
+ * user's own `true` does not carry over (their allowedDomains and other array grants merge in and stay;
+ * doctor says `network: false` is not enforced by claude-code's shell). With the user's sandbox on, `enabled: true`
+ * goes in too, so a merge that replaces the whole `sandbox` object cannot turn it off.
+ */
+export function claudeAccessArgs(access: Access, network = true, repo?: string): string[] {
+  const base = CLAUDE_ACCESS[access];
+  if (access !== "workspace-write") return base;
+  const sock = dockerSocket();
+  const sandbox = {
+    ...(claudeSandboxOn(repo) ? { enabled: true } : {}),
+    filesystem: { allowWrite: writableRoots() },
+    ...(network
+      ? {
+          network: { allowLocalBinding: true, ...(sock ? { allowUnixSockets: [sock] } : {}) },
+          excludedCommands: ["docker *"],
+        }
+      : // a boolean overrides the user's own `allowLocalBinding: true`; their array grants cannot be revoked here
+        { network: { allowLocalBinding: false } }),
+  };
+  const args = [...base, "--settings", JSON.stringify({ sandbox })];
+  if (!network) {
+    const i = args.indexOf("--disallowedTools") + 1;
+    args[i] = [args[i], "WebFetch", "WebSearch"].join(",");
+  }
+  return args;
+}
+
+/** `sandbox.enabled` in one settings file, when it says true or false; undefined when absent or unreadable. */
+function sandboxEnabledIn(file: string): boolean | undefined {
+  try {
+    const on = JSON.parse(readFileSync(file, "utf8"))?.sandbox?.enabled;
+    return typeof on === "boolean" ? on : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether Claude Code's Bash sandbox is on for a worker in `repo` (`sandbox.enabled`): the most specific
+ * settings file that says wins, as Claude Code layers them: the user's settings.json, then the project's
+ * .claude/settings.json and .claude/settings.local.json (Claude Code has no user-level settings.local.json).
+ */
+export function claudeSandboxOn(repo: string = process.cwd()): boolean {
+  const files = [
+    join(claudeHome(), "settings.json"),
+    join(repo, ".claude", "settings.json"),
+    join(repo, ".claude", "settings.local.json"),
+  ];
+  return files.map(sandboxEnabledIn).findLast((on) => on !== undefined) ?? false;
+}
+
+/**
+ * Spec §5: with Claude Code's own sandbox off (its default) a headless worker's Bash is an unsandboxed
+ * shell, which doctor probes as is. With it on, only a model turn runs inside it, so doctor says what to
+ * check instead of spending one.
+ */
+async function accessShell(): Promise<AccessShell | string> {
+  if (claudeSandboxOn())
+    return "Claude Code's own sandbox is on (sandbox.enabled): catherd passes the lock, temp, loopback and Docker grants in --settings; outbound HTTPS reaches only sandbox.network.allowedDomains, so add registry.npmjs.org and the hosts your checks need there";
+  return scratchShell("an unsandboxed shell (Claude Code's sandbox is off)", []);
+}
+
 function plan(r: RunRequest): SpawnPlan {
   if (r.thread !== null && !THREAD.test(r.thread))
     throw new CatherdError("E_ADMIT_THREAD", `"${r.thread}" is not a Claude Code session id`, {
@@ -80,7 +154,7 @@ function plan(r: RunRequest): SpawnPlan {
       ...(r.thread === null ? ["--session-id", crypto.randomUUID()] : ["--resume", r.thread]),
       "--permission-prompts",
       "none",
-      ...CLAUDE_ACCESS[r.access],
+      ...claudeAccessArgs(r.access, r.network, r.repo),
       // --bare would also drop OAuth, so a Claude plan could not log in; --safe-mode keeps auth
       ...(r.isolated ? ["--safe-mode"] : []),
     ],
@@ -147,10 +221,29 @@ function finalize(run: FinishedRun): Outcome {
   };
 }
 
+const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+/** Spec §3.7: the main thread's last tool call (a command, a file edit, another tool) or its text. */
+function claudeActivity(e: Record<string, any>): string | undefined {
+  if (e.type !== "assistant" || e.parent_tool_use_id) return undefined;
+  const c = (e.message?.content ?? []).at(-1);
+  if (c?.type === "tool_use") {
+    const input = c.input ?? {};
+    if (typeof input.command === "string") return `$ ${input.command}`;
+    if (typeof input.file_path === "string")
+      return `${EDIT_TOOLS.has(c.name) ? "edit" : String(c.name)} ${input.file_path}`;
+    return String(c.name ?? "tool");
+  }
+  if (c?.type === "text" && typeof c.text === "string") return c.text;
+  return undefined;
+}
+
 function parse(line: string): EventDelta {
   const e = parseClaudeLine(line);
   if (!e) return {};
   const d: EventDelta = { lastEvent: eventName(e) };
+  const activity = claudeActivity(e);
+  if (activity) d.activity = activity;
   if (typeof e.session_id === "string" && e.session_id) d.thread = e.session_id;
   if (e.type === "system" && e.subtype === "api_retry") d.retrying = true;
   if (e.type === "rate_limit_event" && e.rate_limit_info?.status === "rejected") d.limit = true;
@@ -218,6 +311,7 @@ export const claudeCodeAdapter: BackendAdapter = {
   enforcement: { "read-only": "advisory", "workspace-write": "advisory", full: "advisory" },
   errors: { limit: CLAUDE_LIMIT, tooOld: CLAUDE_TOO_OLD },
   resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
+  accessShell,
   // the `result` event is the last thing claude prints; a CLI still running 30 s later is stuck
   graceAfterFinalMs: 30_000,
 };

package/src/adapters/codex/index.ts

@@ -1,9 +1,9 @@
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CatherdError } from "../../domain/errors.ts";
 import type { Access, RunStatus } from "../../domain/record.ts";
 import {
+  type AccessShell,
   type BackendAdapter,
   compareVersions,
   type DiscoveredModel,
@@ -15,6 +15,7 @@ import {
   type SpawnPlan,
 } from "../backend.ts";
 import { type CliResult, runCli } from "../cli.ts";
+import { scratchShell, writableRoots } from "../access.ts";
 import { CODEX_LIMIT, CODEX_TOO_OLD, foldCodexEvents, parseCodexLine } from "./events.ts";
 
 /** The item types that are a tool call running, as the idle watchdog counts them. */
@@ -30,6 +31,43 @@ const SANDBOX: Record<Access, string> = {
   full: "danger-full-access",
 };
 
+/**
+ * The `writable_roots` the user's Codex config lists under its top-level `[sandbox_workspace_write]`
+ * (`$CODEX_HOME/config.toml`). A `-c` override replaces that array, so catherd passes the union. A
+ * `--profile`'s or a managed requirements file's roots are not read. Unreadable or absent: none.
+ */
+export function userWritableRoots(): string[] {
+  const file = join(userCodexHome(), "config.toml");
+  if (!existsSync(file)) return [];
+  try {
+    const roots = (Bun.TOML.parse(readFileSync(file, "utf8")) as Record<string, unknown>)
+      .sandbox_workspace_write as { writable_roots?: unknown } | undefined;
+    const list = roots?.writable_roots;
+    return Array.isArray(list) ? list.filter((r): r is string => typeof r === "string" && r !== "") : [];
+  } catch {
+    // a config Codex cannot parse either: Codex reports it on the run itself
+    return [];
+  }
+}
+
+/**
+ * Spec §5: a workspace-write worker also writes the lock and temp dirs, and (unless the role says
+ * `network: false`) reaches the network and binds loopback. `network_access` is always set, to false for
+ * `network: false`, since leaving it out would keep a `network_access = true` from the user's config.toml.
+ * The same `-c` overrides go to `codex sandbox` in doctor's probes, so doctor tests exactly what a worker gets. `-c …writable_roots=` replaces the
+ * user's own roots, so theirs go in too; an isolated run ignores the user's config, so it has none.
+ */
+export function codexGrants(access: Access, network = true, isolated = false): string[] {
+  if (access !== "workspace-write") return [];
+  const roots = [...new Set([...(isolated ? [] : userWritableRoots()), ...writableRoots()])];
+  return [
+    "-c",
+    `sandbox_workspace_write.network_access=${network}`,
+    "-c",
+    `sandbox_workspace_write.writable_roots=${JSON.stringify(roots)}`,
+  ];
+}
+
 /** How long a `codex` query (version, login, models) may take before it counts as failed. */
 export const codexShell = { timeoutMs: 15_000 };
 
@@ -51,6 +89,7 @@ function plan(r: RunRequest): SpawnPlan {
     "--json",
     "-o",
     r.replyPath,
+    ...codexGrants(r.access, r.network, r.isolated),
   ];
   const sandbox = SANDBOX[r.access];
   const args =
@@ -169,29 +208,44 @@ async function listModels(): Promise<DiscoveredModel[]> {
 }
 
 /**
- * Spec §10.3: runs a write into `dir` under `codex sandbox <os> --full-auto`, the workspace-write sandbox,
- * from a scratch folder. null when this machine has no Codex sandbox to test with (the control fails).
+ * Spec §12: `codex sandbox [-c …] -- <cmd>` in the workspace-write sandbox with the grants a worker gets
+ * (codexGrants), else the old `codex sandbox <os> --full-auto` form. Each form is tried with `true` first;
+ * a string says why neither runs here.
  */
-async function canWrite(dir: string): Promise<{ ok: boolean; fix?: string } | null> {
+async function accessShell(o: { network: boolean }): Promise<AccessShell | string> {
+  const grants = codexGrants("workspace-write", o.network);
   const os = process.platform === "darwin" ? "macos" : process.platform === "linux" ? "linux" : null;
-  if (!os) return null;
-  const cwd = mkdtempSync(join(tmpdir(), "catherd-sandbox-"));
-  try {
-    const run = (...script: string[]) => sh(["sandbox", os, "--full-auto", "--", "sh", "-c", ...script], cwd);
-    if (!(await run("true"))?.ok) return null;
-    const probe = join(dir, `.doctor-${process.pid}`);
-    // the path goes in as $1, never into the script text
-    const r = await run('touch "$1" && rm -f "$1"', "_", probe);
-    if (!r) return null;
-    return r.ok
-      ? { ok: true }
-      : {
-          ok: false,
-          fix: `add "${dir}" to writable_roots under [sandbox_workspace_write] in ~/.codex/config.toml`,
-        };
-  } finally {
-    rmSync(cwd, { recursive: true, force: true });
+  const forms: [string, string[]][] = [
+    ["codex sandbox", ["codex", "sandbox", "-c", "sandbox_mode=workspace-write", ...grants, "--"]],
+    ...(os
+      ? [
+          [
+            `codex sandbox ${os} --full-auto (the old form)`,
+            ["codex", "sandbox", os, "--full-auto", ...grants, "--"],
+          ],
+        ]
+      : []),
+  ] as [string, string[]][];
+  for (const [how, prefix] of forms) {
+    const shell = scratchShell(how, prefix);
+    if ((await shell.run("true", []))?.ok) return shell;
+    shell.close();
   }
+  return "no codex sandbox to test with on this machine (codex sandbox did not run `true`)";
+}
+
+/** Spec §3.7: a command Codex runs, the files it changes, or its message. */
+function codexActivity(e: Record<string, any>): string | undefined {
+  const it = e.item;
+  if (!it || (e.type !== "item.started" && e.type !== "item.completed")) return undefined;
+  if (it.type === "command_execution" && typeof it.command === "string") return `$ ${it.command}`;
+  if (it.type === "file_change" && Array.isArray(it.changes))
+    return `edit ${it.changes
+      .map((c: { path?: unknown }) => c.path)
+      .filter((p: unknown) => typeof p === "string")
+      .join(", ")}`;
+  if (it.type === "agent_message" && typeof it.text === "string") return it.text;
+  return undefined;
 }
 
 export const codexAdapter: BackendAdapter = {
@@ -213,6 +267,7 @@ export const codexAdapter: BackendAdapter = {
       ...(id !== null && open !== null ? { item: { id, open } } : {}),
       ...(e.type === "turn.completed" ? { tokens: f.tokens } : {}),
       lastEvent: f.lastEvent ?? undefined,
+      ...(codexActivity(e) ? { activity: codexActivity(e) } : {}),
       ...(f.turnFailed ? { failure: f.failure ?? "turn failed" } : {}),
       ...(f.limit ? { limit: true } : {}),
       ...(f.tooOld ? { tooOld: true } : {}),
@@ -223,5 +278,5 @@ export const codexAdapter: BackendAdapter = {
   errors: { limit: CODEX_LIMIT, tooOld: CODEX_TOO_OLD },
   resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
   graceAfterFinalMs: null,
-  canWrite,
+  accessShell,
 };

package/src/adapters/opencode/index.ts

@@ -17,6 +17,7 @@ import {
   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";
@@ -181,10 +182,24 @@ function finalize(run: FinishedRun): Outcome {
   };
 }
 
+/** 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);
@@ -313,4 +328,6 @@ export const opencodeAdapter: BackendAdapter = {
   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/domain/errors.ts

@@ -17,6 +17,8 @@ export type ErrorCode =
   | "E_ADMIT_ID"
   | "E_ADMIT_THREAD"
   | "E_LANE_INVALID"
+  | "E_LAND_GATE"
+  | "E_CLIMB_DESIGN"
   | "E_JEV_KEY"
   | "E_JEV_NETWORK"
   | "E_JEV_RESPONSE"

package/src/domain/failover.ts

@@ -0,0 +1,119 @@
+import { billingKeyOf, type Catalog, DIMS, type Dim, rungInfo, scoresOf } from "./catalog.ts";
+import { type BillingMode, compareCost, type Cost, costOf, DEFAULT_BILLING } from "./cost.ts";
+import { type Rung, tryParseRung } from "./ids.ts";
+import { DIFFICULTIES, KINDS } from "./lane.ts";
+
+/**
+ * Spec §7.1 and §4.5: a stand-in on the same quota would be out of quota too. The billing key names the
+ * quota, except that the native `claude` path and headless `claude-code` both draw on the Claude plan.
+ */
+export const quotaOf = (r: Rung): string => (billingKeyOf(r) === "claude" ? "claude-code" : billingKeyOf(r));
+
+/** Whether a rung draws on the Claude plan (native `claude:` or headless `claude-code:`). */
+export function claudeBilled(rung: string): boolean {
+  const r = tryParseRung(rung);
+  return r !== null && quotaOf(r) === "claude-code";
+}
+
+/** A rung's scores by dim, its own or borrowed through a treat-like; null when unscored or not a rung. */
+export function valuesOf(c: Catalog, rung: string): Partial<Record<Dim, number>> | null {
+  try {
+    return scoresOf(c, rungInfo(c, rung).canonical)?.values ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** The dims used by the routing bars (kind × difficulty) the rung clears: what makes it fit its lanes. */
+export function barDims(c: Catalog, rung: string): Dim[] {
+  const v = valuesOf(c, rung);
+  if (!v) return [];
+  const used = new Set<Dim>();
+  for (const kind of KINDS)
+    for (const d of DIFFICULTIES) {
+      const bar = Object.entries(c.bars[kind][d]).filter(([, min]) => min !== undefined) as [Dim, number][];
+      if (bar.every(([dim, min]) => (v[dim] ?? Number.NEGATIVE_INFINITY) >= min))
+        for (const [dim] of bar) used.add(dim);
+    }
+  return DIMS.filter((d) => used.has(d));
+}
+
+/**
+ * Spec 1.1 §11: the dims, among those the rung's bars use, on which `standIn` scores below `rung` (a
+ * missing score counts as below). Empty means the stand-in clears every bar the rung clears, at least as
+ * well: no downgrade.
+ */
+export function downgradeDims(c: Catalog, rung: string, standIn: string): Dim[] {
+  const a = valuesOf(c, rung);
+  if (!a) return [];
+  const b = valuesOf(c, standIn) ?? {};
+  return barDims(c, rung).filter((d) => (b[d] ?? Number.NEGATIVE_INFINITY) < (a[d] as number));
+}
+
+/**
+ * Spec 1.1 §11 "the ladder goes down": the dims both rungs are scored on where `upper` (the later rung)
+ * scores below `lower`, when it scores above it on none of them. Empty when it does not go down.
+ */
+export function ladderDropDims(c: Catalog, lower: string, upper: string): Dim[] {
+  const a = valuesOf(c, lower);
+  const b = valuesOf(c, upper);
+  if (!a || !b) return [];
+  const shared = DIMS.filter((d) => a[d] !== undefined && b[d] !== undefined);
+  if (shared.some((d) => (b[d] as number) > (a[d] as number))) return [];
+  return shared.filter((d) => (b[d] as number) < (a[d] as number));
+}
+
+const costFor = (c: Catalog, billing: Partial<Record<string, BillingMode>>, rung: string): Cost => {
+  const info = rungInfo(c, rung);
+  return costOf(info.family, info.parsed.effort, billing[info.key] ?? DEFAULT_BILLING[info.key]);
+};
+
+/**
+ * Spec 1.1 §11: the rungs of `pool` that can stand in for `rung`, best first. A stand-in is on another
+ * quota, scored, paid from a plan or subscription under `billing` (a metered one spends money nobody chose
+ * to), startable by `dispatch` (not a native `claude:` subagent), and no downgrade on the rung's bar dims.
+ * Claude-billed stand-ins rank last, then the cheapest first.
+ */
+export function rankStandIns(
+  c: Catalog,
+  billing: Partial<Record<string, BillingMode>>,
+  rung: string,
+  pool: readonly string[],
+): string[] {
+  const from = tryParseRung(rung);
+  if (!from) return [];
+  const fits = [...new Set(pool)].filter((x) => {
+    const r = tryParseRung(x);
+    if (!r || r.backend === "claude" || quotaOf(r) === quotaOf(from) || !valuesOf(c, x)) return false;
+    if (costFor(c, billing, x).tier === 1) return false;
+    return downgradeDims(c, rung, x).length === 0;
+  });
+  return fits.sort(
+    (a, b) =>
+      Number(claudeBilled(a)) - Number(claudeBilled(b)) ||
+      compareCost(costFor(c, billing, a), costFor(c, billing, b)) ||
+      a.localeCompare(b),
+  );
+}
+
+/** How a family's `on` key or a model id's prefix maps to the backend that runs it. */
+const BACKEND_OF_KEY: Record<string, string> = { "opencode-go": "opencode" };
+
+/**
+ * Every rung the catalog knows how to name: each shipped family's model on each backend at each effort,
+ * each listed model at each effort, and each treat-like whose model is an opencode id (`opencode-go/…`,
+ * `opencode/…`), such as the shipped Kimi K3 stand-in. Sorted, without duplicates.
+ */
+export function catalogRungs(c: Catalog): string[] {
+  const out = new Set<string>();
+  for (const f of c.families)
+    for (const [key, m] of Object.entries(f.on)) {
+      if (!m) continue;
+      for (const e of m.efforts) out.add(`${BACKEND_OF_KEY[key] ?? key}:${m.id}#${e}`);
+    }
+  for (const [backend, l] of Object.entries(c.listed))
+    for (const m of l.models) for (const e of m.efforts) out.add(`${backend}:${m.id}#${e}`);
+  for (const canonical of Object.keys(c.treatLike))
+    if (/^opencode(-go)?\//.test(canonical)) out.add(`opencode:${canonical}`);
+  return [...out].sort();
+}

package/src/domain/lane.ts

@@ -60,6 +60,29 @@ export function parseLaneHeader(text: string): LaneHeader {
   };
 }
 
+/** The fix every lane-header refusal carries: the values the catalog knows. */
+export const LANE_HEADER_FIX = `write the lane's header lines as Kind: ${KINDS.join("|")} and Difficulty: ${DIFFICULTIES.join("|")}`;
+
+/**
+ * Spec 1.1 §6: a lane's `Kind:` and `Difficulty:` must be values the catalog knows, so routing never falls
+ * back on a typo. `where` names the lane file in the message. Throws E_LANE_INVALID; returns the header.
+ */
+export function assertLaneHeader(text: string, where: string): LaneHeader {
+  const h = parseLaneHeader(text);
+  const problems: string[] = [];
+  const check = (label: string, value: string | null, ok: boolean) => {
+    if (ok) return;
+    problems.push(
+      value === null ? `no ${label}: line` : `${label} "${unquote(value)}" is not one the catalog knows`,
+    );
+  };
+  check("Kind", field(text, "kind"), h.kind !== null);
+  check("Difficulty", field(text, "difficulty"), h.difficulty !== null);
+  if (problems.length)
+    throw new CatherdError("E_LANE_INVALID", `${where}: ${problems.join("; ")}`, { fix: LANE_HEADER_FIX });
+  return h;
+}
+
 const bare = (p: string) => p.replace(/\/+$/, "");
 const covers = (outer: string, inner: string) => inner === outer || inner.startsWith(`${outer}/`);
 

package/src/domain/notice.ts

@@ -0,0 +1,95 @@
+/**
+ * Spec §3.5: the message catherd pushes to the main thread when roles finish or need attention. Pure text; the
+ * notifier (services/notifier.ts) gathers the facts and infra/peer-inbox.ts sends the result.
+ */
+
+/** Spec §3.6: `later` waits for the receiver's turn to end, `next` drains at its next tool round. Never `now`. */
+export type NoticePriority = "later" | "next";
+
+/** One role's news: it finished (`record`), or an event while it runs (`stall`). */
+export interface Notice {
+  kind: "finished" | "stalled";
+  runId: string;
+  runTitle: string;
+  dispatchId: string;
+  name: string;
+  role: string;
+  /** the lane it worked, when it had one: the multi-role preview names it */
+  lane: string | null;
+  rung: string;
+  /** the record's status, or for a limit what failover did ("limit on X; failed over to Y"), or the event */
+  status: string;
+  /** the reply's STATUS word, null without a STATUS line */
+  replyStatus: string | null;
+  secs: number;
+  changedOwned: number;
+  /** the worker's reply (finished notices), capped when the message is written */
+  reply: string;
+  priority: NoticePriority;
+}
+
+/** The body of a reply a message carries at most (spec §3.5). */
+export const REPLY_CAP = 2_000;
+
+const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+
+/** The first line of one role's block: it must stand alone, since the Desktop preview shows only it. */
+export function noticeHeader(n: Notice): string {
+  const head = `catherd · ${n.runTitle} · ${n.name} ${n.role} · ${n.rung} · ${n.status}`;
+  if (n.kind === "stalled") return `${head} · running ${n.secs}s`;
+  return [
+    head,
+    n.replyStatus ? `STATUS: ${n.replyStatus}` : "no STATUS",
+    `${n.secs}s`,
+    plural(n.changedOwned, "owned file changed", "owned files changed"),
+  ].join(" · ");
+}
+
+/** The reply, at most `cap` characters, cut on a line boundary, saying where the rest is. */
+export function capNoticeReply(reply: string, cap = REPLY_CAP): string {
+  const text = reply.trimEnd();
+  if (text.length <= cap) return text;
+  const cut = text.slice(0, cap);
+  const at = cut.lastIndexOf("\n");
+  return `${at > 0 ? cut.slice(0, at) : cut}\n…(cut; result(run, name) has the rest)`;
+}
+
+/**
+ * The envelope's own tags are neutralised in a body, in any case (a parser may not care), so a reply can never
+ * close the envelope early.
+ */
+const neutral = (s: string) => s.replace(/(cross)-(session)-(message)/gi, "$1 $2 $3");
+
+function block(n: Notice): string {
+  const call = `run: "${n.runId}", name: "${n.name}"`;
+  if (n.kind === "stalled") return `${noticeHeader(n)}\nPeek: peek(${call})`;
+  const reply = capNoticeReply(n.reply);
+  return [noticeHeader(n), ...(reply ? [reply] : []), `Record: result(${call})`].join("\n");
+}
+
+/** The preview line of a message that carries several roles: `catherd · <title> · 3 roles finished: …`. */
+function previewOf(ns: Notice[]): string {
+  const titles = [...new Set(ns.map((n) => n.runTitle))];
+  const where = titles.length === 1 ? titles[0] : plural(titles.length, "run", "runs");
+  const what = ns.every((n) => n.kind === "finished")
+    ? `${ns.length} roles finished`
+    : `${plural(ns.length, "role", "roles")} to look at`;
+  const each = ns.map(
+    (n) => `${n.lane ?? n.name} ${n.kind === "stalled" ? "stalled" : n.status.split(";")[0]}`,
+  );
+  return `catherd · ${where} · ${what}: ${each.join(", ")}`;
+}
+
+/** The message body for one or more notices: one block per role, a preview line first when there are several. */
+export function formatNotices(ns: Notice[]): string {
+  if (ns.length === 1) return neutral(block(ns[0] as Notice));
+  return neutral([previewOf(ns), ...ns.map(block)].join("\n\n"));
+}
+
+/** The message's priority: the most urgent of its notices. */
+export const priorityOf = (ns: Notice[]): NoticePriority =>
+  ns.some((n) => n.priority === "next") ? "next" : "later";
+
+/** The envelope catherd sends: from-name only, no `from` (the MCP server has no reply address). */
+export const envelope = (body: string): string =>
+  `<cross-session-message from-name="catherd">\n${body}\n</cross-session-message>`;