@phnx-labs/agents-cli 1.22.70 → 1.22.71

package/dist/lib/daemon/runner.js

@@ -15,6 +15,7 @@
  */
 import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
+import * as fsp from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
 import { getCliLaunch, getAgentsBinDir } from '../cli-entry.js';
@@ -23,14 +24,15 @@ import { getRunsDir, getUserAgentsDir, readMeta, getDaemonDir } from '../state.j
 import { shortCodexHome } from '../codex-home.js';
 import { prepareJobHome, buildSpawnEnv, getJobHomePath, assertSandboxForwardsHostGhAuth, linkVersionAuth } from '../sandbox.js';
 import { resolveModel, buildReasoningFlags } from '../models.js';
-import { createTimer, redactPrompt, emitRoutineEnd } from '../feed/events.js';
+import { createTimer, redactPrompt, emitRoutineEnd, emitRoutineEndAsync } from '../feed/events.js';
 import { resolveHarnessAdapter } from '../harness/index.js';
 import { applyAddDirs } from '../add-dir.js';
 import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, detectAuthFailure, isAuthFailureFromLog, authFailureReason, AGENT_COMMANDS, } from '../exec.js';
 import { resolveActor } from '../actor.js';
 import { loadTask as loadHostTask } from '../hosts/tasks.js';
-import { reconcileTask as reconcileHostTask } from '../hosts/reconcile.js';
-import { backgroundSpawnOptions, killTree } from '../platform/process.js';
+import { reconcileTask as reconcileHostTask, reconcileTaskAsync as reconcileHostTaskAsync } from '../hosts/reconcile.js';
+import { backgroundSpawnOptions, isAlive, killTree } from '../platform/process.js';
+import { execFileBounded } from '../exec-bounded.js';
 import lockfile from 'proper-lockfile';
 import { ensureLockTarget } from '../fs-atomic.js';
 import { logAndContinueOnLockCompromised } from '../lock-compromise.js';
@@ -2228,6 +2230,40 @@ const MAX_WALL_CLOCK_MS = 24 * 60 * 60 * 1000;
  * compares against the process's actual start time via `ps`. Returns true
  * when the PID is alive AND plausibly ours.
  */
