catherd-cli 1.4.0 → 1.5.0

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

@@ -16,6 +16,8 @@ import {
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { claudeHome } from "../../infra/paths.ts";
+import { ROLE_MCP_SERVER, roleMcpTools } from "../../domain/role-tools.ts";
+import { roleMcpConfig } from "../../infra/role-mcp.ts";
 import { dockerSocket, scratchShell, writableRoots } from "../access.ts";
 import { jsonOf, runCli } from "../cli.ts";
 import {
@@ -74,15 +76,21 @@ export const CLAUDE_ACCESS: Record<Access, string[]> = {
  * them Docker: the socket and `docker *` are network grants) and sets `allowLocalBinding: false`, so the
  * user's own `true` does not carry over (their allowedDomains and other array grants merge in and stay;
  * doctor says `network: false` is not enforced by claude-code's shell). With the user's sandbox on, `enabled: true`
- * goes in too, so a merge that replaces the whole `sandbox` object cannot turn it off.
+ * goes in too, so a merge that replaces the whole `sandbox` object cannot turn it off. A `repo` of null reads the
+ * user's settings only: a run that drops the project's settings files (`--setting-sources ""`).
  */
-export function claudeAccessArgs(access: Access, network = true, repo?: string): string[] {
+export function claudeAccessArgs(
+  access: Access,
+  network = true,
+  repo?: string | null,
+  extra: string[] = [],
+): string[] {
   const base = CLAUDE_ACCESS[access];
   if (access !== "workspace-write") return base;
   const sock = dockerSocket();
   const sandbox = {
     ...(claudeSandboxOn(repo) ? { enabled: true } : {}),
-    filesystem: { allowWrite: writableRoots() },
+    filesystem: { allowWrite: [...new Set([...writableRoots(), ...extra])] },
     ...(network
       ? {
           network: { allowLocalBinding: true, ...(sock ? { allowUnixSockets: [sock] } : {}) },
@@ -113,12 +121,14 @@ function sandboxEnabledIn(file: string): boolean | undefined {
  * Whether Claude Code's Bash sandbox is on for a worker in `repo` (`sandbox.enabled`): the most specific
  * settings file that says wins, as Claude Code layers them: the user's settings.json, then the project's
  * .claude/settings.json and .claude/settings.local.json (Claude Code has no user-level settings.local.json).
+ * A `repo` of null reads the user's settings.json only.
  */
-export function claudeSandboxOn(repo: string = process.cwd()): boolean {
+export function claudeSandboxOn(repo: string | null = process.cwd()): boolean {
   const files = [
     join(claudeHome(), "settings.json"),
-    join(repo, ".claude", "settings.json"),
-    join(repo, ".claude", "settings.local.json"),
+    ...(repo === null
+      ? []
+      : [join(repo, ".claude", "settings.json"), join(repo, ".claude", "settings.local.json")]),
   ];
   return files.map(sandboxEnabledIn).findLast((on) => on !== undefined) ?? false;
 }
@@ -128,17 +138,114 @@ export function claudeSandboxOn(repo: string = process.cwd()): boolean {
  * shell, which doctor probes as is. With it on, only a model turn runs inside it, so doctor says what to
  * check instead of spending one.
  */
-async function accessShell(): Promise<AccessShell | string> {
-  if (claudeSandboxOn())
-    return "Claude Code's own sandbox is on (sandbox.enabled): catherd passes the lock, temp, loopback and Docker grants in --settings; outbound HTTPS reaches only sandbox.network.allowedDomains, so add registry.npmjs.org and the hosts your checks need there";
+async function accessShell(o: { repos?: string[] } = {}): Promise<AccessShell | string> {
+  // the setting is per repo (its .claude/settings*.json over the user's): each repo a worker runs in counts,
+  // not only the directory doctor runs in
+  const repos = o.repos?.length ? o.repos : [process.cwd()];
+  const on = repos.filter((r) => claudeSandboxOn(r));
+  if (on.length)
+    return `Claude Code's own sandbox is on (sandbox.enabled)${o.repos?.length ? ` in ${on.join(", ")}` : ""}: catherd passes the lock, temp, loopback and Docker grants in --settings; outbound HTTPS reaches only sandbox.network.allowedDomains, so add registry.npmjs.org and the hosts your checks need there`;
   return scratchShell("an unsandboxed shell (Claude Code's sandbox is off)", []);
 }
 
+/**
+ * An isolated run without the user's customizations. --bare would also drop OAuth, so a Claude plan could not
+ * log in; --safe-mode keeps auth, but drops every --mcp-config server too (Claude Code 2.1.287: "--mcp-config:
+ * … ignored (safe mode)"). A run with the role server (spec 1.5 plan 21, #42 finding 1) gets the same isolation
+ * piece by piece instead: only the --mcp-config servers, no settings file (so no hooks, no enabled plugins), no
+ * skills, CLAUDE.md and auto-memory off through the env, and the user's auth, provider, model, deny rules and
+ * allowed domains carried into --settings (carriedUserSettings).
+ */
+/** The user settings keys --setting-sources "" would drop that a run needs: auth, provider and model. */
+const CARRIED_SETTINGS = [
+  "apiKeyHelper",
+  "env",
+  "awsAuthRefresh",
+  "awsCredentialExport",
+  "gcpAuthRefresh",
+  "model",
+] as const;
+
+/**
+ * What an isolated run with the role server keeps of the user's settings.json (plan 21 review, finding 1):
+ * --safe-mode keeps the settings files and drops only customizations, while `--setting-sources ""` drops the
+ * files, so a Bedrock, Vertex, gateway or apiKeyHelper login would fail. Carried: the auth and provider keys,
+ * `model`, `permissions.deny` and `sandbox.network`; never hooks, plugins, allow rules or the rest.
+ */
+function carriedUserSettings(): Record<string, unknown> {
+  let user: Record<string, any>;
+  try {
+    user = JSON.parse(readFileSync(join(claudeHome(), "settings.json"), "utf8"));
+  } catch {
+    return {};
+  }
+  if (!user || typeof user !== "object") return {};
+  const out: Record<string, unknown> = {};
+  for (const k of CARRIED_SETTINGS) if (user[k] !== undefined) out[k] = user[k];
+  const deny = user.permissions?.deny;
+  if (Array.isArray(deny) && deny.length) out.permissions = { deny };
+  const network = user.sandbox?.network;
+  if (network && typeof network === "object") out.sandbox = { network };
+  return out;
+}
+
+/** `--settings` with the user's carried keys merged under catherd's own: catherd's sandbox grants win. */
+function withCarriedSettings(args: string[]): string[] {
+  const carried = carriedUserSettings();
+  if (!Object.keys(carried).length) return args;
+  const at = args.indexOf("--settings");
+  const own: Record<string, any> = at >= 0 ? JSON.parse(args[at + 1] as string) : {};
+  const userNet: Record<string, unknown> = (carried.sandbox as any)?.network ?? {};
+  const ownNet: Record<string, unknown> = own.sandbox?.network ?? {};
+  const sockets = [
+    ...((userNet.allowUnixSockets as string[] | undefined) ?? []),
+    ...((ownNet.allowUnixSockets as string[] | undefined) ?? []),
+  ];
+  const sandbox =
+    carried.sandbox || own.sandbox
+      ? {
+          sandbox: {
+            ...own.sandbox,
+            network: {
+              ...userNet,
+              ...ownNet,
+              ...(sockets.length ? { allowUnixSockets: [...new Set(sockets)] } : {}),
+            },
+          },
+        }
+      : {};
+  const json = JSON.stringify({ ...carried, ...own, ...sandbox });
+  if (at < 0) return [...args, "--settings", json];
+  const out = [...args];
+  out[at + 1] = json;
+  return out;
+}
+
+function isolationArgs(r: RunRequest): string[] {
+  if (!r.roleMcp) return ["--safe-mode"];
+  return ["--strict-mcp-config", "--setting-sources", "", "--disable-slash-commands"];
+}
+
 function plan(r: RunRequest): SpawnPlan {
   if (r.thread !== null && !THREAD.test(r.thread))
     throw new CatherdError("E_ADMIT_THREAD", `"${r.thread}" is not a Claude Code session id`, {
       fix: "pass the thread from the earlier RunRecord",
     });
+  // isolated with the role server, `--setting-sources ""` drops the project's settings (its network grants too),
+  // so only the user's carried settings.json decides whether the sandbox is on (PR #46)
+  const carried = r.isolated && !!r.roleMcp;
+  const access = claudeAccessArgs(r.access, r.network, carried ? null : r.repo, r.scratch ? [r.scratch] : []);
+  const accessArgs = carried ? withCarriedSettings(access) : [...access];
+  if (r.roleMcp) {
+    const tools = roleMcpTools(r.roleMcp.role).map((tool) => `mcp__${ROLE_MCP_SERVER}__${tool}`);
+    const allowed = accessArgs.indexOf("--allowedTools");
+    if (allowed >= 0) accessArgs[allowed + 1] = [accessArgs[allowed + 1], ...tools].join(",");
+    else accessArgs.push("--allowedTools", tools.join(","));
+    accessArgs.push(
+      "--mcp-config",
+      JSON.stringify({ mcpServers: { [ROLE_MCP_SERVER]: roleMcpConfig(r.roleMcp) } }),
+    );
+  }
   return {
     cmd: "claude",
     args: [
@@ -154,11 +261,14 @@ function plan(r: RunRequest): SpawnPlan {
       ...(r.thread === null ? ["--session-id", crypto.randomUUID()] : ["--resume", r.thread]),
       "--permission-prompts",
       "none",
-      ...claudeAccessArgs(r.access, r.network, r.repo),
-      // --bare would also drop OAuth, so a Claude plan could not log in; --safe-mode keeps auth
-      ...(r.isolated ? ["--safe-mode"] : []),
+      ...accessArgs,
+      ...(r.isolated ? isolationArgs(r) : []),
     ],
-    env: {},
+    // CLAUDE.md and auto-memory off, as --safe-mode turns them off (spec 1.5 plan 21)
+    env:
+      r.isolated && r.roleMcp
+        ? { CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1", CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1" }
+        : {},
     cwd: r.repo,
     stdinPath: r.briefPath,
   };
@@ -232,7 +342,9 @@ function claudeActivity(e: Record<string, any>): string | undefined {
     if (typeof input.command === "string") return `$ ${input.command}`;
     if (typeof input.file_path === "string")
       return `${EDIT_TOOLS.has(c.name) ? "edit" : String(c.name)} ${input.file_path}`;
-    return String(c.name ?? "tool");
+    // another tool shows its first string argument, as opencode's activity does
+    const first = Object.values(input).find((v) => typeof v === "string");
+    return `${String(c.name ?? "tool")}${typeof first === "string" ? ` ${first}` : ""}`;
   }
   if (c?.type === "text" && typeof c.text === "string") return c.text;
   return undefined;

package/src/adapters/codex/events.ts

@@ -8,6 +8,8 @@ export interface CodexFold {
   limit: boolean;
   tooOld: boolean;
   lastEvent: string | null;
+  /** plan 22: the agent message that ended each completed turn, in order */
+  finals: string[];
 }
 
 /**
@@ -43,10 +45,18 @@ export function foldCodexEvents(lines: string[]): CodexFold {
     limit: false,
     tooOld: false,
     lastEvent: null,
+    finals: [],
   };
+  let said: string | null = null;
   for (const line of lines) {
     const e = parseCodexLine(line);
     if (!e) continue;
+    if (e.type === "item.completed" && e.item?.type === "agent_message" && typeof e.item.text === "string")
+      said = e.item.text;
+    if (e.type === "turn.completed" && said !== null) {
+      f.finals.push(said);
+      said = null;
+    }
     f.lastEvent = e.item?.type ? `${e.type}/${e.item.type}` : e.type;
     const msg: string = e.message ?? e.error?.message ?? e.item?.message ?? "";
     if (CODEX_TOO_OLD.some((r) => r.test(msg))) f.tooOld = true;

package/src/adapters/codex/index.ts

@@ -1,7 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { codexRoleMcpArgs } from "../../infra/role-mcp.ts";
 import { CatherdError } from "../../domain/errors.ts";
 import type { Access, RunStatus } from "../../domain/record.ts";
+import { composeReply } from "../../domain/reply.ts";
 import {
   type AccessShell,
   type BackendAdapter,
@@ -57,9 +59,14 @@ export function userWritableRoots(): string[] {
  * The same `-c` overrides go to `codex sandbox` in doctor's probes, so doctor tests exactly what a worker gets. `-c …writable_roots=` replaces the
  * user's own roots, so theirs go in too; an isolated run ignores the user's config, so it has none.
  */
-export function codexGrants(access: Access, network = true, isolated = false): string[] {
+export function codexGrants(
+  access: Access,
+  network = true,
+  isolated = false,
+  extra: string[] = [],
+): string[] {
   if (access !== "workspace-write") return [];
-  const roots = [...new Set([...(isolated ? [] : userWritableRoots()), ...writableRoots()])];
+  const roots = [...new Set([...(isolated ? [] : userWritableRoots()), ...writableRoots(), ...extra])];
   return [
     "-c",
     `sandbox_workspace_write.network_access=${network}`,
@@ -89,7 +96,8 @@ function plan(r: RunRequest): SpawnPlan {
     "--json",
     "-o",
     r.replyPath,
-    ...codexGrants(r.access, r.network, r.isolated),
+    ...codexGrants(r.access, r.network, r.isolated, r.scratch ? [r.scratch] : []),
+    ...(r.roleMcp ? codexRoleMcpArgs(r.roleMcp) : []),
   ];
   const sandbox = SANDBOX[r.access];
   const args =
@@ -125,6 +133,7 @@ function finalize(run: FinishedRun): Outcome {
                 : "ok";
   const lastErr = run.stderr.trim().split("\n").at(-1) ?? "";
   const home = run.request.isolated ? isolatedCodexHomePath() : userCodexHome();
+  const reply = composeReply(f.finals, run.reply);
   return {
     status,
     thread: f.thread ?? run.request.thread,
@@ -138,6 +147,8 @@ function finalize(run: FinishedRun): Outcome {
             code: status,
             message: f.failure ?? (lastErr || `${stopped}, exit ${run.exit.code ?? run.exit.signal}`),
           },
+    // plan 22: -o keeps the last turn's message; a later turn never overwrites the report
+    ...(reply !== run.reply ? { reply } : {}),
   };
 }
 
@@ -243,7 +254,7 @@ function codexActivity(e: Record<string, any>): string | undefined {
     return `edit ${it.changes
       .map((c: { path?: unknown }) => c.path)
       .filter((p: unknown) => typeof p === "string")
-      .join(", ")}`;
+      .join(", ")}`.trimEnd();
   if (it.type === "agent_message" && typeof it.text === "string") return it.text;
   return undefined;
 }
@@ -263,12 +274,13 @@ export const codexAdapter: BackendAdapter = {
     // Not a todo_list: update_plan opens one that only completes with the turn, and would mute the watchdog
     const id = typeof e.item?.id === "string" && CODEX_TOOL_ITEMS.has(e.item.type) ? e.item.id : null;
     const open = e.type === "item.started" ? true : e.type === "item.completed" ? false : null;
+    const activity = codexActivity(e);
     return {
       ...(f.thread ? { thread: f.thread } : {}),
       ...(id !== null && open !== null ? { item: { id, open } } : {}),
       ...(e.type === "turn.completed" ? { tokens: f.tokens } : {}),
       lastEvent: f.lastEvent ?? undefined,
-      ...(codexActivity(e) ? { activity: codexActivity(e) } : {}),
+      ...(activity ? { activity } : {}),
       ...(f.turnFailed ? { failure: f.failure ?? "turn failed" } : {}),
       ...(f.limit ? { limit: true } : {}),
       ...(f.tooOld ? { tooOld: true } : {}),

package/src/adapters/cursor/index.ts

@@ -100,7 +100,13 @@ function plan(r: RunRequest): SpawnPlan {
 }
 
 async function listModels(): Promise<DiscoveredModel[]> {
-  const r = await runCli(cursorBin(), ["models"], { ...cursorShell, env: { NO_OPEN_BROWSER: "1" } });
+  const bin = cursorBin();
+  // an `agent` that is not Cursor's (grok's, say) is never asked for models: nothing to list, as when absent
+  if (bin === "agent") {
+    const v = await runCli(bin, ["--version"], cursorShell).catch(() => null);
+    if (!v || !CURSOR_VERSION.test(v.out)) return [];
+  }
+  const r = await runCli(bin, ["models"], { ...cursorShell, env: { NO_OPEN_BROWSER: "1" } });
   return r?.ok ? parseCursorModels(r.out) : [];
 }
 

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

@@ -50,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),

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");
 }