catherd-cli 1.3.0 → 1.5.0

package/src/adapters/grok/home.ts

@@ -21,9 +21,9 @@ const COMPAT = ["CLAUDE", "CURSOR"].flatMap((tool) =>
 /**
  * Spec 1.3 §5.4: an isolated run's env. GROK_HOME and the toggles alone still load the user's Claude Code
  * plugins, agents and permission rules (research §3.8 [run]), so HOME moves too, and GROK_HOME lives in it.
+ * `home`: another root than the isolated runs' (doctor's sandbox check runs in a scratch one).
  */
-export function grokHomeEnv(): Record<string, string> {
-  const home = isolatedGrokRoot();
+export function grokHomeEnv(home = isolatedGrokRoot()): Record<string, string> {
   return {
     ...movedHomeEnv(home),
     GROK_HOME: join(home, ".grok"),
@@ -82,10 +82,47 @@ const tomlError = (text: string): string | null => {
   }
 };
 
+/** The `read_write` roots of each profile in catherd's block as it stands, by profile name. */
+function blockRoots(block: string): Record<string, string[]> {
+  try {
+    const p =
+      (Bun.TOML.parse(block) as { profiles?: Record<string, { read_write?: unknown }> }).profiles ?? {};
+    return Object.fromEntries(
+      Object.entries(p).map(([k, v]) => [
+        k,
+        Array.isArray(v.read_write) ? v.read_write.filter((r): r is string => typeof r === "string") : [],
+      ]),
+    );
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * `profiles` with each one's `read_write` merged into the block's current roots: those that still exist, in
+ * their order, then the new ones. Two catherd homes on one machine (another CATHERD_HOME, other lock dirs) then
+ * converge on one block instead of rewriting each other's.
+ */
+function mergedProfiles(
+  profiles: Record<string, Record<string, unknown>>,
+  was: Record<string, string[]>,
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(profiles).map(([name, p]) => {
+      const mine = Array.isArray(p.read_write) ? (p.read_write as string[]) : [];
+      const kept = (was[name] ?? []).filter((r) => existsSync(r));
+      const roots = [...new Set([...kept, ...mine])];
+      return [name, { ...p, read_write: roots }];
+    }),
+  );
+}
+
 /**
- * `text` (a sandbox.toml) with catherd's marked block set to `profiles`: the old block cut out, the new one
- * appended. Outside the block only trailing blank lines change. `why` when catherd must not write: the file
- * is not TOML, defines a `catherd-*` profile of its own, or has lost the block's end marker.
+ * `text` (a sandbox.toml) with catherd's marked block set to `profiles`: rewritten where it stands, or appended
+ * when there is none. A rewrite in place keeps every line outside the block, and what each line belongs to: a
+ * bare key the user put after the block stays in the table it was in. The block's existing roots that still
+ * exist stay (mergedProfiles). `why` when catherd must not write: the file is not TOML, defines a `catherd-*`
+ * profile of its own, or has lost the block's end marker.
  */
 export function withCatherdProfiles(
   text: string,
@@ -95,21 +132,22 @@ export function withCatherdProfiles(
   const end = start === -1 ? -1 : text.indexOf(END, start);
   if (start !== -1 && end === -1)
     return { why: `catherd's block has lost its end marker (${END}): delete the block` };
-  // the block goes with the blank line catherd put before it
-  const rest =
-    start === -1
-      ? text
-      : text.slice(0, start).replace(/\n\n$/, "\n") + text.slice(end + END.length).replace(/^\r?\n/, "");
+  const after = start === -1 ? "" : text.slice(end + END.length).replace(/^\r?\n/, "");
+  // the file without the block, for the checks: the block goes with the blank line catherd put before it
+  const rest = start === -1 ? text : text.slice(0, start).replace(/\n\n$/, "\n") + after;
   const bad = tomlError(rest);
   if (bad) return { why: `it is not valid TOML (${bad})` };
   const own = Object.keys((Bun.TOML.parse(rest) as { profiles?: object }).profiles ?? {}).find((k) =>
     k.startsWith("catherd-"),
   );
   if (own) return { why: `it has a [profiles.${own}] of its own: rename it, catherd's tables are catherd-*` };
+  const was = start === -1 ? {} : blockRoots(text.slice(start, end));
+  const block = `${HEADER}\n${Bun.TOML.stringify({ profiles: mergedProfiles(profiles, was) })}${END}\n`;
   const head = rest.trimEnd();
-  const out = `${head ? `${head}\n\n` : ""}${HEADER}\n${Bun.TOML.stringify({ profiles })}${END}\n`;
-  const after = tomlError(out);
-  return after ? { why: `it is not valid TOML with catherd's tables added (${after})` } : { text: out };
+  const out =
+    start === -1 ? `${head ? `${head}\n\n` : ""}${block}` : `${text.slice(0, start)}${block}${after}`;
+  const broken = tomlError(out);
+  return broken ? { why: `it is not valid TOML with catherd's tables added (${broken})` } : { text: out };
 }
 
 /**
@@ -119,14 +157,31 @@ export function withCatherdProfiles(
  */
 export function writeGrokProfiles(home: string): void {
   const path = join(home, "sandbox.toml");
-  // a link (a dotfiles repo) stays a link: the atomic rename goes to the file it points at
-  const file = lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink() ? realpathSync(path) : path;
-  const was = existsSync(file) ? readFileSync(file, "utf8") : "";
-  const next = withCatherdProfiles(was);
-  if ("why" in next)
-    throw new CatherdError("E_CONFIG_INVALID", `catherd will not edit ${file}: ${next.why}`, {
+  const refuse = (file: string, why: string) =>
+    new CatherdError("E_CONFIG_INVALID", `catherd will not edit ${file}: ${why}`, {
       fix: `fix ${file}, or isolate grok (catherd profile set harness.grok.isolated true)`,
     });
+  // a link (a dotfiles repo) stays a link: the atomic rename goes to the file it points at
+  let file = path;
+  if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink())
+    try {
+      file = realpathSync(path);
+    } catch (e) {
+      throw refuse(path, `it is a link catherd cannot follow (${(e as NodeJS.ErrnoException).code ?? e})`);
+    }
+  let was = "";
+  try {
+    was = existsSync(file) ? readFileSync(file, "utf8") : "";
+  } catch (e) {
+    throw refuse(file, `catherd cannot read it (${(e as NodeJS.ErrnoException).code ?? e})`);
+  }
+  const next = withCatherdProfiles(was);
+  if ("why" in next) throw refuse(file, next.why);
   if (next.text === was) return;
-  writeTextAtomic(file, next.text, { mode: existsSync(file) ? statSync(file).mode & 0o777 : 0o600 });
+  try {
+    writeTextAtomic(file, next.text, { mode: existsSync(file) ? statSync(file).mode & 0o777 : 0o600 });
+  } catch (e) {
+    // a read-only store (a Nix home, say) or a folder catherd may not write
+    throw refuse(file, `catherd cannot write it (${(e as NodeJS.ErrnoException).code ?? e})`);
+  }
 }

package/src/adapters/grok/index.ts

@@ -1,5 +1,5 @@
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { CatherdError } from "../../domain/errors.ts";
 import type { Rung } from "../../domain/ids.ts";
 import type { Access, RunStatus } from "../../domain/record.ts";
@@ -57,11 +57,13 @@ const NO_UPDATE = { GROK_DISABLE_AUTOUPDATER: "1" };
 export const grokShell = { timeoutMs: 15_000 };
 
 /**
- * A fresh run's session id (`-s`), derived from its dispatch dir so finalize knows it without the stream: a run
- * killed before grok's `end` (a timeout, a cancel) still records the session grok saved (plan 16 final review).
+ * A fresh run's session id (`-s`), derived from its dispatch id (the dispatch dir's last part) so finalize knows
+ * it without the stream: a run killed before grok's `end` (a timeout, a cancel) still records the session grok
+ * saved (plan 16 final review). The id alone, not the full path: a data dir reached by another path (a link,
+ * `/private/var` for `/var`) gives the same session.
  */
 export function sessionFor(r: Pick<RunRequest, "dispatchDir">): string {
-  const h = new Bun.CryptoHasher("sha256").update(r.dispatchDir).digest("hex");
+  const h = new Bun.CryptoHasher("sha256").update(basename(r.dispatchDir)).digest("hex");
   const variant = ((Number.parseInt(h[16] as string, 16) & 0x3) | 0x8).toString(16);
   return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${variant}${h.slice(17, 20)}-${h.slice(20, 32)}`;
 }
@@ -125,11 +127,20 @@ function shippedOnGrok(): ShippedGrok {
   return shipped;
 }
 
-async function listModels(): Promise<DiscoveredModel[]> {
-  const r = await runCli("grok", ["models"], { ...grokShell, env: NO_UPDATE });
+/** `grok models` under `env`: the user's GROK_HOME (its login) by default, catherd's isolated one with the key. */
+async function listAs(env: Record<string, string>): Promise<DiscoveredModel[]> {
+  const r = await runCli("grok", ["models"], { ...grokShell, env });
   return r?.ok ? parseGrokModels(r.out, shippedOnGrok()).models : [];
 }
 
+const listModels = (): Promise<DiscoveredModel[]> => listAs(NO_UPDATE);
+
+/**
+ * The discovery cache an isolated run is judged by: the listing under catherd's own GROK_HOME, where only
+ * XAI_API_KEY signs grok in, apart from the native login's (1.3 follow-ups: the two accounts may differ).
+ */
+export const ISOLATED_LISTING = "grok-isolated";
+
 /**
  * Spec 1.3 §5.3–§5.4: an isolated run needs XAI_API_KEY (its home holds no login, and the user's auth.json is
  * never copied: its refresh token rotates, research §3.9); a workspace-write run needs catherd-ws in the
@@ -150,7 +161,13 @@ async function prepare(req: {
   if (req.isolated) ensurePrivateDir(home);
   if (req.access === "workspace-write") writeGrokProfiles(home);
   const { model, effort } = req.rung;
-  const models = await discovered("grok", listModels, { maxAgeMs: DAY_MS, need: model });
+  // an isolated run signs in with the key, so its model is checked against the key's own listing
+  const models = req.isolated
+    ? await discovered(ISOLATED_LISTING, () => listAs({ ...NO_UPDATE, ...grokHomeEnv() }), {
+        maxAgeMs: DAY_MS,
+        need: model,
+      })
+    : await discovered("grok", listModels, { maxAgeMs: DAY_MS, need: model });
   if (models.length === 0) return; // grok listed nothing: let the run itself say what is wrong
   const m = models.find((x) => x.id === model);
   if (!m)
@@ -241,7 +258,9 @@ async function sandboxInfo(): Promise<{ id: string; label: string; detail: strin
     const r = await runCli(
       "grok",
       ["-p", "hi", "--output-format", "streaming-json", "--sandbox", "read-only", "--no-auto-update"],
-      { ...grokShell, env: { ...NO_UPDATE, GROK_HOME: home, XAI_API_KEY: "" } },
+      // a scratch HOME as well as GROK_HOME, with memory and the compat features off: nothing of the user's
+      // own Claude Code or Cursor setup loads into the check (1.3 follow-ups)
+      { ...grokShell, env: { ...NO_UPDATE, ...grokHomeEnv(home), XAI_API_KEY: "" } },
     );
     if (!r) return null;
     const refused = /could not apply the '?read-only'? sandbox profile/.test(r.err);

package/src/adapters/opencode/index.ts

@@ -155,6 +155,20 @@ function finalize(run: FinishedRun): Outcome {
   const f = foldOpencodeEvents(run.eventLines);
   const stopped = run.exit.reason;
   const tooOld = f.tooOld || OPENCODE_TOO_OLD.some((r) => r.test(run.stderr));
+  // plan 23: the provider kept failing; failover takes it as a usage limit, onto the next backend
+  if (stopped === "provider-unavailable")
+    return {
+      status: "limit",
+      thread: f.thread ?? run.request.thread,
+      tokens: f.tokens,
+      costUsd: f.costUsd,
+      images: [],
+      error: {
+        code: "provider-unavailable",
+        message: f.error?.message ?? "the provider retried with no progress",
+      },
+      reply: f.reply,
+    };
   const status: RunStatus =
     stopped === "cancelled"
       ? "cancelled"
@@ -201,6 +215,8 @@ function parse(line: string): EventDelta {
   const activity = opencodeActivity(e);
   if (activity) d.activity = activity;
   if (typeof e.sessionID === "string") d.thread = e.sessionID;
+  // plan 23: each provider retry starts a step again with nothing between; the supervisor counts them
+  if (e.type === "step_start") d.step = true;
   if (e.type === "step_finish") {
     d.tokens = opencodeTokens(e.part?.tokens);
     d.requestInput = d.tokens.input;
@@ -220,6 +236,21 @@ function parse(line: string): EventDelta {
  * older messages keep their errors, so only the newest assistant message counts, and with `sinceMs` only
  * if this run wrote it.
  */
+/**
+ * Plan 23: the provider retry the newest assistant message this run wrote is waiting out (a 503, an
+ * overloaded backend), by its attempt number; null when it is not retrying.
+ */
+function providerRetryOf(messages: unknown, sinceMs: number): number | null {
+  if (!Array.isArray(messages)) return null;
+  const m = messages.find((x) => x?.type === "assistant") as Record<string, any> | undefined;
+  if (!m?.retry || !(m.time?.created >= sinceMs)) return null;
+  return typeof m.retry.attempt === "number" ? m.retry.attempt : 1;
+}
+
+async function providerRetry(thread: string, sinceMs: number): Promise<number | null> {
+  return providerRetryOf((await opencodeApi("GET", `/api/session/${thread}/message`))?.data, sinceMs);
+}
+
 function limitRetry(messages: unknown, sinceMs?: number): string | null {
   if (!Array.isArray(messages)) return null;
   const m = messages.find((x) => x?.type === "assistant") as Record<string, any> | undefined;
@@ -265,7 +296,12 @@ async function isBusy(thread: string, sinceMs?: number): Promise<boolean> {
   const active = (await opencodeApi("GET", "/api/session/active"))?.data;
   if (!active || typeof active !== "object" || !(thread in active)) return false;
   const messages = (await opencodeApi("GET", `/api/session/${thread}/message`))?.data;
-  return Array.isArray(messages) && limitRetry(messages, sinceMs) === null;
+  // plan 23: a session only retrying its provider is not busy, so the idle timeout still runs
+  return (
+    Array.isArray(messages) &&
+    limitRetry(messages, sinceMs) === null &&
+    providerRetryOf(messages, sinceMs ?? 0) === null
+  );
 }
 
 /** Killing the v2 client does not stop its session; the service must be told (research §2.4). */
@@ -327,6 +363,7 @@ export const opencodeAdapter: BackendAdapter = {
   resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
   interrupt: (thread) => interrupt(thread),
   isBusy: (thread, _cwd, sinceMs) => isBusy(thread, sinceMs),
+  providerRetry: (thread, _cwd, sinceMs) => providerRetry(thread, sinceMs),
   failoverFor,
   graceAfterFinalMs: null,
   reportsCost: true,

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { HOST_ARG } from "./entry/host-arg.ts";
 import type { ArgsDef } from "citty";
 import { errorMessage } from "./domain/errors.ts";
 import { runtimeRefusal } from "./domain/runtime.ts";
@@ -12,7 +13,7 @@ if (refusal) {
 
 const { realpathSync } = await import("node:fs");
 const { fileURLToPath } = await import("node:url");
-const { defineCommand, renderUsage, runCommand } = await import("citty");
+const { defineCommand, renderUsage, runCommand, parseArgs } = await import("citty");
 const { CatherdError, isCatherdError } = await import("./domain/errors.ts");
 const { EXIT, exitCodeOf, printError, stripAnsi } = await import("./entry/cli-kit.ts");
 const { VERSION } = await import("./infra/version.ts");
@@ -21,6 +22,7 @@ type Command = ReturnType<typeof defineCommand>;
 
 /** The dashboard's flags, typed as any command's args so `main` stays a plain `Command`. */
 const dashboardArgs: ArgsDef = {
+  ...HOST_ARG,
   plain: {
     type: "boolean",
     description: "the dashboard in ASCII without colour (NO_COLOR also drops colour)",
@@ -48,7 +50,12 @@ export const main: Command = defineCommand({
     doctor: () => import("./entry/doctor-command.ts").then((m) => m.doctorCommand),
     catalog: () => import("./entry/catalog-command.ts").then((m) => m.catalogCommand),
     knowledge: () => import("./entry/knowledge-command.ts").then((m) => m.knowledgeCommand),
+    workspace: () => import("./entry/workspace-command.ts").then((m) => m.workspaceCommand),
     lock: () => import("./entry/lock-command.ts").then((m) => m.lockCommand),
+    "run-file": () => import("./entry/role-cli-command.ts").then((m) => m.runFileCommand),
+    gate: () => import("./entry/role-cli-command.ts").then((m) => m.gateCommand),
+    pause: () => import("./entry/pause-command.ts").then((m) => m.pauseCommand),
+    resume: () => import("./entry/pause-command.ts").then((m) => m.resumeCommand),
     "capture-fixtures": () =>
       import("./entry/capture-fixtures-command.ts").then((m) => m.captureFixturesCommand),
     mcp: () => import("./entry/mcp/command.ts").then((m) => m.mcpCommand),
@@ -56,7 +63,7 @@ export const main: Command = defineCommand({
   },
   // citty runs this after any subcommand too; only a bare `catherd` loads and opens the dashboard
   async run(ctx) {
-    if (!ctx.rawArgs.every((a) => a.startsWith("-"))) return;
+    if (ctx.args._.length > 0) return;
     await (await import("./entry/tui/run.tsx")).tuiRun(ctx);
   },
 });
@@ -69,14 +76,24 @@ async function commandFor(argv: string[]): Promise<[Command, Command | undefined
   let cmd = main;
   let parent: Command | undefined;
   const path: string[] = [];
-  for (const a of argv) {
-    if (a.startsWith("-")) continue;
+  let remaining = argv;
+  while (true) {
+    const defs = await resolve(cmd.args ?? {});
+    const navigationArgs: ArgsDef = Object.fromEntries(
+      Object.entries(defs).map(([key, def]) => [
+        key,
+        { ...def, required: false, ...(def.type === "enum" ? { type: "string" as const } : {}) },
+      ]),
+    ) as ArgsDef;
+    const a = parseArgs(remaining, navigationArgs)._[0];
+    if (!a) break;
     const subs = cmd.subCommands ? await resolve(cmd.subCommands) : undefined;
     const next = subs?.[a];
     if (!next) break;
     parent = cmd;
     cmd = (await resolve(next)) as Command;
     path.push(a);
+    remaining = remaining.slice(remaining.indexOf(a) + 1);
   }
   return [cmd, parent, path];
 }
@@ -123,22 +140,39 @@ export async function runCli(argv: string[]): Promise<number> {
     console.log(`${await helpText(cmd, path)}\n`);
     return EXIT.ok;
   }
-  const command = own.find((a) => !a.startsWith("-"));
-  // a bare `catherd` opens the dashboard, which takes only its own flags: a typo is not a terminal problem
-  const flag = (a: string) => (a.startsWith("--") ? (a.slice(2).split("=")[0] ?? "") : "");
-  // citty negates a boolean as `--no-<name>`
-  const known = (name: string) =>
-    Object.hasOwn(dashboardArgs, name) ||
-    (name.startsWith("no-") && dashboardArgs[name.slice(3)]?.type === "boolean");
-  const unknown = command === undefined ? own.find((a) => !known(flag(a))) : undefined;
-  if (unknown !== undefined) {
-    printError(new CatherdError("E_INPUT_INVALID", `unknown option ${unknown}`, { fix: "catherd --help" }));
-    return EXIT.usage;
-  }
-  // `lock` forwards signals to its command itself; everything else stops at once on Ctrl-C. The command is
-  // the first word that is not a flag: `catherd --plain lock -- …` is `lock` too.
-  if (command !== "lock") process.once("SIGINT", () => process.exit(EXIT.interrupted));
   try {
+    const command = parseArgs(own, dashboardArgs)._[0];
+    // a bare `catherd` opens the dashboard, which takes only its own flags: a typo is not a terminal problem
+    const flag = (a: string) => (a.startsWith("--") ? (a.slice(2).split("=")[0] ?? "") : "");
+    // citty negates a boolean as `--no-<name>`
+    const known = (name: string) =>
+      Object.hasOwn(dashboardArgs, name) ||
+      (name.startsWith("no-") && dashboardArgs[name.slice(3)]?.type === "boolean");
+    const unknown =
+      command === undefined
+        ? own.find((a, i) => a.startsWith("-") && !known(flag(a)) && own[i - 1] !== "--host")
+        : undefined;
+    if (unknown !== undefined) {
+      printError(new CatherdError("E_INPUT_INVALID", `unknown option ${unknown}`, { fix: "catherd --help" }));
+      return EXIT.usage;
+    }
+    // `lock` forwards signals to its command itself; everything else stops at once on Ctrl-C. The command is
+    // the first word that is not a flag: `catherd --plain lock -- …` is `lock` too.
+    if (command !== "lock") process.once("SIGINT", () => process.exit(EXIT.interrupted));
+    const parsed = parseArgs(own, dashboardArgs);
+    if (parsed.host !== undefined) {
+      const forwarded = own.filter(
+        (a, i) => a !== "--host" && own[i - 1] !== "--host" && !a.startsWith("--host="),
+      );
+      rawArgs.splice(
+        0,
+        rawArgs.length,
+        ...forwarded,
+        "--host",
+        String(parsed.host),
+        ...(dashdash < 0 ? [] : argv.slice(dashdash)),
+      );
+    }
     await runCommand(main, { rawArgs });
     return Number(process.exitCode ?? EXIT.ok);
   } catch (e) {

package/src/domain/agents.ts

@@ -1,7 +1,7 @@
 import { parseRung, tryParseRung } from "./ids.ts";
 import { agentName, type Profile } from "./profile.ts";
 import type { Access } from "./record.ts";
-import { nativeDisallowedTools, rolePrompt } from "./role-prompts.ts";
+import { NOT_THE_ORCHESTRATOR, nativeDisallowedTools, rolePrompt } from "./role-prompts.ts";
 import { ROLES, type Role } from "./roles.ts";
 
 export interface AgentFile {
@@ -32,6 +32,8 @@ export function renderAgent(o: {
     "",
     rolePrompt(o.role, o.version),
     "",
+    NOT_THE_ORCHESTRATOR,
+    "",
   ].join("\n");
 }
 

package/src/domain/brief.ts

@@ -0,0 +1,91 @@
+import { replyContract } from "./role-prompts.ts";
+import { ROLE_MCP_SERVER, roleMcpTools } from "./role-tools.ts";
+import type { Role } from "./roles.ts";
+
+/** What admission adds to a role's brief, besides its reply contract (spec 1.5 plan 21). */
+export interface BriefContext {
+  run: string;
+  name: string;
+  role: Role;
+  /** the lane file as it stands at admission, header and body */
+  lane: { id: string; text: string } | null;
+  /** the role's scratch folder, its TMPDIR, on a backend that grants it */
+  scratch: string | null;
+  /** whether the role's harness lists the catherd_role tools */
+  roleServer: boolean;
+}
+
+/** The CLI form of each role server tool, which any role can run from its shell. */
+function cliForm(tool: string, run: string): string {
+  switch (tool) {
+    case "read_run_file":
+      return `catherd run-file read ${run} <path>`;
+    case "write_run_file":
+      return `catherd run-file write ${run} <path> (the content on stdin)`;
+    case "read_knowledge":
+      return "catherd knowledge show";
+    case "gate_check":
+      return `catherd gate check ${run} --milestone <M> --item <item> --command <command> --paths <path,…>`;
+    case "gate_pass":
+      return `catherd gate pass ${run} --item <item> --command <command> --paths <path,…> --evidence <evidence>`;
+    default:
+      return tool;
+  }
+}
+
+const LANE_OPEN = (id: string) => `<lane-file path="lanes/${id}.md">`;
+const LANE_CLOSE = "</lane-file>";
+
+/**
+ * The lane file inlined (spec 1.5 plan 21): an isolated headless worker cannot read the run folder, so its Owns,
+ * fast check and body travel in the brief itself.
+ */
+export function laneBlock(id: string, text: string): string {
+  return [
+    `Your lane file, lanes/${id}.md, as it stood when you were dispatched:`,
+    LANE_OPEN(id),
+    text.trimEnd(),
+    LANE_CLOSE,
+  ].join("\n");
+}
+
+/** Who the role is, where its temp files go, and how it reaches its run's files and gate. */
+export function roleNotes(c: BriefContext): string {
+  const tools = roleMcpTools(c.role);
+  const lines = [`catherd: you are ${c.name} of run ${c.run}.`];
+  if (c.scratch)
+    lines.push(
+      `Your scratch folder is ${c.scratch}, which is your $TMPDIR: put temporary files, logs and builds there, never in /tmp. catherd removes it with the run, so anything the orchestrator must keep goes in your reply.`,
+    );
+  const cli = tools.map((t) => cliForm(t, c.run)).join("; ");
+  lines.push(
+    c.roleServer
+      ? `Your catherd tools: ${tools.map((t) => `mcp__${ROLE_MCP_SERVER}__${t}`).join(", ")}. If they are not listed, run the same from your shell: ${cli}.`
+      : `Your catherd commands, from your shell: ${cli}.`,
+  );
+  return lines.join("\n");
+}
+
+/**
+ * The brief admission writes: the orchestrator's text, the lane file, the role's notes, then its reply contract,
+ * each once. A failover stand-in that reruns an earlier brief gets the lane file as it stands now and its own notes,
+ * never two copies.
+ */
+export function composeBrief(brief: string, c: BriefContext): string {
+  const contract = replyContract(c.role);
+  let body = brief.trimEnd();
+  if (body.endsWith(contract)) body = body.slice(0, -contract.length).trimEnd();
+  if (c.lane) {
+    const open = LANE_OPEN(c.lane.id);
+    const start = body.lastIndexOf(open);
+    const end = body.indexOf(LANE_CLOSE, start);
+    if (start >= 0 && end >= 0) {
+      const lead = body.lastIndexOf("\n\n", start);
+      body = `${body.slice(0, lead >= 0 ? lead : start)}${body.slice(end + LANE_CLOSE.length)}`.trimEnd();
+    }
+  }
+  const notesStart = body.lastIndexOf("\n\ncatherd: you are ");
+  if (notesStart >= 0) body = body.slice(0, notesStart).trimEnd();
+  const parts = [body, ...(c.lane ? [laneBlock(c.lane.id, c.lane.text)] : []), roleNotes(c), contract];
+  return `${parts.filter(Boolean).join("\n\n")}\n`;
+}

package/src/domain/calibration.ts

@@ -34,6 +34,13 @@ export const DIM_SOURCES: Record<Dim, { anchor: FieldRef | "shipped"; others: Fi
         benchmark: "Artificial Analysis Coding Index",
       },
       { source: "epoch", field: "frontiercode", benchmark: "FrontierCode (Epoch AI)" },
+      // spec 1.5 plan 24: per model and effort, it scores a new release the day it ships (the identity run's
+      // GPT-6.1 Sol: medium 47.8, about Astra low)
+      {
+        source: "artificial-analysis",
+        field: "artificial_analysis_intelligence_index",
+        benchmark: "Artificial Analysis Intelligence Index",
+      },
     ],
   },
   // plan 14 Ruling C-2: the vendors' Terminal-Bench 4.0 values, not Epoch's Terminal-Bench 2.0, which shares

package/src/domain/catalog.ts

@@ -84,6 +84,11 @@ const FamilySchema = z.looseObject({
   notes: z.record(z.string(), z.string()).default({}),
   /** the day the vendor released it (models.dev), a stand-in feature (spec 1.2 §6.3) */
   releaseDate: z.iso.date().optional(),
+  /**
+   * spec 1.5 plan 24: the family this one succeeds in the same line (GPT-6.1 Sol after GPT-6 Sol): until a
+   * value of its own arrives, a rung takes at least its predecessor's value at the same effort
+   */
+  predecessor: z.string().min(1).optional(),
   /** a sync's speed facts (spec 1.2 §4.1), `<source>.<field>` → value; they never carry a bar */
   speed: z.record(z.string(), z.number()).optional(),
 });
@@ -211,6 +216,8 @@ export interface Catalog {
    * whose value it uses as `inferred` (spec 1.2 §6.1); filled by the stand-in ranking (services/standins.ts)
    */
   inferred: Record<string, Partial<Record<Dim, InferredStandIn>>>;
+  /** the thresholds the user's override set or removed, as `<kind>/<difficulty>/<dim>` (route says "your override") */
+  userBars?: string[];
 }
 
 /**
@@ -317,11 +324,14 @@ export function buildCatalog(o: {
   for (const [rung, like] of Object.entries(o.override?.treatLike ?? {}))
     treatLike[rung] = { like, source: "user" };
   const bars = structuredClone(o.scores.bars) as Bars;
+  const userBars: string[] = [];
   for (const kind of KINDS)
     for (const d of DIFFICULTIES)
-      for (const [dim, min] of Object.entries(o.override?.bars[kind]?.[d] ?? {}) as [Dim, number | null][])
+      for (const [dim, min] of Object.entries(o.override?.bars[kind]?.[d] ?? {}) as [Dim, number | null][]) {
+        userBars.push(`${kind}/${d}/${dim}`);
         if (min === null) delete bars[kind][d][dim];
         else bars[kind][d][dim] = min;
+      }
   return {
     families: o.facts ? applyFacts(o.models.families, o.facts) : o.models.families,
     backends: o.models.backends,
@@ -333,6 +343,7 @@ export function buildCatalog(o: {
     secs: o.secs ?? {},
     features: o.features ?? {},
     inferred: {},
+    userBars,
   };
 }
 

package/src/domain/changes.ts

@@ -33,6 +33,28 @@ export function changedPaths(before: Snapshot, after: Snapshot): string[] {
     .sort();
 }
 
+/** Spec 1.5 plan 21: a writer's implicit docs lane, when its brief names no Owns. */
+export const DOCS_OWNS = ["docs/**", "*.md"];
+
+/** The paths of an `Owns:` line in a brief (as a lane file writes it), or null when it has none. */
+export function briefOwns(brief: string): string[] | null {
+  const line = /^Owns:\s*(.+)$/m.exec(brief)?.[1];
+  const paths = line
+    ?.split(",")
+    .map((p) => p.trim().replace(/^`|`$/g, ""))
+    .filter(Boolean);
+  return paths?.length ? paths : null;
+}
+
+/**
+ * Whether `path` is inside an Owns entry: a path covers what is under it, and the other way round (as lanes'
+ * Owns always did); `dir/**` covers what is under dir; `*.ext` (no slash) is any file with that extension.
+ */
+export function ownsPath(path: string, entry: string): boolean {
+  if (entry.startsWith("*.") && !entry.includes("/")) return path.endsWith(entry.slice(1));
+  return overlaps([path], [entry.replace(/\/\*\*$/, "")]).length > 0;
+}
+
 /**
  * Spec §4.4: `changedOwned` are the changes inside the lane's Owns; `violations` the ones outside it
  * that no overlapping dispatch owns either. `strict` is false for a laneless dispatch that may write
@@ -44,7 +66,7 @@ export function splitChanges(
   others: string[],
   strict: boolean,
 ): { changedOwned: string[]; violations: string[] } {
-  const inside = (p: string, paths: string[]) => overlaps([p], paths).length > 0;
+  const inside = (p: string, paths: string[]) => paths.some((entry) => ownsPath(p, entry));
   return {
     changedOwned: changed.filter((p) => inside(p, owns)),
     violations: strict ? changed.filter((p) => !inside(p, owns) && !inside(p, others)) : [],

package/src/domain/cost.ts

@@ -51,19 +51,24 @@ export const CHATGPT_UNIT_USD = 0.019;
 export interface Cost {
   /** 0: paid from a subscription; 1: metered. Every tier-0 rung ranks before any tier-1 rung. */
   tier: 0 | 1;
-  /** comparable across billing modes, in list-price dollars per task; null when unknown */
+  /**
+   * comparable across billing modes, in list-price dollars per task; 0 for an unpriced rung paid from a plan or
+   * subscription (it spends nothing beyond the flat fee); null for an unpriced metered one
+   */
   value: number | null;
   mode: BillingMode;
 }
 
 /**
- * Spec §5.3. Every mode yields list-price dollars per task, so plans compare with each other:
+ * Spec §5.3. Every mode yields list-price dollars per task, so plans compare with each other. Spec 1.5 plan 24:
+ * a rung catherd has no price for costs 0 within its tier when a plan or subscription pays for it, so it can
+ * start a lane (the profile's ladder order then breaks the tie); a metered one stays unknown, last in its tier.
  * chatgpt-plan scales the official quota weight (Luna 1, Sol 20, Astra 60) by the effort factor;
  * claude-plan uses API prices as the proxy, with Fable metered (catherd cannot tell Pro from Max);
  * Go's share of its monthly dollar limit is dollars / limit, which orders the same as dollars.
  */
 export function costOf(family: Family | null, effort: string, mode: BillingMode): Cost {
-  if (!family) return { tier: mode === "metered" ? 1 : 0, value: null, mode };
+  if (!family) return mode === "metered" ? { tier: 1, value: null, mode } : { tier: 0, value: 0, mode };
   const usd = taskUsd(family.price, effort);
   switch (mode) {
     case "chatgpt-plan":