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

package/dist/harness.d.ts

@@ -2,8 +2,25 @@ import type { CodingAgentAdapter } from './adapters';
 import { SessionModelGateway } from './adapters/model-gateway';
 import { ControlPlaneClient } from './control-plane';
 import { CredentialStore } from './credential-store';
+import { type DiscoverHarnessesOptions } from './harness-discovery';
 import { ArtifactInspector, EventSink, Notifier, SecretProvider, Telemetry, ConversationStore, TranscriptStore, WorkspaceProvider } from './ports';
-import { HarnessOptions, HealthReport } from './types';
+import { HarnessOptions, HealthReport, RunnerHarness } from './types';
+/**
+ * How often the installed harnesses are looked for again.
+ *
+ * Five minutes: short enough that a harness installed or signed in to after
+ * start shows up without a restart or a re-enrol, and long enough that the
+ * heartbeat (30 s) does not start a handful of CLIs every time. Between passes
+ * every heartbeat sends the cached answer.
+ */
+export declare const HARNESS_DISCOVERY_REFRESH_MS: number;
+/** Listed in `capabilities.features` when `capabilities.harnesses` is sent. */
+export declare const HARNESS_DISCOVERY_FEATURE = "harnessDiscovery";
+/**
+ * A short tag for WHAT a harness list says, ignoring WHEN it was found.
+ * Two passes that found the same thing give the same tag.
+ */
+export declare function harnessContentKey(harnesses: readonly RunnerHarness[]): string;
 /**
  * The control plane refused this harness's PROTOCOL or VERSION. FINAL.
  *
@@ -90,6 +107,8 @@ export interface HarnessDeps {
     approvalRenewIntervalMs?: number;
     /** Injected in tests. */
     clientFactory?: (url: string) => ControlPlaneClient;
+    /** Injected in tests; defaults to the real `discoverHarnesses`. */
+    discoverHarnesses?: (options: DiscoverHarnessesOptions) => Promise<RunnerHarness[]>;
 }
 /**
  * THE HARNESS.
@@ -153,6 +172,23 @@ export declare class Harness {
     private modelCatalog;
     /** Epoch ms of the last successful (or attempted) model probe. */
     private modelProbeAt;
+    /**
+     * The harnesses found on this machine, from the last discovery pass.
+     *
+     * Cached for the same reason the model catalogue is: a pass starts several
+     * CLIs, and the heartbeat must not. NULL on a sandbox runner, which never
+     * runs discovery, and until the first pass has finished.
+     */
+    private harnessReport;
+    /** Epoch ms when the last discovery pass STARTED. Doubles as a cooldown. */
+    private harnessDiscoveryAt;
+    private harnessDiscoveryInFlight;
+    /**
+     * The `harnessesDigest` the control plane said it has stored, from its last
+     * heartbeat answer. Null until it says so, and for ever with an older
+     * control plane.
+     */
+    private ackedHarnessesDigest;
     /**
      * Empty gateway for the model probe. The probe builds a FRESH adapter and
      * must not read a live turn's credential; a null config is "no gateway",
@@ -272,6 +308,37 @@ export declare class Harness {
      * an empty-but-meaningful list) when the catalogue is empty.
      */
     private applyModelCatalog;
