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

package/README.md

@@ -4,7 +4,9 @@ Run a Peakflo coding agent on your machine.
 
 ## Quick start
 
-Use Node.js 22.19 or newer and install Git. Install the Pi coding agent once:
+Use Node.js 22.19 or newer and install Git. The runner checks the Node.js
+version when it starts and stops with one line if it is older (see
+"Troubleshooting"). Install the Pi coding agent once:
 
 ```sh
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent
@@ -44,13 +46,36 @@ Claude Code (`claude`), Cursor (`cursor-agent`), Pi (`pi`) and OpenCode
 whether it is signed in, and the models it offers. Peakflo shows this list in
 the agent editor and in the chat details.
 
-Finding a harness does not mean the runner can use it. The runner runs turns
-with Pi only; the other harnesses are shown as "Detected, not yet runnable by
-this runner".
+**Which ones the runner can run.** Pi always. On a desktop or self-hosted
+machine also Codex, Claude Code and Cursor, each for as long as it is
+installed and signed in on that machine — the runner uses that sign-in, as you
+do when you run the tool yourself. An agent in Peakflo can then be given that
+harness and one of its models. OpenCode is listed and cannot be run yet. A
+cloud sandbox runs Pi only.
+
+- These turns use your own Codex, Claude or Cursor account. They do not go
+  through the Peakflo model gateway and are not metered by Peakflo.
+- When you sign out of a harness, or remove it, the runner stops taking work
+  for it after its next check.
+- Claude Code also needs the Claude Agent SDK, which is not installed with the
+  runner: `npm install -g @anthropic-ai/claude-agent-sdk`. Without it Peakflo
+  shows Claude Code as "Detected, not runnable by this runner" with this
+  instruction.
+- Each turn starts the harness's own program and stops it when the turn ends.
+  The conversation continues from the session the harness saved on this
+  machine.
 
 **When it looks.** Once after start, without delaying registration, and then
 every five minutes while no turn is running. A harness you install or sign in
-to later appears without a restart.
+to later appears without a restart. At most two of these programs run at the
+same time.
+
+**A slow machine.** Some of these programs take several seconds to start. When
+one does not answer in time, Peakflo shows it as "Installed — check timed out,
+will retry", not as unavailable. The runner checks it again after 30 seconds,
+then 60, then 120, and after that with the normal five-minute pass. A state
+that was already known (signed in, or not signed in) is kept when a later
+check times out.
 
 **What it runs.** To do this the runner starts those programs, as your user,
 with `--version` and a status or model-list command. It looks in the absolute
@@ -71,6 +96,27 @@ about what a third-party program prints.
 `PF_HARNESS_DISCOVERY=0`. The runner then starts none of these programs and
 reports no list. Running turns with Pi is not affected.
 
+## Troubleshooting
+
+**`npx @peakflo/agent-harness` fails with a 404.** Your `~/.npmrc` maps the
+`@peakflo` scope to another registry (for example GitHub Packages). Name the
+public registry for this one command:
+
+```sh
+npx --@peakflo:registry=https://registry.npmjs.org @peakflo/agent-harness@latest start
+```
+
+**"pf-agent-harness needs Node.js 22.19 or newer".** Switch to a newer
+Node.js, for example `nvm install 22 && nvm use 22`, and start again. npm only
+prints an `EBADENGINE` warning for an older Node.js and installs anyway; the
+runner is what stops. The requirement comes from Pi, which the runner starts
+with the same Node.js. To start on an older Node.js at your own risk, set
+`PF_ALLOW_UNSUPPORTED_NODE=1`.
+
+**"Durable store unavailable, running in memory".** The runner could not
+create or open its database under `--workspace-root`. It creates that
+directory itself when it is missing, so check that the path is writable.
+
 ## Releasing
 
 `.github/scripts/agent-harness-release.mjs` publishes this package

package/dist/adapter-resolver.d.ts

@@ -0,0 +1,61 @@
+import { type CodingAgentAdapter } from './adapters';
+import type { AdapterPorts } from './harness';
+/**
+ * Give a vendor adapter the one thing the runner asks of a backend at the end
+ * of a turn: `stopServer()`.
+ *
+ * ONE PROCESS PER TURN, as for Pi. In 20x an adapter lives as long as the app
+ * and its CLI process stays up between messages. Here every turn is a new
+ * lease with its own MCP token, the runner may be handed the same chat by a
+ * control plane that last ran it elsewhere, and nothing may be left running
+ * when no turn is. So the process a turn started is stopped when the turn
+ * ends, and the next turn resumes the vendor's own saved session by its
+ * checkpoint (Codex thread id, Claude session id, Cursor ACP session id) —
+ * the path these adapters already have for "the app was restarted".
+ *
+ * Leaving the process up is not merely wasteful: `codex app-server` keeps the
+ * thread open for writing, and the next turn's `thread/resume` from a second
+ * process is refused with "already has an active writer".
+ *
+ * The session ids are recorded here, from what `createSession` returned and
+ * `resumeSession` was given, rather than read out of the adapter's private
+ * state. `destroySession` is the adapters' own teardown and does not delete
+ * the vendor's saved session.
+ */
+/** How long the end of a turn waits for one vendor session to stop. */
+export declare const STOP_TIMEOUT_MS = 5000;
+export declare function stopAtTurnEnd<T extends CodingAgentAdapter>(adapter: T, instanceId?: string | null, options?: {
+    /**
+     * The adapter numbers its parts from 1 in every process
+     * (`agent-response-1`). See `pollMessages` below.
+     */
+    partIdsRestartEveryProcess?: boolean;
+}): T;
+/**
+ * A random id for THIS runner's vendor sessions, written once into the
+ * runner's own state directory (never into a vendor's). Survives a restart;
+ * two runners never share one. Null when it cannot be written, which keeps
+ * the older behaviour (try to resume, fall back to replay).
+ */
+export declare function vendorInstanceId(stateDir: string): string | null;
+/**
+ * Which adapter drives which backend — the same table as 20x
+ * `agent-manager.ts` `getAdapter`.
+ *
+ * Pi on every runtime. Codex, Claude Code and Cursor on a desktop or
+ * self-hosted runner only: they use the vendor sign-in that is already on the
+ * machine, and a cloud sandbox has none and must not be given one.
+ *
+ * A NEW ADAPTER FOR EVERY TURN, for every backend, stopped when the turn
+ * ends (`stopAtTurnEnd`). This is where the runner differs from 20x, which
+ * keeps one adapter per harness for the life of the app.
+ *
+ * Advertising a backend the host cannot run makes the control plane route
+ * work to a runner that must then fail it, so `capabilities.backends` lists a
+ * vendor backend only while discovery says it is installed and signed in (see
+ * `Harness.vendorBackendsFor`). This function is the last line: it refuses
+ * anything that should not have been leased here.
+ */
+export declare function createAdapterResolver(runtime: string, 
+/** The runner's own state directory (its workspace root). */
+stateDir?: string): (backend: string, ports: AdapterPorts) => CodingAgentAdapter;

package/dist/adapter-resolver.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_TIMEOUT_MS = void 0;
+exports.stopAtTurnEnd = stopAtTurnEnd;
+exports.vendorInstanceId = vendorInstanceId;
+exports.createAdapterResolver = createAdapterResolver;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const adapters_1 = require("./adapters");
+const vendor_backends_1 = require("./vendor-backends");
+/**
+ * Hand the vendor CLI the workspace by its REAL path.
+ *
+ * Claude Code files a session under a directory named after the real path of
+ * its working directory, and the adapter looks for that file under the path it
+ * was given. With a workspace root that goes through a symlink (on macOS
+ * `/tmp` is one, to `/private/tmp`) the two differ, the session file is "not
+ * found", and every turn replays instead of resuming. Seen for real while
+ * proving this change. Changed in place: the same config object is passed to
+ * every later call of the turn.
+ */
+function setRealWorkspacePath(config) {
+    try {
+        config.workspaceDir = (0, node_fs_1.realpathSync)(config.workspaceDir);
+    }
+    catch {
+        // Not there yet, or unreadable: keep the path as given.
+    }
+}
+/**
+ * Give a vendor adapter the one thing the runner asks of a backend at the end
+ * of a turn: `stopServer()`.
+ *
+ * ONE PROCESS PER TURN, as for Pi. In 20x an adapter lives as long as the app
+ * and its CLI process stays up between messages. Here every turn is a new
+ * lease with its own MCP token, the runner may be handed the same chat by a
+ * control plane that last ran it elsewhere, and nothing may be left running
+ * when no turn is. So the process a turn started is stopped when the turn
+ * ends, and the next turn resumes the vendor's own saved session by its
+ * checkpoint (Codex thread id, Claude session id, Cursor ACP session id) —
+ * the path these adapters already have for "the app was restarted".
+ *
+ * Leaving the process up is not merely wasteful: `codex app-server` keeps the
+ * thread open for writing, and the next turn's `thread/resume` from a second
+ * process is refused with "already has an active writer".
+ *
+ * The session ids are recorded here, from what `createSession` returned and
+ * `resumeSession` was given, rather than read out of the adapter's private
+ * state. `destroySession` is the adapters' own teardown and does not delete
+ * the vendor's saved session.
+ */
+/** How long the end of a turn waits for one vendor session to stop. */
+exports.STOP_TIMEOUT_MS = 5_000;
+function stopAtTurnEnd(adapter, instanceId, options = {}) {
+    if (instanceId) {
+        /*
+         * WHOSE CHECKPOINT IS IT. A vendor session lives on the machine that made
+         * it (`~/.codex`, `~/.claude`, Cursor's own store). A chat that is leased
+         * to another runner next carries a checkpoint that means nothing there;
+         * with this id the runner sees that at once and replays the conversation,
+         * instead of asking the vendor CLI for a session it never had.
+         */
+        adapter.backendInstanceId =
+            () => instanceId;
+    }
+    const started = new Map();
+    const realIds = new Map();
+    const createSession = adapter.createSession.bind(adapter);
+    const resumeSession = adapter.resumeSession.bind(adapter);
+    adapter.createSession = async (config) => {
+        setRealWorkspacePath(config);
+        const id = await createSession(config);
+        started.set(id, config);
+        return id;
+    };
+    adapter.resumeSession = async (sessionId, config) => {
+        // Recorded BEFORE the call: a resume that fails half-way may already have
+        // started the process.
+        setRealWorkspacePath(config);
+        started.set(sessionId, config);
+        return resumeSession(sessionId, config);
+    };
+    /*
+     * A PART WITH NO ROLE IS THE ASSISTANT'S — the rule 20x applies where it
+     * reads these adapters' parts (`agent-manager.ts`: `part.role || 'assistant'`).
+     * The Claude Code adapter sends the model's own text with no role at all and
+     * relies on that. The runner's projection reads a missing role as `system`,
+     * which is right for Pi and would show Claude's whole answer as a system
+     * notice. So the 20x default is applied here, for these adapters only.
+     */
+    /*
+     * PART IDS THAT START AGAIN IN EVERY PROCESS ARE MADE UNIQUE PER TURN.
+     *
+     * The ACP adapter names the answer of a turn `agent-response-<n>`, counting
+     * from 1 in each process. In 20x one process serves the whole conversation,
+     * so the numbers keep growing. Here each turn has its own process, so every
+     * turn's answer was `agent-response-1` and the transcript — which stores a
+     * part by its id — replaced the previous turn's answer with the new one.
+     * Seen for real with Cursor: two turns, one answer left.
+     *
+     * The id is prefixed with the turn id on its way out. The adapter keeps
+     * working in its own ids: it is given its own "already seen" sets, because
+     * the runner's hold the prefixed ids and the adapter compares against the
+     * ids it produces. After a resume the adapter has already dropped the
+     * replayed history from its buffer, so only this turn's parts come through.
+     */
+    const ownSeen = {
+        messages: new Set(),
+        parts: new Set(),
+        lengths: new Map()
+    };
+    const pollMessages = adapter.pollMessages.bind(adapter);
+    adapter.pollMessages = async (...args) => {
+        const scoped = options.partIdsRestartEveryProcess === true;
+        const turnId = args[4]?.turnId;
+        const parts = scoped
+            ? await pollMessages(args[0], ownSeen.messages, ownSeen.parts, ownSeen.lengths, args[4])
+            : await pollMessages(...args);
+        for (const part of parts) {
+            if (scoped && turnId && part.id)
+                part.id = `${turnId}:${part.id}`;
+            if (!part.role)
+                part.role = adapters_1.MessageRole.ASSISTANT;
+            // The id the vendor gave the session, when it differs from the one
+            // `createSession` returned. See `checkpointSessionId` below.
+            if (part.realSessionId)
+                realIds.set(args[0], part.realSessionId);
+        }
+        return parts;
+    };
+    /*
+     * The session id to SAVE for the next turn. Claude Code's real id arrives on
+     * a part of the stream; 20x re-keys its session when it sees one. The runner
+     * asks here at the end of the turn and saves the real id as the checkpoint.
+     */
+    adapter.checkpointSessionId = (sessionId) => realIds.get(sessionId);
+    adapter.stopServer =
+        async () => {
+            for (const [sessionId, config] of started) {
+                try {
+                    // BOUNDED. This runs between a turn's last part and the release of
+                    // its lease; a vendor CLI that will not die must not hold that up.
+                    await Promise.race([
+                        adapter.destroySession(sessionId, config),
+                        new Promise((resolve) => {
+                            const timer = setTimeout(resolve, exports.STOP_TIMEOUT_MS);
+                            timer.unref();
+                        })
+                    ]);
+                }
+                catch {
+                    // Teardown is best-effort; the next id still gets its turn.
+                }
+            }
+            started.clear();
+        };
+    return adapter;
+}
+/**
+ * A random id for THIS runner's vendor sessions, written once into the
+ * runner's own state directory (never into a vendor's). Survives a restart;
+ * two runners never share one. Null when it cannot be written, which keeps
+ * the older behaviour (try to resume, fall back to replay).
+ */
+function vendorInstanceId(stateDir) {
+    const marker = (0, node_path_1.join)(stateDir, '.pf-vendor-instance-id');
+    try {
+        const existing = (0, node_fs_1.readFileSync)(marker, 'utf8').trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        // Not written yet.
+    }
+    try {
+        const id = (0, node_crypto_1.randomUUID)();
+        (0, node_fs_1.mkdirSync)(stateDir, { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)(marker, `${id}\n`, { mode: 0o600, flag: 'wx' });
+        return id;
+    }
+    catch {
+        try {
+            // Lost a race with another start: read what the winner wrote.
+            return (0, node_fs_1.readFileSync)(marker, 'utf8').trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Which adapter drives which backend — the same table as 20x
+ * `agent-manager.ts` `getAdapter`.
+ *
+ * Pi on every runtime. Codex, Claude Code and Cursor on a desktop or
+ * self-hosted runner only: they use the vendor sign-in that is already on the
+ * machine, and a cloud sandbox has none and must not be given one.
+ *
+ * A NEW ADAPTER FOR EVERY TURN, for every backend, stopped when the turn
+ * ends (`stopAtTurnEnd`). This is where the runner differs from 20x, which
+ * keeps one adapter per harness for the life of the app.
+ *
+ * Advertising a backend the host cannot run makes the control plane route
+ * work to a runner that must then fail it, so `capabilities.backends` lists a
+ * vendor backend only while discovery says it is installed and signed in (see
+ * `Harness.vendorBackendsFor`). This function is the last line: it refuses
+ * anything that should not have been leased here.
+ */
+function createAdapterResolver(runtime, 
+/** The runner's own state directory (its workspace root). */
+stateDir) {
+    const instanceId = stateDir ? vendorInstanceId(stateDir) : null;
+    const build = (backend) => {
+        switch (backend) {
+            case 'codex':
+                return new adapters_1.CodexAppServerAdapter();
+            case 'claude-code':
+                return new adapters_1.ClaudeCodeAdapter();
+            case 'cursor':
+                return new adapters_1.AcpAdapter('cursor');
+            default:
+                throw new Error(`No adapter for backend "${backend}".`);
+        }
+    };
+    return (backend, ports) => {
+        if (backend === 'pi') {
+            // The adapter reads the per-turn gateway holder directly. If the lease
+            // has no model token SessionRunner refuses before this is reached.
+            return new adapters_1.PiAdapter(ports.modelGateway);
+        }
+        if ((0, vendor_backends_1.isVendorBackend)(backend)) {
+            const blocker = (0, vendor_backends_1.vendorBackendBlocker)(backend, runtime);
+            if (blocker) {
+                throw new Error(`Backend "${backend}" cannot run here. ${blocker}`);
+            }
+            return stopAtTurnEnd(build(backend), instanceId ? `${backend}:${instanceId}` : null, { partIdsRestartEveryProcess: backend === 'cursor' });
+        }
+        throw new Error(`Backend "${backend}" is not wired in this build. ` +
+            'Available: pi, and on a desktop or self-hosted runner codex, ' +
+            'claude-code and cursor.');
+    };
+}

package/dist/adapters/claude-code-adapter.js

@@ -46,6 +46,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClaudeCodeAdapter = exports.ClaudeSystemSubtype = void 0;
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
 const permission_mode_1 = require("../runtime/permission-mode");
+const vendor_backends_1 = require("../vendor-backends");
 let ClaudeAgentSDK = null;
 /** Module-level cache for the resolved Claude executable path (persists across adapter instances) */
 let resolvedClaudeExecutablePath = null;
@@ -270,7 +271,10 @@ class ClaudeCodeAdapter {
     }
     async loadSDK() {
         try {
-            ClaudeAgentSDK = await Promise.resolve().then(() => __importStar(require('@anthropic-ai/claude-agent-sdk')));
+            // CHANGED from 20x: the SDK is not bundled with the runner (it would add
+            // ~190 MB to every install), so it is also looked for in the global
+            // node_modules. See `vendor-backends.ts`.
+            ClaudeAgentSDK = (await (0, vendor_backends_1.importClaudeSdk)());
             console.log('[ClaudeCodeAdapter] SDK loaded successfully');
         }
         catch (error) {

package/dist/cli.js

@@ -34,10 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-const adapters_1 = require("./adapters");
+const adapter_resolver_1 = require("./adapter-resolver");
 const contract_1 = require("./contract");
 const credential_store_1 = require("./credential-store");
 const harness_1 = require("./harness");
+const node_floor_1 = require("./node-floor");
 const options_1 = require("./options");
 const version_1 = require("./version");
 const USAGE = `pf-agent-harness — headless Peakflo coding-agent harness
