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

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
@@ -50,7 +52,15 @@ this runner".
 
 **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 +81,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/cli.js

@@ -38,6 +38,7 @@ const adapters_1 = require("./adapters");
 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,6 +82,9 @@ 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.
 `;
@@ -144,6 +148,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.
      *

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[]>;

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";
 /**
@@ -182,6 +198,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 +339,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.
      *

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");
@@ -41,6 +42,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 +209,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 +369,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 +384,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', {
@@ -795,13 +845,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 +877,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 +905,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.
      *
@@ -865,6 +963,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';
@@ -907,7 +1006,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.

package/dist/node-floor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * THE NODE.JS FLOOR, CHECKED AT START.
+ *
+ * `package.json` says `engines.node: ">=22.19"`. npm treats that as advice: on
+ * an older Node it prints EBADENGINE and installs anyway, and `npx` then starts
+ * the runner as if nothing was wrong. So the floor was a line in a manifest
+ * that nothing enforced.
+ *
+ * WHERE THE FLOOR COMES FROM. Not from this package's own code — that needs
+ * `node:sqlite` without a flag (Node 22.13). It comes from Pi, the one backend
+ * this runner runs turns with: `@earendil-works/pi-coding-agent` declares
+ * `engines.node >=22.19.0`, and Pi's launcher is `#!/usr/bin/env node`, so Pi
+ * normally runs on the same Node as the runner. Pi 1.1.0 was seen to start on
+ * 22.14 (`--version`, `--list-models`), and nobody has shown that a full turn
+ * works there. An upstream requirement that is not proven false is kept.
+ *
+ * WHAT HAPPENS BELOW THE FLOOR. A desktop or self-hosted runner refuses to
+ * start, with one line that says what to do. `PF_ALLOW_UNSUPPORTED_NODE=1`
+ * starts it anyway, with a one-line warning, for someone who knows their
+ * setup works. A SANDBOX only warns: its Node is whatever the image was built
+ * with, nobody is at a terminal to read the line, and a refusal there would
+ * take a cloud runner out of service for a requirement of a tool the image
+ * already carries.
+ *
+ * PURE: no process state is read here, so every branch can be tested.
+ */
+/** Parse `22.19`, `v22.19.0`, `>=22.19` into numbers. Null when it is none of those. */
+export declare function parseNodeVersion(text: string): number[] | null;
+export declare function isNodeVersionAtLeast(current: string, floor: string): boolean;
+export type NodeFloorVerdict = {
+    action: 'start';
+} | {
+    action: 'warn';
+    message: string;
+} | {
+    action: 'refuse';
+    message: string;
+};
+export declare function checkNodeFloor(input: {
+    /** `process.versions.node`, e.g. `22.14.0`. */
+    current: string;
+    /** `engines.node` of this package, e.g. `>=22.19`. Null when unreadable. */
+    floor: string | null;
+    runtime: string | undefined;
+    env: NodeJS.ProcessEnv;
+}): NodeFloorVerdict;