+    /**
+     * Look for the installed harnesses again and cache the answer.
+     *
+     * NEVER ON A SANDBOX. A cloud sandbox image ships exactly what the control
+     * plane put in it, so there is nothing to discover, and its capability
+     * report must stay what it was before this existed.
+     *
+     * Never rejects. One pass at a time: a second call while a pass is running
+     * returns the running one.
+     */
+    private refreshHarnessDiscovery;
+    /**
+     * Attach the cached harness report to a capability report.
+     *
+     * `runnable` is decided HERE, against the backends of THIS report, and not
+     * taken from the cache: the backend list is re-probed on every heartbeat
+     * and the harness list only every few minutes, so a cached `runnable` could
+     * contradict `backends`. Pi's models are copied from its backend entry for
+     * the same reason — one source, so the two lists cannot disagree.
+     */
+    private applyHarnessReport;
+    private harnessDiscoveryEnabled;
+    /**
+     * Whether to start a discovery pass on this heartbeat.
+     *
+     * NEVER WHILE A TURN IS RUNNING — the same rule as `modelsNeedRefresh`. A
+     * pass starts up to a dozen CLI processes; a turn in progress should not
+     * compete with them for the machine, and nothing is lost by waiting: the
+     * next idle heartbeat starts the pass.
+     */
+    private harnessesNeedRefresh;
     /**
      * Whether the model catalogue needs a (rare) re-probe.
      *

package/dist/harness.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Harness = exports.UpgradeRequestedError = exports.VersionRefusedError = void 0;
+exports.Harness = exports.UpgradeRequestedError = exports.VersionRefusedError = exports.HARNESS_DISCOVERY_FEATURE = exports.HARNESS_DISCOVERY_REFRESH_MS = void 0;
+exports.harnessContentKey = harnessContentKey;
+const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const model_gateway_1 = require("./adapters/model-gateway");
 const capabilities_1 = require("./capabilities");
@@ -9,6 +11,7 @@ const control_plane_1 = require("./control-plane");
 const credential_store_1 = require("./credential-store");
 const github_command_guards_1 = require("./github-command-guards");
 const github_workspace_1 = require("./github-workspace");
+const harness_discovery_1 = require("./harness-discovery");
 const health_1 = require("./health");
 const model_probe_1 = require("./model-probe");
 const ports_default_1 = require("./ports-default");
@@ -29,6 +32,28 @@ const LEASE_MIN_EMPTY_POLL_MS = 250;
  * process. Every six hours is a bounded refresh of a slowly changing catalog.
  */
 const MODEL_PROBE_REFRESH_MS = 6 * 60 * 60 * 1000;
+/**
+ * How often the installed harnesses are looked for again.
+ *
+ * Five minutes: short enough that a harness installed or signed in to after
+ * start shows up without a restart or a re-enrol, and long enough that the
+ * heartbeat (30 s) does not start a handful of CLIs every time. Between passes
+ * every heartbeat sends the cached answer.
+ */
+exports.HARNESS_DISCOVERY_REFRESH_MS = 5 * 60 * 1000;
+/** Listed in `capabilities.features` when `capabilities.harnesses` is sent. */
+exports.HARNESS_DISCOVERY_FEATURE = 'harnessDiscovery';
+/**
+ * A short tag for WHAT a harness list says, ignoring WHEN it was found.
+ * Two passes that found the same thing give the same tag.
+ */
+function harnessContentKey(harnesses) {
+    const content = harnesses.map(({ detectedAt: _detectedAt, ...rest }) => rest);
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(JSON.stringify(content))
+        .digest('hex')
+        .slice(0, 32);
+}
 /**
  * The control plane refused this harness's PROTOCOL or VERSION. FINAL.
  *
@@ -134,6 +159,23 @@ class Harness {
     modelCatalog = null;
     /** Epoch ms of the last successful (or attempted) model probe. */
     modelProbeAt = 0;
+    /**
+     * The harnesses found on this machine, from the last discovery pass.
+     *
+     * Cached for the same reason the model catalogue is: a pass starts several
+     * CLIs, and the heartbeat must not. NULL on a sandbox runner, which never
+     * runs discovery, and until the first pass has finished.
+     */
+    harnessReport = null;
+    /** Epoch ms when the last discovery pass STARTED. Doubles as a cooldown. */
+    harnessDiscoveryAt = 0;
+    harnessDiscoveryInFlight = null;
+    /**
+     * The `harnessesDigest` the control plane said it has stored, from its last
+     * heartbeat answer. Null until it says so, and for ever with an older
+     * control plane.
+     */
+    ackedHarnessesDigest = null;
     /**
      * Empty gateway for the model probe. The probe builds a FRESH adapter and
      * must not read a live turn's credential; a null config is "no gateway",
@@ -283,6 +325,13 @@ 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.
@@ -298,6 +347,8 @@ class Harness {
          */
         await this.refreshModelCatalog(true);
         this.applyModelCatalog(this.capabilities);
