@peakflo/agent-harness 0.2.17 → 0.2.18

package/README.md

@@ -269,6 +269,48 @@ Cursor reports an account limit as a normal reply ("Upgrade your plan to
 continue"). The runner turns a reply that is only that sentence into a failed
 turn that says it comes from the Cursor account on the runner.
 
+## Runner presence and Claude Code paths
+
+Heartbeats use the last completed capability report. A slow CLI version probe
+runs in the background and cannot delay the liveness request. Only one such
+probe runs at a time. A later heartbeat carries the completed report.
+
+The CLI search includes `~/.local/bin`, `~/.claude/local`, Homebrew, npm, pnpm,
+Volta, Bun and installed NVM Node versions. If Claude is still missing, the
+runner reads PATH from a bounded login-shell check. It keeps only absolute PATH
+entries. It does not retain shell output. Runner credentials are removed from
+the shell environment.
+
+Set an absolute executable path to override discovery and the Claude adapter:
+
+```sh
+pf-agent-harness start --stored-credential --claude-path /absolute/path/to/claude
+```
+
+`PF_CLAUDE_PATH=/absolute/path/to/claude` is the equivalent environment option.
+`service install --claude-path /absolute/path/to/claude` saves the path in the
+service configuration. Keep the other service install options for the existing
+connection. `service repair --claude-path /absolute/path/to/claude` updates an
+existing service. Select `--vendor claude-code` for a service made by Connect.
+An invalid override fails discovery; it does not select a different executable.
+
+Read-only checks for a Claude Code service made by Connect:
+
+```sh
+pf-agent-harness service status --vendor claude-code
+command -v claude
+claude --version
+```
+
+On macOS, this service writes logs to
+`~/.pf-agent-harness/logs/claude-code/stdout.log` and `stderr.log`. On Linux,
+use `journalctl --user -u pf-agent-harness-claude-code.service`. Do not share
+tokens, credential files or unfiltered logs.
+
+Release note: this fix needs a new `@peakflo/agent-harness` release and an
+owner-controlled local service update. No sandbox image change is required.
+A running service is not updated by these source changes.
+
 ## Troubleshooting
 
 **`npx @peakflo/agent-harness` fails with a 404.** Your `~/.npmrc` maps the

package/dist/adapter-resolver.d.ts

@@ -68,4 +68,6 @@ export declare function vendorInstanceId(stateDir: string): string | null;
  */
 export declare function createAdapterResolver(runtime: string, 
 /** The runner's own state directory (its workspace root). */
-stateDir?: string): (backend: string, ports: AdapterPorts) => CodingAgentAdapter;
+stateDir?: string, options?: {
+    claudePath?: string;
+}): (backend: string, ports: AdapterPorts) => CodingAgentAdapter;

package/dist/adapter-resolver.js