package/dist/node-floor.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * THE NODE.JS FLOOR, CHECKED AT START.
+ *
+ * `package.json` says `engines.node: ">=22.19"`. npm treats that as advice: on
+ * an older Node it prints EBADENGINE and installs anyway, and `npx` then starts
+ * the runner as if nothing was wrong. So the floor was a line in a manifest
+ * that nothing enforced.
+ *
+ * WHERE THE FLOOR COMES FROM. Not from this package's own code — that needs
+ * `node:sqlite` without a flag (Node 22.13). It comes from Pi, the one backend
+ * this runner runs turns with: `@earendil-works/pi-coding-agent` declares
+ * `engines.node >=22.19.0`, and Pi's launcher is `#!/usr/bin/env node`, so Pi
+ * normally runs on the same Node as the runner. Pi 1.1.0 was seen to start on
+ * 22.14 (`--version`, `--list-models`), and nobody has shown that a full turn
+ * works there. An upstream requirement that is not proven false is kept.
+ *
+ * WHAT HAPPENS BELOW THE FLOOR. A desktop or self-hosted runner refuses to
+ * start, with one line that says what to do. `PF_ALLOW_UNSUPPORTED_NODE=1`
+ * starts it anyway, with a one-line warning, for someone who knows their
+ * setup works. A SANDBOX only warns: its Node is whatever the image was built
+ * with, nobody is at a terminal to read the line, and a refusal there would
+ * take a cloud runner out of service for a requirement of a tool the image
+ * already carries.
+ *
+ * PURE: no process state is read here, so every branch can be tested.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNodeVersion = parseNodeVersion;
+exports.isNodeVersionAtLeast = isNodeVersionAtLeast;
+exports.checkNodeFloor = checkNodeFloor;
+/** Parse `22.19`, `v22.19.0`, `>=22.19` into numbers. Null when it is none of those. */
+function parseNodeVersion(text) {
+    const match = text.trim().match(/^(?:>=\s*)?v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!match)
+        return null;
+    return [match[1], match[2] ?? '0', match[3] ?? '0'].map(Number);
+}
+function isNodeVersionAtLeast(current, floor) {
+    const have = parseNodeVersion(current);
+    const need = parseNodeVersion(floor);
+    // A floor or a version that cannot be read is not a reason to refuse.
+    if (!have || !need)
+        return true;
+    for (let index = 0; index < 3; index++) {
+        if (have[index] > need[index])
+            return true;
+        if (have[index] < need[index])
+            return false;
+    }
+    return true;
+}
+function checkNodeFloor(input) {
+    if (!input.floor || isNodeVersionAtLeast(input.current, input.floor)) {
+        return { action: 'start' };
+    }
+    const need = (parseNodeVersion(input.floor) ?? []).slice(0, 2).join('.');
+    const problem = `pf-agent-harness needs Node.js ${need} or newer; this is Node.js ${input.current}.`;
+    const allowed = /^(1|true|yes|on)$/i.test((input.env.PF_ALLOW_UNSUPPORTED_NODE ?? '').trim());
+    if (allowed) {
+        return {
+            action: 'warn',
+            message: `${problem} Starting anyway because PF_ALLOW_UNSUPPORTED_NODE is set.`
+        };
+    }
+    if (input.runtime === 'sandbox') {
+        return {
+            action: 'warn',
+            message: `${problem} Starting anyway in a sandbox.`
+        };
+    }
+    return {
+        action: 'refuse',
+        message: `${problem} Switch to a newer Node.js (for example \`nvm install 22 && nvm use 22\`) and start again.`
+    };
+}

package/dist/store/conversation-store.js

@@ -27,6 +27,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryConversationStore = exports.SqliteConversationStore = void 0;
 exports.openConversationStore = openConversationStore;
+const sqlite_store_1 = require("./sqlite-store");
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS model_messages (
     session_id TEXT NOT NULL,
@@ -292,6 +293,7 @@ function openConversationStore(path) {
         };
     }
     try {
+        (0, sqlite_store_1.ensureStoreDirectory)(path);
         const db = new sqlite.DatabaseSync(path);
         return { store: new SqliteConversationStore(db), durable: true };
     }

package/dist/store/sqlite-store.d.ts

@@ -106,6 +106,23 @@ export interface OpenStoreResult {
     /** Why durability was unavailable. Reported so a degraded fleet is visible. */
     reason?: string;
 }