+        // Attaches the report only if the pass has already finished.
+        this.applyHarnessReport(this.capabilities);
         log('Harness starting', {
             harnessVersion: (0, version_1.getHarnessVersion)(),
             healthPort: this.options.healthPort,
@@ -517,6 +568,10 @@ class Harness {
             if (response.heartbeatIntervalMs) {
                 this.heartbeatIntervalMs = response.heartbeatIntervalMs;
             }
+            this.ackedHarnessesDigest =
+                typeof response.harnessesDigest === 'string'
+                    ? response.harnessesDigest
+                    : null;
             this.observeHarnessPin(response.harnessVersion);
             this.observeSandboxToolsPin(response.sandboxToolsVersion);
             this.applyCommandsSafely(response.sessionCommands ?? []);
@@ -723,6 +778,137 @@ class Harness {
             }
         }
     }
+    /**
+     * Look for the installed harnesses again and cache the answer.
+     *
+     * NEVER ON A SANDBOX. A cloud sandbox image ships exactly what the control
+     * plane put in it, so there is nothing to discover, and its capability
+     * report must stay what it was before this existed.
+     *
+     * Never rejects. One pass at a time: a second call while a pass is running
+     * returns the running one.
+     */
+    refreshHarnessDiscovery() {
+        if (!this.harnessDiscoveryEnabled()) {
+            return Promise.resolve();
+        }
+        if (this.harnessDiscoveryInFlight) {
+            return this.harnessDiscoveryInFlight;
+        }
+        this.harnessDiscoveryAt = Date.now();
+        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)
+                });
+                // 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.
+                if (!this.harnessReport ||
+                    harnessContentKey(report) !== harnessContentKey(this.harnessReport)) {
+                    this.harnessReport = report;
+                }
+                log('Harnesses discovered', {
+                    installed: report
+                        .filter((harness) => harness.installed)
+                        .map((harness) => harness.name),
+                    usable: report
+                        .filter((harness) => harness.usable)
+                        .map((harness) => harness.name)
+                });
+            }
+            catch {
+                // discoverHarnesses never rejects by construction. If a regression
+                // makes it reject, keep the last good answer instead of failing the
+                // start-up or the heartbeat.
+            }
+            finally {
+                this.harnessDiscoveryInFlight = null;
+            }
+        })();
+        this.harnessDiscoveryInFlight = pass;
+        return pass;
+    }
+    /**
+     * Attach the cached harness report to a capability report.
+     *
+     * `runnable` is decided HERE, against the backends of THIS report, and not
+     * taken from the cache: the backend list is re-probed on every heartbeat
+     * and the harness list only every few minutes, so a cached `runnable` could
+     * contradict `backends`. Pi's models are copied from its backend entry for
+     * the same reason — one source, so the two lists cannot disagree.
+     */
+    applyHarnessReport(capabilities) {
+        if (!this.harnessReport) {
+            return;
+        }
+        const harnesses = this.harnessReport.map((harness) => {
+            const backend = capabilities.backends.find((candidate) => candidate.name === harness.name);
+            if (!backend) {
+                return { ...harness, runnable: false };
+            }
+            /*
+             * A HARNESS THIS RUNNER RUNS IS NEVER SHOWN WORSE THAN `backends` SAYS.
+             *
+             * The backend probe runs on every heartbeat and is what work is routed
+             * on. The cached discovery pass is older and looks in other places, so
+             * on its own it could say "not installed" or "version check timed out"
+             * for a Pi that is running turns right now. Where the two disagree, the
+             * backend probe is right.
+             */
+            const entry = {
+                ...harness,
+                installed: true,
+                usable: true,
+                runnable: true,
+                version: backend.version ?? harness.version ?? null
+            };
+            delete entry.reason;
+            if (!entry.models && backend.models && backend.models.length > 0) {
+                entry.models = backend.models.map(({ id, name }) => ({ id, name }));
+                entry.modelSource = 'backend';
+            }
+            return entry;
+        });
+        const digest = harnessContentKey(harnesses);
+        capabilities.harnessesDigest = digest;
+        /*
+         * THE LIST IS SENT ONLY WHEN THE CONTROL PLANE DOES NOT HAVE IT.
+         *
+         * It is about 20 KB on a machine with every harness, and it changes
+         * rarely. A control plane that understands the digest answers each
+         * heartbeat with the digest it has stored; while that equals ours, the
+         * list is left out and only the digest goes. An older control plane never
+         * answers with a digest, so it is sent the list every time — which it
+         * needs, because it replaces `capabilities` as a whole.
+         */
+        if (this.ackedHarnessesDigest !== digest) {
+            capabilities.harnesses = harnesses;
+        }
+        capabilities.features = [
+            ...(capabilities.features ?? []).filter((feature) => feature !== exports.HARNESS_DISCOVERY_FEATURE),
+            exports.HARNESS_DISCOVERY_FEATURE
+        ];
+    }
+    harnessDiscoveryEnabled() {
+        return (this.options.runtime !== 'sandbox' &&
+            this.options.harnessDiscovery !== false);
+    }
+    /**
+     * Whether to start a discovery pass on this heartbeat.
+     *
+     * NEVER WHILE A TURN IS RUNNING — the same rule as `modelsNeedRefresh`. A
+     * pass starts up to a dozen CLI processes; a turn in progress should not
+     * compete with them for the machine, and nothing is lost by waiting: the
+     * next idle heartbeat starts the pass.
+     */
+    harnessesNeedRefresh() {
+        if (!this.harnessDiscoveryEnabled() || this.active.size > 0) {
+            return false;
+        }
+        return Date.now() - this.harnessDiscoveryAt >= exports.HARNESS_DISCOVERY_REFRESH_MS;
+    }
     /**
      * Whether the model catalogue needs a (rare) re-probe.
      *
@@ -765,7 +951,13 @@ class Harness {
                 labels: this.options.labels
             });
             this.applyModelCatalog(capabilities);
+            this.applyHarnessReport(capabilities);
             this.capabilities = capabilities;
+            // Not awaited: the answer is attached to a LATER heartbeat. Only the
+            // cached report is ever sent, so a slow CLI cannot delay a heartbeat.
+            if (this.harnessesNeedRefresh()) {
+                void this.refreshHarnessDiscovery();
+            }
             /*
              * THE MODEL CATALOGUE IS NOT RE-PROBED HERE, EVER. Only the CLI probes
              * run on a heartbeat; Pi discovery starts an RPC process, and doing that
@@ -791,6 +983,10 @@ class Harness {
             if (response.heartbeatIntervalMs) {
                 this.heartbeatIntervalMs = response.heartbeatIntervalMs;
             }
+            this.ackedHarnessesDigest =
+                typeof response.harnessesDigest === 'string'
+                    ? response.harnessesDigest
+                    : null;
             this.observeHarnessPin(response.harnessVersion);
             this.observeSandboxToolsPin(response.sandboxToolsVersion);
             this.applyCommandsSafely(response.sessionCommands ?? []);

package/dist/index.d.ts

@@ -24,6 +24,15 @@ export type { ProbeCapabilitiesOptions, ProbeResult } from './capabilities';
  */
 export { flattenProviderModels, probeBackendModels, probeModelCatalog } from './model-probe';
 export type { ModelCatalog, ModelProbeAdapterFactory, ProviderRecord } from './model-probe';
