catherd-cli 1.5.0 → 2.0.0-beta.20261022113309

package/src/adapters/grok/events.ts

@@ -1,112 +0,0 @@
-import { type Tokens, ZERO_TOKENS } from "../../domain/record.ts";
-
-export interface GrokEnd {
-  stopReason: string;
-  thread: string | null;
-  tokens: Tokens;
-  /** only when the server reported the whole cost (API-key traffic); absent is unknown, never free */
-  costUsd: number | null;
-}
-
-export interface GrokFold {
-  /** the text after the last tool call: the worker's final message (spec 1.3 §5.5) */
-  reply: string;
-  end: GrokEnd | null;
-  /** a terminal `error` event's message: a run that never started a turn prints one instead of `end` */
-  error: string | null;
-  /** the sum of the per-response `usage` events, for a stream with no `end` */
-  used: Tokens;
-  lastEvent: string | null;
-}
-
-/**
- * Research §3.10: the limit texts of the 1.0.44 binary ([bin] "rate limit for your plan", "free Grok Build
- * usage limit", "temporarily overloaded") and of the 2026-09-25 research's source read. Their apostrophes are
- * U+2019, so no pattern spells one.
- */
-export const GROK_LIMIT = [
-  /rate limit/i,
-  /usage limit/i,
-  /too many requests/i,
-  /resource.exhausted/i,
-  /at capacity/i,
-  /temporarily overloaded/i,
-];
-/** A plan without Grok Build: no wait fixes it. */
-export const GROK_NOT_LIMIT = [/requires a Grok subscription/i];
-/** clap's error for a flag this grok does not know, exit 2 (research §3.3 [run]). */
-export const GROK_TOO_OLD = [/unexpected argument '/i];
-/** research §3.3 [run]: a logged-out run's one error event */
-const GROK_AUTH = [/Not signed in/i];
-
-type Event = Record<string, any>;
-
-export function parseGrokLine(line: string): Event | null {
-  if (!line.trim().startsWith("{")) return null;
-  try {
-    const e = JSON.parse(line) as unknown;
-    return e && typeof e === "object" && !Array.isArray(e) ? (e as Event) : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Spec 1.3 §5.5: `input_tokens` is uncached only (research §3.3), so input adds the cache reads and writes. */
-export function grokTokens(u: Event | undefined): Tokens {
-  if (!u) return { ...ZERO_TOKENS };
-  const n = (k: string) => (typeof u[k] === "number" ? (u[k] as number) : 0);
-  const cached = n("cache_read_input_tokens");
-  return {
-    input: n("input_tokens") + cached + n("cache_creation_input_tokens"),
-    cached,
-    output: n("output_tokens"),
-  };
-}
-
-export const isLimit = (text: string): boolean =>
-  GROK_LIMIT.some((r) => r.test(text)) && !GROK_NOT_LIMIT.some((r) => r.test(text));
-export const isTooOld = (text: string): boolean => GROK_TOO_OLD.some((r) => r.test(text));
-export const isAuthFailure = (text: string): boolean => GROK_AUTH.some((r) => r.test(text));
-
-export function eventName(e: Event): string {
-  if (e.type === "tool_call") return `tool_call/${e.toolName ?? e.kind ?? "?"}`;
-  if (e.type === "tool_call_update") return `tool_call_update/${e.status ?? "?"}`;
-  return String(e.type ?? "?");
-}
-
-/** Spec §3.7: a command the worker runs, a file it reads or edits, or its message. */
-export function grokActivity(e: Event): string | undefined {
-  if (e.type === "text") return typeof e.data === "string" && e.data.trim() ? e.data : undefined;
-  if (e.type !== "tool_call") return undefined;
-  const input = (e.rawInput ?? {}) as Event;
-  if (typeof input.command === "string") return `$ ${input.command}`;
-  if (typeof input.path === "string") return `${e.kind === "read" ? "read" : "edit"} ${input.path}`;
-  return String(e.title ?? e.toolName ?? "tool");
-}
-
-export function foldGrokEvents(lines: string[]): GrokFold {
-  const f: GrokFold = { reply: "", end: null, error: null, used: { ...ZERO_TOKENS }, lastEvent: null };
-  for (const line of lines) {
-    const e = parseGrokLine(line);
-    if (!e) continue;
-    f.lastEvent = eventName(e);
-    if (e.type === "tool_call" || e.type === "tool_call_update") f.reply = "";
-    else if (e.type === "text" && typeof e.data === "string") f.reply += e.data;
-    else if (e.type === "usage") {
-      const t = grokTokens(e.usage);
-      f.used = {
-        input: f.used.input + t.input,
-        cached: f.used.cached + t.cached,
-        output: f.used.output + t.output,
-      };
-    } else if (e.type === "end")
-      f.end = {
-        stopReason: String(e.stopReason ?? "?"),
-        thread: typeof e.sessionId === "string" && e.sessionId ? e.sessionId : null,
-        tokens: e.usage ? grokTokens(e.usage) : f.used,
-        costUsd: typeof e.total_cost_usd === "number" ? e.total_cost_usd : null,
-      };
-    else if (e.type === "error") f.error = String(e.message ?? "error");
-  }
-  return f;
-}

package/src/adapters/grok/home.ts

@@ -1,187 +0,0 @@
-import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { CatherdError } from "../../domain/errors.ts";
-import type { Access } from "../../domain/record.ts";
-import { dataDir } from "../../infra/paths.ts";
-import { writeTextAtomic } from "../../infra/store.ts";
-import { movedHomeEnv, writableRoots } from "../access.ts";
-
-/** The user's GROK_HOME: grok's config, login, sessions and sandbox profiles. */
-export const userGrokHome = (): string => process.env.GROK_HOME || join(homedir(), ".grok");
-
-/** Where isolated grok runs keep their HOME; computing it creates nothing. */
-export const isolatedGrokRoot = (): string => join(dataDir(), "grok-home");
-
-/** The Claude Code and Cursor compatibility toggles of grok's config reference (research §3.8). */
-const COMPAT = ["CLAUDE", "CURSOR"].flatMap((tool) =>
-  ["AGENTS", "RULES", "SKILLS", "MCPS", "HOOKS"].map((what) => `GROK_${tool}_${what}_ENABLED`),
-);
-
-/**
- * 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(home = isolatedGrokRoot()): Record<string, string> {
-  return {
-    ...movedHomeEnv(home),
-    GROK_HOME: join(home, ".grok"),
-    GROK_MEMORY: "0",
-    ...Object.fromEntries(COMPAT.map((k) => [k, "0"])),
-  };
-}
-
-/** What stops grok's kernel read-only profile here (research §3.6); tests point it elsewhere. */
-export const grokHost = { platform: process.platform as string, dockerSocket: "/var/run/docker.sock" };
-
-/** The tools a read-only role keeps where grok's read-only profile refuses to start (spec 1.3 §5.3). */
-export const READ_TOOLS = "read_file,grep,list_dir,web_search,web_fetch";
-
-/**
- * Spec 1.3 §5.3: grok refuses `read-only` (and every profile extending it) on a Mac whose docker socket is a
- * symlink (Docker Desktop, OrbStack, Colima; research §3.6 [run]), so a read-only role there runs in the
- * `workspace` profile with only the read tools: advisory, where the kernel profile is enforced.
- */
-export function readOnlyRefused(): boolean {
-  return (
-    grokHost.platform === "darwin" &&
-    lstatSync(grokHost.dockerSocket, { throwIfNoEntry: false })?.isSymbolicLink() === true
-  );
-}
-
-/** Spec 1.3 §5.3: the sandbox profile (and, where read-only cannot apply, the tool filter) of each access. */
-export function grokAccess(access: Access, network = true): string[] {
-  if (access === "full") return ["--sandbox", "off"];
-  if (access === "workspace-write") return ["--sandbox", network ? "catherd-ws" : "catherd-ws-offline"];
-  return readOnlyRefused() ? ["--sandbox", "workspace", "--tools", READ_TOOLS] : ["--sandbox", "read-only"];
-}
-
-/**
- * catherd's sandbox profiles: `workspace` plus catherd's writable roots (literal directories; research §3.6),
- * and the same without child network (Linux only; macOS has no child-network control).
- */
-export function catherdProfiles(): Record<string, Record<string, unknown>> {
-  const read_write = writableRoots();
-  return {
-    "catherd-ws": { extends: "workspace", read_write },
-    "catherd-ws-offline": { extends: "workspace", read_write, restrict_network: true },
-  };
-}
-
-const BEGIN = "# >>> catherd";
-const END = "# <<< catherd";
-const HEADER = `${BEGIN}'s sandbox profiles for its grok workers: catherd rewrites this block, so edit outside it`;
-
-const tomlError = (text: string): string | null => {
-  try {
-    Bun.TOML.parse(text);
-    return null;
-  } catch (e) {
-    return e instanceof Error ? e.message : String(e);
-  }
-};
-
-/** 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`: 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,
-  profiles = catherdProfiles(),
-): { text: string } | { why: string } {
-  const start = text.indexOf(BEGIN);
-  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` };
-  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 =
-    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 };
-}
-
-/**
- * Spec 1.3 §5.3, §9 Q3: puts catherd's `[profiles.catherd-*]` tables into `home`'s sandbox.toml (grok reads
- * custom profiles only there or in the repo's `.grok/`), keeping the file's mode; the rest of the file is the
- * user's. Throws E_CONFIG_INVALID, touching nothing, when catherd must not write it.
- */
-export function writeGrokProfiles(home: string): void {
-  const path = join(home, "sandbox.toml");
-  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;
-  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,358 +0,0 @@
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-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";
-import { assetPath } from "../../infra/assets.ts";
-import { ensurePrivateDir } from "../../infra/store.ts";
-import { realTmpdir } from "../access.ts";
-import {
-  type BackendAdapter,
-  compareVersions,
-  type DiscoveredModel,
-  type EventDelta,
-  extractVersion,
-  type FinishedRun,
-  type Outcome,
-  type Probe,
-  type RunRequest,
-  type SpawnPlan,
-} from "../backend.ts";
-import { runCli } from "../cli.ts";
-import { discovered } from "../discovery.ts";
-import {
-  eventName,
-  foldGrokEvents,
-  GROK_LIMIT,
-  GROK_TOO_OLD,
-  grokActivity,
-  grokTokens,
-  isAuthFailure,
-  isLimit,
-  isTooOld,
-  parseGrokLine,
-} from "./events.ts";
-import {
-  grokAccess,
-  grokHomeEnv,
-  isolatedGrokRoot,
-  readOnlyRefused,
-  userGrokHome,
-  writeGrokProfiles,
-} from "./home.ts";
-import { parseGrokModels, type ShippedGrok } from "./models.ts";
-
-export { isolatedGrokRoot } from "./home.ts";
-
-/** Spec 1.3 §5.1: the version whose help, docs and argument checks were read (research §3). */
-export const GROK_MIN_VERSION = "1.0.44";
-export const GROK_INSTALL = "curl -fsSL https://x.ai/cli/install.sh | bash";
-const THREAD = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const DAY_MS = 24 * 60 * 60_000;
-const LOGIN_FIX = "grok login, or grok login --device-code without a browser, or export XAI_API_KEY=<key>";
-/** research §3.1 [doc 14]: grok never updates itself under a worker or a probe */
-const NO_UPDATE = { GROK_DISABLE_AUTOUPDATER: "1" };
-
-/** How long a `grok` query (version, models, the sandbox check) may take before it counts as failed. */
-export const grokShell = { timeoutMs: 15_000 };
-
-/**
- * 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(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)}`;
-}
-
-/** Whether grok got as far as a session: any event but a lone terminal error (not signed in, a bad flag). */
-const sessionStarted = (lines: string[]): boolean =>
-  lines.some((l) => {
-    try {
-      return (JSON.parse(l) as { type?: unknown }).type !== "error";
-    } catch {
-      return false;
-    }
-  });
-
-function plan(r: RunRequest): SpawnPlan {
-  if (r.thread !== null && !THREAD.test(r.thread))
-    throw new CatherdError("E_ADMIT_THREAD", `"${r.thread}" is not a grok session id`, {
-      fix: "pass the thread from the earlier RunRecord",
-    });
-  const access = grokAccess(r.access, r.network !== false);
-  return {
-    cmd: "grok",
-    args: [
-      // headless grok never reads stdin (research §3.2 [doc 14]): the brief goes by file
-      "--prompt-file",
-      r.briefPath,
-      "--output-format",
-      "streaming-json",
-      "--cwd",
-      r.repo,
-      "-m",
-      r.rung.model,
-      ...(r.rung.effort === "default" ? [] : ["--effort", r.rung.effort]),
-      // hidden (research §3.2 [run]): trust for this session, no self-update, no memory (spec 1.3 §9 Q8)
-      "--always-approve",
-      "--trust",
-      "--no-auto-update",
-      "--no-memory",
-      // a fresh session takes catherd's id; a resumed one keeps the profile it started with and refuses
-      // another (research §3.5), while a tool filter is no profile: a read-only role keeps its read tools
-      ...(r.thread === null
-        ? [...access, "-s", sessionFor(r)]
-        : [...(access.includes("--tools") ? access.slice(-2) : []), "-r", r.thread]),
-    ],
-    env: { ...NO_UPDATE, ...(r.isolated ? grokHomeEnv() : {}) },
-    cwd: r.repo,
-    stdinPath: null,
-  };
-}
-
-/** The catalog's grok models (`on.grok`): grok lists no efforts (research §3.4), the catalog does. */
-let shipped: ShippedGrok | null = null;
-function shippedOnGrok(): ShippedGrok {
-  if (shipped) return shipped;
-  const doc = JSON.parse(readFileSync(assetPath("catalog/models.json"), "utf8")) as {
-    families: { on: Record<string, { id: string; efforts: string[]; context?: number } | undefined> }[];
-  };
-  shipped = {};
-  for (const f of doc.families)
-    if (f.on.grok) shipped[f.on.grok.id] = { efforts: f.on.grok.efforts, context: f.on.grok.context ?? null };
-  return shipped;
-}
-
-/** `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
- * sandbox.toml of the GROK_HOME it runs with; the model must be one grok lists, at an effort the catalog offers.
- */
-async function prepare(req: {
-  rung: Rung;
-  access: Access;
-  isolated: boolean;
-  repo: string;
-  network?: boolean;
-}): Promise<void> {
-  if (req.isolated && !process.env.XAI_API_KEY)
-    throw new CatherdError("E_BACKEND_NOT_LOGGED_IN", "an isolated grok run needs XAI_API_KEY", {
-      fix: "export XAI_API_KEY=<key>, or catherd profile set harness.grok.isolated false",
-    });
-  const home = req.isolated ? join(isolatedGrokRoot(), ".grok") : userGrokHome();
-  if (req.isolated) ensurePrivateDir(home);
-  if (req.access === "workspace-write") writeGrokProfiles(home);
-  const { model, effort } = req.rung;
-  // 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)
-    throw new CatherdError("E_BACKEND_MODEL_UNKNOWN", `grok does not list ${model}`, {
-      fix: "run grok models, and use a model it lists",
-    });
-  if (effort !== "default" && m.efforts.length > 0 && !m.efforts.includes(effort))
-    throw new CatherdError("E_BACKEND_MODEL_UNKNOWN", `${model} has no effort "${effort}" on grok`, {
-      fix: `use one of: ${["default", ...m.efforts].map((e) => `grok:${model}#${e}`).join(", ")}`,
-    });
-}
-
-function finalize(run: FinishedRun): Outcome {
-  const f = foldGrokEvents(run.eventLines);
-  const stopped = run.exit.reason;
-  const said = f.error ?? run.stderr;
-  const status: RunStatus =
-    stopped === "cancelled"
-      ? "cancelled"
-      : stopped === "idle-timeout" || stopped === "wall-timeout"
-        ? "timeout"
-        : f.end?.stopReason === "end_turn"
-          ? "ok"
-          : f.end
-            ? "failed"
-            : run.exit.code === 2 || isTooOld(run.stderr)
-              ? "cli-too-old"
-              : isLimit(said)
-                ? "limit"
-                : "failed";
-  const errLines = run.stderr.trim().split("\n");
-  // clap's usage lines follow its error: the error line says what went wrong
-  const lastErr = errLines.find((l) => isTooOld(l)) ?? errLines.at(-1) ?? "";
-  const message = f.end
-    ? `stopped: ${f.end.stopReason}`
-    : isAuthFailure(said)
-      ? `grok is not signed in (fix: ${LOGIN_FIX})`
-      : f.error || lastErr || `no end event (${stopped}, exit ${run.exit.code ?? run.exit.signal})`;
-  return {
-    status,
-    thread:
-      f.end?.thread ??
-      run.request.thread ??
-      (sessionStarted(run.eventLines) ? sessionFor(run.request) : null),
-    tokens: f.end?.tokens ?? f.used,
-    costUsd: f.end?.costUsd ?? null,
-    images: [],
-    error: status === "ok" ? null : { code: status, message },
-    ...(status === "ok" ? { reply: f.reply } : {}),
-  };
-}
-
-function parse(line: string): EventDelta {
-  const e = parseGrokLine(line);
-  if (!e) return {};
-  const d: EventDelta = { lastEvent: eventName(e) };
-  const activity = grokActivity(e);
-  if (activity) d.activity = activity;
-  // a tool call runs from its tool_call until an update leaves in_progress, often printing nothing: busy
-  if ((e.type === "tool_call" || e.type === "tool_call_update") && typeof e.toolCallId === "string")
-    d.item = { id: e.toolCallId, open: e.type === "tool_call" || e.status === "in_progress" };
-  // one usage event per model response (research §3.3): the input that response read
-  if (e.type === "usage") d.requestInput = grokTokens(e.usage).input;
-  if (e.type === "end") {
-    d.final = true;
-    d.tokens = grokTokens(e.usage);
-    if (typeof e.sessionId === "string" && e.sessionId) d.thread = e.sessionId;
-    if (typeof e.total_cost_usd === "number") d.costUsd = e.total_cost_usd;
-    if (e.stopReason !== "end_turn") d.failure = `stopped: ${e.stopReason}`;
-  }
-  // research §3.3 [run]: a run that cannot go on prints an error and no end
-  if (e.type === "error") {
-    d.final = true;
-    d.failure = String(e.message ?? "error");
-    if (isLimit(d.failure)) d.limit = true;
-  }
-  return d;
-}
-
-/**
- * Spec 1.3 §5.6: doctor's `sandbox:grok` row, from a run that spends no turn: grok applies its sandbox before it
- * checks the login (research §3.6 [run]), so from an empty GROK_HOME with no API key the run stops at the
- * refusal when read-only cannot apply here, else at "Not signed in".
- */
-async function sandboxInfo(): Promise<{ id: string; label: string; detail: string } | null> {
-  const home = mkdtempSync(join(realTmpdir(), "catherd-grok-check-"));
-  try {
-    const r = await runCli(
-      "grok",
-      ["-p", "hi", "--output-format", "streaming-json", "--sandbox", "read-only", "--no-auto-update"],
-      // 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);
-    const why = r.err
-      .split("\n")
-      .find((l) => l.startsWith("warning: "))
-      ?.slice("warning: ".length);
-    const detail = !refused
-      ? "grok's read-only profile applies here; catherd runs a read-only role in it (enforced)"
-      : `grok refuses its read-only profile here${why ? ` (${why})` : ""}; ${
-          readOnlyRefused()
-            ? "catherd runs a read-only role in the workspace profile with the read tools only (advisory)"
-            : "a read-only grok role fails here: give it another backend or full access"
-        }`;
-    return { id: "sandbox:grok", label: "grok sandbox", detail };
-  } finally {
-    rmSync(home, { recursive: true, force: true });
-  }
-}
-
-/**
- * Spec 1.3 §5.1, §5.6. Logged in: the first line of `grok models`, which answers fast, with no browser, when
- * logged out (research §3.4 [run]); a Grok login bills the subscription, an API key per token. A grok the OS
- * cannot execute (a Linux build on macOS, research §3.1) throws here, and probeBackend reports it.
- */
-async function probe(): Promise<Probe> {
-  const v = await runCli("grok", ["--version"], { ...grokShell, env: NO_UPDATE });
-  if (!v)
-    return {
-      installed: false,
-      version: null,
-      versionOk: false,
-      loggedIn: null,
-      problems: [{ code: "E_BACKEND_MISSING", message: "grok is not on PATH", fix: GROK_INSTALL }],
-    };
-  const version = extractVersion(v.out);
-  const versionOk = version !== null && compareVersions(version, GROK_MIN_VERSION) >= 0;
-  const m = await runCli("grok", ["models"], { ...grokShell, env: NO_UPDATE });
-  const { loggedIn, login } = parseGrokModels(`${m?.out ?? ""}\n${m?.err ?? ""}`);
-  const problems: Probe["problems"] = [];
-  if (!versionOk)
-    problems.push({
-      code: "E_BACKEND_TOO_OLD",
-      message: `grok ${version ?? "?"} is older than ${GROK_MIN_VERSION}`,
-      fix: "grok update --stable",
-    });
-  if (loggedIn === false)
-    problems.push({
-      code: "E_BACKEND_NOT_LOGGED_IN",
-      message: "grok is not logged in (grok models says: You are not authenticated.)",
-      fix: LOGIN_FIX,
-    });
-  const info = await sandboxInfo();
-  return {
-    installed: true,
-    version,
-    versionOk,
-    loggedIn,
-    ...(login
-      ? { login, billing: login === "API key" ? ("metered" as const) : ("subscription" as const) }
-      : {}),
-    problems,
-    ...(info ? { info: [info] } : {}),
-  };
-}
-
-export const grokAdapter: BackendAdapter = {
-  id: "grok",
-  minVersion: GROK_MIN_VERSION,
-  install: GROK_INSTALL,
-  probe,
-  listModels,
-  prepare,
-  plan,
-  parse,
-  finalize,
-  // spec 1.3 §5.3: the kernel holds each profile, except read-only where only a tool allowlist can (a Mac with a
-  // symlinked docker socket); on macOS no profile controls the network
-  enforcement: {
-    get "read-only"() {
-      return readOnlyRefused() ? "advisory" : "enforced";
-    },
-    "workspace-write": "enforced",
-    full: "enforced",
-  },
-  errors: { limit: GROK_LIMIT, tooOld: GROK_TOO_OLD },
-  // a session keeps the sandbox profile it started with and refuses another (research §3.5)
-  resume: { supported: true, sameAccessOnly: true, threadPattern: THREAD },
-  isolationNote:
-    "native grok loads your Claude Code plugins, agents, skills, hooks and permission rules, and your Cursor rules and MCP",
-  isolationKey: "XAI_API_KEY",
-  // a one-shot run may drain uploads for ~150 s after end (research §3.3); the record is complete at end
-  graceAfterFinalMs: 30_000,
-  reportsCost: true,
-};