@peakflo/agent-harness 0.2.8 → 0.2.9-rc.1

package/dist/harness-discovery.js

@@ -0,0 +1,727 @@
+"use strict";
+/**
+ * HARNESS DISCOVERY — which coding harnesses are installed on this machine.
+ *
+ * Modelled on 20x, where the harness code came from:
+ *   - `src/main/agent-installer/detect.js` finds the binaries (`claude`,
+ *     `codex`, `cursor-agent`, `opencode`, `pi`) with `--version`, after it
+ *     puts the well-known install directories on PATH;
+ *   - `src/renderer/src/types/index.ts` holds the static model lists the 20x
+ *     agent form shows for Claude Code, Codex and Cursor.
+ *
+ * WHAT THIS IS NOT. It is not the list of backends this runner can run.
+ * `capabilities.backends` stays that list and the control plane routes on it.
+ * An entry here says "this CLI is on the machine", and `runnable` says whether
+ * the runner can also drive it. Detection never implies turn support.
+ *
+ * RULES THIS MODULE KEEPS:
+ *
+ * 1. NEVER THROWS, NEVER REJECTS. One broken CLI must not hide the others, so
+ *    every harness is probed on its own, inside its own try/catch and its own
+ *    deadline.
+ * 2. TIME-LIMITED. Each command has a timeout and each harness has a total
+ *    deadline. A CLI that hangs is killed and reported as timed out.
+ * 3. NO SECRETS LEAVE THIS FILE. Sign-in is decided from an exit code, one
+ *    boolean of a status reply, or the existence of an environment variable or
+ *    a file. No status text is kept. Every `reason` is a constant from
+ *    `REASONS` below, never something a CLI printed. Model ids and names are
+ *    the only CLI text that is reported, and each one is checked first.
+ * 4. NO GLOBAL SIDE EFFECTS. `process.env.PATH` is not changed; the search path
+ *    is local and is handed to each child process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_HARNESSES = exports.CURSOR_STATIC_MODELS = exports.CODEX_STATIC_MODELS = exports.CLAUDE_STATIC_MODELS = exports.REASONS = exports.DISCOVERY_HARNESS_TIMEOUT_MS = exports.DISCOVERY_COMMAND_TIMEOUT_MS = void 0;
+exports.discoverySearchPath = discoverySearchPath;
+exports.discoveryChildEnv = discoveryChildEnv;
+exports.sanitizeHarnessModels = sanitizeHarnessModels;
+exports.parseVersion = parseVersion;
+exports.saysSignedOut = saysSignedOut;
+exports.parseCodexModelCache = parseCodexModelCache;
+exports.parseCodexDefaultModel = parseCodexDefaultModel;
+exports.parseCursorModels = parseCursorModels;
+exports.parseOpencodeModels = parseOpencodeModels;
+exports.discoverHarnesses = discoverHarnesses;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** One command: `--version`, a status check, or a model listing. */
+exports.DISCOVERY_COMMAND_TIMEOUT_MS = 8_000;
+/** Everything for one harness. Harnesses run concurrently, so this is also the bound for the whole pass. */
+exports.DISCOVERY_HARNESS_TIMEOUT_MS = 20_000;
+const MAX_MODELS_PER_HARNESS = 200;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+/**
+ * Every sentence a `reason` can be. A closed set on purpose: text printed by a
+ * CLI can hold an account email or a key, and a constant cannot.
+ */
+exports.REASONS = {
+    notInstalled: 'Not installed on this machine.',
+    versionTimedOut: 'The version check timed out.',
+    versionFailed: 'The version check failed.',
+    discoveryTimedOut: 'Discovery timed out.',
+    discoveryFailed: 'Discovery failed.',
+    signInTimedOut: 'The sign-in check timed out.',
+    signInUnknown: 'Sign-in could not be confirmed.',
+    codexSignIn: 'Not signed in. Run `codex login` on this machine.',
+    claudeSignIn: 'Not signed in. Run `claude auth login` on this machine.',
+    cursorSignIn: 'Not signed in. Run `cursor-agent login` on this machine.'
+};
+/* -------------------------------------------------------------------------- */
+/* Static model lists — copied from 20x `src/renderer/src/types/index.ts`      */
+/* -------------------------------------------------------------------------- */
+/** 20x `CLAUDE_MODELS`. Claude Code has no command that lists models. */
+exports.CLAUDE_STATIC_MODELS = [
+    { id: 'claude-fable-5-1', name: 'Claude Fable 5.1' },
+    { id: 'claude-fable-5', name: 'Claude Fable 5' },
+    { id: 'claude-opus-5-5', name: 'Claude Opus 5.5' },
+    { id: 'claude-opus-5', name: 'Claude Opus 5' },
+    { id: 'claude-sonnet-5-5', name: 'Claude Sonnet 5.5' },
+    { id: 'claude-sonnet-5', name: 'Claude Sonnet 5' },
+    { id: 'claude-opus-4-8', name: 'Claude Opus 4.8' },
+    { id: 'claude-opus-4-7', name: 'Claude Opus 4.7' },
+    { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6' },
+    { id: 'claude-sonnet-4-5', name: 'Claude Sonnet 4.5' },
+    { id: 'claude-opus-4-6', name: 'Claude Opus 4.6' },
+    { id: 'claude-haiku-4-5', name: 'Claude Haiku 4.5' },
+    { id: 'claude-3-7-sonnet-20250219', name: 'Claude 3.7 Sonnet' },
+    { id: 'claude-3-5-sonnet-20241022', name: 'Claude 3.5 Sonnet (Oct)' },
+    { id: 'claude-3-5-sonnet-20240620', name: 'Claude 3.5 Sonnet (Jun)' }
+];
+/** 20x `CODEX_MODELS`. Used only when Codex's own model cache cannot be read. */
+exports.CODEX_STATIC_MODELS = [
+    { id: 'gpt-6-astra', name: 'GPT-6 Astra' },
+    { id: 'gpt-6.1-sol', name: 'GPT-6.1 Sol' },
+    { id: 'gpt-6-sol', name: 'GPT-6 Sol' },
+    { id: 'gpt-6-luna', name: 'GPT-6 Luna' },
+    { id: 'gpt-5.6-sol', name: 'GPT-5.6 Sol' },
+    { id: 'gpt-5.6-terra', name: 'GPT-5.6 Terra' },
+    { id: 'gpt-5.6-luna', name: 'GPT-5.6 Luna' },
+    { id: 'gpt-5.5', name: 'GPT-5.5' },
+    { id: 'gpt-5.4', name: 'GPT-5.4' },
+    { id: 'gpt-5.4-mini', name: 'GPT-5.4 Mini' },
+    { id: 'gpt-5.3-codex-spark', name: 'GPT-5.3 Codex Spark' }
+];
+/** 20x `CURSOR_MODELS`. Used only when `cursor-agent models` gives nothing. */
+exports.CURSOR_STATIC_MODELS = [
+    { id: 'composer-2.5', name: 'Composer 2.5' },
+    { id: 'grok-4.5', name: 'Grok 4.5' }
+];
+/**
+ * Where to look for a harness binary: PATH first, then the directories the
+ * harness installers use. The well-known directories come from 20x
+ * `detect.js` (`ensureAgentPaths` and `getPiCommandCandidates`). The directory
+ * of the running `node` is added because a runner started by launchd or
+ * systemd has a short PATH, and an npm-installed CLI sits beside that `node`.
+ */
+function discoverySearchPath(env, home, platform = process.platform) {
+    /*
+     * ABSOLUTE ENTRIES ONLY. A relative entry (`.`, `node_modules/.bin`) means
+     * "whatever is in the directory the runner was started from", and a file
+     * named `codex` there is not the user's Codex.
+     */
+    const fromEnv = (env.PATH ?? env.Path ?? '')
+        .split(node_path_1.delimiter)
+        .filter((entry) => entry !== '' && (0, node_path_1.isAbsolute)(entry));
+    const known = platform === 'win32'
+        ? [
+            (0, node_path_1.join)(home, 'AppData', 'Roaming', 'npm'),
+            (0, node_path_1.join)(home, '.local', 'bin'),
+            (0, node_path_1.join)(home, '.opencode', 'bin')
+        ]
+        : [
+            (0, node_path_1.join)(home, '.local', 'bin'),
+            (0, node_path_1.join)(home, '.opencode', 'bin'),
+            '/opt/homebrew/bin',
+            '/usr/local/bin',
+            (0, node_path_1.join)(home, '.npm-global', 'bin'),
+            (0, node_path_1.join)(home, '.volta', 'bin'),
+            (0, node_path_1.join)(home, '.bun', 'bin')
+        ];
+    return [...new Set([...fromEnv, ...known, (0, node_path_1.dirname)(process.execPath)])];
+}
+function isExecutableFile(path) {
+    try {
+        if (!(0, node_fs_1.statSync)(path).isFile())
+            return false;
+        (0, node_fs_1.accessSync)(path, node_fs_1.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultResolveCommand(command, searchPath, env) {
+    // npm installs `.cmd` wrappers on Windows, so the bare name is not a file.
+    const extensions = process.platform === 'win32'
+        ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+        : [''];
+    for (const dir of searchPath) {
+        for (const extension of extensions) {
+            const candidate = (0, node_path_1.join)(dir, `${command}${extension}`);
+            if (isExecutableFile(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function defaultExec(command, args, timeoutMs, env) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer = null;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(result);
+        };
+        try {
+            const isWindows = process.platform === 'win32';
+            const child = (0, node_child_process_1.execFile)(
+            // `shell: true` is what resolves `.cmd` wrappers on Windows (20x
+            // detect.js). With a shell the path must be quoted by hand.
+            isWindows ? `"${command}"` : command, args, {
+                timeout: timeoutMs,
+                killSignal: 'SIGKILL',
+                shell: isWindows,
+                windowsHide: true,
+                maxBuffer: MAX_OUTPUT_BYTES,
+                env: { ...env, NO_COLOR: '1', TERM: 'dumb' }
+            }, (error, stdout, stderr) => {
+                const failure = error;
+                finish({
+                    code: failure
+                        ? typeof failure.code === 'number'
+                            ? failure.code
+                            : null
+                        : 0,
+                    stdout: String(stdout ?? ''),
+                    stderr: String(stderr ?? ''),
+                    timedOut: failure?.killed === true
+                });
+            });
+            // A CLI that waits for input must see end-of-file, not a terminal.
+            child.stdin?.end();
+            child.on('error', () => undefined);
+            /*
+             * THE BACKSTOP. `execFile` calls back only when the output pipes close,
+             * and a killed CLI can leave a child of its own holding them open. This
+             * timer answers anyway, so a hanging harness costs its timeout and no
+             * more.
+             */
+            timer = setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // Already gone.
+                }
+                finish({ code: null, stdout: '', stderr: '', timedOut: true });
+            }, timeoutMs + 250);
+            timer.unref();
+        }
+        catch {
+            // execFile can throw synchronously (EACCES on a non-executable path).
+            finish({ code: null, stdout: '', stderr: '', timedOut: false });
+        }
+    });
+}
+/**
+ * The environment a harness CLI is started with.
+ *
+ * EVERY `PF_*` VARIABLE IS REMOVED. Those are this runner's own settings and
+ * include `PF_ENROLMENT_TOKEN`; a third-party CLI has no use for them and
+ * must not be handed them. The rest is kept, because each CLI finds its own
+ * login through it (`HOME`, `CODEX_HOME`, `ANTHROPIC_API_KEY`, ...).
+ */
+function discoveryChildEnv(env, searchPath) {
+    const child = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (!/^PF_/i.test(key))
+            child[key] = value;
+    }
+    // `Path` is how Windows spells it; one PATH only, the search path.
+    delete child.Path;
+    child.PATH = searchPath.join(node_path_1.delimiter);
+    return child;
+}
+function resolveDeps(overrides = {}) {
+    const env = overrides.env ?? process.env;
+    const home = overrides.home ?? (0, node_os_1.homedir)();
+    const searchPath = discoverySearchPath(env, home);
+    const childEnv = discoveryChildEnv(env, searchPath);
+    return {
+        exec: (command, args, timeoutMs) => defaultExec(command, args, timeoutMs, childEnv),
+        resolveCommand: (command) => defaultResolveCommand(command, searchPath, env),
+        realpath: (path) => (0, node_fs_1.realpathSync)(path),
+        readFile: (path) => {
+            try {
+                return (0, node_fs_1.readFileSync)(path, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        exists: (path) => (0, node_fs_1.existsSync)(path),
+        now: () => new Date(),
+        ...overrides,
+        env,
+        home
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Cleaning what a CLI printed                                                 */
+/* -------------------------------------------------------------------------- */
+// eslint-disable-next-line no-control-regex
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f\u200b-\u200d\ufeff]/g;
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/@+[\]-]{0,127}$/;
+/** An email, a bearer value, a JWT, or a key with a well-known prefix. */
+const SECRET_LIKE = /[^\s@]+@[^\s@]+\.[^\s@]+|\bBearer\s|\beyJ[\w-]{10,}|\b(?:sk|pk|rk)-[\w-]{8,}|\bgh[pousr]_\w{8,}|\bxox[abprs]-[\w-]{8,}|\bAKIA[A-Z0-9]{12,}/i;
+function cleanLine(text) {
+    return text.replace(ANSI, '').replace(CONTROL, '').trim();
+}
+/**
+ * Keep only entries that look like a model. Anything that looks like a secret
+ * is dropped whole: a model list has no reason to hold one, so the safe
+ * reading of such a line is that it is not a model.
+ */
+function sanitizeHarnessModels(models) {
+    const out = [];
+    const seen = new Set();
+    for (const entry of models) {
+        if (out.length >= MAX_MODELS_PER_HARNESS)
+            break;
+        if (typeof entry?.id !== 'string')
+            continue;
+        const id = cleanLine(entry.id);
+        if (!MODEL_ID.test(id) || SECRET_LIKE.test(id) || seen.has(id))
+            continue;
+        const rawName = typeof entry.name === 'string' ? cleanLine(entry.name) : '';
+        const name = rawName && !SECRET_LIKE.test(rawName) ? rawName : id;
+        seen.add(id);
+        out.push({
+            id,
+            name: name.slice(0, 120),
+            ...(entry.default === true ? { default: true } : {})
+        });
+    }
+    return out;
+}
+/** Mark exactly one model as the default: `preferred` when listed, else the first. */
+function withDefault(models, preferred) {
+    if (models.length === 0)
+        return models;
+    const chosen = (preferred && models.find((model) => model.id === preferred)?.id) ||
+        models.find((model) => model.default)?.id ||
+        models[0].id;
+    return models.map(({ id, name }) => id === chosen ? { id, name, default: true } : { id, name });
+}
+/** The first version-like token, as 20x `detect.js` reads it. */
+function parseVersion(output) {
+    const match = cleanLine(output).match(/(\d+\.\d+[\w.+-]*)/);
+    return match ? match[1].slice(0, 64) : null;
+}
+function hasEnv(env, names) {
+    return names.some((name) => Boolean(env[name]));
+}
+/** An on/off variable that is switched ON. Present is not enough. */
+function hasFlag(env, names) {
+    return names.some((name) => /^(1|true|yes|on)$/i.test((env[name] ?? '').trim()));
+}
+/**
+ * A CLI said it is NOT signed in. Tested BEFORE any positive pattern, because
+ * "You are not currently logged in" also contains "logged in".
+ */
+const SIGNED_OUT = /\bnot\b[^.\n]{0,40}\b(?:logged|signed)[\s-]?in\b|\bnot\s+authenticated\b|\bunauthenticated\b|\blogged\s+out\b|\bsigned\s+out\b|\blog\s?in\s+required\b|\bplease\s+(?:log|sign)\s?in\b|\bno\s+credentials\b/i;
+const SIGNED_IN = /\b(?:logged|signed)\s+in\b|\bauthenticated\b/i;
+function saysSignedOut(text) {
+    return SIGNED_OUT.test(text);
+}
+function parseJsonObject(text) {
+    if (!text)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/* ---- Codex --------------------------------------------------------------- */
+function codexHome(deps) {
+    return deps.env.CODEX_HOME || (0, node_path_1.join)(deps.home, '.codex');
+}
+/**
+ * Codex keeps the models its account can use in `models_cache.json`. This is a
+ * model cache, not a credential file; only `slug`, `display_name`,
+ * `visibility` and `priority` are read from it.
+ */
+function parseCodexModelCache(text) {
+    const cache = parseJsonObject(text);
+    const list = Array.isArray(cache?.models) ? cache.models : [];
+    const listed = list
+        .filter((entry) => Boolean(entry) &&
+        typeof entry === 'object' &&
+        typeof entry.slug === 'string' &&
+        // 'hide' marks internal models the Codex picker does not show either.
+        (entry.visibility ?? 'list') === 'list')
+        .sort((a, b) => (typeof a.priority === 'number'
+        ? a.priority
+        : Number.MAX_SAFE_INTEGER) -
+        (typeof b.priority === 'number' ? b.priority : Number.MAX_SAFE_INTEGER));
+    return sanitizeHarnessModels(listed.map((entry) => ({ id: entry.slug, name: entry.display_name })));
+}
+/** The top-level `model = "..."` of `config.toml`. Nothing else is read. */
+function parseCodexDefaultModel(text) {
+    if (!text)
+        return null;
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        // A table header ends the top level; keys below it belong to the table.
+        if (trimmed.startsWith('['))
+            return null;
+        const match = trimmed.match(/^model\s*=\s*["']([^"']{1,128})["']/);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+const CODEX = {
+    name: 'codex',
+    label: 'Codex',
+    commands: ['codex'],
+    async checkAuth({ deps, run }) {
+        // 20x `codex-adapter.ts` `checkHealth` accepts these two keys.
+        if (hasEnv(deps.env, ['OPENAI_API_KEY', 'CODEX_API_KEY'])) {
+            return { usable: true };
+        }
+        // Exit code only. The reply names the sign-in method, which is not needed.
+        const status = await run(['login', 'status']);
+        if (status.timedOut)
+            return { usable: false, reason: exports.REASONS.signInTimedOut };
+        // The exit code decides; the text is only tested for a plain "not
+        // logged in", in case a version exits 0 while saying so. Nothing is kept.
+        return status.code === 0 &&
+            !saysSignedOut(`${status.stdout}\n${status.stderr}`)
+            ? { usable: true }
+            : { usable: false, reason: exports.REASONS.codexSignIn };
+    },
+    async listModels({ deps }) {
+        const home = codexHome(deps);
+        const preferred = parseCodexDefaultModel(deps.readFile((0, node_path_1.join)(home, 'config.toml')));
+        const cached = parseCodexModelCache(deps.readFile((0, node_path_1.join)(home, 'models_cache.json')));
+        if (cached.length > 0) {
+            return { models: withDefault(cached, preferred), source: 'config' };
+        }
+        return {
+            models: withDefault([...exports.CODEX_STATIC_MODELS], preferred),
+            source: 'static'
+        };
+    }
+};
+/* ---- Claude Code --------------------------------------------------------- */
+function claudeHome(deps) {
+    return deps.env.CLAUDE_CONFIG_DIR || (0, node_path_1.join)(deps.home, '.claude');
+}
+const CLAUDE = {
+    name: 'claude-code',
+    label: 'Claude Code',
+    commands: ['claude'],
+    async checkAuth({ deps, run }) {
+        if (hasEnv(deps.env, [
+            'ANTHROPIC_API_KEY',
+            'ANTHROPIC_AUTH_TOKEN',
+            'CLAUDE_CODE_OAUTH_TOKEN'
+        ]) ||
+            // These two are on/off switches, so `=0` and `=false` mean OFF.
+            hasFlag(deps.env, ['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX'])) {
+            return { usable: true };
+        }
+        const status = await run(['auth', 'status']);
+        if (status.timedOut)
+            return { usable: false, reason: exports.REASONS.signInTimedOut };
+        /*
+         * The reply is JSON that also holds the account email and organisation.
+         * ONE boolean is read from it and the rest is dropped here.
+         */
+        const loggedIn = parseJsonObject(status.stdout)?.loggedIn;
+        if (loggedIn === true)
+            return { usable: true };
+        if (loggedIn === false)
+            return { usable: false, reason: exports.REASONS.claudeSignIn };
+        if (saysSignedOut(`${status.stdout}\n${status.stderr}`)) {
+            return { usable: false, reason: exports.REASONS.claudeSignIn };
+        }
+        // Exit 0 with a reply that cannot be read is NOT taken as signed in:
+        // without the boolean there is nothing to base "yes" on.
+        // An older CLI has no `auth status`. On Linux the login is a file; only
+        // its existence is checked. On macOS it is in the Keychain, which is not
+        // read, so the honest answer there is "could not confirm".
+        if (deps.exists((0, node_path_1.join)(claudeHome(deps), '.credentials.json'))) {
+            return { usable: true };
+        }
+        return { usable: false, reason: exports.REASONS.signInUnknown };
+    },
+    async listModels({ deps }) {
+        // Only the `model` key is read. The file can also hold an `env` block.
+        const configured = parseJsonObject(deps.readFile((0, node_path_1.join)(claudeHome(deps), 'settings.json')))?.model;
+        return {
+            models: withDefault([...exports.CLAUDE_STATIC_MODELS], typeof configured === 'string' ? configured : null),
+            source: 'static'
+        };
+    }
+};
+/* ---- Cursor -------------------------------------------------------------- */
+/**
+ * `cursor-agent models` prints one `id - Name` line per model and marks the
+ * default with `(current, default)` or `(default)`.
+ */
+function parseCursorModels(output) {
+    const parsed = [];
+    for (const raw of output.split('\n')) {
+        const match = cleanLine(raw).match(/^(\S+)\s+-\s+(.+)$/);
+        if (!match)
+            continue;
+        const marker = match[2].match(/\s*\(([^()]*)\)\s*$/);
+        const isMarker = marker ? /\b(current|default)\b/i.test(marker[1]) : false;
+        parsed.push({
+            id: match[1],
+            name: isMarker ? match[2].slice(0, marker.index).trim() : match[2],
+            ...(isMarker && /\bdefault\b/i.test(marker[1]) ? { default: true } : {})
+        });
+    }
+    return sanitizeHarnessModels(parsed);
+}
+const CURSOR = {
+    name: 'cursor',
+    label: 'Cursor',
+    // 20x drives `cursor-agent` (`agent-manager.ts`: `cursor-agent acp`). Newer
+    // installers also add a plain `agent` command.
+    commands: ['cursor-agent', 'agent'],
+    /*
+     * `agent` IS A NAME OTHER TOOLS USE TOO. On the machine this was written on,
+     * `agent` is a different vendor's CLI. So `agent` counts as Cursor only when
+     * the file it resolves to lives in a Cursor directory.
+     */
+    accept(command, path, deps) {
+        if (command !== 'agent')
+            return true;
+        try {
+            // A path SEGMENT, not any mention: `~/work/cursor-notes/bin/agent` is
+            // not Cursor. The installer puts the real file under
+            // `~/.local/share/cursor-agent/` and older ones under `~/.cursor/`.
+            return /[\\/](?:cursor-agent|\.cursor)[\\/]/i.test(deps.realpath(path));
+        }
+        catch {
+            return false;
+        }
+    },
+    async checkAuth({ deps, run }) {
+        if (hasEnv(deps.env, ['CURSOR_API_KEY']))
+            return { usable: true };
+        const status = await run(['status']);
+        if (status.timedOut)
+            return { usable: false, reason: exports.REASONS.signInTimedOut };
+        // The reply names the account. It is tested here and never stored.
+        const text = `${status.stdout}\n${status.stderr}`;
+        // The negative test comes first and wins.
+        if (saysSignedOut(text)) {
+            return { usable: false, reason: exports.REASONS.cursorSignIn };
+        }
+        if (status.code === 0 && SIGNED_IN.test(text)) {
+            return { usable: true };
+        }
+        return { usable: false, reason: exports.REASONS.signInUnknown };
+    },
+    async listModels({ run }, usable) {
+        // The listing needs a signed-in account, so it is not tried without one.
+        if (usable) {
+            const listed = await run(['models']);
+            const models = listed.code === 0 ? parseCursorModels(listed.stdout) : [];
+            if (models.length > 0) {
+                return { models: withDefault(models), source: 'cli' };
+            }
+        }
+        return { models: withDefault([...exports.CURSOR_STATIC_MODELS]), source: 'static' };
+    }
+};
+/* ---- Pi ------------------------------------------------------------------ */
+const PI = {
+    name: 'pi',
+    label: 'Pi',
+    commands: ['pi'],
+    // Pi needs no login of its own here: each turn brings the Peakflo model
+    // gateway and a key for it.
+    async checkAuth() {
+        return { usable: true };
+    },
+    // The runner already probes Pi's models for `backends[].models`
+    // (model-probe.ts). The caller copies that list in, so Pi is not started
+    // twice.
+    async listModels() {
+        return null;
+    }
+};
+/* ---- OpenCode ------------------------------------------------------------ */
+/** `opencode models` prints one `provider/model` id per line. */
+function parseOpencodeModels(output) {
+    return sanitizeHarnessModels(output
+        .split('\n')
+        .map((line) => cleanLine(line))
+        .filter((line) => /^[^\s/]+\/\S+$/.test(line))
+        .map((id) => ({ id, name: id })));
+}
+const OPENCODE = {
+    name: 'opencode',
+    label: 'OpenCode',
+    commands: ['opencode'],
+    // OpenCode has no status command and serves some models with no login.
+    async checkAuth() {
+        return { usable: true };
+    },
+    async listModels({ run }) {
+        const listed = await run(['models']);
+        const models = listed.code === 0 ? parseOpencodeModels(listed.stdout) : [];
+        return models.length > 0 ? { models, source: 'cli' } : null;
+    }
+};
+/** Every harness this build knows how to look for, in display order. */
+exports.KNOWN_HARNESSES = [
+    CODEX,
+    CLAUDE,
+    CURSOR,
+    PI,
+    OPENCODE
+].map(({ name, label }) => ({ name, label }));
+const SPECS = [CODEX, CLAUDE, CURSOR, PI, OPENCODE];
+/* -------------------------------------------------------------------------- */
+/* The pass                                                                    */
+/* -------------------------------------------------------------------------- */
+async function probeHarness(spec, entry, deps, commandTimeoutMs, isExpired) {
+    let path = null;
+    for (const command of spec.commands) {
+        const found = deps.resolveCommand(command);
+        if (found && (spec.accept?.(command, found, deps) ?? true)) {
+            path = found;
+            break;
+        }
+    }
+    if (!path)
+        return;
+    entry.installed = true;
+    entry.version = null;
+    delete entry.reason;
+    const resolved = path;
+    const context = {
+        path: resolved,
+        deps,
+        /*
+         * NOTHING IS STARTED AFTER THE HARNESS DEADLINE. The report has already
+         * been sent without this harness by then, so a sign-in check or a model
+         * listing started now would be a process nobody is waiting for.
+         */
+        run: (args) => isExpired()
+            ? Promise.resolve({
+                code: null,
+                stdout: '',
+                stderr: '',
+                timedOut: true
+            })
+            : deps.exec(resolved, args, commandTimeoutMs)
+    };
+    const version = await context.run(['--version']);
+    if (version.timedOut) {
+        entry.reason = exports.REASONS.versionTimedOut;
+        return;
+    }
+    if (version.code !== 0) {
+        entry.reason = exports.REASONS.versionFailed;
+        return;
+    }
+    // 20x reads stdout and stderr together: some CLIs print the version on stderr.
+    // A version that cannot be parsed stays null and the harness is still reported.
+    entry.version = parseVersion(`${version.stdout}\n${version.stderr}`);
+    const auth = await spec.checkAuth(context);
+    entry.usable = auth.usable;
+    if (!auth.usable && auth.reason)
+        entry.reason = auth.reason;
+    const listed = await spec.listModels(context, auth.usable);
+    if (listed && listed.models.length > 0) {
+        entry.models = listed.models;
+        entry.modelSource = listed.source;
+    }
+}
+/**
+ * Look for every known harness. ALWAYS resolves, with one entry per known
+ * harness in a fixed order — a harness that is missing is reported as
+ * `installed: false`, so the reader can tell "not installed" from "this runner
+ * does not report harnesses".
+ */
+async function discoverHarnesses(options = {}) {
+    const commandTimeoutMs = options.commandTimeoutMs ?? exports.DISCOVERY_COMMAND_TIMEOUT_MS;
+    const harnessTimeoutMs = options.harnessTimeoutMs ?? exports.DISCOVERY_HARNESS_TIMEOUT_MS;
+    const runnable = new Set(options.runnableBackends ?? []);
+    let deps = null;
+    let detectedAt = new Date().toISOString();
+    try {
+        deps = resolveDeps(options.deps);
+        detectedAt = deps.now().toISOString();
+    }
+    catch {
+        // `os.homedir()` throws on some locked-down hosts. Report every harness
+        // as not found rather than fail the runner.
+    }
+    return Promise.all(SPECS.map(async (spec) => {
+        /*
+         * The entry is filled in as the probe goes, so a deadline or a throw
+         * part-way still reports what was already learnt (found, and where).
+         */
+        const entry = {
+            name: spec.name,
+            label: spec.label,
+            installed: false,
+            usable: false,
+            reason: exports.REASONS.notInstalled,
+            runnable: false,
+            detectedAt
+        };
+        if (!deps) {
+            entry.reason = exports.REASONS.discoveryFailed;
+            return entry;
+        }
+        let timer = null;
+        let expired = false;
+        const work = probeHarness(spec, entry, deps, commandTimeoutMs, () => expired).then(() => 'done', () => 'failed');
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                expired = true;
+                resolve('expired');
+            }, harnessTimeoutMs);
+            timer.unref();
+        });
+        const outcome = await Promise.race([work, deadline]);
+        if (timer)
+            clearTimeout(timer);
+        // A copy, so a probe still running after its deadline cannot change
+        // what was reported.
+        const report = { ...entry };
+        if (outcome !== 'done') {
+            report.usable = false;
+            report.reason = expired
+                ? exports.REASONS.discoveryTimedOut
+                : exports.REASONS.discoveryFailed;
+            delete report.models;
+            delete report.modelSource;
+        }
+        // Runnable needs both: the runner drives it AND the binary is there.
+        report.runnable = report.installed && runnable.has(spec.name);
+        return report;
+    }));
+}