+/**
+ * Harness discovery — which coding harnesses (Codex, Claude Code, Cursor, Pi,
+ * OpenCode) are installed on this machine, whether each is signed in, and the
+ * models each offers. Reported as `capabilities.harnesses`, apart from
+ * `capabilities.backends`: finding a harness does not mean this runner can
+ * run a turn with it.
+ */
+export { discoverHarnesses, KNOWN_HARNESSES, DISCOVERY_COMMAND_TIMEOUT_MS, DISCOVERY_HARNESS_TIMEOUT_MS } from './harness-discovery';
+export type { DiscoverHarnessesOptions, DiscoveryDeps, DiscoveryExecResult } from './harness-discovery';
 export type { ArtifactInspector, EventSink, HarnessPorts, InspectedArtifact, Notifier, SecretProvider, StoredPart, StoredPartInput, TaskMcpProvider, TaskMcpScope, Telemetry, TokenInjector, TranscriptStore, WorkspaceProvider, WorkspaceRequest } from './ports';
 export { CompositeEventSink, DirectoryWorkspaceProvider, NoArtifactInspector, NoSecretProvider, NoopTelemetry, NullEventSink, ServerNotifier, SessionTokenInjector, StaticTaskMcpProvider } from './ports-default';
 export type { DirectoryWorkspaceOptions } from './ports-default';