@@ -81,30 +82,12 @@ Options:
                                 default for desktop/self-hosted; never runs
                                 in a sandbox.
 
+Needs Node.js 22.19 or newer; start stops with one line on an older one.
+PF_ALLOW_UNSUPPORTED_NODE=1 starts anyway, at your own risk.
+
 In a managed sandbox pf-bootstrap supplies these through the environment, so
 the enrolment token never appears in /proc/<pid>/cmdline.
 `;
-/**
- * Which adapter drives which backend.
- *
- * PI ONLY IN THIS BUILD, even though the legacy adapters remain exported for
- * extracted and are exported from the package. The others are wired by a HOST
- * that has verified their prerequisites: Claude Code needs
- * `@anthropic-ai/claude-agent-sdk` (an optional dependency, absent from the
- * sandbox image), and Codex and ACP need binaries the image does not ship.
- * Advertising a backend the host cannot actually run would make the control
- * plane route work to a runner that must then fail it.
- */
-function resolveAdapter(backend, ports) {
-    if (backend === 'pi') {
-        // The adapter reads the per-turn gateway holder directly. If the lease has
-        // no model token SessionRunner refuses before this constructor is reached.
-        return new adapters_1.PiAdapter(ports.modelGateway);
-    }
-    throw new Error(`Backend "${backend}" is not wired in this build. ` +
-        'Only "pi" is available; the other adapters are exported for a ' +
-        'host to wire once it has verified their prerequisites.');
-}
 /**
  * Read `--flag value` from argv. A tiny duplicate of the reader in options.ts,
  * because the login decision has to be made BEFORE `parseOptions` runs — that
@@ -144,6 +127,26 @@ async function main() {
         process.exitCode = 2;
         return;
     }
+    /*
+     * THE NODE.JS FLOOR — checked first, before the browser sign-in, so nobody
+     * signs in and picks an organisation only to be told to change Node. See
+     * `node-floor.ts` for where the floor comes from and why a sandbox only
+     * warns.
+     */
+    const nodeFloor = (0, node_floor_1.checkNodeFloor)({
+        current: process.versions.node,
+        floor: (0, version_1.getNodeFloor)(),
+        runtime: readOptionValue(argv.slice(1), 'runtime') ??
+            process.env.PF_RUNNER_RUNTIME,
+        env: process.env
+    });
+    if (nodeFloor.action === 'refuse') {
+        process.stderr.write(`${nodeFloor.message}\n`);
+        process.exit(1);
+    }
+    if (nodeFloor.action === 'warn') {
+        process.stderr.write(`Warning: ${nodeFloor.message}\n`);
+    }
     /*
      * NO TOKEN? OFFER TO SIGN IN, BUT ONLY WHERE THAT CAN POSSIBLY WORK.
      *
@@ -180,6 +183,7 @@ async function main() {
     }
     const options = (0, options_1.parseOptions)(startArgs, process.env);
     const handedOffCredential = (0, credential_store_1.takeHandedOffCredential)(process.env);
+    const resolveAdapter = (0, adapter_resolver_1.createAdapterResolver)(options.runtime, options.workspaceRoot);
     const harness = new harness_1.Harness(options, {
         getAdapter: (backend, ports) => resolveAdapter(backend, ports),
         ...(handedOffCredential

package/dist/harness-discovery.d.ts

@@ -29,21 +29,44 @@
  *    is local and is handed to each child process.
  */
 import type { RunnerHarness, RunnerHarnessModel } from './types';
-/** One command: `--version`, a status check, or a model listing. */
-export declare const DISCOVERY_COMMAND_TIMEOUT_MS = 8000;
-/** Everything for one harness. Harnesses run concurrently, so this is also the bound for the whole pass. */
-export declare const DISCOVERY_HARNESS_TIMEOUT_MS = 20000;
+/**
+ * One command: `--version`, a status check, or a model listing.
+ *
+ * MEASURED, NOT GUESSED. On the Mac where the first release candidate was
+ * tried, with two runners and other work going on, `cursor-agent --version`
+ * took 9.4 s cold and 3.7 s warm ALONE, and 6-10 s when five harnesses were
+ * probed at once; `opencode --version` took 3-5 s alone and 7-9 s beside the
+ * others. The first limit was 8 s, so both lost on a busy machine and were
+ * shown as broken. The limit is now well above the slowest start seen — and
+ * the pass no longer starts every CLI at once (`DISCOVERY_CONCURRENCY`),
+ * which is what made each of them slow.
+ */
+export declare const DISCOVERY_COMMAND_TIMEOUT_MS = 20000;
+/**
+ * The budget for finding out a harness's STATE: its version and whether it is
+ * signed in. The model listing is NOT inside this budget — it has one command
+ * timeout of its own and can never change the state (see `probeHarness`).
+ */
+export declare const DISCOVERY_HARNESS_TIMEOUT_MS = 45000;
+/**
+ * How many harnesses are probed at the same time. Each harness runs its
+ * commands one after another, so this is also the most CLI processes
+ * discovery ever has running. Two, not five: these CLIs are heavy to start
+ * (most are bundled Node programs), and five cold starts at once roughly
+ * doubled the start time of each on the test machine.
+ */
+export declare const DISCOVERY_CONCURRENCY = 2;
 /**
  * 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.
  */
 export declare const REASONS: {
     readonly notInstalled: "Not installed on this machine.";
-    readonly versionTimedOut: "The version check timed out.";
+    readonly versionTimedOut: "Installed. The version check timed out and will be tried again.";
     readonly versionFailed: "The version check failed.";
-    readonly discoveryTimedOut: "Discovery timed out.";
+    readonly discoveryTimedOut: "Installed. The check timed out and will be tried again.";
     readonly discoveryFailed: "Discovery failed.";
-    readonly signInTimedOut: "The sign-in check timed out.";
+    readonly signInTimedOut: "Installed. The sign-in check timed out and will be tried again.";
     readonly signInUnknown: "Sign-in could not be confirmed.";
     readonly codexSignIn: "Not signed in. Run `codex login` on this machine.";
     readonly claudeSignIn: "Not signed in. Run `claude auth login` on this machine.";
@@ -81,6 +104,13 @@ export interface DiscoverHarnessesOptions {
     runnableBackends?: readonly string[];
     commandTimeoutMs?: number;
     harnessTimeoutMs?: number;
+    /** Harnesses probed at once. Defaults to `DISCOVERY_CONCURRENCY`. */
+    concurrency?: number;
+    /**
+     * Probe ONLY these harnesses and return only their entries. Used to check
+     * again the ones whose last check timed out, without starting the others.
+     */
+    only?: readonly string[];
     deps?: Partial<DiscoveryDeps>;
 }
 /**
@@ -137,6 +167,7 @@ export declare const KNOWN_HARNESSES: ReadonlyArray<{
  * 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".
+ * does not report harnesses". With `only`, just those harnesses are probed and
+ * returned.
  */
 export declare function discoverHarnesses(options?: DiscoverHarnessesOptions): Promise<RunnerHarness[]>;