@@ -290,14 +290,14 @@ function vendorInstanceId(stateDir) {
  */
 function createAdapterResolver(runtime, 
 /** The runner's own state directory (its workspace root). */
-stateDir) {
+stateDir, options = {}) {
     const instanceId = stateDir ? vendorInstanceId(stateDir) : null;
     const build = (backend) => {
         switch (backend) {
             case 'codex':
                 return new adapters_1.CodexAppServerAdapter();
             case 'claude-code':
-                return new adapters_1.ClaudeCodeAdapter();
+                return new adapters_1.ClaudeCodeAdapter(options.claudePath);
             case 'cursor':
                 return new adapters_1.AcpAdapter('cursor');
             default:

package/dist/adapters/claude-code-adapter.d.ts

@@ -26,6 +26,7 @@ export declare enum ClaudeSystemSubtype {
     THINKING_TOKENS = "thinking_tokens"
 }
 export declare class ClaudeCodeAdapter implements CodingAgentAdapter {
+    private readonly executableOverride?;
     private sessions;
     private sdkLoading;
     private claudeExecutablePath;
@@ -36,7 +37,7 @@ export declare class ClaudeCodeAdapter implements CodingAgentAdapter {
      * latency of the fixed-interval polling heartbeat.
      */
     onDataAvailable?: (sessionId: string) => void;
-    constructor();
+    constructor(executableOverride?: string | undefined);
     /**
      * Find the Claude CLI executable path
      */

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

@@ -48,8 +48,8 @@ exports.assertClaudeIsolatedConfigVersion = assertClaudeIsolatedConfigVersion;
 exports.verifyClaudeIsolatedConfigVersion = verifyClaudeIsolatedConfigVersion;
 /**
  * Extracted verbatim from 20x `src/main/adapters/claude-code-adapter.ts`.
- * CHANGED: nothing. The only import it has is `./coding-agent-adapter`, which
- * sits in the same directory here too. `@anthropic-ai/claude-agent-sdk` is an
+ * CLI resolution is shared with runner discovery. The remaining adapter
+ * behavior follows the desktop implementation. `@anthropic-ai/claude-agent-sdk` is an
  * optional dependency (dynamically imported) and is declared ambiently in
  * `./optional-agent-sdks.d.ts` so `tsc` succeeds when it is not installed.
  * Source formatting (no semicolons) preserved.
@@ -57,11 +57,10 @@ exports.verifyClaudeIsolatedConfigVersion = verifyClaudeIsolatedConfigVersion;
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
+const harness_path_1 = require("../harness-path");
 const permission_mode_1 = require("../runtime/permission-mode");
 const vendor_environment_1 = require("./vendor-environment");
 let ClaudeAgentSDK = null;
-/** Module-level cache for the resolved Claude executable path (persists across adapter instances) */
-let resolvedClaudeExecutablePath = null;
 const MINIMUM_ISOLATED_CONFIG_VERSION = [2, 1, 144];
 function assertClaudeIsolatedConfigVersion(version) {
     const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:\s|$)/);
@@ -120,6 +119,7 @@ const TERMINAL_TASK_STATUSES = new Set(['completed', 'failed', 'killed', 'stoppe
  */
 const MAX_BACKGROUND_TASK_AGE_MS = 60 * 60 * 1000; // 60 minutes
 class ClaudeCodeAdapter {
+    executableOverride;
     sessions = new Map();
     sdkLoading = null;
     claudeExecutablePath = null;
@@ -130,7 +130,8 @@ class ClaudeCodeAdapter {
      * latency of the fixed-interval polling heartbeat.
      */
     onDataAvailable;
-    constructor() {
+    constructor(executableOverride) {
+        this.executableOverride = executableOverride;
         this.sdkLoading = this.loadSDK();
     }
     /**
@@ -140,84 +141,13 @@ class ClaudeCodeAdapter {
         if (this.claudeExecutablePath) {
             return this.claudeExecutablePath;
         }
-        // Check module-level cache (persists across adapter instances)
-        if (resolvedClaudeExecutablePath) {
-            this.claudeExecutablePath = resolvedClaudeExecutablePath;
-            return this.claudeExecutablePath;
-        }
-        const isWin = process.platform === 'win32';
-        try {
-            const { execFile } = await Promise.resolve().then(() => __importStar(require('child_process')));
-            const { promisify } = await Promise.resolve().then(() => __importStar(require('util')));
-            const execFileAsync = promisify(execFile);
-            // Try to find claude in PATH
-            const whichCmd = isWin ? 'where' : 'which';
-            const binaryName = 'claude';
-            const { stdout } = await execFileAsync(whichCmd, [binaryName]);
-            let found = stdout.trim().split(/\r?\n/)[0];
-            // On Windows, the SDK spawns the executable directly without shell,
-            // so .cmd files fail with EINVAL. Resolve .cmd → the underlying cli.js
-            // so the SDK uses `node cli.js` instead.
-            if (isWin) {
-                found = await this.resolveWindowsCmdToJs(found);
-            }
-            this.claudeExecutablePath = found;
-            resolvedClaudeExecutablePath = found;
-            console.log(`[ClaudeCodeAdapter] Found claude executable at: ${this.claudeExecutablePath}`);
-            return this.claudeExecutablePath;
-        }
-        catch {
-            // Common installation locations — must cover Homebrew, npm globals,
-            // pnpm globals, Volta, and NVM paths so the binary is found even when
-            // the shell PATH wasn't fully resolved (packaged macOS GUI app).
-            const home = process.env.HOME || process.env.USERPROFILE || '';
-            const commonPaths = isWin
-                ? [
-                    `${home}\\AppData\\Roaming\\npm\\node_modules\\@anthropic-ai\\claude-code\\cli.js`,
-                    `${home}\\AppData\\Roaming\\npm\\claude.cmd`,
-                    `${home}\\AppData\\Roaming\\npm\\claude.exe`,
-                    `${home}\\.local\\bin\\claude.cmd`,
-                    `${home}\\.local\\bin\\claude.exe`
-                ]
-                : [
-                    '/usr/local/bin/claude',
-                    '/opt/homebrew/bin/claude',
-                    `${home}/.local/bin/claude`,
-                    `${home}/.npm-global/bin/claude`,
-                    `${home}/Library/pnpm/claude`,
-                    `${home}/.volta/bin/claude`,
-                ];
-            // Dynamically detect NVM-managed npm global bin (avoids hardcoding a Node version)
-            if (!isWin && home) {
-                try {
-                    const { join } = await Promise.resolve().then(() => __importStar(require('path')));
-                    const { readdirSync } = await Promise.resolve().then(() => __importStar(require('fs')));
-                    const nvmDir = join(home, '.nvm', 'versions', 'node');
-                    const versions = readdirSync(nvmDir);
-                    versions.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
-                    for (const v of versions) {
-                        commonPaths.push(join(nvmDir, v, 'bin', 'claude'));
-                    }
-                }
-                catch {
-                    // NVM not installed — skip
-                }
-            }
-            const { existsSync } = await Promise.resolve().then(() => __importStar(require('fs')));
-            for (const path of commonPaths) {
-                if (existsSync(path)) {
-                    let resolved = path;
-                    if (isWin && path.endsWith('.cmd')) {
-                        resolved = await this.resolveWindowsCmdToJs(path);
-                    }
-                    this.claudeExecutablePath = resolved;
-                    resolvedClaudeExecutablePath = resolved;
-                    console.log(`[ClaudeCodeAdapter] Found claude executable at: ${this.claudeExecutablePath}`);
-                    return this.claudeExecutablePath;
-                }
-            }
-            throw new Error('Claude CLI not found. Install it with: npm install -g @anthropic-ai/claude-code');
+        const found = await (0, harness_path_1.resolveClaudeCommand)(this.executableOverride);
+        if (!found) {
+            throw new Error('Claude Code not found. Install Claude Code or set --claude-path to its absolute executable path.');
         }
+        this.claudeExecutablePath = process.platform === 'win32'
+            ? await this.resolveWindowsCmdToJs(found) : found;
+        return this.claudeExecutablePath;
     }
     /**
      * On Windows, .cmd wrapper files can't be spawned directly by the SDK
@@ -262,6 +192,8 @@ class ClaudeCodeAdapter {
             ANTHROPIC_API_KEY: useApiKey ? config.apiKeys?.anthropic ?? process.env.ANTHROPIC_API_KEY : undefined,
             CLAUDE_CODE_OAUTH_TOKEN: useApiKey ? undefined : process.env.CLAUDE_CODE_OAUTH_TOKEN
         });
+        // Keep the installed GitHub guard first, and add service-safe CLI/Node paths.
+        env.PATH = (0, harness_path_1.harnessSearchPath)(env, (0, node_os_1.homedir)()).join(node_path_1.delimiter);
         if (useApiKey)
             delete env.CLAUDE_CODE_OAUTH_TOKEN;
         else

package/dist/adapters/vendor-environment.js

@@ -30,6 +30,7 @@ const HOST_KEYS = [
     'PATHEXT'
 ];
 const SESSION_KEYS = [
+    'PATH',
     'HTTPS_PROXY',
     'https_proxy',
     'NO_PROXY',

package/dist/cli.js

@@ -87,6 +87,7 @@ Options:
   --max-sessions <n>            concurrent sessions   (env PF_MAX_CONCURRENT_SESSIONS,
                                 default 10 for desktop/self-hosted; sandbox is configured by control plane)
   --labels <a,b>                routing labels        (env PF_RUNNER_LABELS)
+  --claude-path <path>          absolute Claude CLI path (PF_CLAUDE_PATH)
   --vendor-harnesses <list>     allow codex,claude-code,cursor on this machine
                                 (env PF_VENDOR_HARNESSES; default none)
   --no-harness-discovery        do not look for Codex, Claude Code, Cursor,
@@ -265,7 +266,7 @@ async function main() {
         env: process.env
     }).assertNoDuplicateRunner(options);
     const handedOffCredential = (0, credential_store_1.takeHandedOffCredential)(startEnv);
-    const resolveAdapter = (0, adapter_resolver_1.createAdapterResolver)(options.runtime, options.workspaceRoot);
+    const resolveAdapter = (0, adapter_resolver_1.createAdapterResolver)(options.runtime, options.workspaceRoot, { claudePath: options.claudePath });
     const harness = new harness_1.Harness(options, {
         getAdapter: (backend, ports) => resolveAdapter(backend, ports),
         ...(handedOffCredential

package/dist/harness-discovery.d.ts

@@ -28,6 +28,7 @@
  * 4. NO GLOBAL SIDE EFFECTS. `process.env.PATH` is not changed; the search path
  *    is local and is handed to each child process.
  */
+import { harnessSearchPath } from './harness-path';
 import type { RunnerHarness, RunnerHarnessModel } from './types';
 /**
  * One command: `--version`, a status check, or a model listing.
@@ -112,6 +113,8 @@ export interface DiscoverHarnessesOptions {
      */
     only?: readonly string[];
     deps?: Partial<DiscoveryDeps>;
+    /** Operator-selected Claude executable; also used by the turn adapter. */
+    claudePath?: string;
 }
 /**
  * Where to look for a harness binary: PATH first, then the directories the
@@ -120,7 +123,7 @@ export interface DiscoverHarnessesOptions {
  * of the running `node` is added because a runner started by launchd or
  * systemd has a short PATH, and an npm-installed CLI sits beside that `node`.
  */
-export declare function discoverySearchPath(env: NodeJS.ProcessEnv, home: string, platform?: NodeJS.Platform): string[];
+export declare const discoverySearchPath: typeof harnessSearchPath;
 /**
  * The environment a harness CLI is started with.
  *

package/dist/harness-discovery.js

@@ -30,8 +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_CONCURRENCY = exports.DISCOVERY_HARNESS_TIMEOUT_MS = exports.DISCOVERY_COMMAND_TIMEOUT_MS = void 0;
-exports.discoverySearchPath = discoverySearchPath;
+exports.KNOWN_HARNESSES = exports.discoverySearchPath = 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.discoveryChildEnv = discoveryChildEnv;
 exports.sanitizeHarnessModels = sanitizeHarnessModels;
 exports.parseVersion = parseVersion;
@@ -45,6 +44,7 @@ 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");
+const harness_path_1 = require("./harness-path");
 /**
  * One command: `--version`, a status check, or a model listing.
  *
@@ -142,57 +142,7 @@ exports.CURSOR_STATIC_MODELS = [
  * of the running `node` is added because a runner started by launchd or
  * systemd has a short PATH, and an npm-installed CLI sits beside that `node`.
  */
-function discoverySearchPath(env, home, platform = process.platform) {
-    /*
-     * ABSOLUTE ENTRIES ONLY. A relative entry (`.`, `node_modules/.bin`) means
-     * "whatever is in the directory the runner was started from", and a file
-     * named `codex` there is not the user's Codex.
-     */
-    const fromEnv = (env.PATH ?? env.Path ?? '')
-        .split(node_path_1.delimiter)
-        .filter((entry) => entry !== '' && (0, node_path_1.isAbsolute)(entry));
-    const known = platform === 'win32'
-        ? [
-            (0, node_path_1.join)(home, 'AppData', 'Roaming', 'npm'),
-            (0, node_path_1.join)(home, '.local', 'bin'),
-            (0, node_path_1.join)(home, '.opencode', 'bin')
-        ]
-        : [
-            (0, node_path_1.join)(home, '.local', 'bin'),
-            (0, node_path_1.join)(home, '.opencode', 'bin'),
-            '/opt/homebrew/bin',
-            '/usr/local/bin',
-            (0, node_path_1.join)(home, '.npm-global', 'bin'),
-            (0, node_path_1.join)(home, '.volta', 'bin'),
-            (0, node_path_1.join)(home, '.bun', 'bin')
-        ];
-    return [...new Set([...fromEnv, ...known, (0, node_path_1.dirname)(process.execPath)])];
-}
-function isExecutableFile(path) {
-    try {
-        if (!(0, node_fs_1.statSync)(path).isFile())
-            return false;
-        (0, node_fs_1.accessSync)(path, node_fs_1.constants.X_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function defaultResolveCommand(command, searchPath, env) {
-    // npm installs `.cmd` wrappers on Windows, so the bare name is not a file.
-    const extensions = process.platform === 'win32'
-        ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
-        : [''];
-    for (const dir of searchPath) {
-        for (const extension of extensions) {
-            const candidate = (0, node_path_1.join)(dir, `${command}${extension}`);
-            if (isExecutableFile(candidate))
-                return candidate;
-        }
-    }
-    return null;
-}
+exports.discoverySearchPath = harness_path_1.harnessSearchPath;
 function defaultExec(command, args, timeoutMs, env) {
     return new Promise((resolve) => {
         let settled = false;
@@ -275,14 +225,24 @@ function discoveryChildEnv(env, searchPath) {
     child.PATH = searchPath.join(node_path_1.delimiter);
     return child;
 }
-function resolveDeps(overrides = {}) {
-    const env = overrides.env ?? process.env;
+async function resolveDeps(overrides = {}, claudePath) {
+    const env = {
+        ...(overrides.env ?? process.env),
+        ...(claudePath ? { PF_CLAUDE_PATH: claudePath } : {})
+    };
+    if (!overrides.env && !env.SHELL)
+        env.SHELL = (0, harness_path_1.defaultLoginShell)();
     const home = overrides.home ?? (0, node_os_1.homedir)();
-    const searchPath = discoverySearchPath(env, home);
+    const searchPath = (0, exports.discoverySearchPath)(env, home);
+    if (!overrides.resolveCommand &&
+        !(0, harness_path_1.resolveHarnessCommand)('claude', searchPath, env) &&
+        !env.PF_CLAUDE_PATH) {
+        searchPath.push(...(await (0, harness_path_1.loginShellSearchPath)(env)));
+    }
     const childEnv = discoveryChildEnv(env, searchPath);
     return {
         exec: (command, args, timeoutMs) => defaultExec(command, args, timeoutMs, childEnv),
-        resolveCommand: (command) => defaultResolveCommand(command, searchPath, env),
+        resolveCommand: (command) => (0, harness_path_1.resolveHarnessCommand)(command, searchPath, env),
         realpath: (path) => (0, node_fs_1.realpathSync)(path),
         readFile: (path) => {
             try {
@@ -739,7 +699,7 @@ async function discoverHarnesses(options = {}) {
     let deps = null;
     let detectedAt = new Date().toISOString();
     try {
-        deps = resolveDeps(options.deps);
+        deps = await resolveDeps(options.deps, options.claudePath);
         detectedAt = deps.now().toISOString();
     }
     catch {

package/dist/harness-path.d.ts

@@ -0,0 +1,10 @@
+export declare const LOGIN_PATH_TIMEOUT_MS = 2000;
+/** launchd can omit SHELL even though the account has a configured login shell. */
+export declare function defaultLoginShell(): string | undefined;
+export declare function harnessSearchPath(env: NodeJS.ProcessEnv, home: string, platform?: NodeJS.Platform): string[];
+/** Only PATH is retained. Shell startup output and runner credentials are never returned. */
+export declare function loginShellSearchPath(env: NodeJS.ProcessEnv, timeoutMs?: number): Promise<string[]>;
+export declare function executableFile(path: string): boolean;
+export declare function resolveHarnessCommand(command: string, searchPath: readonly string[], env: NodeJS.ProcessEnv): string | null;
+/** Shared by discovery and the adapter, so a detected CLI is the CLI that runs. */
+export declare function resolveClaudeCommand(explicitPath?: string): Promise<string | null>;

package/dist/harness-path.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOGIN_PATH_TIMEOUT_MS = void 0;
+exports.defaultLoginShell = defaultLoginShell;
+exports.harnessSearchPath = harnessSearchPath;
+exports.loginShellSearchPath = loginShellSearchPath;
+exports.executableFile = executableFile;
+exports.resolveHarnessCommand = resolveHarnessCommand;
+exports.resolveClaudeCommand = resolveClaudeCommand;
+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");
+exports.LOGIN_PATH_TIMEOUT_MS = 2_000;
+const PATH_MARKER = '__PF_HARNESS_PATH__';
+/** launchd can omit SHELL even though the account has a configured login shell. */
+function defaultLoginShell() {
+    if (process.platform === 'win32')
+        return undefined;
+    try {
+        return (0, node_os_1.userInfo)().shell ?? '/bin/sh';
+    }
+    catch {
+        return process.platform === 'darwin' ? '/bin/zsh' : '/bin/sh';
+    }
+}
+function harnessSearchPath(env, home, platform = process.platform) {
+    const inherited = (env.PATH ?? env.Path ?? '')
+        .split(node_path_1.delimiter)
+        .filter(node_path_1.isAbsolute);
+    const known = platform === 'win32'
+        ? [
+            (0, node_path_1.join)(home, 'AppData', 'Roaming', 'npm'),
+            (0, node_path_1.join)(home, '.local', 'bin'),
+            (0, node_path_1.join)(home, '.opencode', 'bin')
+        ]
+        : [
+            (0, node_path_1.join)(home, '.local', 'bin'),
+            (0, node_path_1.join)(home, '.claude', 'local'),
+            (0, node_path_1.join)(home, '.opencode', 'bin'),
+            '/opt/homebrew/bin',
+            '/usr/local/bin',
+            (0, node_path_1.join)(home, '.npm-global', 'bin'),
+            (0, node_path_1.join)(home, 'Library', 'pnpm'),
+            (0, node_path_1.join)(home, '.volta', 'bin'),
+            (0, node_path_1.join)(home, '.bun', 'bin')
+        ];
+    if (platform !== 'win32') {
+        try {
+            const nvm = (0, node_path_1.join)(home, '.nvm', 'versions', 'node');
+            const versions = (0, node_fs_1.readdirSync)(nvm).filter((name) => /^v\d+[.\d]*$/.test(name));
+            versions.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+            known.push(...versions.slice(0, 32).map((version) => (0, node_path_1.join)(nvm, version, 'bin')));
+        }
+        catch {
+            /* NVM is optional. */
+        }
+    }
+    return [...new Set([...inherited, ...known, (0, node_path_1.dirname)(process.execPath)])];
+}
+/** Only PATH is retained. Shell startup output and runner credentials are never returned. */
+function loginShellSearchPath(env, timeoutMs = exports.LOGIN_PATH_TIMEOUT_MS) {
+    const shell = env.SHELL;
+    if (!shell ||
+        !(0, node_path_1.isAbsolute)(shell) ||
+        !['zsh', 'bash', 'sh'].includes((0, node_path_1.basename)(shell))) {
+        return Promise.resolve([]);
+    }
+    const childEnv = Object.fromEntries(Object.entries(env).filter(([key]) => !/^PF_/i.test(key)));
+    return new Promise((resolve) => {
+        let settled = false;
+        let child = null;
+        let timer = null;
+        const killProbe = () => {
+            try {
+                if (process.platform !== 'win32' && child?.pid) {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                else
+                    child?.kill('SIGKILL');
+            }
+            catch {
+                /* The shell can already have exited. */
+            }
+        };
+        const finish = (paths) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(paths);
+        };
+        timer = setTimeout(() => {
+            killProbe();
+            finish([]);
+        }, timeoutMs + 100);
+        timer.unref();
+        try {
+            let output = '';
+            let bytes = 0;
+            child = (0, node_child_process_1.spawn)(shell, ['-ilc', `printf '\\n${PATH_MARKER}%s\\n' "$PATH"`], {
+                env: childEnv,
+                detached: process.platform !== 'win32',
+                stdio: ['ignore', 'pipe', 'ignore']
+            });
+            child.stdout?.on('data', (chunk) => {
+                bytes += chunk.length;
+                if (bytes > 128 * 1024) {
+                    killProbe();
+                    finish([]);
+                }
+                else
+                    output += chunk.toString();
+            });
+            child.on('close', (code) => {
+                if (code !== 0)
+                    return finish([]);
+                const line = output
+                    .split('\n')
+                    .find((entry) => entry.startsWith(PATH_MARKER));
+                finish((line?.slice(PATH_MARKER.length) ?? '')
+                    .split(node_path_1.delimiter)
+                    .filter(node_path_1.isAbsolute));
+            });
+            child.on('error', () => finish([]));
+        }
+        catch {
+            finish([]);
+        }
+    });
+}
+function executableFile(path) {
+    try {
+        if (!(0, node_fs_1.statSync)(path).isFile())
+            return false;
+        (0, node_fs_1.accessSync)(path, node_fs_1.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveHarnessCommand(command, searchPath, env) {
+    if (command === 'claude' && env.PF_CLAUDE_PATH) {
+        const explicit = env.PF_CLAUDE_PATH;
+        // An invalid explicit choice must not silently select a different binary.
+        return (0, node_path_1.isAbsolute)(explicit) && executableFile(explicit) ? explicit : null;
+    }
+    const extensions = process.platform === 'win32'
+        ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+        : [''];
+    for (const dir of searchPath) {
+        for (const extension of extensions) {
+            const candidate = (0, node_path_1.join)(dir, `${command}${extension}`);
+            if (executableFile(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** Shared by discovery and the adapter, so a detected CLI is the CLI that runs. */
+async function resolveClaudeCommand(explicitPath) {
+    const env = {
+        ...process.env,
+        SHELL: process.env.SHELL ?? defaultLoginShell(),
+        ...(explicitPath ? { PF_CLAUDE_PATH: explicitPath } : {})
+    };
+    const paths = harnessSearchPath(env, (0, node_os_1.homedir)());
+    const found = resolveHarnessCommand('claude', paths, env);
+    if (found || env.PF_CLAUDE_PATH)
+        return found;
+    return resolveHarnessCommand('claude', [...paths, ...(await loginShellSearchPath(env))], env);
+}

package/dist/harness.d.ts

@@ -233,6 +233,7 @@ export declare class Harness {
     private heartbeatIntervalMs;
     private leaseWaitSeconds;
     private heartbeatTimer;
+    private capabilityProbeInFlight;
     /** Fires when the runner credential should be rotated. Durable runtimes re-persist the new one. */
     private rotateTimer;
     private readonly credentialStore;
@@ -429,6 +430,7 @@ export declare class Harness {
      */
     private modelsNeedRefresh;
     private scheduleHeartbeat;
+    private refreshCapabilities;
     private sendHeartbeat;
     /** A bad command must not stop the others or fail a transcript ingest. */
     private applyCommandsSafely;

package/dist/harness.js

@@ -252,6 +252,7 @@ class Harness {
     heartbeatIntervalMs;
     leaseWaitSeconds = contract_1.DEFAULT_LEASE_WAIT_SECONDS;
     heartbeatTimer = null;
+    capabilityProbeInFlight = null;
     /** Fires when the runner credential should be rotated. Durable runtimes re-persist the new one. */
     rotateTimer = null;
     credentialStore;
@@ -928,6 +929,9 @@ class Harness {
             try {
                 const fresh = await discover({
                     runnableBackends: (this.capabilities?.backends ?? []).map((backend) => backend.name),
+                    ...(this.options.claudePath
+                        ? { claudePath: this.options.claudePath }
+                        : {}),
                     ...(only ? { only } : {})
                 });
                 const report = mergeHarnessReports(this.harnessReport, fresh);
@@ -1168,16 +1172,37 @@ class Harness {
         // Never hold the event loop open on the heartbeat alone.
         this.heartbeatTimer.unref();
     }
+    refreshCapabilities() {
+        if (this.capabilityProbeInFlight || this.stopping)
+            return;
+        const pass = (async () => {
+            try {
+                const capabilities = await (0, capabilities_1.probeCapabilities)({
+                    maxConcurrentSessions: this.options.maxConcurrentSessions,
+                    labels: this.options.labels
+                });
+                if (!this.stopping)
+                    this.capabilities = capabilities;
+            }
+            catch {
+                // A failed capability refresh must not hide an otherwise healthy runner.
+                log('Capability refresh failed; keeping the last report');
+            }
+        })();
+        this.capabilityProbeInFlight = pass;
+        void pass.finally(() => {
+            if (this.capabilityProbeInFlight === pass)
+                this.capabilityProbeInFlight = null;
+        });
+    }
     async sendHeartbeat() {
         try {
-            // Capabilities are RE-PROBED, not cached from registration. A host is
-            // upgraded in place: docker can appear and a backend can be installed
-            // without the runner ever restarting, and the control plane routes work
-            // on this answer.
-            const capabilities = await (0, capabilities_1.probeCapabilities)({
-                maxConcurrentSessions: this.options.maxConcurrentSessions,
-                labels: this.options.labels
-            });
+            // CLI version probes can hang. Keep the last completed report and send
+            // liveness now; one background pass updates the following heartbeat.
+            const capabilities = this.capabilities;
+            if (!capabilities)
+                throw new Error('Runner has no initial capabilities.');
+            this.refreshCapabilities();
             this.applyModelCatalog(capabilities);
             this.applyHarnessReport(capabilities);
             this.capabilities = capabilities;

package/dist/options.js

@@ -219,7 +219,13 @@ function parseOptions(argv, env) {
     // Resolved before the object literal, because the workspace-root DEFAULT
     // depends on it.
     const runtime = parseRuntime(readFlag(argv, 'runtime') ?? env.PF_RUNNER_RUNTIME);
+    const claudePath = readFlag(argv, 'claude-path') ?? env.PF_CLAUDE_PATH;
+    if (claudePath !== undefined &&
+        (!(0, node_path_1.isAbsolute)(claudePath) || /[\r\n\0]/.test(claudePath))) {
+        throw new OptionsError('Claude path must be an absolute executable path.');
+    }
     return {
+        ...(claudePath ? { claudePath } : {}),
         controlPlaneUrl,
         enrolmentToken: enrolmentToken ?? '',
         healthPort: parsePort(readFlag(argv, 'health-port') ?? env.PF_HARNESS_HEALTH_PORT, DEFAULT_HEALTH_PORT),

package/dist/service.d.ts

@@ -63,7 +63,7 @@ export declare class ServiceManager {
     install(input: string[]): Promise<void>;
     private vendorFlag;
     private checkNodeVersion;
-    repair(): void;
+    repair(input?: string[]): void;
     assertNoDuplicateRunner(options: {
         workspaceRoot: string;
         healthPort: number;

package/dist/service.js

@@ -35,7 +35,8 @@ const VALUE_FLAGS = new Set([
     '--runtime',
     '--max-sessions',
     '--labels',
-    '--vendor-harnesses'
+    '--vendor-harnesses',
+    '--claude-path'
 ]);
 const SWITCH_FLAGS = new Set(['--no-harness-discovery']);
 /** Service names for an instance. Only vendor names are accepted. */
@@ -172,6 +173,12 @@ function serviceStartArgs(input, env, home) {
     if (env.PF_VENDOR_HARNESSES && !values.has('--vendor-harnesses')) {
         values.set('--vendor-harnesses', safe(env.PF_VENDOR_HARNESSES));
     }
+    const claudePath = values.get('--claude-path') ?? env.PF_CLAUDE_PATH;
+    if (claudePath !== undefined) {
+        if (!(0, node_path_1.isAbsolute)(claudePath))
+            throw new Error('Claude path must be absolute.');
+        values.set('--claude-path', safe(claudePath));
+    }
     const vendorNames = values.get('--vendor-harnesses');
     if (vendorNames !== undefined) {
         const names = vendorNames
@@ -430,13 +437,36 @@ class ServiceManager {
         if (floor.action === 'refuse')
             throw new Error(floor.message);
     }
-    repair() {
+    repair(input = []) {
         this.supported();
         this.checkNodeVersion();
         const prior = this.readConfig();
-        this.checkCredential(prior.startArgs);
+        let claudePath = this.context.env.PF_CLAUDE_PATH;
+        for (let index = 0; index < input.length; index++) {
+            const flag = input[index];
+            if (flag === '--claude-path')
+                claudePath = input[++index];
+            else if (flag.startsWith('--claude-path='))
+                claudePath = flag.slice(14);
+            else
+                throw new Error('Service repair accepts only --claude-path.');
+            if (!claudePath)
+                throw new Error('Missing value for --claude-path.');
+        }
+        const startArgs = [...prior.startArgs];
+        if (claudePath !== undefined) {
+            if (!(0, node_path_1.isAbsolute)(claudePath))
+                throw new Error('Claude path must be absolute.');
+            const at = startArgs.indexOf('--claude-path');
+            if (at >= 0)
+                startArgs.splice(at, 2);
+            startArgs.push('--claude-path', safe(claudePath));
+        }
+        (0, options_1.parseOptions)(startArgs, {});
+        this.checkCredential(startArgs);
         this.writeAndStart({
             ...prior,
+            startArgs,
             nodePath: this.context.nodePath,
             cliPath: this.context.cliPath,
             path: this.context.env.PATH ?? prior.path
@@ -576,7 +606,7 @@ async function runServiceCommand(input, context) {
             manager.status();
             break;
         case 'repair':
-            manager.repair();
+            manager.repair(args.slice(1));
             break;
         case 'uninstall':
             manager.uninstall();

package/dist/types.d.ts

@@ -38,6 +38,8 @@
  *    Do not "improve" this by adding a `--token` flag.
  */
 export interface HarnessOptions {
+    /** Absolute operator-selected Claude executable. Never a shell command. */
+    claudePath?: string;
     /** workflow-api base url, e.g. https://stage-api.peakflo.ai */
     controlPlaneUrl: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "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",