package/dist/index.js

@@ -23,8 +23,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MIN_SUPPORTED_PROTOCOL_VERSION = exports.MAX_LEASE_WAIT_SECONDS = exports.MAX_INGEST_PART_BYTES = exports.MAX_INGEST_PARTS = exports.HARNESS_UPGRADE_EXIT_CODE = exports.FINAL_HTTP_STATUSES = exports.EPHEMERAL_PART_TYPES = exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_LEASE_WAIT_SECONDS = exports.DEFAULT_LEASE_TTL_MS = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.DEFAULT_BASE_DELAY_MS = exports.CONTRACT_ERROR_CODES = exports.openTranscriptStore = exports.SqliteTranscriptStore = exports.MemoryTranscriptStore = exports.writeToChildStdin = exports.isBenignStreamError = exports.guardStream = exports.guardChildStreams = exports.toIngestPart = exports.projectParts = exports.SessionRunner = exports.McpAuthProxy = exports.GitHubWorkspaceProvider = exports.StaticTaskMcpProvider = exports.SessionTokenInjector = exports.ServerNotifier = exports.NullEventSink = exports.NoopTelemetry = exports.NoSecretProvider = exports.NoArtifactInspector = exports.DirectoryWorkspaceProvider = exports.CompositeEventSink = exports.probeModelCatalog = exports.probeBackendModels = exports.flattenProviderModels = exports.probeCapabilities = exports.probe = exports.getPiVersion = exports.getHarnessVersion = exports.parseOptions = exports.OptionsError = exports.HealthServer = exports.ProtocolRefusedError = exports.ControlPlaneError = exports.ControlPlaneClient = exports.VersionRefusedError = exports.UpgradeRequestedError = exports.Harness = void 0;
-exports.isProtocolSupported = exports.isPersistablePart = exports.isFinalStatus = exports.isEphemeralPartType = exports.ingestPartByteLength = exports.ROUTES = exports.PROTOCOL_VERSION_HEADER = exports.PROTOCOL_VERSION = exports.PERSISTED_PART_TYPES = exports.MISSED_HEARTBEATS_BEFORE_OFFLINE = void 0;
+exports.HARNESS_UPGRADE_EXIT_CODE = exports.FINAL_HTTP_STATUSES = exports.EPHEMERAL_PART_TYPES = exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_LEASE_WAIT_SECONDS = exports.DEFAULT_LEASE_TTL_MS = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.DEFAULT_BASE_DELAY_MS = exports.CONTRACT_ERROR_CODES = exports.openTranscriptStore = exports.SqliteTranscriptStore = exports.MemoryTranscriptStore = exports.writeToChildStdin = exports.isBenignStreamError = exports.guardStream = exports.guardChildStreams = exports.toIngestPart = exports.projectParts = exports.SessionRunner = exports.McpAuthProxy = exports.GitHubWorkspaceProvider = exports.StaticTaskMcpProvider = exports.SessionTokenInjector = exports.ServerNotifier = exports.NullEventSink = exports.NoopTelemetry = exports.NoSecretProvider = exports.NoArtifactInspector = exports.DirectoryWorkspaceProvider = exports.CompositeEventSink = exports.DISCOVERY_HARNESS_TIMEOUT_MS = exports.DISCOVERY_COMMAND_TIMEOUT_MS = exports.KNOWN_HARNESSES = exports.discoverHarnesses = exports.probeModelCatalog = exports.probeBackendModels = exports.flattenProviderModels = exports.probeCapabilities = exports.probe = exports.getPiVersion = exports.getHarnessVersion = exports.parseOptions = exports.OptionsError = exports.HealthServer = exports.ProtocolRefusedError = exports.ControlPlaneError = exports.ControlPlaneClient = exports.VersionRefusedError = exports.UpgradeRequestedError = exports.Harness = void 0;
+exports.isProtocolSupported = exports.isPersistablePart = exports.isFinalStatus = exports.isEphemeralPartType = exports.ingestPartByteLength = exports.ROUTES = exports.PROTOCOL_VERSION_HEADER = exports.PROTOCOL_VERSION = exports.PERSISTED_PART_TYPES = exports.MISSED_HEARTBEATS_BEFORE_OFFLINE = exports.MIN_SUPPORTED_PROTOCOL_VERSION = exports.MAX_LEASE_WAIT_SECONDS = exports.MAX_INGEST_PART_BYTES = exports.MAX_INGEST_PARTS = void 0;
 /* ---- The process ---------------------------------------------------------- */
 var harness_1 = require("./harness");
 Object.defineProperty(exports, "Harness", { enumerable: true, get: function () { return harness_1.Harness; } });
