@tsconfigdotjson/vibe-os 0.2.0-rc.1 → 0.3.0

package/server/harness.ts

@@ -1,655 +1,443 @@
-// What the agent CLIs on this machine can be told to do.
+// The harnesses a profile can launch, and what each one can be told to do.
 //
-// The profile editor offers models and permission modes as dropdowns, which
-// means something has to know what the valid values are. Hardcoding them would
-// be wrong within a release or two — Claude ships new models faster than this
-// project ships anything — so they are read off the binary that is actually
-// installed. Update Claude Code and the dropdowns follow.
+// A harness is an adapter in `harnesses/`: a spec (the command, the flags the
+// editor offers, how to resume) plus optional code for discovery, session
+// setup and doctor checks. Adding one is one file and one line in `BUILT_IN`.
 //
-// Hermes answers a narrower version of the same question. It has no listing
-// mode at all (`hermes model` is an interactive wizard), so what is discoverable
-// is its own configuration: which providers it has been set up with, what it
-// would use by default, and where its browser tools will land.
-//
-// Cursor sits between the two. `cursor-agent models` is a real listing mode,
-// but it lists the account's models rather than the binary's — so the answer
-// exists only while the box is logged in, and an empty list means "could not
-// read" rather than "nothing to offer".
-
-import { execFile } from "node:child_process";
-import { readFile, stat } from "node:fs/promises";
-import { promisify } from "node:util";
-import { CHROME_UNIT_PATH, cdpUrlMatches, portsFromUnits } from "./browser.ts";
+// A box can add its own without a fork, as data: every
+// `<state dir>/harnesses/*.json` is a spec. Those get the generic discovery
+// (found on PATH, `--version`, and a login check if the spec names one) and no
+// code of their own.
+
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import {
+  CUSTOM,
+  type HarnessReport,
+  type HarnessSpec,
+  SHELL,
+} from "../shared/harness.ts";
+import { claude } from "./harnesses/claude.ts";
+import { codex } from "./harnesses/codex.ts";
+import { cursor } from "./harnesses/cursor.ts";
+import { hermes } from "./harnesses/hermes.ts";
+import {
+  type Discovery,
+  type HarnessAdapter,
+  loggedIn,
+  output,
+  resolveBinary,
+  run,
+  versionToken,
+} from "./harnesses/util.ts";
 import { log } from "./log.ts";
 
