viewable-one 0.0.0-stage → 0.12.2

package/lib/detect.mjs

@@ -0,0 +1,629 @@
+// WHAT CODING AGENTS THIS MACHINE ACTUALLY HAS, asked once and answered as
+// data.
+//
+// The board can show a Run button for an engine that is not installed, and
+// until something looks, the first proof is a failed session. This module is
+// the looking: `<bin> --version` for each engine, plus the one login fact
+// that is cheap and true (Claude Code writes ~/.claude/.credentials.json when
+// you log in).
+//
+// STAGE 1 PRINTS IT, STAGE 2 WRITES IT INTO THE MARK FILE and the app shows
+// dots. That is why the probe is its own module now rather than a few lines
+// inside `glytch init`: the caller that needs it next is the daemon, not the
+// installer.
+//
+// "FOUND" IS NOT "READY" and the labels here say installed, never working.
+// A binary on PATH that is logged out, out of date, or broken still answers
+// --version. The first real run stays the proof.
+//
+// WHY THE LIST IS SPELLED HERE rather than derived from AGENTS: two of the
+// three names are the same set (claude, opencode), but `acp-claude` runs on
+// `process.execPath` - probing node's version would report "found" on every
+// machine that can run this file at all, which is every machine. So the probe
+// list is what a PERSON would install, and AGENTS stays what a runner can
+// spawn. They are different questions.
+
+import { discoverCodex } from "./codex-rpc.mjs";
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, posix, win32 } from "node:path";
+
+import { findWindowsCommand, runnableCommand } from "./windows-command.mjs";
+
+/** How long a `--version` may take before it is called not-found. Generous
+ * for a cold binary, short enough that a machine with three of them does not
+ * make `viewable init` feel hung. */
+export const PROBE_TIMEOUT_MS = 5_000;
+
+export const PROBE_BINS = [
+  { key: "claude", bin: "claude", label: "Claude Code" },
+  { key: "opencode", bin: "opencode", label: "opencode" },
+  // Native app-server sessions use the same installed CLI we probe here.
+  { key: "codex", bin: "codex", label: "codex" },
+];
+
+/** Where the NATIVE (non-npm) Claude Code installer puts the binary, tried
+ * only as a fallback when the bare `claude` on PATH could not be run. npm
+ * installs a `.cmd`/`.exe` shim that `runnableCommand`'s PATHEXT search
+ * already finds through `Path`; the native installer writes a real
+ * executable straight to one of two fixed places and edits PATH itself - and
+ * a probe run in the SAME terminal session that just ran the installer often
+ * still has the OLD PATH, because Windows only broadcasts the change (a
+ * shell may not be listening) and a POSIX profile edit needs a new shell to
+ * be sourced. "Not on PATH this second" is not "not installed", so these two
+ * places are checked directly before giving up: `~/.local/bin` (the
+ * installer's own default, both platforms) and, Windows only, the
+ * standalone installer's per-user Program Files
+ * (`%LOCALAPPDATA%\Programs\claude\claude.exe`). `platform`/`env` are the
+ * same seams `runnableCommand` takes, so this is provable on macOS. */
+export function nativeClaudeCandidates({ platform = process.platform, env = process.env } = {}) {
+  const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
+  if (platform === "win32") {
+    const localAppData = env.LOCALAPPDATA?.trim();
+    return [
+      win32.join(home, ".local", "bin", "claude.exe"),
+      ...(localAppData ? [win32.join(localAppData, "Programs", "claude", "claude.exe")] : []),
+    ];
+  }
+  return [posix.join(home, ".local", "bin", "claude")];
+}
+
+// ---------------------------------------------------------------------------
+// RESOLVING A BINARY FOR A REAL SPAWN, not just a probe (2026-09-20).
+//
+// THE BUG THIS SECTION EXISTS FOR: a run spawned "spawn claude ENOENT" while
+// `claude --version` worked fine in the person's own terminal on the same
+// machine. The runner daemon is started by launchd (or systemd/a Windows
+// service), and that PROCESS'S PATH is the service manager's own default -
+// typically `/usr/bin:/bin:/usr/sbin:/sbin` on macOS - not the PATH a login
+// shell builds from `.zshrc`/`.bash_profile`/nvm/a brew `shellenv` line. On
+// POSIX, `runnableCommand` above (windows-command.mjs's sibling concern) does
+// NOTHING for a bare name - `{file: bin, shell: false}`, unchanged - so
+// `spawn("claude", ...)` was always relying on THIS process's inherited PATH,
+// and a daemon's inherited PATH is the wrong one to trust.
+//
+// `nativeClaudeCandidates` above already covers one case of this (the native
+// installer's `~/.local/bin/claude`, tried only for `claude` itself, from
+// `execProbe`'s retry). What follows generalizes past that: every engine this
+// bridge can spawn (`claude`, `opencode`, `codex`), not one name, and a login
+// shell asked directly rather than three more hard-coded paths guessed at -
+// the well-known directories are a fast, no-process-spawned first guess, and
+// the login shell is the same answer typing the bare name at that person's
+// own prompt would give, aliases aside (which a headless spawn could not use
+// anyway).
+
+/** Directories a login shell's PATH usually has that a service manager's does
+ *  not: an installer's own default, homebrew's two prefixes (Apple Silicon
+ *  and Intel share this list because checking a directory that is not there
+ *  costs one `existsSync` and nothing else), a manual PATH addition Claude
+ *  Code's own docs mention (`~/.claude/local`), and opencode's own installer
+ *  directory (`~/.opencode/bin` - 2026-09-21, measured on a Mac where
+ *  `opencode` lives ONLY there and in an nvm bin dir, so under bash, or with
+ *  no `$SHELL` at all, the daemon could not find it any other way). Windows
+ *  already gets a PATH/PATHEXT search at spawn time (`runnableCommand`),
+ *  so this is empty there rather than a second, competing guess. */
+export function knownBinDirs({ platform = process.platform, env = process.env } = {}) {
+  if (platform === "win32") return [];
+  const home = env.HOME?.trim() || homedir();
+  return [
+    posix.join(home, ".local", "bin"),
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    posix.join(home, ".claude", "local"),
+    posix.join(home, ".opencode", "bin"),
+  ];
+}
+
+/** The USABLE line out of a login shell's `command -v` output (2026-09-21,
+ *  review): a shell that prints a startup banner before running the `-c`
+ *  command (p10k, direnv, nvm's own version line) puts that banner FIRST and
+ *  the actual path LAST, so taking `split("\n")[0]` was reading the banner,
+ *  not the answer. Scan from the end instead and accept the first line that
+ *  is both an absolute path and something that actually exists on disk - a
+ *  bare name (an alias or a shell function `command -v` can also report) is
+ *  not a spawnable path and is skipped rather than returned. */
+function lastUsablePath(stdout, { exists }) {
+  const lines = String(stdout ?? "").split("\n").map((line) => line.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (posix.isAbsolute(line) && exists(line)) return line;
+  }
+  return null;
+}
+
+/** `command -v <bin>` under the person's own login shell, asked at most ONCE
+ *  PER (shell, bin) FOR THE LIFE OF THIS PROCESS: a login shell can be slow
+ *  to start (nvm, a heavy `.zshrc`), a daemon asks this for at most a small
+ *  handful of names (one per engine it ever tries to spawn), and every
+ *  request after the first must not pay for a shell spawn it already has the
+ *  answer to. Returns `null` on any failure - no `$SHELL` in this
+ *  environment, the shell exits non-zero, the binary really is not on that
+ *  PATH either - never throws: "could not resolve" is the caller's fact to
+ *  report, not this function's to raise.
+ *
+ *  TWO SHELLS, NOT ONE (2026-09-21, review): `$SHELL -lc` runs a login shell
+ *  but NOT an interactive one, and a non-interactive login zsh does not read
+ *  `.zshrc` - which is exactly where most macOS PATH additions (nvm, `npm
+ *  install -g`, bun) live. `-lc` alone answered `null` on the machine this
+ *  whole file was written for. When `-lc` comes back with nothing usable,
+ *  this retries once with `-ilc` (interactive login), which does read
+ *  `.zshrc`. Both spawns carry the same `timeoutMs` guard - an interactive
+ *  shell is the slower of the two to start, not a reason to wait longer for
+ *  it. */
+const loginShellCache = new Map();
+export async function loginShellWhich(bin, { env = process.env, execImpl = execFile, timeoutMs = PROBE_TIMEOUT_MS, exists = existsSync } = {}) {
+  const shell = env.SHELL?.trim();
+  if (!shell) return null;
+  const key = `${shell}::${bin}`;
+  if (loginShellCache.has(key)) return loginShellCache.get(key);
+
+  const runShell = (flag) => new Promise((resolve) => {
+    try {
+      execImpl(
+        shell,
+        [flag, 'command -v -- "$PM_RESOLVE_BIN"'],
+        { timeout: timeoutMs, env: { ...env, PM_RESOLVE_BIN: bin } },
+        (error, stdout) => resolve(error ? null : lastUsablePath(stdout, { exists })),
+      );
+    } catch {
+      resolve(null);
+    }
+  });
+
+  let found = await runShell("-lc");
+  if (!found) found = await runShell("-ilc");
+  loginShellCache.set(key, found);
+  return found;
+}
+
+/** Every directory on `env.PATH`, POSIX-split - the SAME list a bare
+ *  `spawn(bin, ...)` would already search on its own, read here too so a
+ *  caller that resolved successfully gets back a real path rather than
+ *  "probably fine". Only ever called on POSIX (`resolveAgentBinary` returns
+ *  before this on `win32`), so there is no `Path`/`;`-split branch to carry -
+ *  `windows-command.mjs`'s `runnableCommand` already owns that search. */
+function ownPathDirs({ env = process.env } = {}) {
+  return String(env.PATH ?? "").split(":").map((s) => s.trim()).filter(Boolean);
+}
+
+/** Can `bin` actually be spawned on this machine, and from where?
+ *
+ * THREE STEPS, cheapest and most-likely-to-answer first: this process's own
+ * PATH (what a bare `spawn(bin, ...)` would already find - checked here too,
+ * with `existsSync`, so a caller gets back a concrete path instead of a
+ * boolean), the well-known install directories (`knownBinDirs`, also no
+ * process spawned), and last a login shell's `command -v` (`loginShellWhich`
+ * - slowest, memoized, asked only when the first two came up empty).
+ *
+ * On POSIX a `bin` that already names a place (it contains a separator) is
+ * `PM_<AGENT>_BIN` set to an explicit path, handed back unchanged and
+ * unchecked. Windows answers with the spawn's own Path/PATHEXT search
+ * (`findWindowsCommand`): `knownBinDirs` returns nothing there and
+ * `loginShellWhich` needs `$SHELL`, which a Windows service does not set. */
+export async function resolveAgentBinary(bin, { platform = process.platform, env = process.env, exists = existsSync, execImpl = execFile } = {}) {
+  const onWindows = platform === "win32" ? findWindowsCommand(bin, { env, exists }) : undefined;
+  if (onWindows !== undefined) return { found: onWindows !== null, path: onWindows ?? bin, via: onWindows ? "path" : "none" };
+  if (/[\\/]/.test(bin)) return { found: true, path: bin, via: "unchanged" };
+  for (const dir of ownPathDirs({ env })) {
+    const candidate = posix.join(dir, bin);
+    if (exists(candidate)) return { found: true, path: candidate, via: "path" };
+  }
+  for (const dir of knownBinDirs({ platform, env })) {
+    const candidate = posix.join(dir, bin);
+    if (exists(candidate)) return { found: true, path: candidate, via: "known-dir" };
+  }
+  const shellPath = await loginShellWhich(bin, { env, execImpl, exists });
+  if (shellPath && exists(shellPath)) return { found: true, path: shellPath, via: "login-shell" };
+  return { found: false, path: bin, via: "none" };
+}
+
+/** The default runner of a probe: `<bin> --version`, never throwing.
+ *
+ * `platform`, `env`, `exists`, `readFile` and `execImpl` are injected so the
+ * `.cmd` resolution is provable on macOS. On Windows, npm installs `claude`
+ * and `opencode` as `.cmd` shims; `runnableCommand` resolves their Node entry
+ * points without exposing request arguments to cmd.exe.
+ *
+ * A PROBE IS THE ONLY THING THAT RETRIES (2026-09-12 review, F3). This ran
+ * interactive commands too, through a `stdio` mode, and the `claude` PATH-miss
+ * retry below ran for those as well: a `claude mcp login glytch` the person
+ * DECLINED in their browser exits non-zero, which this read as "not found on
+ * PATH" and re-ran through `~/.local/bin/claude` - a second browser window
+ * for a consent that was just refused. `--version` is safe to run twice and a
+ * login verb is not, so the interactive path is `runInteractive` below, which
+ * resolves its command once and runs it once. This function no longer takes
+ * `stdio` at all.
+ *
+ * For `claude` specifically, a PATH miss is retried against
+ * `nativeClaudeCandidates` before this reports not-found - see that function
+ * for why a native install can be right there and still lose the first
+ * lookup. */
+export const execProbe = (
+  bin,
+  args,
+  {
+    timeoutMs = PROBE_TIMEOUT_MS,
+    cwd,
+    platform = process.platform,
+    env = process.env,
+    exists,
+    readFile,
+    execImpl = execFile,
+  } = {},
+) => {
+  const checkExists = exists ?? existsSync;
+  const run = (target) =>
+    new Promise((resolve) => {
+      let resolved;
+      try {
+        resolved = runnableCommand(target, args, { platform, env, ...(exists ? { exists } : {}), ...(readFile ? { readFile } : {}) });
+      } catch (error) {
+        resolve({ ok: false, stdout: "", stderr: String(error?.message ?? error), code: null });
+        return;
+      }
+      const options = { env, timeout: timeoutMs, windowsHide: true, shell: resolved.shell, ...(cwd ? { cwd } : {}) };
+      execImpl(resolved.file, resolved.args, options, (error, stdout, stderr) => {
+        // `code` is part of the shape both runners answer in. execFile's error
+        // carries the exit status as a number when the child ran and failed,
+        // and a string like "ENOENT" when it never started - only the number
+        // is an exit code, so anything else is reported as null.
+        if (error) {
+          resolve({
+            ok: false,
+            stdout: "",
+            stderr: String(stderr ?? ""),
+            code: typeof error.code === "number" ? error.code : null,
+          });
+        } else {
+          resolve({ ok: true, stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), code: 0 });
+        }
+      });
+    });
+  return (async () => {
+    const first = await run(bin);
+    if (first.ok || bin !== "claude") return first;
+    for (const candidate of nativeClaudeCandidates({ platform, env })) {
+      if (!checkExists(candidate)) continue;
+      const result = await run(candidate);
+      if (result.ok) return result;
+    }
+    return first;
+  })();
+};
+
+/** How much of a failed interactive verb's stderr is kept: the LAST 64KB.
+ * Only the last line is ever reported (init-connect's `lastStderrLine`), and a
+ * verb that decides to stream progress at a terminal it thinks it has could
+ * otherwise grow this string without a ceiling for as long as the person
+ * leaves the browser open. The tail is the half that carries the failure. */
+export const STDERR_TAIL_LIMIT = 64 * 1024;
+
+/** RUN ONE COMMAND, ONCE, WITH THE PERSON'S OWN TERMINAL UNDER IT.
+ *
+ * This is what `init` drives an agent's OAuth verb with (brief 31, Move 2,
+ * 2026-09-12): `claude mcp login glytch` refuses a pipe with "stdin isn't a
+ * terminal" (measured on 2.1.269), so stdin and stdout are inherited - the
+ * flow can run and print its URL - and stderr stays piped so a failure still
+ * has a last line to report.
+ *
+ * WHY NOT `execFile`: it does not honour `stdio` at all. It builds the child's
+ * spawn options from a fixed field list (cwd, env, gid, uid, shell, signal,
+ * windowsHide, windowsVerbatimArguments, timeout, maxBuffer, killSignal) so it
+ * can always pipe all three streams itself and buffer them for its callback; a
+ * `stdio` option handed to it is silently dropped and the child never sees the
+ * terminal (confirmed 2026-09-12: a probe run that way under `script -q` still
+ * reported the child's `stdin.isTTY` as `undefined`). `spawn` is the primitive
+ * that honours it.
+ *
+ * WHY IT IS ITS OWN FUNCTION (2026-09-12 review, F3): this used to be a mode
+ * of `execProbe`, and inherited that function's `claude` PATH-miss retry. A
+ * declined consent exits non-zero, so a person who said no in the browser got
+ * a SECOND browser window from `~/.local/bin/claude`. The command is resolved
+ * once here, through the same `runnableCommand` every other spawn in this
+ * package uses, and run exactly once - a verb with a person in it gets one
+ * attempt, always.
+ *
+ * Answers in the same shape a probe does, `{ok, stdout, stderr, code}`;
+ * `stdout` is always "" because with stdio inherited there was never anything
+ * captured to return. `timeoutMs` is the caller's to name - the 5s probe
+ * timeout is for `--version`, and this waits on someone finding their password
+ * manager - and is left off entirely when it is not given. */
+export const runInteractive = (
+  bin,
+  args,
+  {
+    timeoutMs,
+    cwd,
+    platform = process.platform,
+    env = process.env,
+    exists,
+    readFile,
+    stdio = ["inherit", "inherit", "pipe"],
+    spawnImpl = spawn,
+  } = {},
+) =>
+  new Promise((resolve) => {
+    let resolved;
+    try {
+      resolved = runnableCommand(bin, args, { platform, env, ...(exists ? { exists } : {}), ...(readFile ? { readFile } : {}) });
+    } catch (error) {
+      resolve({ ok: false, stdout: "", stderr: String(error?.message ?? error), code: null });
+      return;
+    }
+    const options = {
+      windowsHide: true,
+      shell: resolved.shell,
+      stdio,
+      ...(timeoutMs ? { timeout: timeoutMs } : {}),
+      ...(cwd ? { cwd } : {}),
+    };
+    let stderr = "";
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    const child = spawnImpl(resolved.file, resolved.args, options);
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => {
+        stderr += String(chunk);
+        if (stderr.length > STDERR_TAIL_LIMIT) stderr = stderr.slice(stderr.length - STDERR_TAIL_LIMIT);
+      });
+    }
+    child.on("error", (error) =>
+      settle({ ok: false, stdout: "", stderr: stderr || String(error?.message ?? error), code: null }),
+    );
+    child.on("close", (code) => settle({ ok: code === 0, stdout: "", stderr, code }));
+  });
+
+/** Claude Code's login marker ON THE PLATFORMS THAT KEEP ONE AS A FILE.
+ *
+ * `CLAUDE_CONFIG_DIR` moves the whole config directory, and the file with it
+ * ("Claude Code keeps the `.credentials.json` file under that directory
+ * instead" - code.claude.com/docs/en/authentication#credential-management),
+ * so it is honoured here rather than assuming `~/.claude`.
+ *
+ * Its PRESENCE is the whole check. Reading its CONTENTS would mean this
+ * package handling someone's credentials, which it will not do. */
+export const claudeCredentialsPath = (env = process.env) => {
+  const configDir = env.CLAUDE_CONFIG_DIR?.trim();
+  if (configDir) return join(configDir, ".credentials.json");
+  return join(env.HOME?.trim() || homedir(), ".claude", ".credentials.json");
+};
+
+/** The macOS Keychain item Claude Code writes its login into.
+ *
+ * THE FILE PROBE ALONE WENT WRONG ON THIS MAC (2026-09-12, 2.1.269): there is
+ * no `~/.claude/.credentials.json`, the machine IS logged in, and `init`
+ * announced "Claude Code found 2.1.269 - NOT logged in" and told him to run
+ * `claude` once and log in. The credential is in the login Keychain.
+ *
+ * WHAT THE DOCS SAY, PER PLATFORM (code.claude.com/docs/en, read 2026-09-12,
+ * pages current through v2.1.265 so they cover 2.1.269; no page names a
+ * version at which the locations changed):
+ *
+ *   macOS    the encrypted login Keychain, with the FILE as a documented
+ *            fallback for when the Keychain cannot be written (a locked
+ *            keychain over SSH) - which is why this probe tries the keychain
+ *            and then still falls through to the file rather than instead
+ *            of it.
+ *   Linux    `~/.claude/.credentials.json`, mode 0600. Not a legacy path:
+ *            it is the documented primary store.
+ *   Windows  `%USERPROFILE%\\.claude\\.credentials.json`. NOT the Windows
+ *            Credential Manager - the docs say "protected by file
+ *            permissions on Windows and Linux", and the whole docs corpus
+ *            has no mention of Credential Manager, DPAPI, libsecret or
+ *            gnome-keyring for this.
+ *   WSL      not addressed anywhere in the docs. It is Linux, so it takes
+ *            the Linux path here by implication, not by a documented rule.
+ *
+ * So the file probe stays correct everywhere except macOS, and on macOS it is
+ * the second question rather than the only one.
+ *
+ * THE SERVICE NAME IS MEASURED, NOT DOCUMENTED. Nothing in the docs names the
+ * keychain item; this string was confirmed by running
+ * `security find-generic-password -s "Claude Code-credentials"` on his Mac
+ * against Claude Code 2.1.269 and getting exit 0. The docs do say
+ * `CLAUDE_CONFIG_DIR` "keys the macOS Keychain entry to that directory too",
+ * so a non-default config dir has an entry under some other name whose shape
+ * is not published - that case falls through to the file probe, which follows
+ * CLAUDE_CONFIG_DIR correctly, and at worst under-reports a login. An
+ * under-reported login is a yellow line telling someone to log in again; an
+ * over-reported one is a session that dies on spawn. */
+export const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+
+/** Is Claude Code logged in on this machine?
+ *
+ * EXIT CODE ONLY. `find-generic-password` is run WITHOUT `-w` and WITHOUT
+ * `-g`, the two flags that would make it emit the secret (to stdout and to
+ * stderr respectively). What comes back is the item's attributes, which are
+ * discarded unread - this package looks at `result.ok` and nothing else, the
+ * same promise `claudeCredentialsPath` makes about the file. */
+export async function claudeLoggedIn({
+  exec = execProbe,
+  env = process.env,
+  platform = process.platform,
+  credentialsPath,
+  fileExists,
+} = {}) {
+  if (platform === "darwin") {
+    const found = await exec("security", ["find-generic-password", "-s", CLAUDE_KEYCHAIN_SERVICE], { env });
+    if (found?.ok === true) return true;
+  }
+  return (fileExists ?? exists)(credentialsPath ?? claudeCredentialsPath(env));
+}
+
+const exists = async (path) => {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Pull a version number out of whatever the binary printed. Claude Code says
+ * "2.1.4 (Claude Code)", opencode says "0.9.1", and a future one will say
+ * something else again - so the first dotted number wins and the rest is
+ * ignored. Undefined when there is nothing that looks like one: found is
+ * still true, because the binary answered. */
+export function versionFrom(text) {
+  const match = /\b(\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?)\b/.exec(String(text ?? ""));
+  return match ? match[1] : undefined;
+}
+
+/** CLI syntax evidence, never a model request. Only explicit model IDs with
+ * documented effort support are advertised; aliases/default can be overridden.
+ * Checked with Claude Code 2.1.312 and code.claude.com/docs/en/model-config
+ * on 2026-10-28 (#3210). These are capabilities, not an availability catalog. */
+export async function probeClaudeEffort(bin, { exec = execProbe, env = process.env, timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  const help = await exec(bin, ["--help"], { env, timeoutMs });
+  if (!help?.ok) return {};
+  const match = /--effort\s+<level>[\s\S]*?\((low,[^)]*)\)/.exec(help.stdout ?? "");
+  if (!match) return {};
+  const levels = match[1].split(",").map((s) => s.trim());
+  const models = Object.create(null);
+  for (const model of ["claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-fable-5-1", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5"]) {
+    models[model] = ["low", "medium", "high", ...(model.endsWith("4-6") ? [] : ["xhigh"]), "max"].filter((level) => levels.includes(level));
+    // Documented 1M variants share the base model's effort support. Advertise
+    // the exact request key so both the picker and runner preserve its suffix.
+    if (model === "claude-opus-4-6" || model === "claude-sonnet-4-6") models[`${model}[1m]`] = models[model];
+  }
+  return models;
+}
+
+/** Probe every engine. Returns the `agents` block stage 2 writes into the
+ * mark file:
+ *
+ *   { claude: {found, version?, loggedIn}, opencode: {found, version?},
+ *     codex: {found} }
+ *
+ * `exec` is injected so the tests cover every branch without a binary being
+ * installed, and so a caller can probe with its own timeout. */
+export async function detectAgents({
+  exec = execProbe,
+  env = process.env,
+  bins = PROBE_BINS,
+  credentialsPath,
+  platform = process.platform,
+  fileExists,
+  timeoutMs = PROBE_TIMEOUT_MS,
+  codexDiscover = exec === execProbe ? discoverCodex : null,
+} = {}) {
+  const agents = {};
+  for (const spec of bins) {
+    const bin = env[`PM_${spec.key.toUpperCase()}_BIN`]?.trim() || spec.bin;
+    const result = await exec(bin, ["--version"], { timeoutMs, env });
+    const found = result?.ok === true;
+    const version = found ? versionFrom(result.stdout || result.stderr) : undefined;
+    agents[spec.key] = { found, ...(version ? { version } : {}) };
+  }
+  // Claude exposes a local marker - a keychain item on macOS, a file
+  // elsewhere; Codex is queried through app-server below.
+  if (agents.claude) {
+    if (agents.claude.found) {
+      const effortModels = await probeClaudeEffort(env.PM_CLAUDE_BIN?.trim() || bins.find((b) => b.key === "claude")?.bin || "claude", { exec, env, timeoutMs });
+      if (Object.keys(effortModels).length) agents.claude.effortModels = effortModels;
+    }
+    agents.claude.loggedIn = await claudeLoggedIn({ exec, env, platform, credentialsPath, fileExists });
+  }
+  if (agents.codex?.found && codexDiscover) {
+    try {
+      Object.assign(agents.codex, await codexDiscover({ bin: env.PM_CODEX_BIN?.trim() || "codex", env, timeoutMs }));
+    } catch { /* version detection remains valid when model discovery fails */ }
+  }
+  return agents;
+}
+
+/** The detection table `viewable init` prints, one line per engine. */
+export function detectionLines(agents, bins = PROBE_BINS) {
+  return bins.map((spec) => {
+    const found = agents?.[spec.key];
+    if (!found?.found) return `  ${spec.label.padEnd(12)} not installed on your computer`;
+    const version = found.version ? ` ${found.version}` : "";
+    const login =
+      found.loggedIn === true ? " - logged in" : found.loggedIn === false ? " - NOT logged in" : "";
+    return `  ${spec.label.padEnd(12)} found${version}${login}`;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// THE DAEMON'S COPY OF THE ANSWER, refreshed on a clock of its own.
+//
+// The mark file is written on the LIVENESS BEAT - every ten seconds, from a
+// timer whose whole job is to say the runner is still here. Three child
+// processes per beat would be absurd, and worse, a beat that waits on
+// `claude --version` on a cold disk is a beat the app is entitled to call
+// stopped. So the probe answers from MEMORY and refreshes in the background,
+// exactly like lib/update.mjs's daily npm check and for the same reason.
+//
+// FIVE MINUTES is the brief's number. It is not a compromise between "fresh"
+// and "cheap": installing a coding agent is a thing a person does once, and
+// the only case that matters is the one where they do it WITH the app open
+// and want the grey dot to go green without restarting anything. Five minutes
+// is short enough for that to feel like the machine noticed.
+//
+// A PROBE FAILURE IS `found: false`, NEVER A MISSING KEY AND NEVER A THROW -
+// `detectAgents` above already guarantees the first two (execProbe resolves
+// on error), and the try/catch here guarantees the third, so a machine where
+// spawning a child fails outright keeps its liveness beat.
+
+/** How often the daemon re-asks what is installed. */
+export const PROBE_INTERVAL_MS = 5 * 60_000;
+
+/**
+ * The cached probe the daemon's beat reads.
+ *
+ * `mark()` is SYNCHRONOUS and cheap, because the beat calls it: it returns
+ * what is known now and starts a refresh in the background when one is due.
+ * Before the first answer it returns `{}` - no `agents` key at all rather
+ * than a block of falses, because "not asked yet" and "not installed" are
+ * different facts and the app's dots must not claim the second while the
+ * first is true. `once()` is how a caller waits for a real answer; the daemon
+ * awaits it before the first folder is watched, so in practice the first mark
+ * a person ever sees already carries the block.
+ */
+export function makeAgentProbe({
+  detect = detectAgents,
+  env = process.env,
+  intervalMs = PROBE_INTERVAL_MS,
+  now = () => Date.now(),
+  log = () => {},
+} = {}) {
+  // null rather than 0 for the same reason update.mjs uses null: with an
+  // injected clock starting at zero, a zero here would read as "checked at
+  // time zero" and the first refresh would never fire.
+  let checkedAt = null;
+  let known = null;
+  let running = false;
+  const run = async () => {
+    running = true;
+    checkedAt = now();
+    try {
+      known = await detect({ env });
+    } catch (error) {
+      // Never take the beat down for a probe. An empty block is honest here:
+      // nothing was learned, so nothing is claimed.
+      log(`agent probe failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      running = false;
+    }
+  };
+  return {
+    /** What is known now, without asking anything. */
+    state: () => (known === null ? null : { ...known }),
+    /** What goes into the mark file, plus a refresh when one is due. */
+    mark() {
+      if (!running && (checkedAt === null || now() - checkedAt >= intervalMs)) void run();
+      return known === null ? {} : { agents: { ...known } };
+    },
+    /** Await one probe. The daemon's start, `doctor`, and the tests use this. */
+    async once() {
+      await run();
+      return known;
+    },
+  };
+}