@@ -55,6 +55,18 @@ var model_probe_1 = require("./model-probe");
 Object.defineProperty(exports, "flattenProviderModels", { enumerable: true, get: function () { return model_probe_1.flattenProviderModels; } });
 Object.defineProperty(exports, "probeBackendModels", { enumerable: true, get: function () { return model_probe_1.probeBackendModels; } });
 Object.defineProperty(exports, "probeModelCatalog", { enumerable: true, get: function () { return model_probe_1.probeModelCatalog; } });
+/**
+ * Harness discovery — which coding harnesses (Codex, Claude Code, Cursor, Pi,
+ * OpenCode) are installed on this machine, whether each is signed in, and the
+ * models each offers. Reported as `capabilities.harnesses`, apart from
+ * `capabilities.backends`: finding a harness does not mean this runner can
+ * run a turn with it.
+ */
+var harness_discovery_1 = require("./harness-discovery");
+Object.defineProperty(exports, "discoverHarnesses", { enumerable: true, get: function () { return harness_discovery_1.discoverHarnesses; } });
+Object.defineProperty(exports, "KNOWN_HARNESSES", { enumerable: true, get: function () { return harness_discovery_1.KNOWN_HARNESSES; } });
+Object.defineProperty(exports, "DISCOVERY_COMMAND_TIMEOUT_MS", { enumerable: true, get: function () { return harness_discovery_1.DISCOVERY_COMMAND_TIMEOUT_MS; } });
+Object.defineProperty(exports, "DISCOVERY_HARNESS_TIMEOUT_MS", { enumerable: true, get: function () { return harness_discovery_1.DISCOVERY_HARNESS_TIMEOUT_MS; } });
 var ports_default_1 = require("./ports-default");
 Object.defineProperty(exports, "CompositeEventSink", { enumerable: true, get: function () { return ports_default_1.CompositeEventSink; } });
 Object.defineProperty(exports, "DirectoryWorkspaceProvider", { enumerable: true, get: function () { return ports_default_1.DirectoryWorkspaceProvider; } });

package/dist/options.js

@@ -150,6 +150,17 @@ function parseBoolean(raw, fallback, name) {
         return false;
     throw new OptionsError(`Invalid ${name}: '${raw}'. Expected true or false.`);
 }
+/** An on/off variable: 1/true/on/yes or 0/false/off/no. A typo fails the start. */
+function parseSwitch(raw, fallback, name) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const value = raw.trim().toLowerCase();
+    if (['1', 'true', 'on', 'yes'].includes(value))
+        return true;
+    if (['0', 'false', 'off', 'no'].includes(value))
+        return false;
+    throw new OptionsError(`Invalid ${name}: '${raw}'. Expected 1 or 0.`);
+}
 /**
  * Flags win over environment variables, so a local developer can override a
  * value that pf-bootstrap injected.
@@ -207,6 +218,11 @@ function parseOptions(argv, env) {
             defaultWorkspaceRoot(),
         runtime,
         maxConcurrentSessions: parseConcurrency(readFlag(argv, 'max-sessions') ?? env.PF_MAX_CONCURRENT_SESSIONS, runtime),
-        labels: parseLabels(readFlag(argv, 'labels') ?? env.PF_RUNNER_LABELS)
+        labels: parseLabels(readFlag(argv, 'labels') ?? env.PF_RUNNER_LABELS),
+        // The flag wins over the environment, so one start can turn it off
+        // without editing a service file.
+        harnessDiscovery: readBoolFlag(argv, 'no-harness-discovery')
+            ? false
+            : parseSwitch(env.PF_HARNESS_DISCOVERY, true, 'harness discovery flag (PF_HARNESS_DISCOVERY)')
     };
 }

package/dist/types.d.ts

@@ -88,6 +88,13 @@ export interface HarnessOptions {
     maxConcurrentSessions: number;
     /** Free-form routing labels, e.g. ['eu-only', 'has-vpn']. */
     labels?: string[];
