@phnx-labs/agents-cli 1.22.70 → 1.22.72

package/dist/lib/daemon/self-update-service.js

@@ -0,0 +1,353 @@
+/**
+ * Daemon self-update service (PHNX-3695, "Fix 2").
+ *
+ * The daemon (`agents __daemon-run`) is a long-running background process that
+ * historically opted OUT of the CLI's interactive auto-update: `bootstrap.ts`
+ * force-sets `AGENTS_CLI_DISABLE_AUTO_UPDATE=1` for `__daemon-run`, so a
+ * running daemon never picked up new agents-cli code until a human ran
+ * `agents daemon restart`. R5 in the root CLAUDE.md ("An installed CLI and its
+ * installed helpers auto-update from the public channel") is binding for the
+ * interactive CLI path (`self-update.ts` / `agents upgrade`) but was silently
+ * NOT held for the one process that runs unattended for days. This service
+ * closes that gap for the daemon specifically, reusing the exact same
+ * verified-install primitives `agents upgrade` already uses — it does not
+ * fork or reimplement them.
+ *
+ * Model: verify-then-exit, not swap-in-place. A daemon cannot safely hot-swap
+ * its own loaded JS mid-process (in-flight ticks, open sockets, a live
+ * ServiceSupervisor). Instead this tick installs + BYTE-VERIFIES the new
+ * package on disk, and only once that succeeds does it `process.exit(0)` —
+ * the OS supervisor (launchd `KeepAlive` / systemd `Restart=always`, see
+ * `daemon/AGENTS.md`'s crash-recovery model) relaunches the daemon, which
+ * then boots the new code. Clients do not need to be told anything: browser
+ * IPC clients re-probe the socket via `waitForBrowserService`
+ * (`browser/ipc.ts`), and the scheduler's atomic `(routine, scheduledFor)`
+ * claim (see `docs/specifications.md` §Scheduling & execution singularity)
+ * means a routine mid-fire at the moment of exit is deduped safely across the
+ * restart rather than double-fired.
+ *
+ * Fail-closed is the whole point: every step below that can fail — the
+ * registry check, the install, the post-install verify — leaves the OLD
+ * daemon running untouched and logs a WARN/ERROR for the next tick to retry.
+ * The daemon must never exit into code it has not proven is the real,
+ * verified, requested version; an unverified exit would let the OS supervisor
+ * relaunch-loop on a broken install.
+ */
+import { BasePeriodicService } from './service.js';
+import { getCliVersion } from '../version.js';
+import { isDevVersionStamp } from '../startup/dev-build.js';
+import { detectAgentsBinaryShadows } from '../binary-shadow.js';
+import { compareVersions } from '../agent-spec/primitives.js';
+import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, downloadVerifiedTarball, ensureGlobalBinLinks, installPackageIntoPrefix, installPackageWithBun, refreshAliasShims, resolveRunningPackageRoot, sweepStaleInstallStaging, verifyInstalledVersion, } from '../self-update.js';
+import { tryAutoPullSystemRepo } from '../git.js';
+import { getSystemAgentsDir } from '../state.js';
+import { runUmbrellaSync } from '../sync-umbrella.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** Runs roughly every 75 minutes — self-update is not urgent (unlike self-heal's 6h drift repair, it changes running code, so it stays well under a day but still infrequent). */
+const SELF_UPDATE_TICK_MS = 75 * 60_000;
+/**
+ * Hard cap per tick: a real download + npm/bun install + verify can
+ * legitimately take minutes on a slow link. 15 minutes matches the task's
+ * stated budget and is short relative to the ~75min cadence. Exported so the
+ * on-demand `request-self-update` IPC handler (`browser/ipc.ts`) can bound
+ * its own `AbortController` on the SAME budget the periodic tick runs under —
+ * one deadline, not two independently-tuned numbers that could drift apart.
+ */
+export const SELF_UPDATE_DEADLINE_MS = 15 * 60_000;
+/**
+ * First tick fires 5 minutes after daemon boot — deliberately longer than
+ * self-heal's 30s stagger (`self-heal-service.ts`): self-heal repairs local
+ * drift and is cheap/safe to run immediately, while self-update can replace
+ * the running package and exit the process, which should never be the very
+ * first thing a freshly-started daemon does (give the box a moment to finish
+ * settling — shims, PATH, other services' startup ticks — before considering
+ * a restart). Every later tick still fires on the normal cadence.
+ */
+const SELF_UPDATE_STARTUP_DELAY_MS = 5 * 60_000;
+export async function fetchLatestNpmMetadata(signal) {
+    const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`, { signal });
+    if (!response.ok) {
+        throw new Error(`registry.npmjs.org responded ${response.status}`);
+    }
+    const data = await response.json();
+    if (typeof data.version !== 'string'
+        || typeof data.dist?.integrity !== 'string'
+        || typeof data.dist?.tarball !== 'string') {
+        throw new Error('npm registry response did not include version, integrity, and tarball');
+    }
+    return { version: data.version, integrity: data.dist.integrity, tarball: data.dist.tarball };
+}
+/**
+ * Install + byte-verify `metadata` into `packageRoot`'s install, exactly the
+ * sequence `bootstrap.ts`'s `installResolvedPackage` runs for `agents
+ * upgrade` (download+integrity-verify -> sweep stale staging -> package-
+ * manager install -> verify installed version -> refresh alias shims).
+ * `bootstrap.ts` cannot be imported here — it runs side-effecting top-level
+ * code (argv parsing, command registration) on import, which the daemon must
+ * never trigger — so this is the same primitives from `self-update.ts`
+ * composed directly, not a fork of the upgrade logic.
+ *
+ * `signal` is threaded into EVERY step's own `signal` option
+ * (`downloadVerifiedTarball` / `installPackageIntoPrefix` /
+ * `installPackageWithBun`, all in `self-update.ts`) rather than raced against
+ * from the outside: those primitives kill the underlying fetch/child process
+ * on abort and their promise rejects only once that real cancellation has
+ * happened. A wrapper that merely stopped AWAITING an unkillable operation
+ * (the prior approach here) left an orphaned `npm install -g`/`bun add -g`
+ * writing into the shared global prefix — which the very next tick's fresh
+ * install (started as soon as the supervisor's backoff fires, seconds later)
+ * would then race into the same directory. Real cancellation is what makes
+ * `attemptSelfUpdateAndExit`'s `inFlightAttempt` dedupe (below) an actual
+ * guarantee instead of a guard whose lifetime is shorter than the operation
+ * it's guarding (found in review, PHNX-3695).
+ */
+export async function installAndVerifyDefault(metadata, packageRoot, signal) {
+    const tarball = await downloadVerifiedTarball(metadata.tarball, metadata.integrity, 60_000, signal);
+    try {
+        await sweepStaleInstallStaging(packageRoot);
+        if (detectPackageManager(packageRoot) === 'bun') {
+            await installPackageWithBun(tarball, signal);
+        }
+        else {
+            await installPackageIntoPrefix(tarball, deriveGlobalPrefix(packageRoot), signal);
+        }
+    }
+    finally {
+        try {
+            await fs.promises.rm(path.dirname(tarball), { recursive: true, force: true });
+        }
+        catch {
+            /* leave it for the OS temp sweep */
+        }
+    }
+    await verifyInstalledVersion(packageRoot, metadata.version);
+    await refreshAliasShims(packageRoot, signal);
+    // PHNX-2768: mirror `bootstrap.ts`'s `installResolvedPackage` — an
+    // `--ignore-scripts` install (both package-manager paths above) can leave
+    // the package.json at the new version but the global bin links
+    // (agents/ag/browser/computer) GONE. Without this, a self-update tick could
+    // exit `updated: true` while every operator-typed `agents` command on that
+    // box now reads "command not found," with no signal anywhere pointing at
+    // why. Same fail-loud contract as the interactive path: a link that cannot
+    // be made to resolve fails the whole attempt rather than reporting success.
+    if (detectPackageManager(packageRoot) !== 'bun' && process.platform !== 'win32') {
+        const prefix = deriveGlobalPrefix(packageRoot);
+        const repairs = await ensureGlobalBinLinks(packageRoot, prefix);
+        const failed = repairs.filter((r) => r.action === 'failed');
+        if (failed.length > 0) {
+            const relink = failed
+                .map((r) => `ln -sf ${path.relative(path.dirname(r.linkPath), r.target)} ${r.linkPath}`)
+                .join(' && ');
+            throw new Error(`upgraded to ${metadata.version} but could not restore the ` +
+                `${failed.map((r) => r.name).join(', ')} command link${failed.length === 1 ? '' : 's'} in ` +
+                `${path.join(prefix, 'bin')} (${failed.map((r) => r.error).join('; ')}). ` +
+                `The box has the new package but no working \`agents\` — relink manually: ${relink}`);
+        }
+    }
+}
+export function defaultSelfUpdateDeps() {
+    return {
+        currentVersion: () => getCliVersion(),
+        isDevBuild: () => isDevVersionStamp(getCliVersion()),
+        detectShadow: () => detectAgentsBinaryShadows().length > 0,
+        packageRoot: () => resolveRunningPackageRoot(__dirname),
+        fetchLatestMetadata: fetchLatestNpmMetadata,
+        installAndVerify: installAndVerifyDefault,
+        syncSystemRepo: async () => {
+            const result = await tryAutoPullSystemRepo(getSystemAgentsDir());
+            if (result.refused) {
+                throw new Error(`system repo origin '${result.actualRemote}' is not the expected system remote — refused`);
+            }
+            if (result.error) {
+                throw new Error(result.error);
+            }
+        },
+        syncLocal: async () => {
+            // Reconcile-only (no fetch — the .system pull above already fetched);
+            // best-effort, same as the system-repo pull: a declined resource here
+            // is not a self-update failure.
+            await runUmbrellaSync({
+                flags: { local: true },
+                log: () => { },
+                yes: true,
+                quiet: true,
+            });
+        },
+    };
+}
+/**
+ * Dedupes concurrent callers onto ONE in-flight attempt. The periodic tick
+ * and an on-demand `request-self-update` IPC call (possibly several, if more
+ * than one version-skewed client reconnects at once) can overlap in the same
+ * process — without this, two concurrent `installAndVerify` calls race on the
+ * same package-manager install directory. Keyed process-wide (not per-deps)
+ * since production always shares one `defaultSelfUpdateDeps()` install target;
+ * tests inject distinct `deps` per case and don't run concurrently with each
+ * other, so this never cross-contaminates test outcomes.
+ */
+let inFlightAttempt = null;
+/**
+ * Core self-update decision + action, shared by the periodic tick
+ * ({@link SelfUpdateService.onTick}) and the on-demand IPC path
+ * (`request-self-update`, `browser/ipc.ts`) — one implementation, so a
+ * version-skew client asking "update now" runs exactly the same fail-closed
+ * logic as the scheduled sweep. Returns rather than throws so callers decide
+ * their own exit timing (the periodic service exits immediately; the IPC
+ * handler must respond to the client on the socket BEFORE exiting, or the
+ * client hangs on a socket that is closing mid-write). Concurrent callers
+ * share one in-flight attempt rather than racing separate installs.
+ */
+export async function attemptSelfUpdateAndExit(ctx, signal, deps = defaultSelfUpdateDeps()) {
+    if (inFlightAttempt)
+        return inFlightAttempt;
+    const attempt = runSelfUpdateAttempt(ctx, signal, deps);
+    inFlightAttempt = attempt;
+    try {
+        return await attempt;
+    }
+    finally {
+        if (inFlightAttempt === attempt)
+            inFlightAttempt = null;
+    }
+}
+async function runSelfUpdateAttempt(ctx, signal, deps) {
+    const syncDecline = selfUpdateSyncDeclineReason(deps);
+    if (syncDecline)
+        return { updated: false, reason: syncDecline };
+    const current = deps.currentVersion();
+    let metadata;
+    try {
+        metadata = await deps.fetchLatestMetadata(signal);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.log('WARN', `self-update: registry check failed, staying on ${current}: ${message}`);
+        return { updated: false, reason: 'registry check failed' };
+    }
+    if (compareVersions(metadata.version, current) <= 0) {
+        return { updated: false, reason: `already current (${current})` };
+    }
+    const packageRoot = deps.packageRoot();
+    try {
+        await deps.installAndVerify(metadata, packageRoot, signal);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.log('ERROR', `self-update: install/verify of ${metadata.version} failed, staying on ${current}: ${message}`);
+        return { updated: false, reason: 'install or verify failed' };
+    }
+    // Best-effort from here: the CLI package itself is already installed and
+    // byte-verified, so a failure pulling the companion .system repo or
+    // reconciling resources must not undo a good CLI upgrade or block the exit
+    // that lets the OS supervisor relaunch onto it — it is logged and left for
+    // the NEXT tick (which runs on the new code) to retry.
+    try {
+        await deps.syncSystemRepo();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.log('WARN', `self-update: .system repo pull failed: ${message}`);
+    }
+    try {
+        await deps.syncLocal();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.log('WARN', `self-update: local reconcile ('agents sync --local') failed: ${message}`);
+    }
+    ctx.log('INFO', `self-update: verified ${current} -> ${metadata.version}; exiting for OS-supervisor relaunch`);
+    return { updated: true };
+}
+/** How long `scheduleSelfUpdateExit` waits before `process.exit(0)` — long enough for an IPC handler's `socket.write` to flush to the OS. */
+const SELF_UPDATE_EXIT_DELAY_MS = 250;
+let exitScheduled = false;
+/**
+ * Schedule the process exit for a verified self-update, exactly once, no
+ * matter how many callers observe `outcome.updated` on the shared
+ * `inFlightAttempt` promise. The periodic tick and an on-demand
+ * `request-self-update` IPC call (`browser/ipc.ts`) can both be awaiting that
+ * SAME promise — if the tick's continuation ran an immediate `process.exit(0)`
+ * while the IPC handler's continuation had not yet reached `socket.write`,
+ * the tick's exit could win the race and the client would see a closed socket
+ * before any response (found in review, PHNX-3695). Routing every caller
+ * through this one guarded, always-delayed scheduling point means the delay
+ * protects EVERY caller's in-flight response, not just the IPC handler's own.
+ */
+export function scheduleSelfUpdateExit() {
+    if (exitScheduled)
+        return;
+    exitScheduled = true;
+    setTimeout(() => process.exit(0), SELF_UPDATE_EXIT_DELAY_MS);
+}
+/**
+ * Fire the on-demand self-update in the BACKGROUND and return its (bounded)
+ * promise WITHOUT the caller having to await it. This is what keeps the
+ * `request-self-update` IPC handler (`browser/ipc.ts`) from parking a
+ * version-skewed `agents browser` verb behind the full
+ * check→download→install→verify: that handler routes through
+ * `reconcileDaemonVersion` on every version-skewed call, so awaiting the whole
+ * install there reintroduces exactly the client-stall PHNX-3605 was written to
+ * prevent (tens of seconds, worst case ~15 min). The handler instead responds
+ * "triggered" immediately and lets this run in the background — the daemon does
+ * install→verify→exit(0) on its own, the OS supervisor relaunches it, and the
+ * browser reconnects.
+ *
+ * The work still shares the module-level {@link attemptSelfUpdateAndExit}
+ * `inFlightAttempt` guard, so a concurrent trigger (or the periodic tick) can't
+ * race a second install into the same prefix. It is bounded by
+ * {@link SELF_UPDATE_DEADLINE_MS} via an `AbortController` nobody awaits (the
+ * timer is `unref`'d so it never keeps the daemon alive on its own and never
+ * dangles in a test). Fail-closed is preserved end to end:
+ * `runSelfUpdateAttempt` already turns an install/verify failure into a
+ * not-updated outcome that leaves the running daemon untouched. The caller
+ * schedules the one decoupled {@link scheduleSelfUpdateExit} off the returned
+ * promise once `updated` is true, so the exit still fires after the IPC
+ * response has flushed.
+ */
+export function triggerSelfUpdateInBackground(ctx, deps = defaultSelfUpdateDeps()) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), SELF_UPDATE_DEADLINE_MS);
+    if (typeof timeout.unref === 'function')
+        timeout.unref();
+    return attemptSelfUpdateAndExit(ctx, controller.signal, deps).finally(() => clearTimeout(timeout));
+}
+/**
+ * The subset of self-update decline checks that are INSTANT and network-free —
+ * a dev build, or a shadowed install. The on-demand IPC handler
+ * (`request-self-update`) runs these SYNCHRONOUSLY so a version-skewed browser
+ * client gets the PHNX-3605 "nothing changed, not evicting" advisory
+ * immediately, instead of a "triggered" it would never act on. The remaining
+ * checks (registry probe, already-current, install/verify) stay inside the
+ * backgrounded {@link attemptSelfUpdateAndExit} so the handler never blocks on
+ * the network or the install. This is the single source of the two instant
+ * decline reasons — {@link runSelfUpdateAttempt} calls it too, so the on-demand
+ * decline text can never drift from the periodic tick's. Returns the decline
+ * reason, or `null` to proceed to the (backgrounded) install path.
+ */
+export function selfUpdateSyncDeclineReason(deps = defaultSelfUpdateDeps()) {
+    if (deps.isDevBuild())
+        return 'dev build — self-update is a no-op';
+    if (deps.detectShadow())
+        return 'another agents binary shadows this install — self-update is a no-op';
+    return null;
+}
+export class SelfUpdateService extends BasePeriodicService {
+    id = 'self-update';
+    intervalMs = SELF_UPDATE_TICK_MS;
+    deadlineMs = SELF_UPDATE_DEADLINE_MS;
+    startupDelayMs = SELF_UPDATE_STARTUP_DELAY_MS;
+    async onStart(_ctx) {
+        // No connections/handles to open — each tick checks the registry fresh.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
+    }
+    async onTick(ctx, signal) {
+        const outcome = await attemptSelfUpdateAndExit(ctx, signal);
+        if (outcome.updated)
+            scheduleSelfUpdateExit();
+    }
+}