-const run = promisify(execFile);
-
-import type { CursorInfo, HarnessInfo, HermesInfo } from "../shared/wire.ts";
-
-export type { CursorInfo, HarnessInfo, HermesInfo };
-
-/**
- * The effort ladder as of writing, used only when the binary cannot be read.
- *
- * Unlike the model aliases, this is not merged with what was discovered. Effort
- * is ordinal — the list *is* the scale, low to max — so a union of two sources
- * would put a newly-added level in the wrong place and quietly mislabel how
- * hard a role thinks. Either the binary's order or this one, never a blend.
- */
-const KNOWN_EFFORT = ["low", "medium", "high", "xhigh", "max"];
-
-const EMPTY: HarnessInfo = {
-  available: false,
-  version: null,
-  aliases: [],
-  models: [],
-  permissionModes: [],
-  effortLevels: KNOWN_EFFORT,
-};
-
-/**
- * Aliases the CLI documents but which do not appear as model ids.
- *
- * Kept as a floor rather than the source of truth: whatever is found in the
- * binary is merged over the top, so a new tier appears on its own.
- */
-const KNOWN_ALIASES = [
-  "default",
-  "opus",
-  "sonnet",
-  "haiku",
-  "fable",
-  "opusplan",
+export { CLAUDE_INSTALL } from "./harnesses/claude.ts";
+export { CODEX_INSTALL } from "./harnesses/codex.ts";
+export { CURSOR_INSTALL } from "./harnesses/cursor.ts";
+export { HERMES_INSTALL } from "./harnesses/hermes.ts";
+export type { HarnessAdapter, HarnessCheck } from "./harnesses/util.ts";
+
+const BUILT_IN: HarnessAdapter[] = [
+  claude as HarnessAdapter,
+  hermes as HarnessAdapter,
+  cursor,
+  codex,
 ];
 
-/**
- * Where the native installers put things, when PATH does not say so.
- *
- * A login shell picks `~/.local/bin` up from `.profile`; a systemd service does
- * not, and vibe-os is meant to run as one. Without this the server cannot find
- * a Claude that the harness will happily launch a moment later, because the
- * harness runs under a login shell and the server does not — so the dropdowns
- * come up empty on exactly the deployment the docs recommend.
- */
-const CLAUDE_PATHS = [
-  `${process.env.HOME ?? ""}/.local/bin/claude`,
-  "/usr/local/bin/claude",
-  "/opt/claude/.local/bin/claude",
-];
+/** Ids a user file cannot take: the built-ins and the two pseudo-harnesses. */
+const RESERVED = new Set([SHELL, CUSTOM, ...BUILT_IN.map((a) => a.spec.id)]);
 
-/**
- * The same problem for Hermes, whose installer offers two layouts.
- *
- * `/usr/local/bin/hermes` is its FHS default, chosen to match Claude Code and
- * the Codex CLI; `~/.local/bin` is what it uses when it cannot write there.
- */
-const HERMES_PATHS = [
-  `${process.env.HOME ?? ""}/.local/bin/hermes`,
-  "/usr/local/bin/hermes",
-];
+let userAdapters: HarnessAdapter[] = [];
+let problems: { file: string; error: string }[] = [];
 
-/**
- * And again for the two commands that make Browser Use mode engage.
- *
- * `uv`'s installer writes to `~/.local/bin` and nowhere else, which is the same
- * directory that neither a systemd service nor an `ssh host 'command'` has on
- * PATH. Without this the check reported a missing uvx on a box that had one, and
- * offered to install what was already installed.
- */
-const home = process.env.HOME ?? "";
-const BROWSER_USE_PATHS = [
-  `${home}/.local/bin/browser-use`,
-  "/usr/local/bin/browser-use",
-];
-const UVX_PATHS = [`${home}/.local/bin/uvx`, "/usr/local/bin/uvx"];
+/** Where a box's own harness specs live. */
+export const harnessDir = (stateDir: string): string =>
+  path.join(stateDir, "harnesses");
 
 /**
- * The commands that install what Hermes needs, named where they are checked.
+ * Reads `<state dir>/harnesses/*.json`. Called once per process, by whatever
+ * resolves the config, so the server, `vibe-os attach` and doctor all see the
+ * same list.
  *
- * doctor prints them under a failed check and `connect-hermes` prints the first
- * one when there is nothing to configure. Both used to be about to grow their
- * own copy of a URL that has to be right.
+ * Synchronous on purpose: it is a handful of small files read once, and the
+ * callers that need the answer (validating a profile, building a window's
+ * command) are synchronous. A file that does not parse or validate is skipped
+ * and reported by doctor; it never stops the server.
  */
-export const CLAUDE_INSTALL = "curl -fsSL https://claude.ai/install.sh | bash";
-export const HERMES_INSTALL =
-  "curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash";
-export const UV_INSTALL = "curl -LsSf https://astral.sh/uv/install.sh | sh";
-
-/** Resolves a command through any symlinks to the real executable. */
-async function resolveBinary(
-  command: string,
-  extraPaths: string[],
-): Promise<string | null> {
-  const candidates: string[] = [];
+export function loadHarnesses(stateDir: string): void {
+  const dir = harnessDir(stateDir);
+  const loaded: HarnessAdapter[] = [];
+  const found: { file: string; error: string }[] = [];
+  let files: string[] = [];
   try {
-    const { stdout } = await run(
-      "/bin/sh",
-      ["-c", 'command -v "$1"', "sh", command],
-      { timeout: 5_000 },
-    );
-    if (stdout.trim()) candidates.push(stdout.trim());
+    files = readdirSync(dir)
+      .filter((f) => f.endsWith(".json"))
+      .sort();
   } catch {
-    // not on PATH — the explicit locations below may still have it
+    // no directory is no user harnesses
   }
-  candidates.push(...extraPaths.filter(Boolean));
-
-  for (const candidate of candidates) {
+  for (const file of files) {
+    const full = path.join(dir, file);
     try {
-      await stat(candidate);
-      const { stdout: real } = await run(
-        "/bin/sh",
-        ["-c", `readlink -f ${JSON.stringify(candidate)}`],
-        {
-          timeout: 5_000,
-        },
-      );
-      return real.trim() || candidate;
-    } catch {
-      // next
+      const spec = validateSpec(JSON.parse(readFileSync(full, "utf8")));
+      if (RESERVED.has(spec.id)) throw new Error(`id ${spec.id} is taken`);
+      if (loaded.some((a) => a.spec.id === spec.id))
+        throw new Error(`id ${spec.id} is already defined by another file`);
+      loaded.push({ spec });
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      found.push({ file: full, error });
+      log.warn(`skipping harness ${full}: ${error}`);
     }
   }
-  return null;
-}
-
-/**
- * Model ids embedded in the executable.
- *
- * grep rather than reading the file in-process: the binary is ~270MB and the
- * answer is a few hundred bytes, so streaming it through a matcher costs
- * nothing while `readFile` would cost the whole thing in memory. Measured at
- * about 0.13s, which is why this is done once at startup rather than cached to
- * disk or fetched over the network.
- */
-async function embeddedModels(binary: string): Promise<string[]> {
-  try {
-    const { stdout } = await run(
-      "grep",
-      ["-aoE", "claude-(opus|sonnet|haiku|fable)-[0-9]+(-[0-9]+)?", binary],
-      { timeout: 30_000, maxBuffer: 4 * 1024 * 1024 },
-    );
-    const seen = new Set(
-      stdout
-        .split("\n")
-        .map((l) => l.trim())
-        .filter(Boolean),
-    );
-    // Newest first: people reach for the latest far more often than a pin to
-    // something old, and a sorted-ascending list buries it.
-    return [...seen].sort((a, b) =>
-      b.localeCompare(a, "en", { numeric: true }),
-    );
-  } catch {
-    return [];
-  }
+  userAdapters = loaded;
+  problems = found;
+  cache.clear();
 }
 
-/**
- * `claude --help`, or empty if it cannot be run.
- *
- * Read once and handed to every parser below. Each `claude` invocation costs a
- * couple of seconds of its own startup, and the help text answers more than one
- * question — asking twice would double the slowest part of discovery to learn
- * nothing new.
- */
-async function helpText(binary: string): Promise<string> {
-  try {
-    const { stdout } = await run(binary, ["--help"], {
-      timeout: 15_000,
-      maxBuffer: 4 * 1024 * 1024,
-    });
-    return stdout;
-  } catch {
-    return "";
-  }
-}
+/** Every harness, built-ins first. */
+export const harnesses = (): HarnessAdapter[] => [...BUILT_IN, ...userAdapters];
 
-/** The choices `--permission-mode` lists in its own help output. */
-function permissionModes(help: string): string[] {
-  // Help text wraps, so the list is matched across newlines and whitespace.
-  const section =
-    /--permission-mode[\s\S]{0,400}?\(choices:([\s\S]{0,300}?)\)/.exec(help);
-  if (!section) return [];
-  return [...section[1].matchAll(/"([^"]+)"/g)].map((m) => m[1]);
-}
+export const harness = (id: string): HarnessAdapter | undefined =>
+  harnesses().find((a) => a.spec.id === id);
 
-/**
- * The levels `--effort` lists in its own help output.
- *
- * `--permission-mode` prints a `(choices: "a", "b")` block this can anchor on;
- * `--effort` prints a bare `(low, medium, high, xhigh, max)`, so the only
- * anchor available is "the first parenthesis after the flag". That is loose
- * enough to catch a sentence in some future release, which is what the shape
- * check is for: every token has to look like a level, or the whole match is
- * discarded and the caller falls back to the known ladder. Half a list read out
- * of a paragraph would be worse than not reading one at all.
- */
-function effortLevels(help: string): string[] {
-  const section = /--effort[\s\S]{0,400}?\(([^)]{0,200})\)/.exec(help);
-  if (!section) return [];
-  const levels = section[1].split(",").map((s) => s.trim());
-  if (levels.length < 2 || !levels.every((l) => /^[a-z][a-z0-9-]*$/.test(l)))
-    return [];
-  return levels;
-}
+/** Whether a profile may name this harness. */
+export const isHarness = (id: string): boolean =>
+  id === SHELL || id === CUSTOM || harness(id) !== undefined;
 
-let cached: Promise<HarnessInfo> | null = null;
+/** User files that were skipped, and why. */
+export const harnessProblems = () => problems;
 
-/**
- * Everything the editor needs to offer, discovered once.
- *
- * Cached for the life of the process: it describes an installed binary, which
- * does not change under a running server, and a restart is already what
- * happens when someone upgrades it.
- */
-export function discoverClaude(): Promise<HarnessInfo> {
-  cached ??= (async (): Promise<HarnessInfo> => {
-    const binary = await resolveBinary("claude", CLAUDE_PATHS);
-    if (!binary) {
-      log.debug(
-        "claude is not on PATH — the profile editor will offer aliases only",
-      );
-      return { ...EMPTY, aliases: KNOWN_ALIASES };
-    }
-
-    // Concurrently, because each `claude` invocation costs a couple of seconds
-    // of its own startup and there is no reason to pay for them in series.
-    const [version, models, help] = await Promise.all([
-      run(binary, ["--version"], { timeout: 15_000 })
-        .then(({ stdout }) => stdout.trim().split(/\s+/)[0] ?? null)
-        .catch(() => null),
-      embeddedModels(binary),
-      helpText(binary),
-    ]);
-
-    const modes = permissionModes(help);
-    const effort = effortLevels(help);
+// ── validation ───────────────────────────────────────────────────────────────
 
-    // A tier that shows up in the binary but not in the list above still gets
-    // an alias, because that is how Claude names them.
-    const tiers = new Set(models.map((m) => m.split("-")[1]).filter(Boolean));
-    const aliases = [...new Set([...KNOWN_ALIASES, ...tiers])];
+const ID = /^[a-z][a-z0-9-]{0,31}$/;
 
-    log.debug(
-      `claude ${version ?? "?"}: ${models.length} models, ${modes.length} permission modes, ` +
-        `${effort.length > 0 ? effort.join("/") : "no"} effort levels`,
-    );
-    return {
-      available: true,
-      version,
-      aliases,
-      models,
-      permissionModes: modes,
-      effortLevels: effort.length > 0 ? effort : KNOWN_EFFORT,
-    };
-  })();
-  return cached;
+function fail(where: string, what: string): never {
+  throw new Error(`${where} ${what}`);
 }
 
-// ── Hermes ───────────────────────────────────────────────────────────────────
-
-/**
- * The reasoning ladder as of writing, used only when the help cannot be read.
- *
- * Not merged with what was discovered, for the reason `KNOWN_EFFORT` gives: the
- * list is the scale, so a union of two sources would put a newly-added level in
- * the wrong place and mislabel how hard a role thinks.
- */
-const KNOWN_REASONING = [
-  "none",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max",
-  "ultra",
-];
-
-const NO_HERMES: HermesInfo = {
-  available: false,
-  version: null,
-  providers: [],
-  defaultProvider: null,
-  defaultModel: null,
-  reasoningLevels: KNOWN_REASONING,
-  browser: {
-    cdpUrl: null,
-    backend: null,
-    cdpPort: null,
-    connected: false,
-    browserUse: false,
-  },
-};
-
-/**
- * One `hermes config get <key> --json`, parsed, or null.
- *
- * The one machine-readable read Hermes offers. Everything downstream treats a
- * null as "could not tell", never as "not set": a key that has never been
- * written, a build that spells it differently and a Python traceback all arrive
- * here the same way, and only the first of those is worth reporting as a fact.
- */
-async function hermesConfig(
-  binary: string,
-  key: string,
-): Promise<Record<string, unknown> | null> {
-  try {
-    const { stdout } = await run(binary, ["config", "get", key, "--json"], {
-      timeout: 20_000,
-      maxBuffer: 4 * 1024 * 1024,
-    });
-    const parsed: unknown = JSON.parse(stdout);
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : null;
-  } catch {
-    return null;
-  }
+function string(
+  value: unknown,
+  where: string,
+  required = false,
+): string | undefined {
+  if (value === undefined && !required) return undefined;
+  if (typeof value !== "string" || value.trim() === "")
+    fail(where, "must be a non-empty string");
+  if (/[\0\r\n]/.test(value)) fail(where, "cannot span lines");
+  return value;
 }
 
-/**
- * The levels `--reasoning` lists in its own help output.
- *
- * The same job `effortLevels` does for Claude, against a different sentence:
- * Hermes writes "Reasoning effort for this session: none, minimal, low, medium,
- * high, xhigh, max, or ultra." across two wrapped lines, so the anchor is the
- * first colon after the flag and the terminator is the full stop.
- *
- * Same shape check, for the same reason. That anchor is loose enough to catch a
- * paragraph in some future release, so every token has to look like a level or
- * the whole match is discarded and the caller falls back to the known ladder.
- */
-export function reasoningLevels(help: string): string[] {
-  const section = /--reasoning[\s\S]{0,200}?:\s*([\s\S]{0,200}?)\./.exec(help);
-  if (!section) return [];
-  const levels = section[1]
-    .split(/,|\bor\b/)
-    .map((s) => s.trim())
-    .filter(Boolean);
-  if (levels.length < 2 || !levels.every((l) => /^[a-z][a-z0-9-]*$/.test(l)))
-    return [];
-  return levels;
+function strings(value: unknown, where: string): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) fail(where, "must be a list of strings");
+  return value.map((v, i) => string(v, `${where}[${i}]`, true) as string);
 }
 
-/**
- * The version out of `hermes --version`, which is not one line.
- *
- * Claude prints `1.2.3 (Claude Code)` and the first token is the answer. Hermes
- * prints a five-line block — its own version, the install directory, the Python
- * it built against, the OpenAI SDK, and a sentence suggesting `hermes version` —
- * so taking the last token of the whole thing yields "status." and taking the
- * first yields "Hermes". Only the first line is about the agent, and the answer
- * is the version-shaped token in it.
- */
-export function hermesVersion(stdout: string): string | null {
-  const first = stdout.split("\n")[0] ?? "";
-  const match = /\bv?(\d+(?:\.\d+)+[^\s()]*)/.exec(first);
-  return match ? match[1] : null;
+function flag(
+  value: unknown,
+  where: string,
+  required = false,
+): string | undefined {
+  const f = string(value, where, required);
+  if (f !== undefined && !f.startsWith("-")) fail(where, "must start with -");
+  return f;
 }
 
-/** A field of a config block, when it is a non-empty string. */
-function str(
-  block: Record<string, unknown> | null,
-  key: string,
-): string | null {
-  const value = block?.[key];
-  return typeof value === "string" && value.trim() ? value.trim() : null;
+function flags(value: unknown, where: string): string[] | undefined {
+  return strings(value, where)?.map((f) => flag(f, where, true) as string);
 }
 
-/**
- * The CDP port the installed Chrome unit actually opened.
- *
- * Read from the unit rather than from a default, for the same reason doctor
- * does it: `install-browser` may have been given `--cdp-port` months ago, and
- * comparing a configured URL against a port nothing is listening on would call a
- * working box broken.
- */
-async function installedCdpPort(): Promise<number | null> {
-  const unit = await readFile(CHROME_UNIT_PATH, "utf8").catch(() => null);
-  if (!unit) return null;
-  return portsFromUnits({ chrome: unit }).cdpPort;
+function object(value: unknown, where: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fail(where, "must be an object");
+  return value as Record<string, unknown>;
 }
 
-let hermesCached: Promise<HermesInfo> | null = null;
+/** Only the keys a spec knows, so a typo is an error rather than ignored. */
+function only(o: Record<string, unknown>, keys: string[], where: string) {
+  for (const k of Object.keys(o))
+    if (!keys.includes(k)) fail(where, `has an unknown key "${k}"`);
+}
 
 /**
- * Everything the Hermes side of the editor needs, discovered once.
- *
- * Deliberately thinner than the Claude side. There is no model list here and
- * there is not going to be one: `hermes model` is an interactive wizard, and a
- * hardcoded list would be a guess about somebody else's account. What is real is
- * what the box is configured for, so that is what is offered, and the model and
- * provider fields stay free text with the discovered values as suggestions.
+ * Checks a user-written spec, and returns only what it checked.
  *
- * No floor of well-known provider names either, unlike `KNOWN_ALIASES` above.
- * A Claude alias works wherever Claude is installed; a Hermes provider id is
- * account configuration, so offering one that is not on this box would suggest a
- * choice that can only fail at launch.
+ * Strict, because the alternative is a profile that launches the wrong argv
+ * with no error anywhere. The mcp field kind and the code hooks are left to
+ * built-ins: a JSON file is a command plus its flags.
  */
-export function discoverHermes(): Promise<HermesInfo> {
-  hermesCached ??= (async (): Promise<HermesInfo> => {
-    const binary = await resolveBinary("hermes", HERMES_PATHS);
-    if (!binary) {
-      log.debug("hermes is not on PATH — Hermes profiles will not launch");
-      return NO_HERMES;
-    }
-
-    // Concurrently: `hermes` is Python, so each invocation costs seconds of
-    // interpreter and import time before it does anything.
-    const [version, help, model, browser, providers, browserUse, cdpPort] =
-      await Promise.all([
-        run(binary, ["--version"], { timeout: 30_000 })
-          .then(({ stdout }) => hermesVersion(stdout))
-          .catch(() => null),
-        // `chat`, not the bare command: `--reasoning` is a flag of that
-        // subcommand, which is also the one a profile actually launches.
-        run(binary, ["chat", "--help"], {
-          timeout: 30_000,
-          maxBuffer: 4 * 1024 * 1024,
-        })
-          .then(({ stdout }) => stdout)
-          .catch(() => ""),
-        hermesConfig(binary, "model"),
-        hermesConfig(binary, "browser"),
-        hermesConfig(binary, "providers"),
-        // Presence, never a run. A cold `uvx browser-use` downloads the package
-        // before it prints anything, which would hold up startup for minutes on
-        // the one box where the answer matters least.
-        Promise.all([
-          resolveBinary("browser-use", BROWSER_USE_PATHS),
-          resolveBinary("uvx", UVX_PATHS),
-        ]).then(([direct, viaUvx]) => Boolean(direct || viaUvx)),
-        installedCdpPort(),
-      ]);
-
-    const defaultProvider = str(model, "provider");
-    const names = [
-      ...Object.keys(providers ?? {}).filter((n) => n.trim()),
-      ...(defaultProvider ? [defaultProvider] : []),
-    ];
-    const cdpUrl = str(browser, "cdp_url");
-    const reasoning = reasoningLevels(help);
-
-    log.debug(
-      `hermes ${version ?? "?"}: ${names.length} providers, ` +
-        `${reasoning.length > 0 ? reasoning.join("/") : "no"} reasoning levels, ` +
-        `browser ${cdpUrl ?? "unset"}, browser-use ${browserUse ? "runnable" : "missing"}`,
-    );
+export function validateSpec(raw: unknown): HarnessSpec {
+  const o = object(raw, "the spec");
+  only(
+    o,
+    [
+      "id",
+      "label",
+      "command",
+      "paths",
+      "leading",
+      "resume",
+      "install",
+      "version",
+      "login",
+      "defaults",
+      "fields",
+      "valued",
+      "optional",
+      "extraPlaceholder",
+    ],
+    "the spec",
+  );
+  const id = string(o.id, "id", true) as string;
+  if (!ID.test(id))
+    fail("id", "must be lowercase letters, digits and dashes, 32 at most");
+
+  let resume: HarnessSpec["resume"];
+  if (o.resume !== undefined) {
+    const r = object(o.resume, "resume");
+    only(r, ["args", "subcommand", "unless"], "resume");
+    if (r.subcommand !== undefined && typeof r.subcommand !== "boolean")
+      fail("resume.subcommand", "must be true or false");
+    resume = {
+      args:
+        strings(r.args, "resume.args") ?? fail("resume.args", "is required"),
+      subcommand: r.subcommand as boolean | undefined,
+      unless: flags(r.unless, "resume.unless"),
+    };
+  }
 
-    return {
-      available: true,
-      version,
-      providers: [...new Set(names)].sort(),
-      defaultProvider,
-      defaultModel: str(model, "default"),
-      reasoningLevels: reasoning.length > 0 ? reasoning : KNOWN_REASONING,
-      browser: {
-        cdpUrl,
-        backend: str(browser, "backend"),
-        cdpPort,
-        connected: cdpPort !== null && cdpUrlMatches(cdpUrl, cdpPort),
-        browserUse,
-      },
+  let login: HarnessSpec["login"];
+  if (o.login !== undefined) {
+    const l = object(o.login, "login");
+    only(l, ["args", "fix"], "login");
+    login = {
+      args: strings(l.args, "login.args") ?? fail("login.args", "is required"),
+      fix: string(l.fix, "login.fix", true) as string,
     };
-  })();
-  return hermesCached;
+  }
+
+  if (!Array.isArray(o.fields)) fail("fields", "must be a list");
+  const keys = new Set<string>();
+  const fields = o.fields.map((rawField, i): HarnessSpec["fields"][number] => {
+    const where = `fields[${i}]`;
+    const f = object(rawField, where);
+    if (f.kind === "toggle") {
+      only(f, ["kind", "flag", "aliases", "label", "hint", "warn"], where);
+      return {
+        kind: "toggle",
+        flag: flag(f.flag, `${where}.flag`, true) as string,
+        aliases: flags(f.aliases, `${where}.aliases`),
+        label: string(f.label, `${where}.label`, true) as string,
+        hint: string(f.hint, `${where}.hint`),
+        warn: string(f.warn, `${where}.warn`),
+      };
+    }
+    if (f.kind === "select") {
+      only(
+        f,
+        [
+          "kind",
+          "key",
+          "label",
+          "flag",
+          "aliases",
+          "prefix",
+          "options",
+          "specials",
+          "free",
+          "none",
+          "placeholder",
+          "hint",
+        ],
+        where,
+      );
+      const key = string(f.key, `${where}.key`, true) as string;
+      if (!/^[a-z][a-z0-9-]*$/.test(key))
+        fail(`${where}.key`, "must be lowercase letters, digits and dashes");
+      if (keys.has(key)) fail(`${where}.key`, `repeats "${key}"`);
+      keys.add(key);
+      if (f.free !== undefined && typeof f.free !== "boolean")
+        fail(`${where}.free`, "must be true or false");
+      const options =
+        f.options === undefined
+          ? undefined
+          : (Array.isArray(f.options)
+              ? f.options
+              : fail(`${where}.options`, "must be a list")
+            ).map((opt, j) => {
+              const ow = `${where}.options[${j}]`;
+              if (typeof opt === "string")
+                return { value: string(opt, ow, true) as string };
+              const oo = object(opt, ow);
+              only(oo, ["value", "label", "group"], ow);
+              return {
+                value: string(oo.value, `${ow}.value`, true) as string,
+                label: string(oo.label, `${ow}.label`),
+                group: string(oo.group, `${ow}.group`),
+              };
+            });
+      const specials =
+        f.specials === undefined
+          ? undefined
+          : (Array.isArray(f.specials)
+              ? f.specials
+              : fail(`${where}.specials`, "must be a list")
+            ).map((s, j) => {
+              const sw = `${where}.specials[${j}]`;
+              const so = object(s, sw);
+              only(so, ["value", "label", "flag", "aliases", "warn"], sw);
+              return {
+                value: string(so.value, `${sw}.value`, true) as string,
+                label: string(so.label, `${sw}.label`, true) as string,
+                flag: flag(so.flag, `${sw}.flag`, true) as string,
+                aliases: flags(so.aliases, `${sw}.aliases`),
+                warn: string(so.warn, `${sw}.warn`),
+              };
+            });
+      const field = {
+        kind: "select" as const,
+        key,
+        label: string(f.label, `${where}.label`, true) as string,
+        flag: flag(f.flag, `${where}.flag`),
+        aliases: flags(f.aliases, `${where}.aliases`),
+        prefix: string(f.prefix, `${where}.prefix`),
+        options,
+        specials,
+        free: f.free as boolean | undefined,
+        none: string(f.none, `${where}.none`),
+        placeholder: string(f.placeholder, `${where}.placeholder`),
+        hint: string(f.hint, `${where}.hint`),
+      };
+      if (!field.flag && !field.specials?.length)
+        fail(where, "needs a flag, specials, or both");
+      return field;
+    }
+    return fail(`${where}.kind`, 'must be "select" or "toggle"');
+  });
+
+  return {
+    id,
+    label: string(o.label, "label", true) as string,
+    command: string(o.command, "command", true) as string,
+    paths: strings(o.paths, "paths"),
+    leading: strings(o.leading, "leading"),
+    resume,
+    install: string(o.install, "install"),
+    version: strings(o.version, "version"),
+    login,
+    defaults: strings(o.defaults, "defaults"),
+    fields,
+    valued: flags(o.valued, "valued"),
+    optional: flags(o.optional, "optional"),
+    extraPlaceholder: string(o.extraPlaceholder, "extraPlaceholder"),
+  };
 }
 
-// ── Cursor ───────────────────────────────────────────────────────────────────
+// ── discovery ────────────────────────────────────────────────────────────────
 
 /**
- * Where Cursor's installer puts things, when PATH does not say so.
+ * How long an adapter's own discovery gets before the editor goes without it.
  *
- * `curl https://cursor.com/install | bash` unpacks a versioned bundle under
- * `~/.local/share/cursor-agent/versions/` and symlinks `cursor-agent` (and a
- * bare `agent`) into `~/.local/bin` — the same directory that neither a systemd
- * service nor an `ssh host 'command'` has on PATH, for the same reason the
- * Claude and Hermes lists above exist. `cursor-agent` is the name checked, not
- * `agent`: both point at the same binary, and only one of them is unambiguous.
+ * Some of it goes to the network (Cursor's model list is the account's), and
+ * a hung CLI must not hold up the editor or doctor forever. Past this the
+ * report carries what the generic part found and every field falls back to
+ * its spec's own options, or free text.
  */
-const CURSOR_PATHS = [
-  `${home}/.local/bin/cursor-agent`,
-  "/usr/local/bin/cursor-agent",
-];
+const DISCOVERY_TIMEOUT = 60_000;
 
-/** The command that installs it, named where doctor checks for it. */
-export const CURSOR_INSTALL = "curl https://cursor.com/install -fsS | bash";
+interface Found {
+  report: HarnessReport;
+  detail: unknown;
+}
 
-const NO_CURSOR: CursorInfo = {
+const cache = new Map<string, Promise<Found>>();
+
+const empty = (id: string): HarnessReport => ({
+  id,
   available: false,
   version: null,
-  models: [],
-  defaultModel: null,
   loggedIn: null,
-};
-
-/**
- * The version out of `cursor-agent --version`.
- *
- * Cursor's CLI versions are date-shaped — `2026.08.11-e8db854`, one line and
- * nothing else on a real install — rather than semver, which is still "digits,
- * dots, then whatever" and the same token shape
- * `hermesVersion` reads. Kept to the first line for the same reason as there:
- * only the first line is a claim about the binary itself, and a wrapper or
- * update notice printed after it must not become the answer.
- */
-export function cursorVersion(stdout: string): string | null {
-  const first = stdout.split("\n").find((l) => l.trim()) ?? "";
-  const match = /\bv?(\d+(?:\.\d+)+[^\s()]*)/.exec(first);
-  return match ? match[1] : null;
+  options: {},
+  defaults: {},
+  notes: [],
+});
+
+function withTimeout<T>(p: Promise<T>, ms: number, fallback: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return Promise.race([
+    p.finally(() => clearTimeout(timer)),
+    new Promise<T>((resolve) => {
+      timer = setTimeout(() => resolve(fallback), ms);
+    }),
+  ]);
 }
 
-/**
- * Model ids out of `cursor-agent models`.
- *
- * The format is verbatim from a real box: an `Available models` header, then
- * one `id - Display Name` per line, then a `Tip:` sentence about `--model`.
- * The default is marked inside the display half — `auto - Auto (default)`.
- *
- * The id is the machine half and the only part kept: it is what `--model`
- * takes, and the display name repeats it in prose. A line has to open with an
- * id-shaped token followed by the ` - ` separator (or nothing at all), which
- * is what keeps the header and the tip out — both contain spaces where the
- * separator would have to be. Half-reading prose would put "Tip" in a model
- * dropdown, which is worse than missing a model.
- *
- * Order is kept as printed. Cursor leads with `auto` and its recommendations,
- * which is a better sort than alphabetical for a 200-entry list.
- */
-export function parseCursorModels(stdout: string): {
-  models: string[];
-  defaultModel: string | null;
-} {
-  const models: string[] = [];
-  let defaultModel: string | null = null;
-  for (const raw of stdout.split("\n")) {
-    const line = raw.trim();
-    if (!line) continue;
-    const match = /^([A-Za-z0-9][\w./-]*)(?:\s+-\s+(.*))?$/.exec(line);
-    if (!match) continue;
-    const [, id, label] = match;
-    if (!models.includes(id)) models.push(id);
-    // The marker word can share its parens: one account prints `(default)`,
-    // another `(current, default)`, so the test is for the word, anchored
-    // inside a parenthesised note rather than to the whole note.
-    if (
-      label &&
-      /\([^)]*\b(default|current|selected)\b[^)]*\)/i.test(label) &&
-      !defaultModel
-    )
-      defaultModel = id;
+async function find(adapter: HarnessAdapter): Promise<Found> {
+  const { spec } = adapter;
+  const binary = await resolveBinary(spec.command, spec.paths ?? []);
+  if (!binary) {
+    log.debug(
+      `${spec.command} is not on PATH — ${spec.label} profiles will not launch`,
+    );
+    return { report: empty(spec.id), detail: undefined };
   }
-  return { models, defaultModel };
-}
 
-/**
- * What `cursor-agent status` says about being logged in, when it says anything.
- *
- * "Not logged in" contains "logged in", so the negative is checked first. A
- * status this cannot read returns null rather than false: only a definite "no"
- * should make the editor warn that a window will sit at a login prompt.
- */
-export function cursorLoggedIn(stdout: string): boolean | null {
-  const text = stdout.toLowerCase();
-  if (
-    /not\s+logged\s+in|logged\s+out|unauthenticated|no.*credentials/.test(text)
-  )
-    return false;
-  if (/logged\s+in|signed\s+in|authenticated/.test(text)) return true;
-  return null;
+  // Concurrently: each of these is its own process start, and some harnesses
+  // (Hermes is Python) spend seconds getting to the first byte.
+  const [version, login, own] = await Promise.all([
+    run(binary, spec.version ?? ["--version"], { timeout: 30_000 })
+      .then(({ stdout }) => versionToken(stdout))
+      .catch(() => null),
+    spec.login
+      ? output(binary, spec.login.args).then((t) =>
+          t === null ? null : loggedIn(t),
+        )
+      : Promise.resolve(null),
+    adapter.discover
+      ? withTimeout<Discovery>(
+          adapter.discover(binary).catch((err: unknown) => {
+            log.warn(`${spec.id} discovery failed: ${String(err)}`);
+            return {};
+          }),
+          DISCOVERY_TIMEOUT,
+          {},
+        )
+      : Promise.resolve<Discovery>({}),
+  ]);
+
+  return {
+    report: {
+      id: spec.id,
+      available: true,
+      version: own.version !== undefined ? own.version : version,
+      loggedIn: login,
+      options: own.options ?? {},
+      defaults: own.defaults ?? {},
+      notes: own.notes ?? [],
+    },
+    detail: own.detail,
+  };
 }
 
-let cursorCached: Promise<CursorInfo> | null = null;
-
 /**
- * Everything the Cursor side of the editor needs, discovered once.
+ * What the box has for one harness, discovered once.
  *
- * Between the other two in what it can know. Unlike Hermes there is a listing
- * mode — `cursor-agent models` — so the model field gets real suggestions. But
- * the list is the account's rather than the binary's: logged out, or offline,
- * it cannot be read, so an empty list is "could not tell" and the field stays
- * free text. No floor of well-known model names, for the reason the Hermes
- * provider list has none: offering a model this account does not have would
- * suggest a choice that can only fail after launch.
+ * Cached for the life of the process: it describes an installed binary, which
+ * does not change under a running server, and a restart is already what
+ * happens when someone upgrades it.
  */
-export function discoverCursor(): Promise<CursorInfo> {
-  cursorCached ??= (async (): Promise<CursorInfo> => {
-    const binary = await resolveBinary("cursor-agent", CURSOR_PATHS);
-    if (!binary) {
-      log.debug(
-        "cursor-agent is not on PATH — Cursor profiles will not launch",
-      );
-      return NO_CURSOR;
-    }
-
-    // Concurrently, as ever: `models` and `status` may each go to the network,
-    // and there is no reason to pay for the round trips in series.
-    const [version, listed, loggedIn] = await Promise.all([
-      run(binary, ["--version"], { timeout: 15_000 })
-        .then(({ stdout }) => cursorVersion(stdout))
-        .catch(() => null),
-      run(binary, ["models"], { timeout: 30_000, maxBuffer: 4 * 1024 * 1024 })
-        .then(({ stdout }) => parseCursorModels(stdout))
-        // Logged out or offline it exits complaining; that is "could not
-        // read", which the empty list already says.
-        .catch(() => ({ models: [], defaultModel: null })),
-      run(binary, ["status"], { timeout: 30_000, maxBuffer: 4 * 1024 * 1024 })
-        .then(({ stdout }) => cursorLoggedIn(stdout))
-        .catch(() => null),
-    ]);
-
-    log.debug(
-      `cursor-agent ${version ?? "?"}: ${listed.models.length} models, ` +
-        `logged ${loggedIn === null ? "in?" : loggedIn ? "in" : "out"}`,
-    );
-
-    return {
-      available: true,
-      version,
-      models: listed.models,
-      defaultModel: listed.defaultModel,
-      loggedIn,
-    };
-  })();
-  return cursorCached;
+export function discover(id: string): Promise<Found> | undefined {
+  const adapter = harness(id);
+  if (!adapter) return undefined;
+  let found = cache.get(id);
+  if (!found) {
+    found = find(adapter);
+    cache.set(id, found);
+  }
+  return found;
 }
+
+/** Every harness's spec, for the editor. */
+export const specs = (): HarnessSpec[] => harnesses().map((a) => a.spec);