+    /**
+     * Look for the coding harnesses installed on this machine and report them.
+     * Defaults to true. `--no-harness-discovery` or `PF_HARNESS_DISCOVERY=0`
+     * turns it off: no harness CLI is started and no list is reported. A
+     * sandbox runner never runs discovery, whatever this says.
+     */
+    harnessDiscovery?: boolean;
 }
 /**
  * Every request body in this contract carries the protocol version, so the
@@ -223,6 +230,65 @@ export interface RunnerCapabilities {
      * serves `knowledge_files_list` / `knowledge_file_download`.
      */
     features?: string[];
+    /**
+     * Coding harnesses FOUND on this host, whether or not this runner can drive
+     * them. Reported by `harness-discovery.ts`.
+     *
+     * DETECTION IS NOT TURN SUPPORT. `backends` stays the only list the control
+     * plane routes on; an entry here with `runnable: false` is information for a
+     * person ("Codex is installed on this machine") and never a promise.
+     *
+     * OPTIONAL AND ADDITIVE, so no protocol bump: an older control plane stores
+     * the field and ignores it, and an older harness simply never sends it.
+     * Absent on a sandbox runner, which skips discovery altogether.
+     */
+    harnesses?: RunnerHarness[];
+    /**
+     * A short tag for the content of `harnesses`. Sent on EVERY capability
+     * report of a runner that runs discovery, also when the list itself is left
+     * out because the control plane already has it (see
+     * `RunnerHeartbeatResponse.harnessesDigest`).
+     */
+    harnessesDigest?: string;
+}
+/** Where a harness's model list came from. */
+export type RunnerHarnessModelSource = 
+/** Asked the harness CLI (`cursor-agent models`, `opencode models`). */
+'cli'
+/** Read from the harness's own model cache file. */
+ | 'config'
+/** A list compiled into this harness build, as 20x does. */
+ | 'static'
+/** The runnable backend's own probe (`backends[].models`). */
+ | 'backend';
+export interface RunnerHarnessModel {
+    id: string;
+    name: string;
+    /** The model the harness would use when none is named. */
+    default?: boolean;
+}
+/** One known coding harness, as found on this host. */
+export interface RunnerHarness {
+    /** 'codex' | 'claude-code' | 'cursor' | 'pi' | 'opencode' — the 20x names. */
+    name: string;
+    /** Display name, e.g. 'Claude Code'. */
+    label: string;
+    installed: boolean;
+    version?: string | null;
+    /** Installed, answering, and signed in. */
+    usable: boolean;
+    /**
+     * Why `usable` is false. ALWAYS one of a fixed set of sentences written in
+     * `harness-discovery.ts` — never text a CLI printed, so it cannot carry an
+     * account name or a token.
+     */
+    reason?: string;
+    /** This runner can run a turn with it: it is also listed in `backends`. */
+    runnable: boolean;
+    models?: RunnerHarnessModel[];
+    modelSource?: RunnerHarnessModelSource;
+    /** ISO time of the discovery pass that first found this state. */
+    detectedAt: string;
 }
 export interface RunnerBackend {
     /** 'opencode' | 'claude-code' | 'codex' | 'acp' | ... — an open vocabulary. */
@@ -319,6 +385,15 @@ export interface RunnerHeartbeatResponse {
      */
     action?: 'none' | 'drain' | 'restart';
     heartbeatIntervalMs?: number;
+    /**
+     * The `capabilities.harnessesDigest` the control plane has stored after
+     * this heartbeat. When it equals the runner's own, the runner leaves the
+     * (large) `harnesses` list out of the next heartbeat. ABSENT from an older
+     * control plane, and the runner then sends the list every time, which is
+     * the only thing that is correct there: an older control plane replaces
+     * `capabilities` as a whole on each heartbeat.
+     */
+    harnessesDigest?: string;
     /**
      * The outbound-only answer to "how does anything reach a running session?".
      * The control plane cannot dial in, so an abort or a user's answer to a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.8",
+  "version": "0.2.9-rc.1",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",