@parall/daemon 1.36.0 → 1.37.0

package/dist/index.js

@@ -1,188 +1,62 @@
 #!/usr/bin/env node
+import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { createLogger, createOtelLogger, initAgentTelemetry, } from '@parall/agent-core';
-import { ParallClient } from '@parall/sdk';
-import { runCLI } from './cli.js';
-import { resolveBundleDir, resolveClaudeDaemonConfig, resolveWsUrl, } from './config.js';
-import { DaemonSupervisor, sleepCancellable } from './supervisor.js';
-import { DaemonUpdater } from './updater.js';
+import { resolveBundleDir } from './daemon-paths.js';
+import { isSelfUpdateDisabledByEnv, isSelfUpdateManaged } from './daemon-update-mode.js';
 const UPDATE_EXIT_CODE = 42;
-let log = createLogger('daemon');
 function formatError(reason) {
     if (reason instanceof Error) {
         return reason.stack ?? reason.message;
     }
     return String(reason);
 }
-/**
- * Self-update should run only when a service manager supervises the daemon —
- * `parall-daemon service install` (launchd/systemd) or the hosted entrypoint.sh
- * keepalive loop. Those wrappers re-exec the overlay bundle on restart, and
- * exit(UPDATE_EXIT_CODE) is precisely what triggers that restart so the new code
- * loads.
- *
- * A bare `npx @parall/daemon` foreground run has neither property: it never
- * exec's the overlay (so a downloaded bundle is dead weight on disk — this very
- * process keeps running the npm launcher code), and nothing restarts it after
- * exit(42). Self-updating there would just kill the daemon with no recovery. So
- * we gate on two positive "managed" signals:
- *   - PRLL_DAEMON_MANAGED=1 — injected into the plist / systemd unit by
- *     `service install`; the authoritative marker.
- *   - launched from the overlay bundle dir — a service wrapper already exec'd
- *     `…/.parall-daemon/bundle/current/parall-daemon.js`. Covers service
- *     installs predating the PRLL_DAEMON_MANAGED marker.
- * Foreground users stay current via `npx @parall/daemon@latest`, which pulls the
- * newest launcher on every run.
- */
-function isSelfUpdateManaged(env, bundleDir) {
-    if (env.PRLL_DAEMON_MANAGED === '1' || env.PRLL_DAEMON_MANAGED === 'true')
-        return true;
-    const entry = process.argv[1];
-    if (entry) {
-        const resolvedEntry = path.resolve(entry);
-        const resolvedBundle = path.resolve(bundleDir);
-        if (resolvedEntry === resolvedBundle || resolvedEntry.startsWith(resolvedBundle + path.sep)) {
-            return true;
-        }
+function errnoCode(err) {
+    if (!err || typeof err !== 'object' || !('code' in err))
+        return undefined;
+    const code = err.code;
+    return typeof code === 'string' ? code : undefined;
+}
+function clearRunningMarker(markerPath) {
+    try {
+        fs.unlinkSync(markerPath);
+    }
+    catch (err) {
+        if (errnoCode(err) === 'ENOENT')
+            return;
+        console.warn(`failed to clear daemon running marker: ${formatError(err)}`);
     }
-    return false;
 }
 /**
- * Outer keepalive: runs `supervisor.run()` in a loop, restarting it with
- * exponential backoff if it rejects. The daemon process only exits when
- * the abort signal fires (SIGINT/SIGTERM) — anything else is treated as
- * a transient failure that we recover from in-process.
- *
- * Why this exists in addition to entrypoint.sh's `while :; do parall-daemon; done`:
- *   - In-process restart preserves the `client` (= same TCP/TLS pool) and
- *     skips the ~hundreds-of-ms cost of Node startup + module loading per
- *     cycle, which matters when the API is flapping.
- *   - The shell wrapper is the "process really crashed" backstop —
- *     segfault, OOM, uncaughtException, etc. The two layers are
- *     complementary: in-process for soft failures, shell for hard failures.
- *
- * Operators can disable the in-process loop by setting
- * PRLL_DAEMON_SUPERVISOR_RESTART_BACKOFF_MS=0 — main() will then exit on
- * any supervisor.run() rejection and rely entirely on the shell wrapper +
- * K8s for restart.
+ * Bootstrap owns the process-lifecycle fact for rollback: "a daemon boot was
+ * entered and did not exit cleanly." Keep this before the app import so config,
+ * telemetry, updater, or other app-startup failures still leave evidence for
+ * the next boot's rollback accounting. CLI subcommands are not daemon boots.
  */
-async function runForever(config, client, log, signal, updater) {
-    let attempt = 0;
-    while (!signal.aborted) {
-        const supervisor = new DaemonSupervisor(config, client, log);
-        if (updater)
-            supervisor.setUpdater(updater);
-        try {
-            await supervisor.run(signal);
-            // Clean exit (signal aborted) — done.
-            await supervisor.stop();
-            return;
-        }
-        catch (err) {
-            // supervisor.run() rejected. The supervisor's per-tick handlers
-            // already swallow individual failures, so the only paths that reach
-            // here are (a) bootstrap fail-fast mode and (b) genuine programmer
-            // bugs. Restart anyway — operators rely on this daemon as the only
-            // thing keeping per-agent children alive on this host.
-            log.error(`supervisor crashed: ${String(err)}`);
-            try {
-                await supervisor.stop();
-            }
-            catch (stopErr) {
-                log.warn(`supervisor.stop() after crash threw: ${String(stopErr)}`);
-            }
-            if (config.supervisorRestartBackoffMs === 0) {
-                log.error('supervisor keepalive disabled (PRLL_DAEMON_SUPERVISOR_RESTART_BACKOFF_MS=0) — exiting');
-                throw err;
-            }
-            const delay = Math.min(config.supervisorRestartBackoffMs * 2 ** attempt, config.supervisorRestartBackoffMaxMs);
-            attempt += 1;
-            log.warn(`restarting supervisor in ${delay}ms (attempt ${attempt})`);
-            const slept = await sleepCancellable(delay, signal);
-            if (!slept)
-                return;
-        }
+function prepareDaemonBootstrap(env = process.env, args = process.argv.slice(2)) {
+    const bundleDir = resolveBundleDir(env);
+    const runningMarker = path.join(bundleDir, 'daemon-running');
+    const lifecycleMarkerEnabled = args.length === 0 && !isSelfUpdateDisabledByEnv(env) && isSelfUpdateManaged(bundleDir, env);
+    if (!lifecycleMarkerEnabled) {
+        return { lifecycleMarkerEnabled: false, runningMarker, uncleanPrevExit: false };
     }
-}
-async function main() {
-    const config = resolveClaudeDaemonConfig(process.env);
-    const telemetry = await initAgentTelemetry('parall-daemon', 'daemon');
-    log = createOtelLogger('daemon', 'daemon');
-    log.info(`boot: api=${config.apiUrl} pollMs=${config.pollIntervalMs} heartbeatMs=${config.heartbeatIntervalMs} agentBin=${config.agentBin}`);
-    log.info(`keepalive: bootstrapBackoffMs=${config.bootstrapBackoffMs} supervisorRestartBackoffMs=${config.supervisorRestartBackoffMs}`);
-    // --- Self-update: rollback check (before any network calls) ---
-    // Only run when a service manager supervises us (see isSelfUpdateManaged):
-    // a bare `npx` foreground run can't load the overlay and won't be restarted
-    // after exit(42), so self-update there would just kill the daemon.
-    let updater = null;
-    const bundleDir = resolveBundleDir(process.env);
-    const selfUpdateEnabled = !config.updateDisabled && isSelfUpdateManaged(process.env, bundleDir);
-    if (selfUpdateEnabled) {
-        updater = new DaemonUpdater(bundleDir, config.updateCdnUrl, log, true);
-        if (updater.checkRollback()) {
-            log.info('rollback applied — exiting for service manager restart');
-            await telemetry.shutdown();
-            process.exit(UPDATE_EXIT_CODE);
-        }
-        log.info(`update: bundleDir=${bundleDir} cdn=${config.updateCdnUrl} interval=${config.updateIntervalMs}ms`);
+    const uncleanPrevExit = fs.existsSync(runningMarker);
+    try {
+        fs.mkdirSync(bundleDir, { recursive: true });
+        fs.writeFileSync(runningMarker, String(process.pid));
     }
-    else if (!config.updateDisabled) {
-        log.info('update: skipped (foreground mode) — run `parall-daemon service install` for managed auto-update');
+    catch (err) {
+        console.warn(`failed to write daemon running marker: ${formatError(err)}`);
     }
-    // The daemon talks to the API as a Machine — the bearer is mck_*.
-    // No orgId is configured here; per-agent subprocesses get their
-    // own org_id via the spawn env.
-    const client = new ParallClient({
-        baseUrl: config.apiUrl,
-        token: config.apiKey,
-        swimlaneName: config.swimlaneName,
-    });
-    const abortController = new AbortController();
-    const onSignal = (sig) => {
-        log.info(`received ${sig} — initiating shutdown`);
-        abortController.abort();
-    };
-    process.on('SIGINT', () => onSignal('SIGINT'));
-    process.on('SIGTERM', () => onSignal('SIGTERM'));
-    // Defensive: unexpected async failures are logged explicitly. Rejections
-    // stay in-process so the supervisor loop can recover; uncaught exceptions
-    // exit so entrypoint.sh's shell-level keepalive restarts from a clean VM.
-    process.on('unhandledRejection', (reason) => {
-        log.error(`unhandledRejection: ${formatError(reason)}`);
-    });
-    process.on('uncaughtException', (err) => {
-        log.error(`uncaughtException: ${formatError(err)}`);
-        process.exitCode = 1;
-        process.exit(1);
+    process.on('exit', (code) => {
+        if (code === 0 || code === UPDATE_EXIT_CODE)
+            clearRunningMarker(runningMarker);
     });
-    config.wsUrl = resolveWsUrl(config.apiUrl, config.wsUrl, config.swimlaneName);
-    // --- Self-update: boot check + periodic timer ---
-    if (updater) {
-        const applied = await updater.checkAndApply().catch((err) => {
-            log.warn(`boot update check failed: ${String(err)}`);
-            return false;
-        });
-        if (applied) {
-            log.info('boot update applied — exiting for restart');
-            await telemetry.shutdown();
-            process.exit(UPDATE_EXIT_CODE);
-        }
-        updater.startPeriodicCheck(config.updateIntervalMs);
-    }
-    await runForever(config, client, log, abortController.signal, updater);
-    await telemetry.shutdown();
+    return { lifecycleMarkerEnabled: true, runningMarker, uncleanPrevExit };
 }
-const cliArgs = process.argv.slice(2);
-runCLI(cliArgs)
-    .then((result) => {
-    if (result === 'handled')
-        return;
-    main().catch((err) => {
-        log.error(`fatal: ${formatError(err)}`);
-        process.exitCode = 1;
-    });
-})
+const bootstrap = prepareDaemonBootstrap();
+void import('./daemon-main.js')
+    .then((mod) => mod.runDaemonEntry(bootstrap))
     .catch((err) => {
-    log.error(`fatal: ${formatError(err)}`);
+    console.error(`fatal: ${formatError(err)}`);
     process.exitCode = 1;
 });

package/dist/runtime-bin-resolver.d.ts

@@ -2,6 +2,10 @@ type RuntimeBinLogger = {
     info: (msg: string) => void;
     warn: (msg: string) => void;
 };
+/** Runtime types whose host CLI the resolver knows how to locate. */
+export declare const DETECTABLE_RUNTIME_TYPES: readonly string[];
+/** The env var `applyRuntimeBinaryEnv` publishes the resolved binary under. */
+export declare function runtimeBinaryEnvVar(runtimeType: string): string | undefined;
 export declare function applyRuntimeBinaryEnv(runtimeType: string, baseEnv: NodeJS.ProcessEnv, log: RuntimeBinLogger): NodeJS.ProcessEnv;
 export {};
 //# sourceMappingURL=runtime-bin-resolver.d.ts.map

package/dist/runtime-bin-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-bin-resolver.d.ts","sourceRoot":"","sources":["../src/runtime-bin-resolver.ts"],"names":[],"mappings":"AAUA,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,CAAC;AA0BF,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,CAAC,UAAU,EAC1B,GAAG,EAAE,gBAAgB,GACpB,MAAM,CAAC,UAAU,CAmCnB"}
+{"version":3,"file":"runtime-bin-resolver.d.ts","sourceRoot":"","sources":["../src/runtime-bin-resolver.ts"],"names":[],"mappings":"AAUA,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,CAAC;AAgCF,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAkC,CAAC;AAEzF,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE3E;AAKD,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,CAAC,UAAU,EAC1B,GAAG,EAAE,gBAAgB,GACpB,MAAM,CAAC,UAAU,CAmCnB"}

package/dist/runtime-bin-resolver.js

@@ -7,12 +7,18 @@ const RUNTIME_BINARIES = {
     codex: { command: 'codex', envVar: 'PRLL_CODEX_BIN' },
     openclaw: { command: 'openclaw', envVar: 'PRLL_OPENCLAW_BIN' },
 };
+/** Runtime types whose host CLI the resolver knows how to locate. */
+export const DETECTABLE_RUNTIME_TYPES = Object.keys(RUNTIME_BINARIES);
+/** The env var `applyRuntimeBinaryEnv` publishes the resolved binary under. */
+export function runtimeBinaryEnvVar(runtimeType) {
+    return RUNTIME_BINARIES[runtimeType]?.envVar;
+}
 const RESOLUTION_CACHE_TTL_MS = 5 * 60_000;
 const resolutionCache = new Map();
 export function applyRuntimeBinaryEnv(runtimeType, baseEnv, log) {
     const env = { ...baseEnv };
     const originalPath = env.PATH;
-    const pathPlan = candidatePathPlan(env);
+    const pathPlan = cachedCandidatePathPlan(env);
     const primaryPath = mergePath(pathPlan.primaryDirs, originalPath);
     env.PATH = mergePath([...pathPlan.primaryDirs, ...pathPlan.versionedFallbackDirs], originalPath);
     const spec = RUNTIME_BINARIES[runtimeType];
@@ -48,6 +54,9 @@ function resolveRuntimeCommand(command, env, inheritedPath, primaryPath, fallbac
     const cached = getCachedResolution(cacheKey);
     if (cached)
         return cached;
+    // A cached miss (cached === null) skips ONLY the login-shell step — see
+    // ResolutionCacheEntry. The cheap fs scans below always run fresh.
+    const runLoginShell = cached === undefined;
     const direct = resolveDirectPath(command);
     if (direct) {
         const resolved = { binaryPath: direct };
@@ -59,10 +68,12 @@ function resolveRuntimeCommand(command, env, inheritedPath, primaryPath, fallbac
         setCachedResolution(cacheKey, fromInheritedPath);
         return fromInheritedPath;
     }
-    const fromShell = resolveFromLoginShell(command, { ...env, PATH: inheritedPath });
-    if (fromShell) {
-        setCachedResolution(cacheKey, fromShell);
-        return fromShell;
+    if (runLoginShell) {
+        const fromShell = resolveFromLoginShell(command, { ...env, PATH: inheritedPath });
+        if (fromShell) {
+            setCachedResolution(cacheKey, fromShell);
+            return fromShell;
+        }
     }
     const fromPrimaryPath = resolveFromPath(command, primaryPath, env);
     if (fromPrimaryPath) {
@@ -74,6 +85,12 @@ function resolveRuntimeCommand(command, env, inheritedPath, primaryPath, fallbac
         setCachedResolution(cacheKey, fromFallbackPath);
         return fromFallbackPath;
     }
+    // Record the miss only on a round that actually ran the login-shell —
+    // re-recording it on a cached-miss round would keep refreshing the TTL and
+    // the login-shell would never get retried.
+    if (runLoginShell) {
+        setCachedResolution(cacheKey, null);
+    }
     return null;
 }
 function resolveDirectPath(command) {
@@ -135,6 +152,21 @@ function resolveFromLoginShell(command, env) {
     }
     return null;
 }
+// The plan involves fs stats over dozens of candidate dirs plus readdirSync
+// over nvm/fnm version roots; since the periodic runtime detector re-resolves
+// every 5 min (×3 runtimes) on top of agent spawns, memoize it on the same
+// TTL as resolutions. A freshly installed version manager dir therefore shows
+// up within one detection interval, same as everything else here.
+const pathPlanCache = new Map();
+function cachedCandidatePathPlan(env) {
+    const key = `${env.HOME ?? ''}\0${env.PRLL_DAEMON_RUNTIME_PATH ?? ''}\0${env.PRLL_DAEMON_EXTRA_PATH ?? ''}`;
+    const hit = pathPlanCache.get(key);
+    if (hit && hit.expiresAt > Date.now())
+        return hit.value;
+    const value = candidatePathPlan(env);
+    pathPlanCache.set(key, { value, expiresAt: Date.now() + RESOLUTION_CACHE_TTL_MS });
+    return value;
+}
 function candidatePathPlan(env) {
     const home = env.HOME || os.homedir();
     const primaryDirs = [
@@ -243,13 +275,14 @@ function commandCandidates(command, env) {
         .map((ext) => ext.toLowerCase());
     return [command, ...exts.map((ext) => `${command}${ext}`)];
 }
+/** undefined = no cache entry; null = cached miss (see ResolutionCacheEntry). */
 function getCachedResolution(cacheKey) {
     const entry = resolutionCache.get(cacheKey);
     if (!entry)
-        return null;
+        return undefined;
     if (entry.expiresAt <= Date.now()) {
         resolutionCache.delete(cacheKey);
-        return null;
+        return undefined;
     }
     return entry.value;
 }

package/dist/runtime-detector.d.ts

@@ -0,0 +1,30 @@
+import type { DetectedRuntime } from '@parall/sdk';
+export type { DetectedRuntime };
+type DetectorLogger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+};
+/**
+ * Resolve a runtime CLI binary the same way agent spawn does. Exposed for
+ * tests to inject a fake resolver into `detectRuntimes`.
+ */
+export declare function resolveRuntimeBinary(runtimeType: string, baseEnv: NodeJS.ProcessEnv): {
+    binaryPath: string;
+    env: NodeJS.ProcessEnv;
+} | null;
+/**
+ * Detect which runtime CLIs exist on this host and whether they actually run.
+ * Absent runtimes are omitted; a binary that resolves but fails `--version`
+ * (exit != 0, timeout, spawn error) reports status 'broken' — a
+ * present-but-unusable install is a stronger signal than absence.
+ *
+ * Resolution reuses the exact spawn-time path (`applyRuntimeBinaryEnv`), so
+ * "detected" and "what an agent child would launch" can't drift apart. The
+ * probe runs with the resolver's anchored PATH because npm-shim CLIs
+ * (`#!/usr/bin/env node`) need their sibling node on PATH to execute.
+ */
+export declare function detectRuntimes(baseEnv: NodeJS.ProcessEnv, log: DetectorLogger, resolveBin?: typeof resolveRuntimeBinary): Promise<DetectedRuntime[]>;
+/** Order-sensitive compare — detection emits entries in stable runtime order. */
+export declare function detectedRuntimesEqual(a: DetectedRuntime[], b: DetectedRuntime[]): boolean;
+export declare function summarizeDetectedRuntimes(detected: DetectedRuntime[]): string;
+//# sourceMappingURL=runtime-detector.d.ts.map

package/dist/runtime-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-detector.d.ts","sourceRoot":"","sources":["../src/runtime-detector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAOnD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,CAAC;AAuBF;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,CAAC,UAAU,GACzB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GAAG,IAAI,CAMvD;AA0BD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,CAAC,UAAU,EAC1B,GAAG,EAAE,cAAc,EACnB,UAAU,GAAE,OAAO,oBAA2C,GAC7D,OAAO,CAAC,eAAe,EAAE,CAAC,CA4B5B;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE,eAAe,EAAE,GAAG,OAAO,CAQzF;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,CAK7E"}

package/dist/runtime-detector.js

@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process';
+import { applyRuntimeBinaryEnv, DETECTABLE_RUNTIME_TYPES, runtimeBinaryEnvVar, } from './runtime-bin-resolver.js';
+// The resolver logs per-runtime resolution lines meant for spawn time; during
+// periodic detection they would repeat every interval, so detection summarizes
+// in ONE line instead and hands the resolver a muted logger.
+const MUTED_LOG = { info: () => { }, warn: () => { } };
+const VERSION_PROBE_TIMEOUT_MS = 10_000;
+// Server-side column cap is 64 (heartbeat validation rejects longer).
+const VERSION_MAX_LEN = 64;
+const IS_WIN32 = process.platform === 'win32';
+// Mirrors the bridges' spawn quoting (claude-agent/codex-agent dispatch.ts):
+// on Windows the resolved binary is usually a `.cmd` npm shim, which execFile
+// can only launch through a shell — and shell mode requires manual quoting.
+function quoteWin32Arg(arg) {
+    if (!/[\s"&|^<>()]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '""')}"`;
+}
+/**
+ * Resolve a runtime CLI binary the same way agent spawn does. Exposed for
+ * tests to inject a fake resolver into `detectRuntimes`.
+ */
+export function resolveRuntimeBinary(runtimeType, baseEnv) {
+    const envVar = runtimeBinaryEnvVar(runtimeType);
+    if (!envVar)
+        return null;
+    const env = applyRuntimeBinaryEnv(runtimeType, baseEnv, MUTED_LOG);
+    const binaryPath = env[envVar];
+    return binaryPath ? { binaryPath, env } : null;
+}
+function probeVersion(binaryPath, env) {
+    return new Promise((resolve) => {
+        execFile(IS_WIN32 ? quoteWin32Arg(binaryPath) : binaryPath, ['--version'], 
+        // shell on Windows: same as the bridge spawn path — a `.cmd` shim can't
+        // be exec'd directly, and without it a healthy install probes 'broken'.
+        { env, timeout: VERSION_PROBE_TIMEOUT_MS, windowsHide: true, shell: IS_WIN32 }, (err, stdout) => {
+            if (err) {
+                resolve({ ok: false });
+                return;
+            }
+            const line = String(stdout)
+                .split(/\r?\n/)
+                .map((l) => l.trim())
+                .find((l) => l.length > 0) ?? '';
+            resolve(line ? { ok: true, version: line.slice(0, VERSION_MAX_LEN) } : { ok: true });
+        });
+    });
+}
+/**
+ * Detect which runtime CLIs exist on this host and whether they actually run.
+ * Absent runtimes are omitted; a binary that resolves but fails `--version`
+ * (exit != 0, timeout, spawn error) reports status 'broken' — a
+ * present-but-unusable install is a stronger signal than absence.
+ *
+ * Resolution reuses the exact spawn-time path (`applyRuntimeBinaryEnv`), so
+ * "detected" and "what an agent child would launch" can't drift apart. The
+ * probe runs with the resolver's anchored PATH because npm-shim CLIs
+ * (`#!/usr/bin/env node`) need their sibling node on PATH to execute.
+ */
+export async function detectRuntimes(baseEnv, log, resolveBin = resolveRuntimeBinary) {
+    // Resolution is synchronous by nature (fs scans + possible login-shell), so
+    // it stays a plain loop; the probes are independent subprocesses and run in
+    // parallel — serial probing would stack their latencies (worst case one
+    // 10s timeout per broken CLI). Promise.all preserves the stable runtime
+    // order the change-comparison relies on.
+    const resolved = DETECTABLE_RUNTIME_TYPES.map((runtimeType) => ({
+        runtimeType,
+        bin: resolveBin(runtimeType, baseEnv),
+    }));
+    const entries = await Promise.all(resolved.map(async ({ runtimeType, bin }) => {
+        if (!bin)
+            return null;
+        const probe = await probeVersion(bin.binaryPath, bin.env);
+        if (probe.ok) {
+            return {
+                runtime_type: runtimeType,
+                ...(probe.version ? { version: probe.version } : {}),
+                status: 'ok',
+            };
+        }
+        log.warn(`runtime detection: ${runtimeType} resolved at ${bin.binaryPath} but --version failed`);
+        return { runtime_type: runtimeType, status: 'broken' };
+    }));
+    return entries.filter((e) => e !== null);
+}
+/** Order-sensitive compare — detection emits entries in stable runtime order. */
+export function detectedRuntimesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((x, i) => x.runtime_type === b[i].runtime_type &&
+        x.version === b[i].version &&
+        x.status === b[i].status);
+}
+export function summarizeDetectedRuntimes(detected) {
+    if (detected.length === 0)
+        return 'none found';
+    return detected
+        .map((d) => `${d.runtime_type}=${d.status === 'ok' ? (d.version ?? 'ok') : 'broken'}`)
+        .join(' ');
+}

package/dist/supervisor.d.ts

@@ -2,6 +2,7 @@ import { type GatewayLogger } from '@parall/agent-core';
 import { type ParallClient } from '@parall/sdk';
 import { type ClaudeDaemonConfig } from './config.js';
 import type { DaemonUpdater } from './updater.js';
+import type { PendingUpdateHealthGate } from './update-health-gate.js';
 /**
  * Sleep that wakes early on abort. Returns true if the full delay elapsed,
  * false if aborted. Used by bootstrap retry and the outer keepalive in
@@ -28,8 +29,12 @@ export declare class DaemonSupervisor {
     private readonly spawningAgents;
     private readonly pendingWorkspaceSetup;
     private readonly browserProfileOpQueues;
+    private readonly browserProfilePendingRevives;
     private readonly workspaceSetupRetryTimers;
+    private readonly agentConfigRefreshRetryTimers;
     private readonly cancelledSpawns;
+    private readonly pendingConfigRefresh;
+    private readonly restartingStates;
     private ws;
     private running;
     private machineId;
@@ -40,23 +45,42 @@ export declare class DaemonSupervisor {
     private connectedClipServiceUrl;
     private stopResolve;
     private updater;
-    private healthConfirmed;
-    private browserProfileManager;
+    private healthGate;
+    private browserProfilePool;
     private clipManager;
     private clipProvider;
     private clipReconcileTimer;
     private clipReconcileInFlight;
+    private detectedRuntimes;
+    private runtimeDetectTimer;
+    private runtimeDetectInFlight;
+    private detectRuntimesFn;
     private hubClient;
     private hubClientUrl;
     constructor(config: ClaudeDaemonConfig, client: ParallClient, log: GatewayLogger);
     setUpdater(updater: DaemonUpdater): void;
+    /** Inject the process-level update health gate. The supervisor only feeds it
+     *  fact signals (machine.hello, supervisor-ended); the gate owns confirm policy. */
+    setHealthGate(gate: PendingUpdateHealthGate): void;
     /** Start the supervisor. Returns a promise that resolves on `stop()`. */
     run(signal: AbortSignal): Promise<void>;
     /** Disconnect WS, cancel timers, SIGTERM all children, await exit. */
     stop(): Promise<void>;
     private bootstrapWithRetry;
     private fullReconcile;
+    private wipeBeforeRevive;
     private reconcileBrowserProfiles;
+    /**
+     * Resolve a profile's outbound proxy for bb-browser account creation (BYOC).
+     * Fetched fresh — account creation is rare (once per profile until reset), so a
+     * proxy edit applies on the next account_create. The mck_-authed machine list is
+     * the only path that carries proxy_password (for replay to bb-browser).
+     *
+     * Fails closed: a fetch failure or a vanished profile THROWS, so the manager never
+     * creates an account that would egress from the host's real IP for a
+     * proxy-configured profile (the caller reports `error` and retries next tick).
+     */
+    private resolveBrowserProfileProxy;
     /**
      * Detects a legacy flat state layout (no agents/ subdir) and migrates it
      * into the per-agent directory for the owning agent. Ownership is determined
@@ -70,6 +94,7 @@ export declare class DaemonSupervisor {
     private handleBrowserProfileLifecycle;
     private enqueueBrowserProfileLifecycle;
     private enqueueBrowserProfileOp;
+    private enqueueBrowserProfileRevive;
     /**
      * Handle one viewer control command and reply via REST. Always answers the
      * request/reply bridge exactly once ({result} on success, {error:{message}}
@@ -83,6 +108,15 @@ export declare class DaemonSupervisor {
     private reconcileMachineClipsNow;
     private startClipReconcileTimer;
     private stopClipReconcileTimer;
+    /**
+     * Detect runtime CLIs on this host and heartbeat the result. `initial`
+     * always reports (it also carries daemon version + self-update capability,
+     * replacing the old version-only startup heartbeat); periodic runs report
+     * only when the detection result changed, keeping steady state write-free.
+     * Serialized via `runtimeDetectInFlight` so a slow probe can't overlap the
+     * next interval tick and race the change comparison.
+     */
+    private detectAndReportRuntimes;
     private machineClipToConfig;
     private manifestFromMachineClip;
     private dependencyMap;
@@ -121,10 +155,38 @@ export declare class DaemonSupervisor {
      */
     private applyClipProviderState;
     private respawnAllChildren;
+    /**
+     * Per-agent counterpart of the machine.config.updated respawn: ONE agent's
+     * explicit llm_source changed, so refresh that agent's cached
+     * provider_config from the server and respawn only its child — every other
+     * child keeps running. The event payload carries only the EFFECTIVE source;
+     * the cache must hold the RAW per-agent config (see ChildState
+     * .providerConfig) so startChild keeps resolving inherit-vs-override
+     * against the CURRENT machine default — caching the effective value would
+     * pin this agent across future machine-level default changes.
+     */
+    private handleAgentConfigUpdated;
+    /**
+     * Intentional single-child respawn for a config change. Marks the state
+     * shuttingDown around the terminate so settleChild doesn't schedule a
+     * competing crash-backoff restart (which would also bump restartAttempts
+     * and delay the new route), clears any pending crash timer so
+     * restartChildNow isn't blocked by it, and bails if the agent detached
+     * while the child was terminating.
+     */
+    private respawnChildForConfig;
+    private scheduleAgentConfigRefreshRetry;
+    private clearAgentConfigRefreshRetry;
     private restartChildNow;
     private spawnAgent;
     private spawnAgentOnce;
     private startChild;
+    /**
+     * SIGTERM the child (SIGKILL after 10s) and resolve once it has exited.
+     * settleChild's 'exit' listener is registered before this one, so
+     * state.child is guaranteed cleared by the time this resolves — callers
+     * may start a replacement child immediately after awaiting.
+     */
     private terminateChild;
     private ensureSharedCredentialLink;
 }

package/dist/supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}