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

package/dist/harness-discovery.js

@@ -30,7 +30,7 @@
  *    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.KNOWN_HARNESSES = exports.CURSOR_STATIC_MODELS = exports.CODEX_STATIC_MODELS = exports.CLAUDE_STATIC_MODELS = exports.REASONS = exports.DISCOVERY_CONCURRENCY = exports.DISCOVERY_HARNESS_TIMEOUT_MS = exports.DISCOVERY_COMMAND_TIMEOUT_MS = void 0;
 exports.discoverySearchPath = discoverySearchPath;
 exports.discoveryChildEnv = discoveryChildEnv;
 exports.sanitizeHarnessModels = sanitizeHarnessModels;
@@ -45,10 +45,33 @@ 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;
+/**
+ * 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.
+ */
+exports.DISCOVERY_COMMAND_TIMEOUT_MS = 20_000;
+/**
+ * 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`).
+ */
+exports.DISCOVERY_HARNESS_TIMEOUT_MS = 45_000;
+/**
+ * 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.
+ */
+exports.DISCOVERY_CONCURRENCY = 2;
 const MAX_MODELS_PER_HARNESS = 200;
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 /**
@@ -57,11 +80,16 @@ const MAX_OUTPUT_BYTES = 1024 * 1024;
  */
 exports.REASONS = {
     notInstalled: 'Not installed on this machine.',
-    versionTimedOut: 'The version check timed out.',
+    /*
+     * The three "timed out" sentences describe a CHECK that did not finish, not
+     * the harness. Each goes out with `transient: true`, and the runner checks
+     * again shortly.
+     */
+    versionTimedOut: 'Installed. The version check timed out and will be tried again.',
     versionFailed: 'The version check failed.',
-    discoveryTimedOut: 'Discovery timed out.',
+    discoveryTimedOut: 'Installed. The check timed out and will be tried again.',
     discoveryFailed: 'Discovery failed.',
-    signInTimedOut: 'The sign-in check timed out.',
+    signInTimedOut: 'Installed. The sign-in check timed out and will be tried again.',
     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.',
@@ -325,6 +353,11 @@ function parseVersion(output) {
     const match = cleanLine(output).match(/(\d+\.\d+[\w.+-]*)/);
     return match ? match[1].slice(0, 64) : null;
 }
+const SIGN_IN_TIMED_OUT = {
+    usable: false,
+    reason: exports.REASONS.signInTimedOut,
+    transient: true
+};
 function hasEnv(env, names) {
     return names.some((name) => Boolean(env[name]));
 }
@@ -405,7 +438,7 @@ const CODEX = {
         // 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 };
+            return SIGN_IN_TIMED_OUT;
         // 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 &&
@@ -446,7 +479,7 @@ const CLAUDE = {
         }
         const status = await run(['auth', 'status']);
         if (status.timedOut)
-            return { usable: false, reason: exports.REASONS.signInTimedOut };
+            return SIGN_IN_TIMED_OUT;
         /*
          * The reply is JSON that also holds the account email and organisation.
          * ONE boolean is read from it and the rest is dropped here.
@@ -528,7 +561,7 @@ const CURSOR = {
             return { usable: true };
         const status = await run(['status']);
         if (status.timedOut)
-            return { usable: false, reason: exports.REASONS.signInTimedOut };
+            return SIGN_IN_TIMED_OUT;
         // 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.
@@ -601,10 +634,7 @@ exports.KNOWN_HARNESSES = [
     OPENCODE
 ].map(({ name, label }) => ({ name, label }));
 const SPECS = [CODEX, CLAUDE, CURSOR, PI, OPENCODE];
-/* -------------------------------------------------------------------------- */
-/* The pass                                                                    */
-/* -------------------------------------------------------------------------- */
-async function probeHarness(spec, entry, deps, commandTimeoutMs, isExpired) {
+async function probeHarness(spec, entry, deps, commandTimeoutMs, isExpired, progress) {
     let path = null;
     for (const command of spec.commands) {
         const found = deps.resolveCommand(command);
@@ -623,9 +653,9 @@ async function probeHarness(spec, entry, deps, commandTimeoutMs, isExpired) {
         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.
+         * NOTHING IS STARTED AFTER THE STATE DEADLINE. The report has already
+         * been sent without this harness by then, so a sign-in check started now
+         * would be a process nobody is waiting for.
          */
         run: (args) => isExpired()
             ? Promise.resolve({
@@ -638,7 +668,10 @@ async function probeHarness(spec, entry, deps, commandTimeoutMs, isExpired) {
     };
     const version = await context.run(['--version']);
     if (version.timedOut) {
+        // The binary EXISTS and did not answer in time. That is a slow machine,
+        // not a broken harness, so it is reported as "will be tried again".
         entry.reason = exports.REASONS.versionTimedOut;
+        entry.transient = true;
         return;
     }
     if (version.code !== 0) {
@@ -652,22 +685,57 @@ async function probeHarness(spec, entry, deps, commandTimeoutMs, isExpired) {
     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;
+    if (!auth.usable && auth.transient)
+        entry.transient = true;
+    /*
+     * THE STATE IS SETTLED HERE, and the state deadline stops counting.
+     *
+     * The model listing below is extra information. It gets one command timeout
+     * of its own and its result can only ADD models: a listing that is slow or
+     * fails leaves `usable` exactly as the sign-in check found it. Before this,
+     * the listing shared one 20 s budget with the two checks above, and a slow
+     * `cursor-agent models` or `opencode models` turned a signed-in harness
+     * into "timed out".
+     */
+    progress.stateKnown = true;
+    progress.onStateKnown?.();
+    try {
+        const listed = await spec.listModels(context, auth.usable);
+        if (listed && listed.models.length > 0) {
+            entry.models = listed.models;
+            entry.modelSource = listed.source;
+        }
+    }
+    catch {
+        // No models. The state above stands.
     }
 }
+/** Run `task` for every item, at most `limit` at a time, keeping the order. */
+async function mapWithLimit(items, limit, task) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await task(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+    return results;
+}
 /**
  * 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.
  */
 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 ?? []);
+    const only = options.only ? new Set(options.only) : null;
+    const specs = only ? SPECS.filter((spec) => only.has(spec.name)) : SPECS;
     let deps = null;
     let detectedAt = new Date().toISOString();
     try {
@@ -678,10 +746,11 @@ async function discoverHarnesses(options = {}) {
         // `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) => {
+    const resolvedDeps = deps;
+    return mapWithLimit(specs, options.concurrency ?? exports.DISCOVERY_CONCURRENCY, 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).
+         * part-way still reports what was already learnt.
          */
         const entry = {
             name: spec.name,
@@ -692,36 +761,52 @@ async function discoverHarnesses(options = {}) {
             runnable: false,
             detectedAt
         };
-        if (!deps) {
+        if (!resolvedDeps) {
             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 progress = { stateKnown: false };
         const deadline = new Promise((resolve) => {
             timer = setTimeout(() => {
                 expired = true;
                 resolve('expired');
             }, harnessTimeoutMs);
             timer.unref();
+            // The deadline is for the STATE only. Once that is known the model
+            // listing runs on its own command timeout.
+            progress.onStateKnown = () => {
+                if (timer)
+                    clearTimeout(timer);
+                timer = null;
+            };
         });
+        const work = probeHarness(spec, entry, resolvedDeps, commandTimeoutMs, () => expired, progress).then(() => 'done', () => 'failed');
         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') {
+        if (outcome === 'expired') {
+            // Found, and the checks did not finish in time: "will be tried again".
+            report.usable = false;
+            report.reason = exports.REASONS.discoveryTimedOut;
+            if (report.installed)
+                report.transient = true;
+            delete report.models;
+            delete report.modelSource;
+        }
+        else if (outcome === 'failed' && !progress.stateKnown) {
             report.usable = false;
-            report.reason = expired
-                ? exports.REASONS.discoveryTimedOut
-                : exports.REASONS.discoveryFailed;
+            report.reason = exports.REASONS.discoveryFailed;
+            delete report.transient;
             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;
-    }));
+    });
 }

package/dist/harness.d.ts

@@ -14,6 +14,22 @@ import { HarnessOptions, HealthReport, RunnerHarness } from './types';
  * every heartbeat sends the cached answer.
  */
 export declare const HARNESS_DISCOVERY_REFRESH_MS: number;
+/**
+ * How long after a pass the checks that TIMED OUT are tried again: three
+ * times, each wait twice the one before. See `scheduleHarnessRetry`.
+ */
+export declare const HARNESS_RETRY_DELAYS_MS: readonly number[];
+/**
+ * Put the result of a pass together with what was known before.
+ *
+ * KEEP THE LAST GOOD STATE. A check that timed out learnt nothing, so when
+ * the previous pass DID settle that harness (signed in, signed out, version
+ * failed) that answer stays. Only a harness with no settled answer yet is
+ * shown as "check timed out, will be tried again".
+ *
+ * A retry pass returns only the harnesses it probed; the others are kept.
+ */
+export declare function mergeHarnessReports(previous: readonly RunnerHarness[] | null, fresh: readonly RunnerHarness[]): RunnerHarness[];
 /** Listed in `capabilities.features` when `capabilities.harnesses` is sent. */
 export declare const HARNESS_DISCOVERY_FEATURE = "harnessDiscovery";
 /**
@@ -107,6 +123,11 @@ export interface HarnessDeps {
     approvalRenewIntervalMs?: number;
     /** Injected in tests. */
     clientFactory?: (url: string) => ControlPlaneClient;
+    /**
+     * Why a vendor backend cannot be run here, or null. Injected in tests;
+     * defaults to `vendorBackendBlocker` (sandbox, or the Claude SDK missing).
+     */
+    vendorBackendBlocker?: (backend: string, runtime: string) => string | null;
     /** Injected in tests; defaults to the real `discoverHarnesses`. */
     discoverHarnesses?: (options: DiscoverHarnessesOptions) => Promise<RunnerHarness[]>;
 }
@@ -182,6 +203,10 @@ export declare class Harness {
     private harnessReport;
     /** Epoch ms when the last discovery pass STARTED. Doubles as a cooldown. */
     private harnessDiscoveryAt;
+    /** Epoch ms of the next retry of timed-out checks, or null when none is due. */
+    private harnessRetryAt;
+    /** Retries scheduled in a row. Back to 0 once nothing is waiting. */
+    private harnessRetryAttempts;
     private harnessDiscoveryInFlight;
     /**
      * The `harnessesDigest` the control plane said it has stored, from its last
@@ -319,6 +344,16 @@ export declare class Harness {
      * returns the running one.
      */
     private refreshHarnessDiscovery;
+    /**
+     * After a pass: check again SOON when a check timed out, instead of leaving
+     * "timed out" on screen for a whole interval.
+     *
+     * Short and bounded: 30 s, then 60 s, then 120 s, and after that the normal
+     * five-minute pass takes over. A machine that is slow for good must not be
+     * probed for ever at a short interval. The counter starts again once
+     * nothing is waiting.
+     */
+    private scheduleHarnessRetry;
     /**
      * Attach the cached harness report to a capability report.
      *
@@ -329,6 +364,25 @@ export declare class Harness {
      * the same reason — one source, so the two lists cannot disagree.
      */
     private applyHarnessReport;
+    /**
+     * Add Codex, Claude Code and Cursor to `backends` — the list work is routed
+     * on — for exactly as long as each is INSTALLED AND SIGNED IN.
+     *
+     * This is the gate that turns "detected" into "runnable", so it is strict:
+     *
+     *   - only from a discovery report, which a sandbox never has;
+     *   - only a harness whose check SETTLED as usable. A check that timed out
+     *     with no earlier answer is not enough to take work on;
+     *   - only when this runner was given adapters at all, and has what the
+     *     adapter needs (Claude Code needs the Claude Agent SDK).
+     *
+     * Recomputed for every capability report from the cached discovery pass, so
+     * a harness that is signed out, or uninstalled, leaves `backends` with the
+     * report that follows the pass which noticed. Nothing is remembered here.
+     *
+     * Returns why each harness that is usable was still NOT added, for the UI.
+     */
+    private addVendorBackends;
     private harnessDiscoveryEnabled;
     /**
      * Whether to start a discovery pass on this heartbeat.

package/dist/harness.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Harness = exports.UpgradeRequestedError = exports.VersionRefusedError = exports.HARNESS_DISCOVERY_FEATURE = exports.HARNESS_DISCOVERY_REFRESH_MS = void 0;
+exports.Harness = exports.UpgradeRequestedError = exports.VersionRefusedError = exports.HARNESS_DISCOVERY_FEATURE = exports.HARNESS_RETRY_DELAYS_MS = exports.HARNESS_DISCOVERY_REFRESH_MS = void 0;
+exports.mergeHarnessReports = mergeHarnessReports;
 exports.harnessContentKey = harnessContentKey;
 const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
@@ -21,6 +22,7 @@ const mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
 const session_runner_1 = require("./runtime/session-runner");
 const conversation_store_1 = require("./store/conversation-store");
 const sqlite_store_1 = require("./store/sqlite-store");
+const vendor_backends_1 = require("./vendor-backends");
 const version_1 = require("./version");
 /** Backoff after a lease poll fails, so an unreachable control plane is not hammered. */
 const LEASE_ERROR_BACKOFF_MS = 5_000;
@@ -41,6 +43,45 @@ const MODEL_PROBE_REFRESH_MS = 6 * 60 * 60 * 1000;
  * every heartbeat sends the cached answer.
  */
 exports.HARNESS_DISCOVERY_REFRESH_MS = 5 * 60 * 1000;
+/**
+ * How long after a pass the checks that TIMED OUT are tried again: three
+ * times, each wait twice the one before. See `scheduleHarnessRetry`.
+ */
+exports.HARNESS_RETRY_DELAYS_MS = [
+    30_000, 60_000, 120_000
+];
+/**
+ * Put the result of a pass together with what was known before.
+ *
+ * KEEP THE LAST GOOD STATE. A check that timed out learnt nothing, so when
+ * the previous pass DID settle that harness (signed in, signed out, version
+ * failed) that answer stays. Only a harness with no settled answer yet is
+ * shown as "check timed out, will be tried again".
+ *
+ * A retry pass returns only the harnesses it probed; the others are kept.
+ */
+function mergeHarnessReports(previous, fresh) {
+    if (!previous)
+        return [...fresh];
+    const before = new Map(previous.map((harness) => [harness.name, harness]));
+    const after = new Map(fresh.map((harness) => [harness.name, harness]));
+    const pick = (name) => {
+        const now = after.get(name);
+        const then = before.get(name);
+        if (!now)
+            return then;
+        return now.transient && then && then.installed && !then.transient
+            ? then
+            : now;
+    };
+    const names = [
+        ...previous.map((harness) => harness.name),
+        ...fresh.map((harness) => harness.name).filter((name) => !before.has(name))
+    ];
+    return names
+        .map(pick)
+        .filter((harness) => harness !== undefined);
+}
 /** Listed in `capabilities.features` when `capabilities.harnesses` is sent. */
 exports.HARNESS_DISCOVERY_FEATURE = 'harnessDiscovery';
 /**
@@ -169,6 +210,10 @@ class Harness {
     harnessReport = null;
     /** Epoch ms when the last discovery pass STARTED. Doubles as a cooldown. */
     harnessDiscoveryAt = 0;
+    /** Epoch ms of the next retry of timed-out checks, or null when none is due. */
+    harnessRetryAt = null;
+    /** Retries scheduled in a row. Back to 0 once nothing is waiting. */
+    harnessRetryAttempts = 0;
     harnessDiscoveryInFlight = null;
     /**
      * The `harnessesDigest` the control plane said it has stored, from its last
@@ -325,13 +370,6 @@ class Harness {
             maxConcurrentSessions: this.options.maxConcurrentSessions,
             labels: this.options.labels
         });
-        /*
-         * STARTED, NEVER AWAITED. Registration must not wait for a third-party
-         * CLI: a pass can take as long as its slowest harness (20 s), and a runner
-         * that is slow to register looks like a runner that did not come back. The
-         * report is attached to the first heartbeat after the pass has finished.
-         */
-        void this.refreshHarnessDiscovery();
         // Install immediately before model probing can start a backend. The lease
         // is process-wide and reference-counted, so concurrent Harness instances
         // share one generic launcher instead of racing to rewrite global PATH.
@@ -347,6 +385,19 @@ class Harness {
          */
         await this.refreshModelCatalog(true);
         this.applyModelCatalog(this.capabilities);
+        /*
+         * STARTED, NEVER AWAITED. Registration must not wait for a third-party
+         * CLI, and a runner that is slow to register looks like a runner that did
+         * not come back. The report is attached to the first heartbeat after the
+         * pass has finished.
+         *
+         * STARTED HERE, AFTER THE MODEL PROBE, and not beside it. The first
+         * release candidate started both at once: the Pi discovery process and
+         * five harness CLIs all cold-starting together, on a machine that was
+         * also starting this very process through npx. Two harnesses lost their
+         * version check to that and were shown as broken for five minutes.
+         */
+        void this.refreshHarnessDiscovery();
         // Attaches the report only if the pass has already finished.
         this.applyHarnessReport(this.capabilities);
         log('Harness starting', {
@@ -713,7 +764,10 @@ class Harness {
      * `force` re-probes regardless of age (used at start-up). Never rejects.
      */
     async refreshModelCatalog(force = false) {
-        const backends = this.capabilities?.backends ?? [];
+        // A vendor harness's models come from discovery, not from this probe:
+        // asking its adapter would start `codex app-server` or `cursor-agent acp`
+        // just to list models that are already known.
+        const backends = (this.capabilities?.backends ?? []).filter((backend) => !(0, vendor_backends_1.isVendorBackend)(backend.name));
         const build = this.deps.getAdapter;
         if (!build || backends.length === 0) {
             this.modelCatalog = null;
@@ -795,13 +849,31 @@ class Harness {
         if (this.harnessDiscoveryInFlight) {
             return this.harnessDiscoveryInFlight;
         }
-        this.harnessDiscoveryAt = Date.now();
+        const now = Date.now();
+        /*
+         * A RETRY PASS probes only the harnesses whose last check timed out. A
+         * full pass, when one is due anyway, covers them too.
+         */
+        const fullPassDue = !this.harnessReport ||
+            now - this.harnessDiscoveryAt >= exports.HARNESS_DISCOVERY_REFRESH_MS;
+        const retryNames = (this.harnessReport ?? [])
+            .filter((harness) => harness.transient)
+            .map((harness) => harness.name);
+        const only = !fullPassDue && this.harnessRetryAt !== null && retryNames.length > 0
+            ? retryNames
+            : undefined;
+        if (!only) {
+            this.harnessDiscoveryAt = now;
+        }
+        this.harnessRetryAt = null;
         const discover = this.deps.discoverHarnesses ?? harness_discovery_1.discoverHarnesses;
         const pass = (async () => {
             try {
-                const report = await discover({
-                    runnableBackends: (this.capabilities?.backends ?? []).map((backend) => backend.name)
+                const fresh = await discover({
+                    runnableBackends: (this.capabilities?.backends ?? []).map((backend) => backend.name),
+                    ...(only ? { only } : {})
                 });
+                const report = mergeHarnessReports(this.harnessReport, fresh);
                 // Same content as before: keep the OLD report, with its
                 // `detectedAt`. A pass that found nothing new must not look like a
                 // change, or the whole list would be sent again every five minutes.
@@ -809,13 +881,20 @@ class Harness {
                     harnessContentKey(report) !== harnessContentKey(this.harnessReport)) {
                     this.harnessReport = report;
                 }
+                this.scheduleHarnessRetry(report);
                 log('Harnesses discovered', {
                     installed: report
                         .filter((harness) => harness.installed)
                         .map((harness) => harness.name),
                     usable: report
                         .filter((harness) => harness.usable)
-                        .map((harness) => harness.name)
+                        .map((harness) => harness.name),
+                    // Named so a slow machine can be told from a broken harness in
+                    // the log: these are checked again, the others are settled.
+                    retrying: report
+                        .filter((harness) => harness.transient)
+                        .map((harness) => harness.name),
+                    ...(only ? { pass: 'retry' } : {})
                 });
             }
             catch {
@@ -830,6 +909,29 @@ class Harness {
         this.harnessDiscoveryInFlight = pass;
         return pass;
     }
+    /**
+     * After a pass: check again SOON when a check timed out, instead of leaving
+     * "timed out" on screen for a whole interval.
+     *
+     * Short and bounded: 30 s, then 60 s, then 120 s, and after that the normal
+     * five-minute pass takes over. A machine that is slow for good must not be
+     * probed for ever at a short interval. The counter starts again once
+     * nothing is waiting.
+     */
+    scheduleHarnessRetry(report) {
+        if (!report.some((harness) => harness.transient)) {
+            this.harnessRetryAttempts = 0;
+            this.harnessRetryAt = null;
+            return;
+        }
+        const delay = exports.HARNESS_RETRY_DELAYS_MS[this.harnessRetryAttempts];
+        if (delay === undefined) {
+            this.harnessRetryAt = null;
+            return;
+        }
+        this.harnessRetryAttempts += 1;
+        this.harnessRetryAt = Date.now() + delay;
+    }
     /**
      * Attach the cached harness report to a capability report.
      *
@@ -843,10 +945,16 @@ class Harness {
         if (!this.harnessReport) {
             return;
         }
+        const blocked = this.addVendorBackends(capabilities);
         const harnesses = this.harnessReport.map((harness) => {
             const backend = capabilities.backends.find((candidate) => candidate.name === harness.name);
             if (!backend) {
-                return { ...harness, runnable: false };
+                const reason = blocked.get(harness.name);
+                return {
+                    ...harness,
+                    runnable: false,
+                    ...(reason ? { notRunnableReason: reason } : {})
+                };
             }
             /*
              * A HARNESS THIS RUNNER RUNS IS NEVER SHOWN WORSE THAN `backends` SAYS.
@@ -865,6 +973,7 @@ class Harness {
                 version: backend.version ?? harness.version ?? null
             };
             delete entry.reason;
+            delete entry.transient;
             if (!entry.models && backend.models && backend.models.length > 0) {
                 entry.models = backend.models.map(({ id, name }) => ({ id, name }));
                 entry.modelSource = 'backend';
@@ -891,6 +1000,51 @@ class Harness {
             exports.HARNESS_DISCOVERY_FEATURE
         ];
     }
+    /**
+     * Add Codex, Claude Code and Cursor to `backends` — the list work is routed
+     * on — for exactly as long as each is INSTALLED AND SIGNED IN.
+     *
+     * This is the gate that turns "detected" into "runnable", so it is strict:
+     *
+     *   - only from a discovery report, which a sandbox never has;
+     *   - only a harness whose check SETTLED as usable. A check that timed out
+     *     with no earlier answer is not enough to take work on;
+     *   - only when this runner was given adapters at all, and has what the
+     *     adapter needs (Claude Code needs the Claude Agent SDK).
+     *
+     * Recomputed for every capability report from the cached discovery pass, so
+     * a harness that is signed out, or uninstalled, leaves `backends` with the
+     * report that follows the pass which noticed. Nothing is remembered here.
+     *
+     * Returns why each harness that is usable was still NOT added, for the UI.
+     */
+    addVendorBackends(capabilities) {
+        const blocked = new Map();
+        if (!this.harnessReport || !this.deps.getAdapter)
+            return blocked;
+        const blocker = this.deps.vendorBackendBlocker ?? vendor_backends_1.vendorBackendBlocker;
+        for (const harness of this.harnessReport) {
+            if (!(0, vendor_backends_1.isVendorBackend)(harness.name))
+                continue;
+            if (!harness.installed || !harness.usable)
+                continue;
+            if (capabilities.backends.some((b) => b.name === harness.name))
+                continue;
+            const reason = blocker(harness.name, this.options.runtime);
+            if (reason) {
+                blocked.set(harness.name, reason);
+                continue;
+            }
+            capabilities.backends.push({
+                name: harness.name,
+                version: harness.version ?? null,
+                ...(harness.models && harness.models.length > 0
+                    ? { models: harness.models.map(({ id, name }) => ({ id, name })) }
+                    : {})
+            });
+        }
+        return blocked;
+    }
     harnessDiscoveryEnabled() {
         return (this.options.runtime !== 'sandbox' &&
             this.options.harnessDiscovery !== false);
@@ -907,7 +1061,11 @@ class Harness {
         if (!this.harnessDiscoveryEnabled() || this.active.size > 0) {
             return false;
         }
-        return Date.now() - this.harnessDiscoveryAt >= exports.HARNESS_DISCOVERY_REFRESH_MS;
+        const now = Date.now();
+        if (this.harnessRetryAt !== null && now >= this.harnessRetryAt) {
+            return true;
+        }
+        return now - this.harnessDiscoveryAt >= exports.HARNESS_DISCOVERY_REFRESH_MS;
     }
     /**
      * Whether the model catalogue needs a (rare) re-probe.