+/**
+ * Make the directory a store file goes in, when it is not there yet.
+ *
+ * sqlite creates the FILE and never the directory: a `--workspace-root` that
+ * does not exist yet made every open fail with "unable to open database
+ * file", and the runner then ran in memory and reported itself degraded —
+ * for a path it was about to create anyway on the first session. Private
+ * mode, because the stores hold transcripts and the model's conversation.
+ *
+ * A directory that ALREADY EXISTS is left exactly as it is, its mode included:
+ * `mkdir` with `recursive` does not touch one, and changing the permissions
+ * of a directory somebody chose is not this function's call.
+ *
+ * Throws when the directory cannot be made; the caller turns that into the
+ * same visible memory fallback as any other open failure.
+ */
+export declare function ensureStoreDirectory(path: string): void;
 /**
  * Open the durable store, or say plainly why it could not be opened.
  *

package/dist/store/sqlite-store.js

@@ -32,7 +32,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryTranscriptStore = exports.SqliteTranscriptStore = void 0;
+exports.ensureStoreDirectory = ensureStoreDirectory;
 exports.openTranscriptStore = openTranscriptStore;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS transcript_parts (
     session_id TEXT NOT NULL,
@@ -309,6 +312,28 @@ class MemoryTranscriptStore {
     }
 }
 exports.MemoryTranscriptStore = MemoryTranscriptStore;
+/**
+ * Make the directory a store file goes in, when it is not there yet.
+ *
+ * sqlite creates the FILE and never the directory: a `--workspace-root` that
+ * does not exist yet made every open fail with "unable to open database
+ * file", and the runner then ran in memory and reported itself degraded —
+ * for a path it was about to create anyway on the first session. Private
+ * mode, because the stores hold transcripts and the model's conversation.
+ *
+ * A directory that ALREADY EXISTS is left exactly as it is, its mode included:
+ * `mkdir` with `recursive` does not touch one, and changing the permissions
+ * of a directory somebody chose is not this function's call.
+ *
+ * Throws when the directory cannot be made; the caller turns that into the
+ * same visible memory fallback as any other open failure.
+ */
+function ensureStoreDirectory(path) {
+    // sqlite's in-memory and temporary databases have no directory.
+    if (path === ':memory:' || path === '')
+        return;
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+}
 /**
  * Open the durable store, or say plainly why it could not be opened.
  *
@@ -333,6 +358,7 @@ function openTranscriptStore(path) {
         };
     }
     try {
+        ensureStoreDirectory(path);
         const db = new sqlite.DatabaseSync(path);
         return { store: new SqliteTranscriptStore(db), durable: true };
     }

package/dist/types.d.ts

@@ -283,6 +283,14 @@ export interface RunnerHarness {
      * account name or a token.
      */
     reason?: string;
+    /**
+     * The check of this harness DID NOT FINISH (it timed out), so `usable:
+     * false` here is not a statement about the harness. The runner checks again
+     * shortly. Only ever sent with `installed: true, usable: false`. A reader
+     * that does not know this field shows the entry as not usable with its
+     * reason, which says the same thing in words.
+     */
+    transient?: boolean;
     /** This runner can run a turn with it: it is also listed in `backends`. */
     runnable: boolean;
     models?: RunnerHarnessModel[];

package/dist/version.d.ts

@@ -1,5 +1,7 @@
 /** The version of THIS package, as installed. */
 export declare function getHarnessVersion(): string;
+/** `engines.node` of THIS package (e.g. `>=22.19`), or null when unreadable. */
+export declare function getNodeFloor(): string | null;
 /**
  * The version of the SANDBOX TOOLS layer (gh, @peculiar/x509, ...) currently
  * installed, or null when nothing was ever synced — a self-hosted runner or

package/dist/version.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getHarnessVersion = getHarnessVersion;
+exports.getNodeFloor = getNodeFloor;
 exports.getInstalledSandboxToolsVersion = getInstalledSandboxToolsVersion;
 exports.getAttemptedSandboxToolsVersion = getAttemptedSandboxToolsVersion;
 exports.getPiVersion = getPiVersion;
@@ -23,6 +24,16 @@ function getHarnessVersion() {
     }
     return cachedHarnessVersion;
 }
+/** `engines.node` of THIS package (e.g. `>=22.19`), or null when unreadable. */
+function getNodeFloor() {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8'));
+        return typeof pkg.engines?.node === 'string' ? pkg.engines.node : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The version of the SANDBOX TOOLS layer (gh, @peculiar/x509, ...) currently
  * installed, or null when nothing was ever synced — a self-hosted runner or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.9-rc.1",
+  "version": "0.2.9-rc.2",
   "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",