@phnx-labs/agents-cli 1.22.117 → 1.22.118

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

@@ -19,12 +19,12 @@
  * 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.
+ * then boots the new code. Clients do not need to be told anything: a socket
+ * client re-probes and reconnects when the daemon relaunches, 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
@@ -93,41 +93,42 @@ export interface SelfUpdateDeps {
 export declare function installAndVerifyDefault(metadata: NpmLatestMetadata, packageRoot: string, signal: AbortSignal): Promise<void>;
 /**
  * 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.
+ * ({@link SelfUpdateService.onTick}) and the on-demand trigger
+ * ({@link triggerSelfUpdateInBackground}) — one implementation, so a
+ * version-skew "update now" caller 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; an on-demand caller that must
+ * respond to a client BEFORE exiting delays via {@link scheduleSelfUpdateExit}).
+ * 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.
+ * `inFlightAttempt` promise. The periodic tick and an on-demand caller can both
+ * be awaiting that SAME promise — if the tick's continuation ran an immediate
+ * `process.exit(0)` while an on-demand caller's continuation had not yet flushed
+ * its response to a client, 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.
  */
 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.
+ * Fire an on-demand self-update in the BACKGROUND and return its (bounded)
+ * promise WITHOUT the caller having to await it — the reusable primitive for a
+ * "update now" trigger that must respond to a client before the daemon exits.
+ * Awaiting the full check→download→install→verify inline would park the caller
+ * for tens of seconds (worst case ~15 min), the client-stall PHNX-3605 was
+ * written to prevent; instead a trigger 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 client reconnects.
+ *
+ * (Its one former production caller was the `request-self-update` verb on the
+ * daemon's browser IPC socket, removed with the standalone `browser` CLI in
+ * PHNX-4101. The primitive stays — tested and reusable — for a future on-demand
+ * trigger; the periodic tick does not use it, exiting inline instead.)
  *
  * The work still shares the module-level {@link attemptSelfUpdateAndExit}
  * `inFlightAttempt` guard, so a concurrent trigger (or the periodic tick) can't
@@ -138,7 +139,7 @@ export declare function scheduleSelfUpdateExit(): void;
  * `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
+ * promise once `updated` is true, so the exit still fires after the caller's
  * response has flushed.
  */
 export declare function triggerSelfUpdateInBackground(ctx: DaemonContext, deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;

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

@@ -19,12 +19,12 @@
  * 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.
+ * then boots the new code. Clients do not need to be told anything: a socket
+ * client re-probes and reconnects when the daemon relaunches, 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
@@ -51,10 +51,13 @@ 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
+ * stated budget and is short relative to the ~75min cadence. Exported so an
+ * on-demand self-update trigger ({@link triggerSelfUpdateInBackground}) 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.
+ * (Its former transport, the `request-self-update` verb on the daemon's browser
+ * IPC socket, left with the standalone `browser` CLI in PHNX-4101; the mechanism
+ * stays for a future on-demand caller.)
  */
 const SELF_UPDATE_DEADLINE_MS = 15 * 60_000;
 /**
@@ -193,14 +196,14 @@ function defaultSelfUpdateDeps() {
 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.
+ * ({@link SelfUpdateService.onTick}) and the on-demand trigger
+ * ({@link triggerSelfUpdateInBackground}) — one implementation, so a
+ * version-skew "update now" caller 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; an on-demand caller that must
+ * respond to a client BEFORE exiting delays via {@link scheduleSelfUpdateExit}).
+ * Concurrent callers share one in-flight attempt rather than racing separate
+ * installs.
  */
 export async function attemptSelfUpdateAndExit(ctx, signal, deps = defaultSelfUpdateDeps()) {
     if (inFlightAttempt)
@@ -292,14 +295,13 @@ 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.
+ * `inFlightAttempt` promise. The periodic tick and an on-demand caller can both
+ * be awaiting that SAME promise — if the tick's continuation ran an immediate
+ * `process.exit(0)` while an on-demand caller's continuation had not yet flushed
+ * its response to a client, 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.
  */
 export function scheduleSelfUpdateExit() {
     if (exitScheduled)
@@ -308,17 +310,19 @@ export function scheduleSelfUpdateExit() {
     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.
+ * Fire an on-demand self-update in the BACKGROUND and return its (bounded)
+ * promise WITHOUT the caller having to await it — the reusable primitive for a
+ * "update now" trigger that must respond to a client before the daemon exits.
+ * Awaiting the full check→download→install→verify inline would park the caller
+ * for tens of seconds (worst case ~15 min), the client-stall PHNX-3605 was
+ * written to prevent; instead a trigger 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 client reconnects.
+ *
+ * (Its one former production caller was the `request-self-update` verb on the
+ * daemon's browser IPC socket, removed with the standalone `browser` CLI in
+ * PHNX-4101. The primitive stays — tested and reusable — for a future on-demand
+ * trigger; the periodic tick does not use it, exiting inline instead.)
  *
  * The work still shares the module-level {@link attemptSelfUpdateAndExit}
  * `inFlightAttempt` guard, so a concurrent trigger (or the periodic tick) can't
@@ -329,7 +333,7 @@ export function scheduleSelfUpdateExit() {
  * `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
+ * promise once `updated` is true, so the exit still fires after the caller's
  * response has flushed.
  */
 export function triggerSelfUpdateInBackground(ctx, deps = defaultSelfUpdateDeps()) {

package/dist/lib/daemon/service.d.ts

@@ -14,8 +14,12 @@
  * know it is being supervised.
  */
 import type { DaemonServiceId } from '../daemon-services.js';
-/** Lifecycle state a supervised service can be in. */
-export type ServiceState = 'idle' | 'running' | 'parked' | 'stopped';
+/**
+ * Lifecycle state a supervised service can be in. There is no `parked` state:
+ * a throw keeps the service `running` (it retries on the next tick) and a
+ * deadline breach exits the whole daemon for a supervised OS restart (PHNX-4116).
+ */
+export type ServiceState = 'idle' | 'running' | 'stopped';
 /** A service's most recently observed health, as reported by the supervisor. */
 export interface ServiceHealth {
     state: ServiceState;
@@ -42,12 +46,12 @@ export interface DaemonService {
 export interface PeriodicService extends DaemonService {
     readonly intervalMs: number;
     /**
-     * Hard cap per tick. An over-budget tick is ABANDONED: the supervisor aborts
-     * the tick's {@link AbortSignal}, parks the service, and schedules a backoff
-     * restart immediately — it does NOT wait for the real promise to settle
-     * (PHNX-3608). A tick that awaits `signal` (or forwards it to its I/O) can
-     * observe the deadline and unwind; one that ignores it is left to drain in the
-     * background while the service is already being restarted.
+     * Hard cap per tick. An over-budget tick is a HANG that cannot be retried
+     * in-process (its promise may never settle), so the supervisor aborts the
+     * tick's {@link AbortSignal} and EXITS the daemon (code 70) for a supervised
+     * systemd/launchd restart (PHNX-4116) — there is no park or in-process backoff.
+     * A tick that awaits `signal` (or forwards it to its I/O) can observe the
+     * deadline and unwind cleanly before the process exits.
      */
     readonly deadlineMs: number;
     /**

package/dist/lib/daemon/supervisor.d.ts

@@ -1,52 +1,53 @@
 /**
- * ServiceSupervisor (RUSH-3193 P1).
+ * ServiceSupervisor (RUSH-3193 P1, PHNX-4116).
  *
  * Owns the timer for every registered `PeriodicService`, replacing the bare
- * `setInterval` closures in `runDaemon()`. Two failure modes motivated it,
- * both observed in production:
+ * `setInterval` closures in `runDaemon()`. Two failure modes motivated it, both
+ * observed in production, and each is now handled without ever leaving a service
+ * silently dark:
  *
  *  - A throw escaping a tick's local try/catch used to hit the process-wide
- *    `uncaughtException` handler and `process.exit(1)` the whole daemon,
- *    taking every OTHER service down with it. Here, a tick failure is caught
- *    per-service and never propagates past `runTick`.
- *  - A tick that hangs on an unbounded await (SSH, keychain) used to latch its
- *    local in-flight guard `true` forever, silently freezing that one service
- *    for the daemon's life (observed ~51h). Here, every tick races a
- *    `deadlineMs` timeout; when the deadline wins, the service is ABANDONED
- *    (PHNX-3608): its `AbortSignal` is aborted so a cooperating tick can unwind
- *    its own I/O, the in-flight guard is released immediately, and the backoff
- *    restart is scheduled right away — it is NOT gated on the runaway promise
- *    settling. An earlier revision kept the guard held until the real promise
- *    settled, which meant a tick that never settles parked the service forever
- *    and blocked backoff restart, `daemon services restart`, and SIGHUP reload —
- *    the exact 12h-usage-dark class this exists to prevent. The orphaned promise
- *    is drained separately in the background; `finishTick` is version-guarded so
- *    its late settlement can never disturb the fresh tick the restart started.
+ *    `uncaughtException` handler and `process.exit(1)` the whole daemon, taking
+ *    every OTHER service down with it. Here a thrown tick is caught per-service,
+ *    recorded via `recordFailure`, and the service keeps ticking on its own
+ *    interval — a throw is recoverable, so it is retried in place on the next
+ *    tick and no sibling is disturbed.
+ *  - A tick that HANGS on an unbounded await (SSH, keychain) used to latch its
+ *    in-flight guard `true` forever, silently freezing that one service for the
+ *    daemon's life (observed ~51h). A hang cannot be retried in-process — the
+ *    promise may never settle — so when a tick (or a `start()`/`restart()`
+ *    lifecycle call) BREACHES its deadline the supervisor records the cause,
+ *    flushes it to disk, and EXITS the process (code 70). systemd
+ *    (`Restart=always`, `RestartSec=30`, `StartLimitIntervalSec=0`) and launchd
+ *    (`KeepAlive` + `ThrottleInterval=30`) restart the daemon within ~30s and the
+ *    wedged service comes back healthy with it.
  *
- * Repeated failures (thrown or timed-out) open a circuit breaker: the service
- * is parked (its timer stopped) and retried on exponential backoff via its own
- * `restart()`, while every sibling service keeps ticking on its own timer,
- * unaffected. `start()`/`stop()`/`restart()` are themselves bounded by
- * {@link ServiceSupervisorOptions.lifecycleDeadlineMs} so a wedged bind or close
- * cannot stall daemon startup or shutdown.
+ * This is the PHNX-4116 model: there is NO `parked` state and NO in-process
+ * backoff restart. A supervised service is `idle` before start, `running` while
+ * ticking, or `stopped` after a live disable / shutdown — a hang is not a fourth
+ * state to sit in, it is a reason to hand the daemon back to its OS supervisor,
+ * which is what actually "just works" like systemd/launchd. `start()`/`stop()`/
+ * `restart()` stay bounded by {@link ServiceSupervisorOptions.lifecycleDeadlineMs}
+ * so a wedged bind or close cannot stall daemon startup or shutdown; a start /
+ * restart lifecycle breach exits the same way a tick breach does.
  */
 import type { DaemonServiceId } from '../daemon-services.js';
 import type { DaemonContext, DaemonService, ServiceHealth } from './service.js';
 interface ServiceSupervisorOptions {
-    /** Consecutive thrown tick failures before a service is parked. Deadline breaches park immediately. Default 3. */
-    parkAfterFailures?: number;
-    /** First restart backoff delay, doubled on each further failed restart attempt. Default 5s. */
-    backoffBaseMs?: number;
-    /** Backoff ceiling. Default 5 minutes. */
-    backoffMaxMs?: number;
     /**
      * Hard cap on a service's `start()`/`stop()`/`restart()` call (PHNX-3608). A
      * wedged bind/close would otherwise stall `startAll()` (which awaits each
-     * `startOne` in turn) or `stopAll()` at shutdown. A start/restart that
-     * breaches it is treated as a failure (parked + backoff); a stop that breaches
-     * it is logged and the service is left marked stopped. Default 30s.
+     * `startOne` in turn) or `stopAll()` at shutdown. A start/restart that breaches
+     * it exits the process for a supervised restart (PHNX-4116); a stop that
+     * breaches it is logged and the service is left marked stopped. Default 30s.
      */
     lifecycleDeadlineMs?: number;
+    /**
+     * How the supervisor ends the process on a deadline breach. Defaults to
+     * `process.exit`; injected in tests so a breach is observable without actually
+     * exiting the test runner (PHNX-4116).
+     */
+    exit?: (code: number) => never;
 }
 interface RegisterServiceOptions {
     /** Register the lifecycle owner but leave it stopped until a live enable. */
@@ -55,10 +56,8 @@ interface RegisterServiceOptions {
 export declare class ServiceSupervisor {
     private readonly registry;
     private ctx;
-    private readonly parkAfterFailures;
-    private readonly backoffBaseMs;
-    private readonly backoffMaxMs;
     private readonly lifecycleDeadlineMs;
+    private readonly exit;
     constructor(opts?: ServiceSupervisorOptions);
     /**
      * Race `op` against a deadline. On breach the returned promise rejects with a
@@ -87,7 +86,11 @@ export declare class ServiceSupervisor {
     startAll(ctx: DaemonContext): Promise<void>;
     /** Stop every registered service and clear all timers. */
     stopAll(): Promise<void>;
-    /** Force one service to restart right now, outside its normal backoff schedule. Drives `agents daemon services restart <id>` (RUSH-3193 P4). */
+    /**
+     * Force one service to restart right now — drives `agents daemon services
+     * restart <id>` (RUSH-3193 P4). A plain stop + start, with no intermediate
+     * `parked` state (PHNX-4116).
+     */
     restartOne(id: DaemonServiceId): Promise<void>;
     /** Whether `id` has a lifecycle owner on this supervisor, running or stopped. */
     isRegistered(id: DaemonServiceId): boolean;
@@ -95,8 +98,7 @@ export declare class ServiceSupervisor {
     registeredIds(): DaemonServiceId[];
     /**
      * Resolve when the service's current tick has really settled. Daemon control
-     * edges use this to queue a requested live transition without polling or
-     * treating a deadline race as cancellation.
+     * edges use this to queue a requested live transition without polling.
      */
     awaitIdle(id: DaemonServiceId): Promise<void>;
     /**
@@ -117,22 +119,31 @@ export declare class ServiceSupervisor {
     private stopOne;
     private scheduleTimer;
     /**
-     * Run one tick under a hard deadline (PHNX-3608). The tick receives an
-     * `AbortSignal` that is aborted when the deadline elapses, so a cooperating
-     * tick can bound its own I/O and unwind. The deadline itself is still enforced
-     * with `Promise.race` — JS cannot forcibly cancel an arbitrary await — but on
-     * a breach the service is ABANDONED, not parked-and-held: the in-flight guard
-     * is released immediately and the backoff restart is scheduled right away
-     * (via `park()`), so a tick that never settles can no longer wedge backoff,
-     * `daemon services restart`, or SIGHUP reload. The runaway promise drains in
-     * the background; `finishTick` is version-guarded on `activeTick`, so its late
-     * settlement can never disturb the fresh tick a restart has since started.
+     * Run one tick under a hard deadline (PHNX-3608, PHNX-4116). The tick receives
+     * an `AbortSignal` that is aborted when the deadline elapses, so a cooperating
+     * tick can bound its own I/O and unwind. The deadline itself is enforced with
+     * `Promise.race` — JS cannot forcibly cancel an arbitrary await.
+     *
+     * A tick that THROWS is recoverable: it is recorded and the interval keeps
+     * firing, so the service retries on its next tick. A tick that BREACHES its
+     * deadline is a hang that can never be retried in-process (the promise may
+     * never settle), so the supervisor exits the process (`exitForRestart`) and
+     * lets systemd/launchd restart the whole daemon.
      */
     private runTick;
-    private park;
-    private scheduleRestart;
-    private attemptRestart;
     private recordFailure;
-    private finishTick;
+    /**
+     * Record a deadline breach durably and exit the process so systemd/launchd
+     * restart the whole daemon (PHNX-4116). `recordSubsystemError` writes
+     * `health.json` synchronously (atomic write under a file lock), so the cause is
+     * on disk before we exit; `recordDaemonRestart` appends to the restart ledger
+     * `agents daemon status` reads for "restarts in the last 24h". Every timer is
+     * frozen first so no further tick fires between this decision and process death
+     * — and so an injected test `exit` (which does not actually exit) still observes
+     * exactly one call.
+     */
+    private exitForRestart;
+    /** Clear every service's interval / startup timer — the process is exiting. */
+    private freezeTimers;
 }
 export {};