+/** Bound the identity `ps` — a hung `ps` must never freeze its caller for long (matches routine-process-cleanup's probe). */
+const PS_IDENTITY_TIMEOUT_MS = 5_000;
+/**
+ * Pure: does a `ps -o etime=` value place the process's birth within 30s of when
+ * we recorded spawning it? An empty/unknown reading conservatively reads as ours
+ * — never reap a run on a doubtful identity probe.
+ */
+function etimeIndicatesOurs(etime, spawnedAt) {
+    if (!etime)
+        return true;
+    const parts = etime.replace(/-/g, ':').split(':').reverse();
+    let uptimeSec = 0;
+    if (parts[0])
+        uptimeSec += parseInt(parts[0], 10);
+    if (parts[1])
+        uptimeSec += parseInt(parts[1], 10) * 60;
+    if (parts[2])
+        uptimeSec += parseInt(parts[2], 10) * 3600;
+    if (parts[3])
+        uptimeSec += parseInt(parts[3], 10) * 86400;
+    const processStartMs = Date.now() - uptimeSec * 1000;
+    return Math.abs(processStartMs - spawnedAt) < 30_000;
+}
+/**
+ * Synchronous identity check for callers OTHER than the periodic heartbeat tick:
+ * the `agents routines list/status` builders and stop-time enumeration (both in
+ * short-lived CLI processes), plus the scheduler's fire-time slot-claim
+ * (`activeRoutineRun`) and status projection (`isRunGenuinelyInFlight`). Those
+ * last two DO run in-process on the daemon's event loop, but are event-driven
+ * (they fire when a job is dispatched, not on a fixed cadence) and the `ps` here
+ * is now bounded to {@link PS_IDENTITY_TIMEOUT_MS} — they are not the
+ * unconditional every-tick scan PHNX-3695 targets. The heartbeat tick's own scan
+ * uses the non-blocking {@link isPidOursAsync} instead.
+ */
 function isPidOurs(pid, spawnedAt) {
     try {
         process.kill(pid, 0);
@@ -2240,42 +2276,75 @@ function isPidOurs(pid, spawnedAt) {
     if (process.platform === 'win32')
         return true;
     try {
-        const etime = execFileSync('ps', ['-p', String(pid), '-o', 'etime='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-        if (!etime)
-            return true;
-        const parts = etime.replace(/-/g, ':').split(':').reverse();
-        let uptimeSec = 0;
-        if (parts[0])
-            uptimeSec += parseInt(parts[0], 10);
-        if (parts[1])
-            uptimeSec += parseInt(parts[1], 10) * 60;
-        if (parts[2])
-            uptimeSec += parseInt(parts[2], 10) * 3600;
-        if (parts[3])
-            uptimeSec += parseInt(parts[3], 10) * 86400;
-        const processStartMs = Date.now() - uptimeSec * 1000;
-        return Math.abs(processStartMs - spawnedAt) < 30_000;
+        const etime = execFileSync('ps', ['-p', String(pid), '-o', 'etime='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: PS_IDENTITY_TIMEOUT_MS }).trim();
+        return etimeIndicatesOurs(etime, spawnedAt);
     }
     catch {
         return true;
     }
 }
+/**
+ * Async, deadline-bounded twin of {@link isPidOurs} for the daemon's heartbeat
+ * tick (`reapExitedRunningJobs`) — the `ps` probe runs on the shared event loop,
+ * so it MUST NOT block it (PHNX-3695). Same semantics: dead pid → not ours;
+ * no recorded `spawnedAt` or Windows → assume ours; a failed/empty probe reads
+ * as ours (conservative — never reap on a doubtful probe).
+ */
+async function isPidOursAsync(pid, spawnedAt) {
+    if (!isAlive(pid))
+        return false;
+    if (spawnedAt === undefined)
+        return true;
+    if (process.platform === 'win32')
+        return true;
+    const res = await execFileBounded('ps', ['-p', String(pid), '-o', 'etime='], { timeoutMs: PS_IDENTITY_TIMEOUT_MS });
+    if (res.code !== 0)
+        return true; // probe failed → keep the run, same as the sync catch
+    return etimeIndicatesOurs(res.stdout.trim(), spawnedAt);
+}
 /**
  * Finalize one `host:`-placed run by healing its host-task sidecar against the
  * remote `.exit` (lib/hosts/reconcile.ts). Mutates + persists the meta only
  * when the sidecar reached a terminal state.
  */
+/** Apply a healed host-task's terminal state to the local run record. Shared by the sync and async host reconcilers. */
+function applyHealedHostRun(meta, healed, 
+// The routine-end emit acquires the event-log file lock. On the daemon
+// heartbeat tick (finalizeHostRunAsync) that MUST be the async, non-blocking
+// variant, or the synchronous `withFileLock` (lockSync + Atomics.wait, up to
+// 30s under contention) freezes the whole event loop — the exact wedge PHNX-3695
+// targets, on a path guard-no-sync-io does not scan (PHNX-3727). The sync CLI
+// path (finalizeHostRun) keeps the default synchronous emit.
+emit = emitRoutineEnd) {
+    if (healed.status !== 'completed' && healed.status !== 'failed')
+        return;
+    finalizeRunMeta(meta, healed.status, healed.exitCode ?? (healed.status === 'completed' ? 0 : 1), { completedAt: healed.finishedAt ?? undefined });
+    writeRunMeta(meta);
+    emit(meta);
+}
 function finalizeHostRun(meta) {
     try {
         const task = loadHostTask(meta.hostTaskId);
         if (!task)
             return;
-        const healed = reconcileHostTask(task);
-        if (healed.status !== 'completed' && healed.status !== 'failed')
+        applyHealedHostRun(meta, reconcileHostTask(task));
+    }
+    catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
+}
+/**
+ * Async twin of {@link finalizeHostRun} for the daemon heartbeat tick
+ * (PHNX-3695). A `host:`-placed run's remote `.exit` is read over ssh; on the
+ * tick that read MUST be async (`reconcileHostTaskAsync` → `sshExecAsync`) or a
+ * single 6s ssh timeout freezes the whole event loop — the exact bug class this
+ * effort targets, worse than the local `ps` probe.
+ */
+async function finalizeHostRunAsync(meta) {
+    try {
+        const task = loadHostTask(meta.hostTaskId);
+        if (!task)
             return;
-        finalizeRunMeta(meta, healed.status, healed.exitCode ?? (healed.status === 'completed' ? 0 : 1), { completedAt: healed.finishedAt ?? undefined });
-        writeRunMeta(meta);
-        emitRoutineEnd(meta);
+        // Tick path: emit through the async, non-blocking file lock (PHNX-3727).
+        applyHealedHostRun(meta, await reconcileHostTaskAsync(task), (m) => { void emitRoutineEndAsync(m); });
     }
     catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
 }
@@ -2349,7 +2418,91 @@ export function isRunGenuinelyInFlight(meta) {
         return false;
     return isPidOurs(meta.pid, meta.spawnedAt);
 }
-/** Scan all runs marked "running" and finalize any whose process has exited. */
+/**
+ * Reconcile ONE `running` record once its process identity is known (`ours` =
+ * the recorded pid is still genuinely the child we spawned). Shared verbatim by
+ * the synchronous {@link monitorRunningJobs} (off-loop callers) and the async
+ * {@link reapExitedRunningJobs} (daemon heartbeat tick) so there is one copy of
+ * the finalize/timeout/report logic — only the surrounding directory/`ps` IO
+ * differs by sync-vs-async flavor. Caller has already confirmed `meta.status`
+ * is `running`. The finalize/report/archive helpers stay synchronous: they run
+ * ONLY when a run actually transitions (times out or its process exited), a
+ * conditional/rare event, not the every-tick scan the loop-starvation fix
+ * (PHNX-3695) targets. The one exception is the `routine.end` EVENT emit, whose
+ * file lock CAN block for up to 30s under contention even on that rare path — so
+ * the emitter is injected: the off-loop sync caller passes `emitRoutineEnd`
+ * (synchronous, so a short-lived CLI process flushes it before exit), the daemon
+ * tick passes a fire-and-forget `emitRoutineEndAsync` (the long-lived daemon
+ * flushes it, and the shared event loop is never blocked on the lock).
+ */
+function reconcileRunningRecord(meta, jobRunsPath, runDirName, ours, emitEnd) {
+    // Host-placed runs (meta.hostTaskId) are handled by the caller, sync or async
+    // — their remote `.exit` read is ssh I/O that must stay off the daemon tick's
+    // event loop (finalizeHostRunAsync). Records reaching here are local-pid runs.
+    const runDirPath = path.join(jobRunsPath, runDirName);
+    const stdoutPath = path.join(runDirPath, 'stdout.log');
+    // Command-mode records carry no agent; there is no stream-json report to
+    // parse or extract. Reap them on pid liveness alone.
+    const isCommandRun = Boolean(meta.command) || !meta.agent;
+    // Age-out runs FIRST, before the null-pid guard below, so a wedged record
+    // still marked `running` past its deadline is always finalized — a
+    // provisional launcher claim whose daemon crashed before spawning a child
+    // (pid null), or an old record whose recorded pid was reused, would
+    // otherwise linger as `running` forever (RUSH-2640). Only kill a process
+    // group that is genuinely still ours; terminating a reused pid would kill
+    // an unrelated process, and a null pid has nothing to kill.
+    const wallClockMs = Date.now() - Date.parse(meta.startedAt);
+    const timeoutMs = meta.timeoutMs ?? MAX_WALL_CLOCK_MS;
+    if (Number.isFinite(wallClockMs) && wallClockMs > timeoutMs) {
+        if (meta.pid && ours)
+            terminateRoutineTree(meta.pid);
+        finalizeRunMeta(meta, 'timeout', null, { errorMessage: 'exceeded configured timeout' });
+        writeRunMeta(meta);
+        emitEnd(meta);
+        if (!isCommandRun) {
+            extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
+            archiveRoutineTranscripts(meta, runDirPath);
+        }
+        return;
+    }
+    if (!meta.pid)
+        return;
+    if (!ours) {
+        if (isCommandRun) {
+            // Command routines normally record their own terminal status via
+            // child.on('exit') (so this record would already be non-'running' and
+            // skipped above). Reaching here means the daemon restarted mid-run and
+            // missed the exit event — recover the true code from the exit-code file
+            // the child wrote; its absence means the child was killed/crashed.
+            const ec = readCommandExitCode(runDirPath);
+            finalizeRunMeta(meta, ec === 0 ? 'completed' : 'failed', ec);
+        }
+        else {
+            const inferred = inferFinalStatusFromLog(stdoutPath, meta.agent);
+            if (inferred) {
+                finalizeRunMeta(meta, inferred.status, inferred.exitCode);
+            }
+            else {
+                finalizeRunMeta(meta, 'failed', null, { errorMessage: 'process exited before final status could be inferred' });
+            }
+        }
+        writeRunMeta(meta);
+        emitEnd(meta);
+        if (!isCommandRun) {
+            extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
+            archiveRoutineTranscripts(meta, runDirPath);
+        }
+    }
+}
+/**
+ * Scan all runs marked "running" and finalize any whose process has exited.
+ *
+ * SYNCHRONOUS — for OFF-loop callers only (the `agents routines list/status`
+ * builders and CLI best-effort orphan reaps), which run in short-lived CLI
+ * processes where a bounded synchronous `ps`/scan cannot starve a served event
+ * loop. The daemon's own heartbeat tick MUST use {@link reapExitedRunningJobs}
+ * instead — a sync scan there would freeze the shared event loop (PHNX-3695).
+ */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();
     if (!fs.existsSync(runsDir))
@@ -2378,67 +2531,67 @@ export function monitorRunningJobs() {
                 const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
                 if (meta.status !== 'running')
                     continue;
-                // `host:`-placed run — no local pid to watch. Reconcile against the
-                // remote `.exit` (completion is confirmed, never guessed: an
-                // unreachable host leaves the run `running` for the next sweep).
+                // `host:`-placed run — no local pid; reconcile against the remote `.exit`.
                 if (meta.hostTaskId) {
                     finalizeHostRun(meta);
                     continue;
                 }
-                const runDirPath = path.join(jobRunsPath, runDirEntry.name);
-                const stdoutPath = path.join(runDirPath, 'stdout.log');
-                // Command-mode records carry no agent; there is no stream-json report to
-                // parse or extract. Reap them on pid liveness alone.
-                const isCommandRun = Boolean(meta.command) || !meta.agent;
-                // Age-out runs FIRST, before the null-pid guard below, so a wedged record
-                // still marked `running` past its deadline is always finalized — a
-                // provisional launcher claim whose daemon crashed before spawning a child
-                // (pid null), or an old record whose recorded pid was reused, would
-                // otherwise linger as `running` forever (RUSH-2640). Only kill a process
-                // group that is genuinely still ours; terminating a reused pid would kill
-                // an unrelated process, and a null pid has nothing to kill.
-                const wallClockMs = Date.now() - Date.parse(meta.startedAt);
-                const timeoutMs = meta.timeoutMs ?? MAX_WALL_CLOCK_MS;
-                if (Number.isFinite(wallClockMs) && wallClockMs > timeoutMs) {
-                    if (meta.pid && isPidOurs(meta.pid, meta.spawnedAt))
-                        terminateRoutineTree(meta.pid);
-                    finalizeRunMeta(meta, 'timeout', null, { errorMessage: 'exceeded configured timeout' });
-                    writeRunMeta(meta);
-                    emitRoutineEnd(meta);
-                    if (!isCommandRun) {
-                        extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
-                        archiveRoutineTranscripts(meta, runDirPath);
-                    }
+                const ours = meta.pid ? isPidOurs(meta.pid, meta.spawnedAt) : false;
+                // Sync emit: an off-loop CLI process must flush the event before it exits.
+                reconcileRunningRecord(meta, jobRunsPath, runDirEntry.name, ours, emitRoutineEnd);
+            }
+            catch { /* corrupt or unreadable meta.json */ }
+        }
+    }
+}
+/**
+ * Async, non-blocking twin of {@link monitorRunningJobs} for the daemon's
+ * heartbeat tick (PHNX-3695). Identical reconciliation via
+ * {@link reconcileRunningRecord}, but the directory walk uses `fs/promises` and
+ * the pid-identity probe uses the deadline-bounded {@link isPidOursAsync}, so
+ * the every-tick scan never freezes the shared event loop — the freeze that
+ * left the browser IPC `version` probe unanswered.
+ */
+export async function reapExitedRunningJobs() {
+    const runsDir = getRunsDir();
+    let jobDirs;
+    try {
+        jobDirs = await fsp.readdir(runsDir, { withFileTypes: true });
+    }
+    catch {
+        return; // runs dir absent — nothing to reap
+    }
+    for (const jobDir of jobDirs) {
+        if (!jobDir.isDirectory())
+            continue;
+        const jobRunsPath = path.join(runsDir, jobDir.name);
+        let runDirs;
+        try {
+            runDirs = await fsp.readdir(jobRunsPath, { withFileTypes: true });
+        }
+        catch {
+            // A retention/cleanup pass may remove a job directory after the root
+            // snapshot. The next sweep observes the remaining state.
+            continue;
+        }
+        for (const runDirEntry of runDirs) {
+            if (!runDirEntry.isDirectory())
+                continue;
+            try {
+                const raw = await fsp.readFile(path.join(jobRunsPath, runDirEntry.name, 'meta.json'), 'utf-8');
+                const meta = JSON.parse(raw);
+                if (meta.status !== 'running')
                     continue;
-                }
-                if (!meta.pid)
+                // `host:`-placed run — read its remote `.exit` over ssh ASYNC so a slow
+                // host never freezes the tick's event loop (PHNX-3695).
+                if (meta.hostTaskId) {
+                    await finalizeHostRunAsync(meta);
                     continue;
-                if (!isPidOurs(meta.pid, meta.spawnedAt)) {
-                    if (isCommandRun) {
-                        // Command routines normally record their own terminal status via
-                        // child.on('exit') (so this record would already be non-'running' and
-                        // skipped above). Reaching here means the daemon restarted mid-run and
-                        // missed the exit event — recover the true code from the exit-code file
-                        // the child wrote; its absence means the child was killed/crashed.
-                        const ec = readCommandExitCode(runDirPath);
-                        finalizeRunMeta(meta, ec === 0 ? 'completed' : 'failed', ec);
-                    }
-                    else {
-                        const inferred = inferFinalStatusFromLog(stdoutPath, meta.agent);
-                        if (inferred) {
-                            finalizeRunMeta(meta, inferred.status, inferred.exitCode);
-                        }
-                        else {
-                            finalizeRunMeta(meta, 'failed', null, { errorMessage: 'process exited before final status could be inferred' });
-                        }
-                    }
-                    writeRunMeta(meta);
-                    emitRoutineEnd(meta);
-                    if (!isCommandRun) {
-                        extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
-                        archiveRoutineTranscripts(meta, runDirPath);
-                    }
                 }
+                const ours = meta.pid ? await isPidOursAsync(meta.pid, meta.spawnedAt) : false;
+                // Fire-and-forget async emit: the event-log lock must never block the
+                // daemon tick's shared event loop; the long-lived daemon still flushes it.
+                reconcileRunningRecord(meta, jobRunsPath, runDirEntry.name, ours, (m) => { void emitRoutineEndAsync(m); });
             }
             catch { /* corrupt or unreadable meta.json */ }
         }

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

@@ -16,7 +16,17 @@
  */
 import { BasePeriodicService } from './service.js';
 import { getDaemonDir } from '../state.js';
-import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+/** Async `existsSync` — never a synchronous stat on the daemon tick loop (PHNX-3695). */
+async function pathExists(p) {
+    try {
+        await fsp.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Matches the historical inline interval (daemon.ts SELF_HEAL_TICK_MS). Runs ~every 6h. */
 const SELF_HEAL_TICK_MS = 6 * 60 * 60_000;
 /** Hard cap per tick — a full resource repair sweep across every version home, short enough a hang never freezes the service for long relative to its 6h cadence. */
@@ -35,10 +45,10 @@ export class SelfHealService extends BasePeriodicService {
         // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
     }
     async onTick(ctx) {
-        if (!fs.existsSync(getDaemonDir()))
+        if (!(await pathExists(getDaemonDir())))
             return;
         const { runSelfHeal, selfHealChangedAnything, selfHealNeedsAttention, summarizeSelfHeal } = await import('../self-heal/registry.js');
-        if (!fs.existsSync(getDaemonDir()))
+        if (!(await pathExists(getDaemonDir())))
             return;
         const report = await runSelfHeal({ mode: 'safe' });
         if (selfHealChangedAnything(report) || selfHealNeedsAttention(report)) {

package/dist/lib/daemon/self-update-service.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 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, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+/**
+ * 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 declare const SELF_UPDATE_DEADLINE_MS: number;
+export interface SelfUpdateOutcome {
+    updated: boolean;
+    reason?: string;
+}
+interface NpmLatestMetadata {
+    version: string;
+    integrity: string;
+    tarball: string;
+}
+/**
+ * Dependency seam so `self-update-service.test.ts` can drive a REAL install
+ * against a fixture npm prefix/tarball without touching the real npm
+ * registry or the real running install. Production code always uses
+ * {@link defaultSelfUpdateDeps} (the default parameter below) — no test-only
+ * branch exists in the exported logic itself.
+ */
+export interface SelfUpdateDeps {
+    currentVersion(): string;
+    isDevBuild(): boolean;
+    detectShadow(): boolean;
+    packageRoot(): string;
+    fetchLatestMetadata(signal: AbortSignal): Promise<NpmLatestMetadata>;
+    installAndVerify(metadata: NpmLatestMetadata, packageRoot: string, signal: AbortSignal): Promise<void>;
+    syncSystemRepo(): Promise<void>;
+    syncLocal(): Promise<void>;
+}
+export declare function fetchLatestNpmMetadata(signal: AbortSignal): Promise<NpmLatestMetadata>;
+/**
+ * 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 declare function installAndVerifyDefault(metadata: NpmLatestMetadata, packageRoot: string, signal: AbortSignal): Promise<void>;
+export declare function defaultSelfUpdateDeps(): SelfUpdateDeps;
+/**
+ * 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 declare function attemptSelfUpdateAndExit(ctx: DaemonContext, signal: AbortSignal, deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
+/**
+ * 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 declare function scheduleSelfUpdateExit(): void;
+/**
+ * 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 declare function triggerSelfUpdateInBackground(ctx: DaemonContext, deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
+/**
+ * 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 declare function selfUpdateSyncDeclineReason(deps?: SelfUpdateDeps): string | null;
+export declare class SelfUpdateService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs: number;
+    readonly startupDelayMs: number;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext, signal: AbortSignal): Promise<void>;
+}
+export {};