package/dist/lib/daemon/state-dir-check-service.js

@@ -23,10 +23,10 @@
  * `supervisor.start()` pairing this requires.
  */
 import { BasePeriodicService } from './service.js';
-import * as fs from 'fs';
+import * as fsp from 'fs/promises';
 /** Matches the historical inline interval (daemon.ts STATE_DIR_CHECK_TICK_MS), overridable for tests. */
 const STATE_DIR_CHECK_TICK_MS = 60_000;
-/** Hard cap per tick — a single synchronous file read, far above what it could ever need. */
+/** Hard cap per tick — a single async file read, far above what it could ever need. */
 const STATE_DIR_CHECK_DEADLINE_MS = 5_000;
 export class StateDirCheckService extends BasePeriodicService {
     id = 'state-dir-check';
@@ -50,7 +50,7 @@ export class StateDirCheckService extends BasePeriodicService {
     async onTick(ctx) {
         let markerMatches = false;
         try {
-            markerMatches = fs.readFileSync(this.lifetimePath, 'utf-8') === this.lifetimeToken;
+            markerMatches = (await fsp.readFile(this.lifetimePath, 'utf-8')) === this.lifetimeToken;
         }
         catch {
             // A missing state dir or marker is the condition this guard detects.

package/dist/lib/daemon/usage-sync-service.js

@@ -23,7 +23,7 @@ export class UsageSyncService extends BasePeriodicService {
     }
     async onTick(ctx) {
         const { consumeUsageSnapshotsFromSharedStore, publishUsageSnapshotToSharedStore } = await import('../accounting/usage-sync.js');
-        const published = publishUsageSnapshotToSharedStore();
+        const published = await publishUsageSnapshotToSharedStore();
         if (published.changed)
             ctx.log('INFO', `usage-sync: published usage snapshot to ${published.path}`);
         if (published.error)

package/dist/lib/daemon/watchdog-service.js

@@ -8,8 +8,8 @@
  * inline behavior (daemon.ts previously `WATCHDOG_TICK_MS`-interval closure).
  */
 import { BasePeriodicService } from './service.js';
-import { getConfigValue } from '../device-config.js';
-import { emit } from '../feed/events.js';
+import { getConfigValueAsync } from '../device-config.js';
+import { emitAsync } from '../feed/events.js';
 /** Matches the historical inline interval (daemon.ts WATCHDOG_TICK_MS). */
 const WATCHDOG_TICK_MS = 3 * 60_000;
 /** Hard cap per tick — `runWatchdogPass` is host-local (adds no SSH fan-out of its own, `watchdog/runner.ts:580`); short enough that a hang never freezes the service for long. */
@@ -25,12 +25,12 @@ export class WatchdogService extends BasePeriodicService {
         // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
     }
     async onTick(ctx) {
-        if (getConfigValue('watchdog.enabled').value !== true)
+        if ((await getConfigValueAsync('watchdog.enabled')).value !== true)
             return;
         const { runWatchdogPass } = await import('../watchdog/service.js');
         const result = await runWatchdogPass({ nudge: true });
         ctx.log('INFO', `watchdog: ${result.counts.total} live, ${result.counts.stalled} stalled, ${result.counts.nudged} nudged`);
-        emit('watchdog.action', {
+        await emitAsync('watchdog.action', {
             module: 'watchdog',
             total: result.counts.total,
             stalled: result.counts.stalled,

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state';
+export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'keychain-reap' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -47,6 +47,11 @@ export const DAEMON_SERVICES = [
         title: 'Self-heal registry',
         description: 'Repairs shims, PATH, shadowing, and resource drift on a schedule.',
     },
+    {
+        id: 'self-update',
+        title: 'Self-update',
+        description: 'Checks npm for a newer agents-cli, installs + verifies it, then exits so the OS supervisor relaunches onto the new code (PHNX-3695).',
+    },
     {
         id: 'keychain-reap',
         title: 'Keychain reap',

package/dist/lib/device-config.d.ts

@@ -113,6 +113,16 @@ export declare function readFleetConfigDefaults(): Record<string, unknown>;
 export declare function readDeviceConfigValues(device: string): Record<string, unknown>;
 /** Get one config key's effective value and the layer that set it. */
 export declare function getConfigValue(name: string, opts?: ConfigTarget): ConfigEntry;
+/**
+ * Async, non-blocking twin of {@link getConfigValue} for the daemon's tick paths
+ * (PHNX-3695) — e.g. the watchdog tick reading `watchdog.enabled` every ~3min.
+ * Same layer precedence (device doc → fleet defaults → default), but the
+ * per-device doc READ is async. The user/fleet layers go through `readMeta`,
+ * which serves from an mtime-stamped in-memory cache (≈ 2 stat syscalls on the
+ * hot path, no file read), and `ensureDeviceConfigMigrated` is a one-shot no-op
+ * after the first process-wide fold — neither blocks the loop meaningfully.
+ */
+export declare function getConfigValueAsync(name: string, opts?: ConfigTarget): Promise<ConfigEntry>;
 /**
  * List every known key with its effective value and the layer that set it.
  *
@@ -250,7 +260,8 @@ export declare function assertDaemonEnabled(): void;
  * minutes. Read by the daemon's periodic tick and, as the fallback when a
  * caller omits `--idle-minutes`, by the `gc` IPC action.
  */
-export declare function resolveBrowserTaskIdleMs(): number | null;
+/** Async so the daemon's browser-task-reap tick reads the config off the shared event loop (PHNX-3695). */
+export declare function resolveBrowserTaskIdleMs(): Promise<number | null>;
 /**
  * Read the effective `agents.max-concurrent` cap for each named device (fleet
  * defaults layered under the per-device doc; no SSH). Devices without a cap

package/dist/lib/device-config.js

@@ -31,6 +31,7 @@
  * Unset always means today's behavior (the documented default).
  */
 import * as fs from 'fs';
+import * as fsp from 'fs/promises';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { META_HEADER, getUserAgentsDir, readMeta, updateMeta, withMetaLock } from './state.js';
@@ -372,17 +373,8 @@ function deviceDocPath(device) {
  * file is a hard error — silently returning null would let the next write wipe
  * the device's routines/config (same contract as routine-activation's reader).
  */
-function readDeviceDoc(device) {
-    const p = deviceDocPath(device);
-    let raw;
-    try {
-        raw = fs.readFileSync(p, 'utf-8');
-    }
-    catch (err) {
-        if (err && err.code === 'ENOENT')
-            return null;
-        throw err;
-    }
+/** Parse + validate a device doc's raw YAML. Shared by the sync and async readers. */
+function parseDeviceDoc(raw, p) {
     const corrupted = (detail) => new Error(`Device config corrupted at ${p}: ${detail}. Inspect and restore from backup.`);
     let parsed;
     try {
@@ -402,6 +394,33 @@ function readDeviceDoc(device) {
     }
     return doc;
 }
+function readDeviceDoc(device) {
+    const p = deviceDocPath(device);
+    let raw;
+    try {
+        raw = fs.readFileSync(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    return parseDeviceDoc(raw, p);
+}
+/** Async twin of {@link readDeviceDoc} for the daemon's tick paths (PHNX-3695) — the device-doc read must not block the shared event loop. */
+async function readDeviceDocAsync(device) {
+    const p = deviceDocPath(device);
+    let raw;
+    try {
+        raw = await fsp.readFile(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    return parseDeviceDoc(raw, p);
+}
 /** Write a device doc (atomic), preserving keys this module does not own
  * (`routines:`). A doc left empty is removed instead of leaving an empty
  * tracked file behind. */
@@ -476,6 +495,36 @@ export function getConfigValue(name, opts) {
         return { spec, value: fleetConfig[spec.yamlKey], source: 'fleet' };
     return { spec, value: undefined, source: 'default' };
 }
+/**
+ * Async, non-blocking twin of {@link getConfigValue} for the daemon's tick paths
+ * (PHNX-3695) — e.g. the watchdog tick reading `watchdog.enabled` every ~3min.
+ * Same layer precedence (device doc → fleet defaults → default), but the
+ * per-device doc READ is async. The user/fleet layers go through `readMeta`,
+ * which serves from an mtime-stamped in-memory cache (≈ 2 stat syscalls on the
+ * hot path, no file read), and `ensureDeviceConfigMigrated` is a one-shot no-op
+ * after the first process-wide fold — neither blocks the loop meaningfully.
+ */
+export async function getConfigValueAsync(name, opts) {
+    ensureDeviceConfigMigrated();
+    const spec = configKeySpec(name);
+    if (spec.scope === 'user') {
+        const value = readMeta().config?.[spec.yamlKey];
+        return { spec, value, source: value !== undefined ? 'user' : 'default' };
+    }
+    if (opts?.fleet) {
+        const value = readFleetConfigDefaults()[spec.yamlKey];
+        return { spec, value, source: value !== undefined ? 'fleet' : 'default' };
+    }
+    const device = targetDevice(opts);
+    assertLocalTarget(spec, device);
+    const docConfig = (await readDeviceDocAsync(device))?.config ?? {};
+    if (spec.yamlKey in docConfig)
+        return { spec, value: docConfig[spec.yamlKey], source: 'device' };
+    const fleetConfig = readFleetConfigDefaults();
+    if (spec.yamlKey in fleetConfig)
+        return { spec, value: fleetConfig[spec.yamlKey], source: 'fleet' };
+    return { spec, value: undefined, source: 'default' };
+}
 /**
  * List every known key with its effective value and the layer that set it.
  *
@@ -844,8 +893,9 @@ export function assertDaemonEnabled() {
  * minutes. Read by the daemon's periodic tick and, as the fallback when a
  * caller omits `--idle-minutes`, by the `gc` IPC action.
  */
-export function resolveBrowserTaskIdleMs() {
-    const minutes = getConfigValue('browser.task-idle-minutes').value ?? 30;
+/** Async so the daemon's browser-task-reap tick reads the config off the shared event loop (PHNX-3695). */
+export async function resolveBrowserTaskIdleMs() {
+    const minutes = (await getConfigValueAsync('browser.task-idle-minutes')).value ?? 30;
     return minutes === 0 ? null : minutes * 60_000;
 }
 /**

package/dist/lib/exec-bounded.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Async, deadline-bounded, process-group-killable subprocess exec (PHNX-3695).
+ *
+ * The daemon runs every background service on ONE Node event loop. A
+ * synchronous `execFileSync`/`spawnSync` on a service tick blocks that loop for
+ * the whole life of the child — and while it is blocked NOTHING else on the loop
+ * runs, including the supervisor's per-tick deadline timer and the browser IPC
+ * server's socket handlers. That is the wedge PHNX-3411 fixed the *symptom* of:
+ * the browser `version` probe (a trivial synchronous handler) "accepts but never
+ * replies" because the loop that would reply is frozen inside a sync spawn.
+ *
+ * `execFileBounded` is the non-blocking replacement for those tick-path spawns.
+ * It spawns with async `child_process.spawn`, so the event loop keeps serving
+ * other work while the child runs, and it bounds the child two ways:
+ *
+ *  - a `timeoutMs` deadline: on expiry it SIGTERMs the child, then SIGKILLs it
+ *    after {@link KILL_GRACE_MS} if it ignored the term — the same escalation
+ *    `sshExecAsync` uses (ssh-exec.ts).
+ *  - a process GROUP kill: the child is spawned as its own group leader
+ *    (`detached` on POSIX) so the signal reaches the whole subtree, not just the
+ *    direct child. A bare `child.kill()` would leave grandchildren running — the
+ *    orphaned-`ps`/`powershell` leak class. Windows uses `taskkill /T`.
+ *
+ * It never throws for a non-zero exit, a signal, or a spawn error: every outcome
+ * is reported in the returned {@link BoundedExecResult} so a caller on a tick
+ * path can branch on it instead of wrapping every call in try/catch.
+ */
+/** Grace between SIGTERM and SIGKILL for a child that overran its deadline. */
+export declare const KILL_GRACE_MS = 250;
+export interface ExecFileBoundedOptions {
+    /** Hard wall-clock cap. On expiry the child's process group is SIGTERMed, then SIGKILLed after {@link KILL_GRACE_MS}. Required — an unbounded tick-path spawn is the bug this helper exists to prevent. */
+    timeoutMs: number;
+    /** Working directory for the child. */
+    cwd?: string;
+    /** Environment for the child (defaults to the current process env). */
+    env?: NodeJS.ProcessEnv;
+    /** Optional stdin to write to the child. */
+    input?: string;
+}
+export interface BoundedExecResult {
+    stdout: string;
+    stderr: string;
+    /** Exit code, or null when the process was killed by a signal (including our timeout kill) or never spawned. */
+    code: number | null;
+    /** True when the deadline elapsed and we killed the child, distinguishing a timeout from an ordinary non-zero exit. */
+    timedOut: boolean;
+}
+/**
+ * Run `file args` with a hard deadline, killing the whole process group on
+ * timeout. Resolves (never rejects) with the captured output and outcome.
+ */
+export declare function execFileBounded(file: string, args: string[], opts: ExecFileBoundedOptions): Promise<BoundedExecResult>;