catherd-cli 1.2.1 → 1.4.0

package/src/adapters/cli.ts

@@ -1,67 +1,4 @@
-import { scrubSecrets } from "../infra/env.ts";
-import { log } from "../infra/log.ts";
-import { killGroup } from "../infra/proc.ts";
-
-export interface CliResult {
-  ok: boolean;
-  out: string;
-  err: string;
-}
-
-/** Process groups of CLI calls still running: an exiting catherd (Ctrl-C is exit 130) kills them. */
-const live = new Set<number>();
-let hooked = false;
-function track(pid: number): void {
-  live.add(pid);
-  if (hooked) return;
-  hooked = true;
-  // a detached group gets no terminal SIGINT, and process.exit skips the timeout, so kill it on the way out
-  process.on("exit", () => {
-    for (const g of live) killGroup(g, "SIGKILL");
-  });
-}
-
-/**
- * Runs `bin <args>` without catherd's secrets and with no stdin; null when `bin` is not on PATH. A call
- * past `timeoutMs` is killed with every process it started (it runs in its own process group) and is
- * reported as failed, so neither a wedged CLI nor a child holding its pipes stalls the caller.
- */
-export async function runCli(
-  bin: string,
-  args: string[],
-  o: { timeoutMs: number; env?: Record<string, string>; cwd?: string },
-): Promise<CliResult | null> {
-  if (!Bun.which(bin, { PATH: process.env.PATH ?? "" })) return null;
-  log("debug", "spawn", { argv: [bin, ...args], env: o.env ?? {} });
-  const p = Bun.spawn([bin, ...args], {
-    cwd: o.cwd,
-    env: { ...scrubSecrets(process.env), ...o.env },
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-    detached: true,
-  });
-  track(p.pid);
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const late = new Promise<null>((resolve) => {
-    timer = setTimeout(() => resolve(null), o.timeoutMs);
-  });
-  try {
-    const done = await Promise.race([
-      Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]),
-      late,
-    ]);
-    if (!done) {
-      killGroup(p.pid, "SIGKILL");
-      return { ok: false, out: "", err: `${bin} ${args.join(" ")} timed out after ${o.timeoutMs} ms` };
-    }
-    const [code, out, err] = done;
-    return { ok: code === 0, out, err };
-  } finally {
-    clearTimeout(timer);
-    live.delete(p.pid);
-  }
-}
+export { runCli, type CliResult } from "../infra/cli.ts";
 
 /** The JSON a CLI printed, or null for empty or unreadable output. */
 export function jsonOf(out: string | undefined): unknown {

package/src/adapters/codex/index.ts

@@ -251,6 +251,7 @@ function codexActivity(e: Record<string, any>): string | undefined {
 export const codexAdapter: BackendAdapter = {
   id: "codex",
   minVersion: CODEX_MIN_VERSION,
+  install: "npm i -g @openai/codex",
   probe,
   listModels,
   plan,
@@ -278,5 +279,6 @@ export const codexAdapter: BackendAdapter = {
   errors: { limit: CODEX_LIMIT, tooOld: CODEX_TOO_OLD },
   resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
   graceAfterFinalMs: null,
+  reportsCost: false,
   accessShell,
 };

package/src/adapters/cursor/events.ts

@@ -0,0 +1,120 @@
+import { type Tokens, ZERO_TOKENS } from "../../domain/record.ts";
+
+export interface CursorResult {
+  isError: boolean;
+  text: string;
+  tokens: Tokens;
+}
+
+export interface CursorFold {
+  thread: string | null;
+  /**
+   * The assistant text after the last tool call, as Cursor's text format prints it; `result.result` runs every
+   * segment together, which would bury the STATUS line (spec 1.3 §3.1, research §2.3). null: no assistant text.
+   */
+  reply: string | null;
+  result: CursorResult | null;
+  lastEvent: string | null;
+}
+
+/**
+ * A usage or rate limit (research §2.3: `ActionRequiredError` and the server's codes; the user-facing text
+ * comes from the server). A team policy looks like one but never passes by waiting (CURSOR_POLICY).
+ */
+export const CURSOR_LIMIT = [
+  /usage limit/i,
+  /rate limit/i,
+  /too many requests/i,
+  /ActionRequiredError/,
+  /USAGE_LIMIT/,
+  /RATE_LIMIT/,
+];
+export const CURSOR_POLICY = [/administrator has disabled/i];
+/** What an older `cursor-agent` prints for a flag catherd passes (commander, exit 1), or the server's verdict. */
+export const CURSOR_TOO_OLD = [/unknown option/i, /OUTDATED_CLIENT/];
+/** research §2.2 [run]: no login and no CURSOR_API_KEY, on stderr, before any event */
+const CURSOR_AUTH = [/Authentication required/i];
+
+type Event = Record<string, any>;
+
+export function parseCursorLine(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 §4.3's convention from `result.usage` (camelCase): `inputTokens` is uncached only (research §2.3,
+ * `max(total - cacheRead - cacheWrite, 0)`), so input adds cache reads and writes back.
+ */
+export function cursorTokens(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("cacheReadTokens");
+  return { input: n("inputTokens") + cached + n("cacheWriteTokens"), cached, output: n("outputTokens") };
+}
+
+const textOf = (e: Event): string =>
+  ((e.message?.content ?? []) as Event[])
+    .filter((c) => c?.type === "text" && typeof c.text === "string")
+    .map((c) => c.text as string)
+    .join("");
+
+/** A tool call's tool: `readToolCall`, `writeToolCall`, or a `function`'s name. */
+function toolOf(e: Event): { name: string; args: Event } {
+  const [kind, call] = Object.entries((e.tool_call ?? {}) as Event)[0] ?? ["?", {}];
+  if (kind !== "function") return { name: kind, args: (call?.args ?? {}) as Event };
+  let args: Event = {};
+  try {
+    args = typeof call?.arguments === "string" ? JSON.parse(call.arguments) : (call?.arguments ?? {});
+  } catch {
+    // arguments that are not JSON: the name alone
+  }
+  return { name: String(call?.name ?? "function"), args };
+}
+
+export function eventName(e: Event): string {
+  if (e.type === "tool_call")
+    return `tool_call/${e.subtype ?? "?"}/${Object.keys(e.tool_call ?? {})[0] ?? "?"}`;
+  return e.subtype ? `${e.type}/${e.subtype}` : String(e.type ?? "?");
+}
+
+/** Spec §3.7: a command the worker runs, a file it reads or edits, or its message. */
+export function cursorActivity(e: Event): string | undefined {
+  if (e.type === "assistant") return textOf(e) || undefined;
+  if (e.type !== "tool_call" || e.subtype !== "started") return undefined;
+  const { name, args } = toolOf(e);
+  if (typeof args.command === "string") return `$ ${args.command}`;
+  if (typeof args.path === "string") return `${name === "readToolCall" ? "read" : "edit"} ${args.path}`;
+  return name;
+}
+
+export const isLimit = (text: string): boolean =>
+  CURSOR_LIMIT.some((r) => r.test(text)) && !CURSOR_POLICY.some((r) => r.test(text));
+export const isTooOld = (text: string): boolean => CURSOR_TOO_OLD.some((r) => r.test(text));
+export const isAuthFailure = (text: string): boolean => CURSOR_AUTH.some((r) => r.test(text));
+
+export function foldCursorEvents(lines: string[]): CursorFold {
+  const f: CursorFold = { thread: null, reply: null, result: null, lastEvent: null };
+  for (const line of lines) {
+    const e = parseCursorLine(line);
+    if (!e) continue;
+    f.lastEvent = eventName(e);
+    if (typeof e.session_id === "string" && e.session_id) f.thread ??= e.session_id;
+    if (e.type === "tool_call") f.reply = null;
+    else if (e.type === "assistant") {
+      const t = textOf(e);
+      if (t) f.reply = (f.reply ?? "") + t;
+    } else if (e.type === "result")
+      f.result = {
+        isError: e.is_error === true,
+        text: typeof e.result === "string" ? e.result : "",
+        tokens: cursorTokens(e.usage),
+      };
+  }
+  return f;
+}

package/src/adapters/cursor/home.ts

@@ -0,0 +1,79 @@
+import { mkdirSync, readlinkSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import type { Access } from "../../domain/record.ts";
+import { dataDir } from "../../infra/paths.ts";
+import { ensurePrivateDir, writeJsonAtomic } from "../../infra/store.ts";
+import { movedHomeEnv, writableRoots } from "../access.ts";
+
+/** Where isolated Cursor runs keep their homes; computing it creates nothing. */
+export const isolatedCursorRoot = (): string => join(dataDir(), "cursor-home");
+
+/**
+ * Spec 1.3 §4.3–§4.4: an isolated run's HOME. Cursor reads its sandbox policy from one `sandbox.json` per home,
+ * so each access (and a workspace-write role without network) gets its own home: lanes of different access
+ * run side by side without rewriting each other's policy.
+ */
+export const isolatedCursorHome = (access: Access, network = true): string =>
+  join(isolatedCursorRoot(), access === "workspace-write" && !network ? "workspace-write-offline" : access);
+
+/**
+ * The env of an isolated run: the moved HOME (the only thing that stops Cursor's hard-coded `~/.claude`,
+ * `~/.codex`, `~/.grok` and `~/.agents` reads, research §2.8), and Cursor's config and data dirs inside it, so a
+ * CURSOR_CONFIG_DIR or XDG_CONFIG_HOME of the user's cannot point it back. Its credentials stay in memory: on
+ * macOS Cursor otherwise saves the CURSOR_API_KEY login to the moved HOME's keychain, which does not exist, and
+ * the failed `security` call raises a "Keychain Not Found" dialog.
+ */
+export function cursorHomeEnv(access: Access, network = true): Record<string, string> {
+  const home = isolatedCursorHome(access, network);
+  const dot = join(home, ".cursor");
+  return {
+    ...movedHomeEnv(home),
+    CURSOR_CONFIG_DIR: dot,
+    CURSOR_DATA_DIR: dot,
+    AGENT_CLI_CREDENTIAL_STORE: "memory",
+  };
+}
+
+/**
+ * The `sandbox.json` of an isolated home (research §2.6): read-only is the kernel's `workspace_readonly`;
+ * workspace-write adds catherd's writable roots and, unless the role has no network, allows it; `full` runs
+ * with the sandbox off (`--force --sandbox disabled`) and needs none.
+ */
+export function cursorSandboxPolicy(access: Access, network = true): Record<string, unknown> | null {
+  if (access === "read-only") return { type: "workspace_readonly" };
+  if (access === "full") return null;
+  return {
+    type: "workspace_readwrite",
+    additionalReadwritePaths: writableRoots(),
+    ...(network ? { networkPolicy: { default: "allow" } } : {}),
+  };
+}
+
+/**
+ * Makes the isolated home for `access` and writes its `sandbox.json`. Every home links one shared `chats`
+ * dir: Cursor looks a resumed chat up there, and an id it cannot find silently starts an empty chat
+ * (research §2.5), so a thread resumed under another access must find it.
+ */
+export function prepareCursorHome(access: Access, network = true): string {
+  const home = isolatedCursorHome(access, network);
+  const dot = join(home, ".cursor");
+  ensurePrivateDir(dot);
+  const chats = join(isolatedCursorRoot(), "chats");
+  mkdirSync(chats, { recursive: true, mode: 0o700 });
+  ensureLink(chats, join(dot, "chats"));
+  const policy = cursorSandboxPolicy(access, network);
+  if (policy) writeJsonAtomic(join(dot, "sandbox.json"), policy);
+  return home;
+}
+
+/**
+ * Links `path` to `target` in one step: two catherd processes preparing the same home race here, and the one that
+ * loses finds the winner's link (EEXIST). That link is kept when it points at `target`; anything else throws.
+ */
+export function ensureLink(target: string, path: string): void {
+  try {
+    symlinkSync(target, path);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST" || readlinkSync(path) !== target) throw e;
+  }
+}

package/src/adapters/cursor/index.ts

@@ -0,0 +1,331 @@
+import { realpathSync } from "node:fs";
+import { CatherdError } from "../../domain/errors.ts";
+import type { Rung } from "../../domain/ids.ts";
+import type { Access, RunStatus } from "../../domain/record.ts";
+import { scratchShell } from "../access.ts";
+import {
+  type AccessShell,
+  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 {
+  CURSOR_LIMIT,
+  CURSOR_TOO_OLD,
+  cursorActivity,
+  cursorTokens,
+  eventName,
+  foldCursorEvents,
+  isAuthFailure,
+  isLimit,
+  isTooOld,
+  parseCursorLine,
+} from "./events.ts";
+import { cursorHomeEnv, prepareCursorHome } from "./home.ts";
+import { cursorSlug, parseCursorModels } from "./models.ts";
+
+export { isolatedCursorHome, isolatedCursorRoot } from "./home.ts";
+
+/** Spec 1.3 §4.1: the version whose help and bundle were read; 2026.06.04 lacks `--add-dir` and more. */
+export const CURSOR_MIN_VERSION = "2026.09.28";
+export const CURSOR_INSTALL = "curl https://cursor.com/install -fsS | bash";
+const THREAD = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Cursor's versions are a date and a hash (`2026.09.28-64d2043`); grok's `agent` prints `grok 1.0.44 (…)`. */
+const CURSOR_VERSION = /^\s*\d{4}\.\d{1,2}\.\d{1,2}-[0-9a-f]+\b/;
+const DAY_MS = 24 * 60 * 60_000;
+const LOGIN_FIX = "cursor-agent login, or export CURSOR_API_KEY=<key>";
+
+/** How long a `cursor-agent` query (version, models, a sandbox probe's `true`) may take before it counts as failed. */
+export const cursorShell = { timeoutMs: 15_000 };
+
+const which = (bin: string): string | null => Bun.which(bin, { PATH: process.env.PATH ?? "" });
+
+/**
+ * Spec 1.3 §4.1: `cursor-agent` first. The installers of Cursor and grok both link `agent` (research §2.1,
+ * §3.1), so `agent` is taken only when `cursor-agent` is missing, and the probe checks what it is.
+ */
+export function cursorBin(): "cursor-agent" | "agent" {
+  return which("cursor-agent") ? "cursor-agent" : "agent";
+}
+
+/**
+ * Spec 1.3 §4.3. Headless without `--force` rejects every approval, and `--sandbox enabled` runs sandboxable
+ * commands without one (research §2.6); `--force` turns the sandbox off, so only `full` passes it.
+ */
+export const CURSOR_ACCESS: Record<Access, string[]> = {
+  "read-only": ["--mode", "ask", "--sandbox", "enabled"],
+  "workspace-write": ["--sandbox", "enabled"],
+  full: ["--force", "--sandbox", "disabled", "--approve-mcps"],
+};
+
+function plan(r: RunRequest): SpawnPlan {
+  if (r.thread !== null && !THREAD.test(r.thread))
+    throw new CatherdError("E_ADMIT_THREAD", `"${r.thread}" is not a Cursor chat id`, {
+      fix: "pass the thread from the earlier RunRecord",
+    });
+  return {
+    cmd: cursorBin(),
+    args: [
+      "-p",
+      "--output-format",
+      "stream-json",
+      "--trust",
+      "--workspace",
+      r.repo,
+      "--model",
+      cursorSlug(r.rung.model, r.rung.effort),
+      // hidden (research §2.1): no env var turns the self-update off, and it must not swap the binary mid-run
+      "--disable-auto-update",
+      ...CURSOR_ACCESS[r.access],
+      // a resume runs in the recorded repo: Cursor looks a chat up by its cwd (research §2.5)
+      ...(r.thread === null ? [] : ["--resume", r.thread]),
+    ],
+    env: {
+      NO_OPEN_BROWSER: "1",
+      ...(r.isolated ? cursorHomeEnv(r.access, r.network !== false) : {}),
+    },
+    cwd: r.repo,
+    // research §2.2: stdin is read to EOF when no positional prompt is given
+    stdinPath: r.briefPath,
+  };
+}
+
+async function listModels(): Promise<DiscoveredModel[]> {
+  const r = await runCli(cursorBin(), ["models"], { ...cursorShell, env: { NO_OPEN_BROWSER: "1" } });
+  return r?.ok ? parseCursorModels(r.out) : [];
+}
+
+/**
+ * Spec 1.3 §4.4, §4.6: an isolated run needs CURSOR_API_KEY (its HOME holds no login) and gets its home and
+ * `sandbox.json`; the rung's slug must be one Cursor lists: the model with that effort suffix, or the bare slug
+ * for `#default`.
+ */
+async function prepare(req: {
+  rung: Rung;
+  access: Access;
+  isolated: boolean;
+  network?: boolean;
+}): Promise<void> {
+  if (req.isolated) {
+    if (!process.env.CURSOR_API_KEY)
+      throw new CatherdError("E_BACKEND_NOT_LOGGED_IN", "an isolated cursor run needs CURSOR_API_KEY", {
+        fix: "export CURSOR_API_KEY=<key>, or catherd profile set harness.cursor.isolated false",
+      });
+    prepareCursorHome(req.access, req.network !== false);
+  }
+  const { model, effort } = req.rung;
+  const models = await discovered("cursor", listModels, { maxAgeMs: DAY_MS, need: model });
+  if (models.length === 0) return; // Cursor 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", `Cursor does not list ${model}`, {
+      fix: `run ${cursorBin()} models; a rung names the slug without its effort suffix`,
+    });
+  if (!m.efforts.includes(effort))
+    throw new CatherdError("E_BACKEND_MODEL_UNKNOWN", `Cursor lists no ${cursorSlug(model, effort)}`, {
+      fix: `use one of: ${m.efforts.map((e) => `cursor:${model}#${e}`).join(", ")}`,
+    });
+}
+
+function finalize(run: FinishedRun): Outcome {
+  const f = foldCursorEvents(run.eventLines);
+  const res = f.result;
+  const stopped = run.exit.reason;
+  const said = [run.stderr, res?.isError ? res.text : ""].join("\n");
+  const status: RunStatus =
+    stopped === "cancelled"
+      ? "cancelled"
+      : stopped === "idle-timeout" || stopped === "wall-timeout"
+        ? "timeout"
+        : res !== null && !res.isError
+          ? "ok"
+          : isTooOld(said)
+            ? "cli-too-old"
+            : isLimit(said)
+              ? "limit"
+              : "failed";
+  const lastErr = run.stderr.trim().split("\n").at(-1) ?? "";
+  const message =
+    res?.isError && res.text
+      ? res.text
+      : isAuthFailure(lastErr)
+        ? `${lastErr} (fix: ${LOGIN_FIX})`
+        : lastErr || `no result event (${stopped}, exit ${run.exit.code ?? run.exit.signal})`;
+  return {
+    status,
+    thread: f.thread ?? run.request.thread,
+    tokens: res?.tokens ?? cursorTokens(undefined),
+    costUsd: null,
+    images: [],
+    error: status === "ok" ? null : { code: status, message },
+    ...(status === "ok" ? { reply: f.reply ?? res?.text ?? "" } : {}),
+  };
+}
+
+function parse(line: string): EventDelta {
+  const e = parseCursorLine(line);
+  if (!e) return {};
+  const d: EventDelta = { lastEvent: eventName(e) };
+  const activity = cursorActivity(e);
+  if (activity) d.activity = activity;
+  if (typeof e.session_id === "string" && e.session_id) d.thread = e.session_id;
+  if (e.type === "retry" && e.subtype === "starting") d.retrying = true;
+  // a tool call runs between its started and completed events, often printing nothing: the run is busy
+  if (e.type === "tool_call" && typeof e.call_id === "string")
+    d.item = { id: e.call_id, open: e.subtype === "started" };
+  if (e.type === "result") {
+    d.final = true;
+    d.tokens = cursorTokens(e.usage);
+    if (e.is_error === true) {
+      d.failure = String(e.result ?? "error");
+      if (isLimit(d.failure)) d.limit = true;
+    }
+  }
+  return d;
+}
+
+const realOr = (p: string): string => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+
+/**
+ * Spec 1.3 §4.1, §4.7. Installed: a `--version` in Cursor's date-hash form (an `agent` that prints another is
+ * someone else's). Logged in: `models` answered; `status` reports token presence, not a working login
+ * (research §2.9), and `models` fails fast, with no browser, when logged out. An `agent` that is another
+ * program than `cursor-agent` is noted, never run.
+ */
+async function probe(): Promise<Probe> {
+  const bin = cursorBin();
+  let v: Awaited<ReturnType<typeof runCli>>;
+  try {
+    v = await runCli(bin, ["--version"], cursorShell);
+  } catch (e) {
+    // an `agent` that is not Cursor's may not even run here (the owner's is a Linux grok, research §3.1)
+    if (bin === "agent") v = { ok: false, out: "", err: String(e) };
+    else throw e;
+  }
+  if (!v || !CURSOR_VERSION.test(v.out)) {
+    const says = (v?.out || v?.err || "").trim().split("\n")[0];
+    return {
+      installed: false,
+      version: null,
+      versionOk: false,
+      loggedIn: null,
+      problems: [
+        {
+          code: "E_BACKEND_MISSING",
+          message: v
+            ? `the ${bin} on PATH is not Cursor's CLI (it says: ${says})`
+            : "cursor-agent is not on PATH",
+          fix: CURSOR_INSTALL,
+        },
+      ],
+    };
+  }
+  const version = extractVersion(v.out);
+  const versionOk = version !== null && compareVersions(version, CURSOR_MIN_VERSION) >= 0;
+  const m = await runCli(bin, ["models"], { ...cursorShell, env: { NO_OPEN_BROWSER: "1" } });
+  const loggedIn = m?.ok ? true : isAuthFailure(`${m?.out ?? ""}\n${m?.err ?? ""}`) ? false : null;
+  const apiKey = !!process.env.CURSOR_API_KEY;
+  const problems: Probe["problems"] = [];
+  if (!versionOk)
+    problems.push({
+      code: "E_BACKEND_TOO_OLD",
+      message: `${bin} ${version ?? "?"} is older than ${CURSOR_MIN_VERSION}`,
+      fix: `${bin} update`,
+    });
+  if (loggedIn === false)
+    problems.push({
+      code: "E_BACKEND_NOT_LOGGED_IN",
+      message: `${bin} is not logged in (a server call says: Authentication required)`,
+      fix: LOGIN_FIX,
+    });
+  const agent = bin === "cursor-agent" ? which("agent") : null;
+  const other = agent && realOr(agent) !== realOr(which("cursor-agent") as string) ? realOr(agent) : null;
+  return {
+    installed: true,
+    version,
+    versionOk,
+    loggedIn,
+    ...(loggedIn ? { login: apiKey ? "API key" : "Cursor" } : {}),
+    // an API key bills at API rates; a Cursor login's billing is the profile's (spec 1.3 §9 Q4)
+    ...(loggedIn && apiKey ? { billing: "metered" as const } : {}),
+    problems,
+    ...(other
+      ? {
+          info: [
+            {
+              id: "name:agent",
+              label: "agent",
+              detail: `the agent on PATH (${other}) is another program than cursor-agent; catherd runs cursor-agent`,
+            },
+          ],
+        }
+      : {}),
+  };
+}
+
+/** How a native worker gets what Cursor's sandbox refused: its own sandbox.json, or catherd's when isolated. */
+const SANDBOX_FIXES: AccessShell["fixes"] = {
+  lock: "a native Cursor worker writes only where ~/.cursor/sandbox.json or the repo's .cursor/sandbox.json lets it: add the directory to additionalReadwritePaths there, or isolate cursor (harness.cursor.isolated), whose sandbox.json catherd writes",
+  temp: "add the temp dir to additionalReadwritePaths in ~/.cursor/sandbox.json, or isolate cursor",
+  loopback:
+    "Cursor's sandbox blocks this bind: allow it in ~/.cursor/sandbox.json's networkPolicy, or isolate cursor",
+  https:
+    "Cursor's sandbox reaches only the domains networkPolicy allows: add the registry to networkPolicy.allow in ~/.cursor/sandbox.json, or isolate cursor",
+  docker:
+    "Cursor's sandbox cannot reach the Docker socket: run the Docker checks in the verifier (full access), or give the role full access",
+};
+
+/**
+ * Spec 1.3 §4.7: doctor's probes run through the hidden `cursor-agent sandbox run`, which runs a command in
+ * Cursor's sandbox with no model turn (research §2.6), under the user's own sandbox policy, as a native worker
+ * runs.
+ */
+async function accessShell(): Promise<AccessShell | string> {
+  const bin = cursorBin();
+  // `sandbox run` joins its args with spaces and runs the result in a shell
+  const shell = scratchShell(`Cursor's sandbox (${bin} sandbox run)`, [bin, "sandbox", "run", "--"], {
+    oneLine: true,
+  });
+  if ((await shell.run("true", []))?.ok) return { ...shell, fixes: SANDBOX_FIXES };
+  shell.close();
+  return `no Cursor sandbox runner here: ${bin} sandbox run (hidden) did not run \`true\``;
+}
+
+export const cursorAdapter: BackendAdapter = {
+  id: "cursor",
+  minVersion: CURSOR_MIN_VERSION,
+  install: CURSOR_INSTALL,
+  probe,
+  listModels,
+  prepare,
+  plan,
+  parse,
+  finalize,
+  // read-only is enforced by the kernel only in an isolated home's sandbox.json; native it is `--mode ask`
+  enforcement: { "read-only": "advisory", "workspace-write": "enforced", full: "enforced" },
+  errors: { limit: CURSOR_LIMIT, tooOld: CURSOR_TOO_OLD },
+  // each run applies its own flags; "Resuming a conversation recomputes Run Everything" (research §2.5)
+  resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
+  accessShell,
+  isolationNote:
+    "native Cursor loads your Claude Code hooks, skills, plugins and permission rules, and your Cursor User Rules; isolation cannot remove the User Rules",
+  isolationKey: "CURSOR_API_KEY",
+  // Cursor waits for background shells after its last turn, with no limit (research §2.10)
+  graceAfterFinalMs: 30_000,
+  reportsCost: false,
+};

package/src/adapters/cursor/models.ts

@@ -0,0 +1,30 @@
+import type { DiscoveredModel } from "../backend.ts";
+import { foldEffortSlugs, stripAnsi } from "../discovery.ts";
+
+/** Effort suffixes Cursor puts on a legacy slug (`gpt-6-sol-xhigh`); any other suffix names a model. */
+export const CURSOR_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+const LINE = /^\s*([a-z0-9][a-z0-9._-]*)\s+-\s+\S/;
+
+/** Spec 1.3 §4.6: an effort is its own slug; `default` is the bare one, with no effort suffix. */
+export const cursorSlug = (model: string, effort: string): string =>
+  effort === "default" ? model : `${model}-${effort}`;
+
+/**
+ * `cursor-agent models` prints `<slug> - <Display Name>` lines under a header, with ` (current, default)`
+ * markers and a tip (research §2.4). Slugs that differ only by an effort suffix fold into one model; its
+ * efforts list `default` when the bare slug is listed too, since only then does a `#default` rung have a slug
+ * to run. Bracket variant strings are never listed, so they are never built.
+ */
+export function parseCursorModels(text: string): DiscoveredModel[] {
+  const slugs = stripAnsi(text)
+    .split("\n")
+    .map((l) => LINE.exec(l)?.[1])
+    .filter((s): s is string => s !== undefined);
+  return [...foldEffortSlugs(slugs, CURSOR_EFFORTS)].map(([id, efforts]) => ({
+    id,
+    efforts: ["default", ...CURSOR_EFFORTS].filter((e) => efforts.has(e)),
+    context: null,
+    imageIn: false,
+  }));
+}

package/src/adapters/discovery.ts

@@ -85,3 +85,24 @@ export async function discovered(
   if (models.length === 0) return cached?.models ?? [];
   return writeDiscovery(backend, models, now, o.repo).models;
 }
+
+/**
+ * Spec 1.3 §4.6, §6.6: a listing's slugs by model, those that differ only by one of `suffixes` (`gpt-6-sol-xhigh`,
+ * `gemini-3.8-flash-high`) folded into one; each model's efforts hold the suffixes it was listed with, and
+ * `default` when its bare slug is listed too.
+ */
+export function foldEffortSlugs(slugs: string[], suffixes: readonly string[]): Map<string, Set<string>> {
+  const byModel = new Map<string, Set<string>>();
+  for (const slug of slugs) {
+    const effort = suffixes.find((e) => slug.endsWith(`-${e}`));
+    const model = effort ? slug.slice(0, -(effort.length + 1)) : slug;
+    const efforts = byModel.get(model) ?? new Set<string>();
+    efforts.add(effort ?? "default");
+    byModel.set(model, efforts);
+  }
+  return byModel;
+}
+
+/** A listing may be coloured: ESC `[` … a letter. */
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*[A-Za-z]`, "g");
+export const stripAnsi = (text: string): string => text.replace(ANSI, "");