catherd-cli 1.4.0 → 1.5.0

package/src/domain/profile-rules.ts

@@ -21,10 +21,25 @@ import { tryParseRung } from "./ids.ts";
 import { DIFFICULTIES, KINDS } from "./lane.ts";
 import { type Profile, type ProfileDoc, unknownValues } from "./profile.ts";
 import { DEFAULT_ACCESS, ROLES, type Role } from "./roles.ts";
-import { candidates, clearsBar, type RoutingProfile } from "./select.ts";
+import {
+  type Candidate,
+  candidates,
+  clearsBar,
+  defaultLadder,
+  type RoutingProfile,
+  select,
+} from "./select.ts";
 
 export { quotaOf };
 
+/**
+ * `reach`: also warn about the kinds and difficulties no worker rung clears (spec 1.5 plan 24), which only an
+ * explicit `profile validate` asks for.
+ */
+export interface ValidateOptions {
+  reach?: boolean;
+}
+
 /** One finding of `validate`: where in the profile, what is wrong, and the action that fixes it. */
 export interface Issue {
   path: string;
@@ -114,7 +129,8 @@ export const routingProfileOf = (p: Profile, role: Role): RoutingProfile => ({
 /**
  * Whether a rung's scores are catherd's guess: borrowed through a treat-like, filled by an inferred stand-in
  * (spec 1.2 §6.1), or only `inferred` ones. `note` says what a treat-like lends: "scores borrowed from X"
- * when the rung has no value of its own, else the dimensions it borrows (a rung a sync scored on some).
+ * when every value is borrowed, else the dimensions it borrows (a rung a sync scored on some); and (1.2
+ * minor) what each inferred stand-in lends: "honesty inferred from Y".
  */
 export function inferredScores(
   c: Catalog,
@@ -125,9 +141,17 @@ export function inferredScores(
   const records = Object.values(s.records);
   const guessed =
     s.via !== null || s.inferred.length > 0 || records.every((r) => r.confidence === "inferred");
-  const all = s.borrowed.length + s.inferred.length === records.length;
-  const note = s.via ? `${all ? "scores" : s.borrowed.join(", ")} borrowed from ${s.via}` : null;
-  return { inferred: guessed, via: s.via, note };
+  const all = s.borrowed.length === records.length;
+  const byStandIn = new Map<string, Dim[]>();
+  for (const d of s.inferred) {
+    const like = s.standIns[d] as string;
+    byStandIn.set(like, [...(byStandIn.get(like) ?? []), d]);
+  }
+  const parts = [
+    ...(s.via ? [`${all ? "scores" : s.borrowed.join(", ")} borrowed from ${s.via}`] : []),
+    ...[...byStandIn].map(([like, dims]) => `${dims.join(", ")} inferred from ${like}`),
+  ];
+  return { inferred: guessed, via: s.via, note: parts.length ? parts.join("; ") : null };
 }
 
 /**
@@ -147,6 +171,7 @@ export function validateProfile(
   backends: readonly string[],
   doc?: ProfileDoc,
   host: OrchestrationHost = "unknown",
+  o: ValidateOptions = {},
 ): Validation {
   const errors: Issue[] = [];
   const warnings: Issue[] = [];
@@ -172,6 +197,13 @@ export function validateProfile(
         message: `${role} runs ${rc.access}; catherd's default for it is ${DEFAULT_ACCESS[role]}`,
       });
     if (!rc.enabled) continue;
+    // spec §5: network: false takes a workspace-write role's network grants; read-only and full have none to take
+    if (rc.network === false && rc.access !== "workspace-write")
+      warnings.push({
+        path: `${at}.network`,
+        message: `network: false does nothing here: it applies to workspace-write roles, and ${role} runs ${rc.access}`,
+        fix: `catherd profile set ${at}.network null`,
+      });
     for (const rung of rc.rungs) {
       const native = nativeClaudeIssue(rung, host, `${at}.rungs`);
       if (native) errors.push(native);
@@ -218,7 +250,7 @@ export function validateProfile(
       if (!scoresOf(c, info.canonical))
         warnings.push({
           path: `${at}.rungs`,
-          message: `${rung} is unscored and no rung is near enough to stand in for it: routing skips it`,
+          message: `${rung} is unscored and no rung is near enough to stand in for it: routing skips it${rung === rc.defaultRung ? `; it is the ${role}'s default rung, so ${defaultFallback(c, p, role)}` : ""}`,
           fix: TREAT_LIKE_FIX(rung),
         });
     }
@@ -257,24 +289,48 @@ export function validateProfile(
             path: `${at}.rungs`,
             message: `${x.rung} clears no routing bar, so a lane starts on it only as the role's default rung and never climbs onto it`,
           });
-    // spec 1.2 §5.2: the logic and hard bars sit at the 60th and 75th percentiles, which a cost-minded ladder
-    // may never reach, and those lanes start at the default rung and climb; only a kind whose every bar the
-    // ladder misses routes blind (plan 14 Ruling 12)
+    // spec 1.5 plan 24: every kind and difficulty no worker rung clears, in one warning; those lanes start at the
+    // default rung (or an easier difficulty's start) and climb only onto rungs at least as strong. Only an
+    // explicit validate says it (Ruling 3): the shipped bars put logic and hard above every Sol rung, the
+    // owner's call, so every save and doctor would repeat it
+    if (o.reach && role === "worker" && usable.length > 1) {
+      const unreached = unreachable(c, usable);
+      if (unreached.length)
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `no worker rung clears ${unreached.join("; ")}: those lanes start at the default rung and climb only onto rungs at least as strong (route names the closest)`,
+        });
+    }
+    // spec 1.5 plan 24: a quota whose rungs never start a lane sits idle but for climbs (the identity run's Go).
+    // Only the worker routes lanes and climbs (Ruling 9); another role routes lane-less to one rung, so a rung
+    // on a second quota is a deliberate spare there, not an idle quota (final review Important 4, Ruling 8)
     if (role === "worker" && usable.length > 1) {
-      const blind = KINDS.filter((k) => !DIFFICULTIES.some((d) => usable.some((x) => clearsBar(c, x, k, d))));
-      if (blind.length)
+      const idle = idleQuotas(c, p, role, usable);
+      for (const [q, rungs] of idle) {
+        // the billing key, not the quota, is what billing is set on (`claude:` and `claude-code:` share one)
+        const keys = [...new Set(usable.filter((x) => rungs.includes(x.rung)).map((x) => x.info.key))];
         warnings.push({
           path: `${at}.rungs`,
-          message: `no worker rung clears any bar for ${blind.join(", ")}; those lanes always start at the default rung`,
+          message: `${q} never starts a ${role} lane: ${rungs.join(", ")} ${rungs.length > 1 ? "run" : "runs"} only on a climb, since another rung starts every lane`,
+          fix: `check ${keys.map((k) => `billing.${k}`).join(" and ")} (a metered rung starts only where nothing paid from a plan clears the bar), or order ${at}.rungs so its rungs come first among equals`,
         });
+      }
     }
   }
 
   const ladders = new Set(ROLES.filter((r) => p.roles[r].enabled).flatMap((r) => p.roles[r].rungs));
-  // the stand-ins catherd could run here, for the fixes below
+  // the stand-ins the fixes below may suggest: on a backend catherd runs and the profile already names (a
+  // ladder or a failover entry), never one this machine may not have (Cursor on a machine without it); a
+  // native claude: rung names claude-code too, the same Claude Code CLI
+  const named = new Set(
+    [...ladders, ...Object.keys(p.failover), ...Object.values(p.failover)].flatMap((x) => {
+      const b = tryParseRung(x)?.backend;
+      return b === undefined ? [] : b === "claude" ? [b, "claude-code"] : [b];
+    }),
+  );
   const pool = catalogRungs(c).filter((x) => {
     const r = tryParseRung(x);
-    return r !== null && backends.includes(r.backend);
+    return r !== null && backends.includes(r.backend) && named.has(r.backend);
   });
   for (const [from, to] of Object.entries(p.failover)) {
     const at = `failover.${from}`;
@@ -294,7 +350,8 @@ export function validateProfile(
       errors.push({ path: at, message: `stand-in ${to}: catherd cannot run ${b.backend} yet` });
       continue;
     }
-    if (!scoresOf(c, rungInfo(c, to).canonical))
+    const unscored = !scoresOf(c, rungInfo(c, to).canonical);
+    if (unscored)
       warnings.push({
         path: at,
         message: `stand-in ${to} is unscored and no rung is near enough to stand in for it`,
@@ -307,7 +364,8 @@ export function validateProfile(
         fix: "name a stand-in on another backend or plan",
       });
     const ranked = rankStandIns(c, p.billing, from, pool);
-    const down = downgradeDims(c, from, to);
+    // an unscored stand-in has its own warning above: no "downgrade" on every bar dim besides
+    const down = unscored ? [] : downgradeDims(c, from, to);
     if (down.length)
       warnings.push({
         path: at,
@@ -334,6 +392,44 @@ export function validateProfile(
   return { errors, warnings };
 }
 
+/** The role's default rung when it is unscored: what routing starts on instead. */
+function defaultFallback(c: Catalog, p: Profile, role: Role): string {
+  try {
+    return `routing falls back to ${defaultLadder(c, routingProfileOf(p, role), role).rung}`;
+  } catch {
+    return "routing has no rung to fall back to";
+  }
+}
+
+/** `repo_code logic, hard` per kind: the kinds and difficulties no rung of `usable` clears. */
+function unreachable(c: Catalog, usable: Candidate[]): string[] {
+  return KINDS.flatMap((k) => {
+    const ds = DIFFICULTIES.filter((d) => !usable.some((x) => clearsBar(c, x, k, d)));
+    return ds.length ? [`${k} ${ds.join(", ")}`] : [];
+  });
+}
+
+/**
+ * Spec 1.5 plan 24: each quota of the role's usable rungs that no kind and difficulty (nor a lane-less route)
+ * ever starts on, whichever quota the run has used least, with its rungs.
+ */
+function idleQuotas(c: Catalog, p: Profile, role: Role, usable: Candidate[]): [string, string[]][] {
+  const quotas = [...new Set(usable.map((x) => quotaOf(x.info.parsed)))];
+  if (quotas.length < 2) return [];
+  const starts = new Set<string>();
+  // every quota gets its turn as the least used, so a tie it could win counts as a start
+  for (const fresh of [null, ...quotas]) {
+    const usage = Object.fromEntries(quotas.map((q) => [q, q === fresh ? 0 : 1]));
+    const rp = { ...routingProfileOf(p, role), usage };
+    starts.add(defaultLadder(c, rp, role).rung);
+    for (const k of KINDS) for (const d of DIFFICULTIES) starts.add(select(c, rp, role, k, d).rung);
+  }
+  const started = new Set(usable.filter((x) => starts.has(x.rung)).map((x) => quotaOf(x.info.parsed)));
+  return quotas
+    .filter((q) => !started.has(q))
+    .map((q) => [q, usable.filter((x) => quotaOf(x.info.parsed) === q).map((x) => x.rung)]);
+}
+
 export function nativeClaudeIssue(rung: string, host: OrchestrationHost, path: string): Issue | null {
   const r = tryParseRung(rung);
   return host !== "claude-code" && r?.backend === "claude"

package/src/domain/profile.ts

@@ -45,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({
@@ -117,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;
@@ -298,6 +310,14 @@ export function resolveProfile(doc: ProfileDoc, name: string, host: Orchestratio
       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"] = {};
@@ -344,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(),
@@ -79,7 +84,16 @@ export const RunRecordSchema = z.looseObject({
 });
 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;
+}