catherd-cli 1.3.0 → 1.5.0

package/src/domain/profile.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "./host.ts";
 import { z } from "zod";
 import type { Budget } from "./budget.ts";
 import { BILLING_KEYS, type BillingKey } from "./catalog.ts";
@@ -44,6 +45,7 @@ const RoleDocSchema = z.looseObject({
   rungs: z.array(z.string()).optional(),
   defaultRung: z.string().optional(),
   network: z.boolean().optional(),
+  timeouts: z.looseObject({ idleMin: positive.optional(), wallMin: positive.optional() }).optional(),
 });
 
 export const ProfileDocSchema = z.looseObject({
@@ -116,8 +118,19 @@ export type RoleConfig = {
   defaultRung?: string;
   /** spec §5: false drops a workspace-write role's network, loopback and Docker grants; absent means granted */
   network?: false;
+  /** plan 23: this role's own idle and wall timeouts, over the profile's `timeouts` (a long gate, a slow model) */
+  timeouts?: { idleMin?: number; wallMin?: number };
 };
 
+/** The idle and wall timeouts a role runs under: its own `timeouts`, else the profile's. */
+export const roleTimeouts = (
+  profile: { timeouts: { idleMin: number; wallMin: number } },
+  role: { timeouts?: { idleMin?: number; wallMin?: number } } | undefined,
+): { idleMin: number; wallMin: number } => ({
+  idleMin: role?.timeouts?.idleMin ?? profile.timeouts.idleMin,
+  wallMin: role?.timeouts?.wallMin ?? profile.timeouts.wallMin,
+});
+
 /** A profile with every default filled in: what the run engine, the CLI and the agent files read. */
 export interface Profile {
   name: string;
@@ -229,7 +242,7 @@ export const PAIRED_FAILOVER: Record<string, string> = Object.fromEntries(
 /** The five billing keys spec §7.1 writes out; cursor and grok arrive with their backends. */
 const WRITTEN_BILLING: BillingKey[] = ["codex", "claude", "claude-code", "opencode-go", "opencode"];
 
-/** The full default profile document, every field written out: what `init` and `profile new` save. */
+/** Stored defaults for init/new; architect/verifier rungs resolve from the current host. */
 export function defaultProfileDoc(name = "default"): ProfileDoc {
   return {
     schema: PROFILE_SCHEMA,
@@ -237,7 +250,7 @@ export function defaultProfileDoc(name = "default"): ProfileDoc {
     objective: "cost",
     jev: { use: "auto" },
     billing: Object.fromEntries(WRITTEN_BILLING.map((k) => [k, DEFAULT_BILLING[k]])),
-    roles: structuredClone(BUILTIN_ROLES),
+    roles: hostDefaultsDoc({ schema: PROFILE_SCHEMA, roles: structuredClone(BUILTIN_ROLES) }).roles,
     harness: {
       codex: { isolated: false },
       "claude-code": { isolated: false },
@@ -252,12 +265,38 @@ export function defaultProfileDoc(name = "default"): ProfileDoc {
   };
 }
 
-/** Spec §7.1: every field a document leaves out takes its default; a missing role takes the built-in one. */
-export function resolveProfile(doc: ProfileDoc, name: string): Profile {
+/** Remove only the four architect/verifier execution choices, preserving other stored fields. */
+export function hostDefaultsDoc(doc: ProfileDoc): ProfileDoc {
+  const next = structuredClone(doc);
+  for (const role of ["architect", "verifier"] as const) {
+    const r = next.roles?.[role];
+    if (r) {
+      delete r.rungs;
+      delete r.defaultRung;
+    }
+  }
+  return next;
+}
+
+/** Resolve omitted role execution choices from the explicit orchestration host. */
+export function resolveProfile(doc: ProfileDoc, name: string, host: OrchestrationHost): Profile {
   const roles = {} as Record<Role, RoleConfig>;
   for (const role of ROLES) {
     const d = doc.roles?.[role];
     const b = BUILTIN_ROLES[role];
+    let omitted = b.rungs;
+    if ((role === "architect" || role === "verifier") && d?.rungs === undefined) {
+      if (host === "unknown" && (d?.enabled ?? b.enabled))
+        throw new CatherdError("E_CONFIG_INVALID", `roles.${role}.rungs needs an orchestration host`, {
+          fix: "pass --host codex or --host claude-code, or set explicit role rungs",
+        });
+      omitted =
+        host === "codex"
+          ? [`codex:gpt-6.1-sol#${role === "architect" ? "high" : "low"}`]
+          : host === "unknown"
+            ? []
+            : b.rungs;
+    }
     // a role that lists its own rungs never inherits the built-in default rung, which may not be among them
     const defaultRung = d?.defaultRung ?? (d?.rungs === undefined ? b.defaultRung : undefined);
     roles[role] = {
@@ -268,9 +307,17 @@ export function resolveProfile(doc: ProfileDoc, name: string): Profile {
           : known(ACCESS, d.access)
             ? d.access
             : STORED_FALLBACK.access,
-      rungs: [...(d?.rungs ?? b.rungs)],
+      rungs: [...(d?.rungs ?? omitted)],
       ...(defaultRung ? { defaultRung } : {}),
       ...(d?.network === false ? { network: false as const } : {}),
+      ...(d?.timeouts?.idleMin !== undefined || d?.timeouts?.wallMin !== undefined
+        ? {
+            timeouts: {
+              ...(d.timeouts.idleMin !== undefined ? { idleMin: d.timeouts.idleMin } : {}),
+              ...(d.timeouts.wallMin !== undefined ? { wallMin: d.timeouts.wallMin } : {}),
+            },
+          }
+        : {}),
     };
   }
   const harness: Profile["harness"] = {};
@@ -317,6 +364,10 @@ const RolePatchSchema = z
     rungs: z.array(RungSchema),
     defaultRung: RungSchema.nullable(),
     network: z.boolean().nullable(),
+    timeouts: z
+      .strictObject({ idleMin: positive.nullable(), wallMin: positive.nullable() })
+      .partial()
+      .nullable(),
   })
   .partial();
 

package/src/domain/record.ts

@@ -6,7 +6,8 @@ export type Access = (typeof ACCESS)[number];
 const RUN_STATUSES = ["ok", "failed", "limit", "cli-too-old", "timeout", "cancelled"] as const;
 export type RunStatus = (typeof RUN_STATUSES)[number];
 
-const REPLY_STATUSES = ["complete", "partial", "blocked", "refused"] as const;
+/** plan 23: `flaky`, a worker's word for a check that failed, then passed when run alone */
+const REPLY_STATUSES = ["complete", "partial", "blocked", "refused", "flaky"] as const;
 export type ReplyStatus = (typeof REPLY_STATUSES)[number];
 
 export interface Tokens {
@@ -27,6 +28,8 @@ export const EXIT_REASONS = [
   "wall-timeout",
   "cancelled",
   "lost",
+  /** plan 23: the provider kept failing (retries with no progress); failover treats it as a usage limit */
+  "provider-unavailable",
 ] as const;
 export type ExitReason = (typeof EXIT_REASONS)[number];
 export interface ExitInfo {
@@ -65,6 +68,8 @@ export const RunRecordSchema = z.looseObject({
   gitUnavailable: z.boolean().optional(),
   replyStatus: z.enum(REPLY_STATUSES).nullable(),
   replyWhy: z.string().nullable(),
+  /** plan 23: the reply's ENV: line, when the environment stopped the role; absent otherwise */
+  environment: z.string().optional(),
   threadHeavy: z.boolean(),
   access: z.enum(ACCESS),
   isolated: z.boolean(),
@@ -75,10 +80,20 @@ export const RunRecordSchema = z.looseObject({
   replyPath: z.string(),
   /** the Claude Code session that dispatched it, copied from admit.json (spec §3.3); absent before 1.1 */
   sessionId: z.string().optional(),
+  host: z.enum(["claude-code", "codex"]).optional(),
 });
 export type RunRecord = z.infer<typeof RunRecordSchema>;
 
-const STATUS_LINE = /^STATUS:\s*(complete|partial|blocked|refused)\s*(?:—|–|-)\s*(.*)$/;
+const STATUS_LINE = /^STATUS:\s*(complete|partial|blocked|refused|flaky)\s*(?:—|–|-)\s*(.*)$/;
+
+/**
+ * Plan 23: what stopped the role, when the environment did: an `ENV: <what>` line of its reply (a VPN, no
+ * Docker, a dead registry); null without one.
+ */
+export function parseReplyEnvironment(reply: string): string | null {
+  const m = /^[ \t]*ENV:[ \t]*(\S.*?)[ \t]*$/m.exec(reply);
+  return m ? (m[1] as string) : null;
+}
 
 /** The role's claim about its own work: the reply's last line, `STATUS: <s> — <why>`. */
 export function parseReplyStatus(reply: string): { status: ReplyStatus | null; why: string | null } {

package/src/domain/reply.ts

@@ -0,0 +1,29 @@
+import { parseReplyStatus } from "./record.ts";
+
+/**
+ * Plan 22: a final reply never overwrites the report. `finals` are the messages that ended each of the run's
+ * turns, in order (a background command's notification can start another turn after the report); `last` is the
+ * reply the CLI kept, the last of them. With more than one, the reply is the longest STATUS-bearing message, the
+ * later ones after it under `later:`, and the report's STATUS line last, so the record's STATUS is the report's.
+ * Otherwise `last` is the reply, unchanged.
+ */
+export function composeReply(finals: string[], last: string): string {
+  if (finals.length < 2) return last;
+  let report = -1;
+  for (const [i, f] of finals.entries())
+    if (
+      parseReplyStatus(f).status !== null &&
+      (report < 0 || f.trim().length >= finals[report]!.trim().length)
+    )
+      report = i;
+  if (report < 0 || report === finals.length - 1) return last;
+  const lines = finals[report]!.trimEnd().split("\n");
+  const status = lines.pop() as string;
+  const later = finals
+    .slice(report + 1)
+    .map((f) => f.trim())
+    .filter(Boolean);
+  if (!later.length) return last;
+  const body = lines.join("\n").trimEnd();
+  return [...(body ? [body, ""] : []), "later:", later.join("\n\n"), "", status.trim(), ""].join("\n");
+}

package/src/domain/role-prompts.ts

@@ -1,19 +1,36 @@
 import type { Access } from "./record.ts";
+import { VERIFIER_GATE_RULES } from "./gate-brief.ts";
+import { COORDINATOR_TOOLS } from "./role-scope.ts";
 import type { Role } from "./roles.ts";
 
 // The role prompts of the native Claude subagents, ported from 0.x (spec D9). Headless backends get the
 // same text from the orchestrator's briefs; only native agents carry it in their agent file.
 
-const RUN_FILES =
-  "The run folder is outside the project. Read and write it only through the catherd MCP tools read_run_file and write_run_file (in the tool list as mcp__plugin_catherd_catherd__read_run_file and mcp__plugin_catherd_catherd__write_run_file), with the run id the orchestrator gave you. Paths are relative to the run folder.";
+/**
+ * How a role reaches its run folder, naming only the tools that role gets (spec 1.5 plan 21, #42 finding 5): every
+ * role reads, the architect and the researcher also write. The CLI forms are the fallback when no tool is listed.
+ */
+const runFiles = (writes: boolean): string =>
+  writes
+    ? "The run folder is outside the project. Read and write it only through catherd's read_run_file and write_run_file, with the run id the orchestrator gave you (native Claude subagents: mcp__plugin_catherd_catherd__<name>; headless Codex and Claude Code roles: mcp__catherd_role__<name>). When neither is listed, run catherd run-file read <run> <path>, and catherd run-file write <run> <path> with the content on stdin. Paths are relative to the run folder."
+    : "The run folder is outside the project. Read it only through catherd's read_run_file, with the run id the orchestrator gave you (native Claude subagents: mcp__plugin_catherd_catherd__read_run_file; headless Codex and Claude Code roles: mcp__catherd_role__read_run_file). When neither is listed, run catherd run-file read <run> <path>. Paths are relative to the run folder.";
 
 const REPLY =
   "Do not commit. Reply in at most 15 lines: results, file:line, and evidence as a log path, not the log. The last line of your reply is: STATUS: complete|partial|blocked|refused — <one line why>";
 
+/**
+ * The worker's reply contract. Plan 22, resume hygiene: a worker's thread may be resumed for its fix round, and a
+ * command its last turn left running in the background ends the resumed CLI (exit 143). Plan 23: acceptance that
+ * builds from HEAD is the verifier's, since a worker does not commit; an environment that stopped it goes on an ENV:
+ * line (climb refuses it); a check that failed, then passed alone, is STATUS: flaky with that evidence.
+ */
+const WORKER_REPLY =
+  "Before you reply, leave nothing running: stop every server, watcher or command you started in the background. Do not commit. Acceptance items that build from HEAD (git archive, a commit's image) belong to the verifier: do not run them, and never commit to get them to run. Reply in at most 15 lines: results, file:line, and evidence as a log path, not the log. When the environment stopped you (no Docker, a VPN, a dead registry), add a line ENV: <what>. The last line of your reply is: STATUS: complete|partial|blocked|refused|flaky — <one line why>; flaky means a check failed, then passed when run alone: name it, and how often each.";
+
 const architect = [
   "You are the architect of a catherd run. The orchestrator gave you the goal, the acceptance lines, the run id, and usually a dossier: a researcher's map of the code this work touches. Workers are other models that run in the project directory with no memory of this conversation. They will write every line of code from your plan.",
   "",
-  `Start from the dossier. Open a project file yourself only to settle a decision the dossier leaves open, and read each file once. Bash is for inspection only. Change nothing in the project. ${RUN_FILES}`,
+  `Start from the dossier. Open a project file yourself only to settle a decision the dossier leaves open, and read each file once. Bash is for inspection only. Change nothing in the project. ${runFiles(true)}`,
   "",
   "When the acceptance lines include plan: <path>[, <path>…], the user already has a plan and there is no dossier. Translate it, do not design: each plan task becomes lanes, each merge request or phase a milestone with its full check. Copy the plan's decisions into plan.md and the lane files, and decide only what the plan leaves undecided.",
   "",
@@ -24,7 +41,7 @@ const architect = [
   "3. Lanes inside each milestone, M1.L1…: each lane gives",
   "   - the files it owns (two lanes of one milestone never share a file);",
   "   - what changes, stated as behavior plus the exact signatures and data shapes it introduces;",
-  "   - its fast check: the command a worker reruns while it works, seconds to a minute or two: its targeted tests plus the linter, and the type check when the project has one, scoped to the packages the lane owns.",
+  "   - its fast check: the command a worker reruns while it works, seconds to a minute or two: its targeted tests plus the linter of every package the lane touches (each package's own: golangci-lint for a Go module, its lint script for a JS one), and the type check when the project has one, scoped to those packages.",
   "",
   "   Every lane of a milestone runs at the same time, so split for width: more small lanes beat one long one.",
   "4. Speed: if the full check takes more than about five minutes, name why and make speeding it up (parallel tests, one shared fixture, fewer real-time waits) a lane of the first milestone.",
@@ -41,6 +58,8 @@ const architect = [
   "",
   "catherd reads the Owns: line to keep two running lanes off the same file, and to tell a refusal (owned files unchanged) from work. It reads Kind: and Difficulty: to pick the lane's model when its router is unsure.",
   "",
+  "Two optional lines follow the five when they apply: `After: Mx.Ly, …` when the lane compiles against another lane's changes (catherd dispatches it only once those finish), and `Allow: path[:line], …` under a fast check that greps for absence, naming the hits that are allowed exceptions. Write such greps with word boundaries.",
+  "",
   "Signatures, data shapes and test case names are yours. Function bodies are the worker's. A plan that contains the implementation turns the worker into a typist and spends the most expensive model on typing.",
   "",
   "Prefer the smallest design that meets the acceptance lines: no abstraction with one implementation, no config for a value that never changes, no comments restating code.",
@@ -54,17 +73,21 @@ const verifier = [
   "You verify work you did not write. You get the acceptance lines, the check command and how to run the thing. You do not get the author's account of it, and you should not look for one.",
   "",
   "1. Run the check command once. Report its exit code and the failing lines. When the check has several gate items (suites, lint, builds, a boot check):",
-  "   - Before each item, call the catherd MCP tool gate_check (mcp__plugin_catherd_catherd__gate_check) with the run id, the milestone you verify (M1, as your brief names it), the item, its command and the repo paths it depends on. When it answers carried: true, do not run the item: report it as carried over from its commit. It also tells the orchestrator which step you are on.",
-  "   - After an item passes, call gate_pass (mcp__plugin_catherd_catherd__gate_pass) with the same item, command and paths, and the evidence.",
-  "   - Run independent items side by side, each heavy one wrapped in catherd lock, which queues them within the machine's slots.",
+  "   - First call gate_check with only the run id and the milestone: it lists the items already recorded for it (reuse their names; re-check the failed ones first, each command capped at 10 minutes) and the repo's gate environment (export it before the first item; a $NAME value is a secret in that env var).",
+  "   - Before each item, call the catherd MCP tool gate_check (mcp__catherd_role__gate_check for native headless Codex/Claude Code roles; mcp__plugin_catherd_catherd__gate_check for native Claude subagents) with the run id, the milestone you verify (M1, as your brief names it), the item, its command and the repo paths it depends on. When it answers carried: true, do not run the item: report it as carried over from its commit. It also tells the orchestrator which step you are on.",
+  "   - After an item passes, call gate_pass (mcp__catherd_role__gate_pass, or mcp__plugin_catherd_catherd__gate_pass for native Claude subagents) with the same item, command and paths, and the evidence.",
+  "   - When neither tool is listed, run the same from your shell: catherd gate check <run> --milestone <M> --item <item> --command <command> --paths <path,…>, then catherd gate pass <run> --item <item> --command <command> --paths <path,…> --evidence <evidence>.",
+  "   - Run independent items side by side, each heavy one wrapped in catherd lock --role verifier -- <command>, which queues them within the machine's slots and keeps another run's verifier from running at the same time.",
   "   - Build each commit's images once, and reuse them for the boot check and the acceptance suite.",
   "2. Exercise every acceptance line through the real entry point: the CLI, the HTTP route, the page. Read source only to find that entry point. When a line needs data or files, build them in a temporary directory outside the project.",
   "3. Read the diff (git diff plus untracked files) for bugs the acceptance lines miss: wrong edge behavior, dead code, leftovers.",
   "",
   "Change nothing in the project. Do not write mutation tests or extra proof tests. The job is to find out whether the work is right, not to grade its test suite.",
   "",
+  ...VERIFIER_GATE_RULES,
+  "",
   "Return, in this order:",
-  "- VERDICT: PASS or VERDICT: FAIL on the first line.",
+  "- VERDICT: PASS or VERDICT: FAIL on the first line, or VERDICT: BLOCKED: environment — <the probe> when the machine stopped the gate.",
   "- One line per acceptance line: A<n> PASS|FAIL, the command you ran and the decisive output.",
   "- One line per gate item: PASS|FAIL, or carried over from <commit>.",
   "- Bugs outside the acceptance lines: file:line, what happens, the input that triggers it.",
@@ -75,11 +98,11 @@ const worker = (version: string) =>
   [
     "You are a worker in a catherd run. The orchestrator's message is your brief: the acceptance lines, the lane file to read, the files you own and the files you must not touch, and your fast check.",
     "",
-    `Read your lane file first. ${RUN_FILES} If the project has a CLAUDE.md or AGENTS.md, follow it.`,
+    `Read your lane file first. ${runFiles(false)} If the project has a CLAUDE.md or AGENTS.md, follow it.`,
     "",
     `Change only the files you own. Run your fast check until it passes. Run the full suite only if the brief says so, and wrap any full build or full test suite in: bunx catherd-cli@${version} lock -- <command>. Other lanes share this machine.`,
     "",
-    REPLY,
+    WORKER_REPLY,
   ].join("\n");
 
 const reviewer = [
@@ -123,7 +146,7 @@ const writer = [
 const researcher = [
   "You answer a factual question about the code, or map it for a dossier. Change nothing in the project. Give file:line for every claim.",
   "",
-  `A dossier lists: the files and folders involved, one line each on what they hold; the existing patterns the work should copy, by path; the build, test and run commands, with how long the full suite takes when the docs, the CI config or a log say so (never run the suite to find out; write "unknown" instead); the lint and type-check commands, and how to scope each to one package; the symbols the change will call or alter, with their signatures; the project rules (CLAUDE.md, AGENTS.md, conventions) that bind this work; and risks: shared files, generated code, slow or flaky tests. It may run to 200 lines. Write it with write_run_file to the path the brief names, and reply with that path. ${RUN_FILES}`,
+  `A dossier lists: the files and folders involved, one line each on what they hold; the existing patterns the work should copy, by path; the build, test and run commands, with how long the full suite takes when the docs, the CI config or a log say so (never run the suite to find out; write "unknown" instead); the lint and type-check commands, and how to scope each to one package; the symbols the change will call or alter, with their signatures; the project rules (CLAUDE.md, AGENTS.md, conventions) that bind this work; and risks: shared files, generated code, slow or flaky tests. It may run to 200 lines. Write it with write_run_file to the path the brief names, and reply with that path. ${runFiles(true)}`,
   "",
   "For a single question, reply in at most 15 lines. The last line of your reply is: STATUS: complete|partial|blocked|refused — <one line why>",
 ].join("\n");
@@ -148,8 +171,8 @@ const STATUS_LINE =
  */
 const CONTRACTS: Record<Role, string> = {
   architect: `Reply briefly: the milestones, each with its lanes as Mx.Ly — one line — owned files, and the full-check command. ${STATUS_LINE}`,
-  verifier: `The first line of your reply is VERDICT: PASS or VERDICT: FAIL. ${STATUS_LINE}`,
-  worker: REPLY,
+  verifier: `The first line of your reply is VERDICT: PASS or VERDICT: FAIL, or VERDICT: BLOCKED: environment — <the probe that proves it> when the machine, not the work, stops the gate (run that probe twice, 5 s apart, before you call the host blocked). ${STATUS_LINE}`,
+  worker: WORKER_REPLY,
   reviewer: REPLY,
   "ui-reviewer": REPLY,
   artist: REPLY,
@@ -169,10 +192,27 @@ export function withReplyContract(role: Role, brief: string): string {
 /** The role's prompt; the worker's names the catherd version whose `lock` it must use. */
 export const rolePrompt = (role: Role, version: string): string => BODIES[role](version);
 
+/** The catherd plugin's MCP tool names as a native Claude subagent sees them. */
+export const NATIVE_TOOL_PREFIX = "mcp__plugin_catherd_catherd__";
+
+/**
+ * The catherd tools a native subagent may never call: the coordinator tools, and record_agent_run, which only the
+ * orchestrator calls (a native verifier recording its own `ok` would satisfy land's evidence).
+ */
+const NATIVE_FORBIDDEN = [...COORDINATOR_TOOLS, "record_agent_run"] as const;
+
+/**
+ * Spec 1.5 plan 21: a native Claude subagent shares the orchestrator's MCP server, so it has no env of its own to
+ * refuse it by. Its agent file forbids the coordinator tools and record_agent_run, and its prompt says why.
+ */
+export const NOT_THE_ORCHESTRATOR = `You are a role of a catherd run, not its orchestrator. Never call catherd's ${NATIVE_FORBIDDEN.join(", ")}: they belong to the orchestrator, which reads your reply.`;
+
 /**
  * Spec D10 for native subagents, whose only lever is the agent file's tool list: read-only drops the
  * editing tools (its Bash stays, for inspection, so enforcement is advisory); every role drops Agent,
- * so a role never spawns its own subagents.
+ * so a role never spawns its own subagents, and catherd's coordinator tools and record_agent_run (spec 1.5 plan 21).
  */
-export const nativeDisallowedTools = (access: Access): string[] =>
-  access === "read-only" ? ["Write", "Edit", "NotebookEdit", "Agent"] : ["Agent"];
+export const nativeDisallowedTools = (access: Access): string[] => [
+  ...(access === "read-only" ? ["Write", "Edit", "NotebookEdit", "Agent"] : ["Agent"]),
+  ...NATIVE_FORBIDDEN.map((tool) => `${NATIVE_TOOL_PREFIX}${tool}`),
+];

package/src/domain/role-scope.ts

@@ -0,0 +1,106 @@
+import { CatherdError } from "./errors.ts";
+import { ID_PATTERN } from "./ids.ts";
+
+/**
+ * Spec 1.5 plan 21: the env var the supervisor sets in every role's process, `<run>/<role-name>`. A process
+ * that carries it is a role of that run: it never owns the run and never reaches the coordinator tools.
+ */
+export const ROLE_ENV = "CATHERD_ROLE";
+
+/** The run and the dispatch name a role process works for. */
+export interface RoleScope {
+  run: string;
+  name: string;
+}
+
+const isId = (s: string): boolean => ID_PATTERN.test(s) && !s.includes("..");
+
+export const formatRoleScope = (s: RoleScope): string => `${s.run}/${s.name}`;
+
+/** `<run>/<role-name>`, else null (unset, empty, or not two ids). */
+export function parseRoleScope(value: string | undefined): RoleScope | null {
+  if (!value) return null;
+  const [run, name, ...rest] = value.split("/");
+  if (rest.length > 0 || !run || !name || !isId(run) || !isId(name)) return null;
+  return { run, name };
+}
+
+/** A run id as `createRun` makes it: `YYYYMMDD-HHMMSS-<slug>`. */
+const RUN_ID = /^\d{8}-\d{6}-/;
+
+/**
+ * The role a temp dir names, when it is a role's scratch, `…/runs/<run>/scratch/<name>[/…]`: Codex passes an
+ * MCP server only a short list of env vars, TMPDIR among them and CATHERD_ROLE not, so a server a role's
+ * Codex starts knows it is a role by its TMPDIR.
+ */
+export function roleScopeOfScratch(tmpdir: string | undefined): RoleScope | null {
+  if (!tmpdir) return null;
+  const parts = tmpdir.split(/[\\/]+/).filter(Boolean);
+  for (let i = parts.length - 2; i >= 2; i--) {
+    if (parts[i] !== "scratch" || parts[i - 2] !== "runs") continue;
+    const run = parts[i - 1] as string;
+    const name = parts[i + 1] as string;
+    if (RUN_ID.test(run)) return parseRoleScope(`${run}/${name}`);
+  }
+  return null;
+}
+
+/** The role this process works for: CATHERD_ROLE, else a TMPDIR that is a role's scratch, else null. */
+export function roleScopeFromEnv(env: Record<string, string | undefined>): RoleScope | null {
+  return parseRoleScope(env[ROLE_ENV]) ?? roleScopeOfScratch(env.TMPDIR);
+}
+
+/**
+ * The tools only the orchestrator calls: each one claims the run, steers a role or changes the run's plan
+ * (spec 1.5 plan 21). A role process gets E_ROLE_SCOPE for them.
+ */
+export const COORDINATOR_TOOLS = [
+  "peek",
+  "result",
+  "dispatch",
+  "run_start",
+  "climb",
+  "land",
+  "park",
+  "cancel",
+  "set_next",
+  "answer",
+  "profile_set",
+  "workspace_start",
+  "workspace_contract",
+  "workspace_child_start",
+  "test_push",
+  "workspace_budget",
+  "workspace_pause",
+  "workspace_resume",
+  "lane_set",
+  "owns_add",
+  "run_pin",
+] as const;
+
+const COORDINATOR = new Set<string>(COORDINATOR_TOOLS);
+
+export const isCoordinatorTool = (tool: string): boolean => COORDINATOR.has(tool);
+
+/**
+ * Whether a role process may not make this call: every coordinator tool, except a `peek` of its own
+ * dispatch (its run and its own name) and a `workspace_contract` read (no `content`).
+ */
+export function refusedForRole(tool: string, args: unknown, scope: RoleScope): boolean {
+  if (!COORDINATOR.has(tool)) return false;
+  const a = (args ?? {}) as Record<string, unknown>;
+  if (tool === "peek") return !(a.run === scope.run && a.name === scope.name);
+  if (tool === "workspace_contract") return a.content !== undefined;
+  return true;
+}
+
+/** E_ROLE_SCOPE: the error a role process gets for a coordinator tool, with the line that fixes it. */
+export function roleScopeError(tool: string, scope: RoleScope): CatherdError {
+  return new CatherdError(
+    "E_ROLE_SCOPE",
+    `${tool} is the orchestrator's: this process runs ${scope.name} of run ${scope.run}`,
+    {
+      fix: `a role reports through its reply; read its run's files with read_run_file, or catherd run-file read ${scope.run} <path>`,
+    },
+  );
+}

package/src/domain/role-tools.ts

@@ -0,0 +1,34 @@
+import type { Role } from "./roles.ts";
+
+export interface RoleMcpContext {
+  run: string;
+  role: Role;
+}
+
+export const ROLE_MCP_SERVER = "catherd_role";
+
+/** Spec 1.5 plan 21: the backends whose harness gets the role server, isolated or not. */
+export const ROLE_SERVER_BACKENDS: readonly string[] = ["codex", "claude-code"];
+
+/**
+ * Spec 1.5 plan 21: the backends whose sandbox catherd grants the role's scratch, so they get it as TMPDIR.
+ * Cursor, Grok and agy write their grants once per isolated home, not per dispatch: they keep the inherited one.
+ */
+export const SCRATCH_BACKENDS: readonly string[] = ["codex", "claude-code", "opencode"];
+
+/**
+ * Whether a role on `backend` gets its scratch as TMPDIR. opencode only when isolated (plan 21 ruling 22): without
+ * --standalone its tools run in the shared background service, whose env the client cannot set.
+ */
+export function grantsScratch(backend: string, isolated: boolean): boolean {
+  if (backend === "opencode") return isolated;
+  return SCRATCH_BACKENDS.includes(backend);
+}
+
+/** Run artifacts and gate evidence have their own authority, independent of repository writes. */
+export function roleMcpTools(role: Role): string[] {
+  const tools = ["read_run_file", "read_knowledge"];
+  if (role === "architect" || role === "researcher") tools.push("write_run_file");
+  if (role === "verifier") tools.push("gate_check", "gate_pass");
+  return tools;
+}

package/src/domain/route.ts

@@ -43,6 +43,35 @@ export interface RouteRow {
   jev?: RouteJev | null;
   /** climb rows: the climb was caused by the environment, not the rung's capability (spec §5.6) */
   env?: boolean;
+  /** route rows (spec 1.5 plan 24): the decision in one line, as `route` returned it */
+  why?: string;
+  /** route rows: where Jev disagreed with the lane's declared Kind/Difficulty */
+  jevSaid?: string;
+  /** route rows: no rung clears the lane's bar, and the closest one */
+  noClear?: string;
+  /** route rows: rungs of equal scores on other quotas competed for the start, and what decided */
+  tie?: string;
+  /** route rows: the chosen rung's thresholds, values and sources (spec 1.2 §5.3), kept out of `route`'s answer */
+  provenance?: unknown;
+}
+
+/**
+ * Spec 1.5 plan 24: one routes.jsonl row for a role's decision outside a lane: `route` without a lane file, or
+ * a lane-less `dispatch` (its `name`). `readRoutes` skips these rows: they have no lane to climb.
+ */
+export interface RoleRouteRow {
+  at: string;
+  lane: null;
+  role: Role;
+  /** the dispatch's name; null for a `route` */
+  name: string | null;
+  rung: string;
+  ladder: string[];
+  source: "route" | "dispatch";
+  /** who chose the rung: the router (its source), or the coordinator passing `rung` to `dispatch` */
+  decidedBy: RouteSource | "orchestrator";
+  why: string;
+  provenance?: unknown;
 }
 
 export function nextRung(ladder: string[], current: string): string | null {
@@ -118,6 +147,50 @@ export function laneOutcome(rows: RouteRow[], lane: string, landed: boolean, at:
   };
 }
 
+/**
+ * Spec 1.5 plan 24: a lane's final outcome in routes.jsonl, beside the route row that holds Jev's answer, for
+ * calibrating Jev's difficulty question: what Jev said and what the route used, whether the lane climbed, and
+ * how it ended. `readRoutes` skips these rows; outcomes.jsonl keeps its own (spec §5.6).
+ */
+export interface OutcomeRouteRow {
+  at: string;
+  lane: string;
+  source: "outcome";
+  decidedBy: RouteSource;
+  kind: Kind | null;
+  difficulty: Difficulty | null;
+  questionSet: string | null;
+  jev: RouteJev | null;
+  /** some climb moved the lane to another rung (an environment climb included) */
+  climbed: boolean;
+  startRung: string;
+  finalRung: string;
+  landed: boolean;
+  start_ok: boolean;
+  envCaused: boolean;
+}
+
+/** The routes.jsonl outcome row of `o`, with the kind and difficulty of the lane's last route. */
+export function outcomeRouteRow(rows: RouteRow[], o: OutcomeRow): OutcomeRouteRow {
+  const start = rows.findLast((r) => r.lane === o.lane && r.source === "route");
+  return {
+    at: o.at,
+    lane: o.lane,
+    source: "outcome",
+    decidedBy: o.source,
+    kind: start?.kind ?? null,
+    difficulty: start?.difficulty ?? null,
+    questionSet: o.questionSet,
+    jev: o.jevProbs,
+    climbed: o.climbs.length > 0,
+    startRung: o.startRung,
+    finalRung: o.finalRung,
+    landed: o.landed,
+    start_ok: o.start_ok,
+    envCaused: o.envCaused,
+  };
+}
+
 /** Spec §5.6: one row per lane, the last one written (last row per lane wins), in first-seen lane order. */
 export function latestOutcomes(rows: OutcomeRow[]): OutcomeRow[] {
   const byLane = new Map<string, OutcomeRow>();