@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/daemon/session-title-service.d.ts

@@ -1,24 +1,3 @@
-/**
- * Session-title service (PHNX-3797) — the ONE generator of session headlines.
- *
- * Every session row's headline used to be the agent's latest transcript line.
- * This service replaces it with a user-anchored NAME: it sweeps the local
- * session index for recent sessions whose title is still the raw first user
- * message, asks a {@link SessionTitleProvider} (the cloud cheap-model call by
- * default) for a short action+object headline, and persists it
- * (`lib/session/title.ts`). Because the value lands in the index, every consumer
- * — the CLI list, the picker, `sessions watch --json`, the fleet mirror, AGI EXT
- * — reads one title that was generated exactly once.
- *
- * Cost is bounded by construction, not by hope: at most
- * {@link SESSION_TITLE_MAX_PER_TICK} generations per tick, only for sessions
- * inside the display window, only for rows whose stored source key no longer
- * matches their user text (so a titled session is a pure DB read forever after),
- * and never for the titler's own spawned sessions. When the harness is missing
- * or signed out every attempt fails, so the service backs off exponentially
- * instead of respawning two processes a minute forever — the rows simply keep
- * showing the user's own words, which is the honest fallback.
- */
 import type { DaemonServiceId } from '../daemon-services.js';
 import { type SessionTitleRunner } from '../session/title.js';
 import { BasePeriodicService, type DaemonContext } from './service.js';
@@ -27,13 +6,9 @@ export declare class SessionTitleService extends BasePeriodicService {
     readonly id: DaemonServiceId;
     readonly intervalMs: number;
     readonly deadlineMs = 110000;
-    /** Let the box settle (shims, PATH, index warm) before spawning a harness. */
     readonly startupDelayMs = 60000;
-    /** Ticks still to skip before the next attempt; 0 = attempt this tick. */
     private skipTicks;
-    /** Skip count applied after the next all-failed sweep. */
     private backoff;
-    /** `run` is the model-call seam (defaults to the real subprocess); tests inject one. */
     constructor(run?: SessionTitleRunner | undefined);
     protected onStart(_ctx: DaemonContext): Promise<void>;
     protected onStop(): Promise<void>;

package/dist/lib/daemon/session-title-service.js

@@ -1,46 +1,17 @@
-/**
- * Session-title service (PHNX-3797) — the ONE generator of session headlines.
- *
- * Every session row's headline used to be the agent's latest transcript line.
- * This service replaces it with a user-anchored NAME: it sweeps the local
- * session index for recent sessions whose title is still the raw first user
- * message, asks a {@link SessionTitleProvider} (the cloud cheap-model call by
- * default) for a short action+object headline, and persists it
- * (`lib/session/title.ts`). Because the value lands in the index, every consumer
- * — the CLI list, the picker, `sessions watch --json`, the fleet mirror, AGI EXT
- * — reads one title that was generated exactly once.
- *
- * Cost is bounded by construction, not by hope: at most
- * {@link SESSION_TITLE_MAX_PER_TICK} generations per tick, only for sessions
- * inside the display window, only for rows whose stored source key no longer
- * matches their user text (so a titled session is a pure DB read forever after),
- * and never for the titler's own spawned sessions. When the harness is missing
- * or signed out every attempt fails, so the service backs off exponentially
- * instead of respawning two processes a minute forever — the rows simply keep
- * showing the user's own words, which is the honest fallback.
- */
 import { runSessionTitleTick, SESSION_TITLE_MAX_PER_TICK } from '../session/title.js';
 import { BasePeriodicService } from './service.js';
-/** Cadence of the sweep. Slow on purpose: a title is not a live signal. */
 const SESSION_TITLE_TICK_MS = 2 * 60_000;
-/** Above the worst case (limit x the per-generation subprocess timeout), below the interval. */
 const SESSION_TITLE_DEADLINE_MS = 110_000;
-/** Ticks skipped after the first all-failed sweep, doubling up to the ceiling. */
 const SESSION_TITLE_BACKOFF_START = 2;
-/** ~1h at the tick cadence — long enough that a signed-out box stays quiet. */
 const SESSION_TITLE_BACKOFF_MAX = 30;
 export class SessionTitleService extends BasePeriodicService {
     run;
     id = 'session-title';
     intervalMs = SESSION_TITLE_TICK_MS;
     deadlineMs = SESSION_TITLE_DEADLINE_MS;
-    /** Let the box settle (shims, PATH, index warm) before spawning a harness. */
     startupDelayMs = 60_000;
-    /** Ticks still to skip before the next attempt; 0 = attempt this tick. */
     skipTicks = 0;
-    /** Skip count applied after the next all-failed sweep. */
     backoff = 0;
-    /** `run` is the model-call seam (defaults to the real subprocess); tests inject one. */
     constructor(run) {
         super();
         this.run = run;
@@ -58,7 +29,6 @@ export class SessionTitleService extends BasePeriodicService {
             ...(this.run ? { run: this.run } : {}),
         });
         if (result.generated > 0) {
-            // A success clears the backoff: whatever was broken is working again.
             this.backoff = 0;
             ctx.log('INFO', `session-title: generated ${result.generated} title(s) (${result.cached} already current)`);
             return;
@@ -70,7 +40,5 @@ export class SessionTitleService extends BasePeriodicService {
             this.skipTicks = this.backoff;
             ctx.log('WARN', `session-title: ${result.failed} generation(s) produced no title; backing off ${this.backoff} tick(s)`);
         }
-        // Nothing generated and nothing failed = every recent session is titled.
-        // That is the steady state, and it logs nothing.
     }
 }

package/dist/lib/daemon/state-dir-check-service.d.ts

@@ -1,27 +1,3 @@
-/**
- * State-dir self-terminate guard as a `PeriodicService` (RUSH-3193 P3).
- *
- * RUSH-2367: self-terminate if this daemon's own state directory has been
- * removed out from under it — the shape of a leaked test-fixture daemon whose
- * /tmp HOME was deleted by its test's own cleanup while the process itself
- * somehow survived. Nothing else can reach a daemon in that state: a
- * different HOME resolves a different `ensureDaemonDir()` and therefore a
- * different instance registry — without this it runs forever. Reads the
- * lifetime marker directly, never the local `ensureDaemonDir()` wrapper,
- * which recreates the directory as a side effect and would defeat the check.
- * Heartbeat/status paths may recreate the directory and pid file after a
- * deletion; they never recreate this per-lifetime token.
- *
- * `lifetimePath`/`lifetimeToken` are per-boot constants computed once at
- * `runDaemon()` start and passed in via the constructor, along with the
- * shutdown callback. Registering (and starting) this service happens AFTER
- * `runDaemon()` defines its `handleShutdown` — unlike the other four migrated
- * services, which register before `supervisor.startAll()` — because the
- * supervisor fires an immediate first tick on start, and calling an
- * as-yet-undefined `handleShutdown` const at that point would throw. See the
- * registration site in daemon.ts for the deferred `supervisor.register()` +
- * `supervisor.start()` pairing this requires.
- */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
 interface StateDirCheckServiceOptions {

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

@@ -1,32 +1,6 @@
-/**
- * State-dir self-terminate guard as a `PeriodicService` (RUSH-3193 P3).
- *
- * RUSH-2367: self-terminate if this daemon's own state directory has been
- * removed out from under it — the shape of a leaked test-fixture daemon whose
- * /tmp HOME was deleted by its test's own cleanup while the process itself
- * somehow survived. Nothing else can reach a daemon in that state: a
- * different HOME resolves a different `ensureDaemonDir()` and therefore a
- * different instance registry — without this it runs forever. Reads the
- * lifetime marker directly, never the local `ensureDaemonDir()` wrapper,
- * which recreates the directory as a side effect and would defeat the check.
- * Heartbeat/status paths may recreate the directory and pid file after a
- * deletion; they never recreate this per-lifetime token.
- *
- * `lifetimePath`/`lifetimeToken` are per-boot constants computed once at
- * `runDaemon()` start and passed in via the constructor, along with the
- * shutdown callback. Registering (and starting) this service happens AFTER
- * `runDaemon()` defines its `handleShutdown` — unlike the other four migrated
- * services, which register before `supervisor.startAll()` — because the
- * supervisor fires an immediate first tick on start, and calling an
- * as-yet-undefined `handleShutdown` const at that point would throw. See the
- * registration site in daemon.ts for the deferred `supervisor.register()` +
- * `supervisor.start()` pairing this requires.
- */
 import { BasePeriodicService } from './service.js';
 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 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';
@@ -42,10 +16,8 @@ export class StateDirCheckService extends BasePeriodicService {
         this.onMissing = opts.onMissing;
     }
     async onStart(_ctx) {
-        // No connections/handles to open — each tick re-reads the lifetime marker.
     }
     async onStop() {
-        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
     }
     async onTick(ctx) {
         let markerMatches = false;
@@ -53,7 +25,6 @@ export class StateDirCheckService extends BasePeriodicService {
             markerMatches = (await fsp.readFile(this.lifetimePath, 'utf-8')) === this.lifetimeToken;
         }
         catch {
-            // A missing state dir or marker is the condition this guard detects.
         }
         if (!markerMatches) {
             ctx.log('WARN', `Daemon state dir no longer exists; exiting (self-terminate guard)`);

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

@@ -1,56 +1,10 @@
-/**
- * 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, 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 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.
- *
- * 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 {
-    /**
-     * 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 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. */
     enabled?: boolean;
 }
 export declare class ServiceSupervisor {
@@ -59,91 +13,25 @@ export declare class ServiceSupervisor {
     private readonly lifecycleDeadlineMs;
     private readonly exit;
     constructor(opts?: ServiceSupervisorOptions);
-    /**
-     * Race `op` against a deadline. On breach the returned promise rejects with a
-     * labelled error while the real `op` is left to settle in the background —
-     * used to bound the lifecycle calls (`start`/`stop`/`restart`) so a wedged one
-     * cannot stall startup or shutdown. `Promise.race` cannot cancel `op`; the
-     * caller decides what a breach means for that service.
-     */
     private withDeadline;
-    /**
-     * Register a service. Must be called before `startAll()`.
-     *
-     * Accepts both `PeriodicService` (ticked on a fixed interval) and
-     * lifecycle-only `DaemonService` (started once, stopped at shutdown). The
-     * supervisor uses `isPeriodicService()` to decide whether to schedule a timer
-     * for each registered entry.
-     */
     register(service: DaemonService, options?: RegisterServiceOptions): void;
-    /**
-     * Flip a tick's in-flight guard off and release every `awaitIdle()` waiter in
-     * the same synchronous step, so no waiter's continuation can run while
-     * `inFlight` is still true (PHNX-3608).
-     */
     private clearInFlight;
-    /** Start every registered service and begin ticking each on its own timer. */
     startAll(ctx: DaemonContext): Promise<void>;
-    /** Stop every registered service and clear all timers. */
     stopAll(): Promise<void>;
-    /**
-     * 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;
-    /** Every currently registered service id. */
     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.
-     */
     awaitIdle(id: DaemonServiceId): Promise<void>;
-    /**
-     * Start one registered service live — drives `agents daemon services enable
-     * <id>` (RUSH-3193 P4). Only affects a service already registered on this
-     * supervisor. Callers that need live enable from a boot-disabled state must
-     * register the service with `{ enabled: false }`, which gives the supervisor
-     * ownership without running its startup side effects.
-     */
     start(id: DaemonServiceId): Promise<void>;
-    /** Stop one registered service live — drives `agents daemon services disable <id>` (RUSH-3193 P4). */
     stop(id: DaemonServiceId): Promise<void>;
-    /** Request an immediate supervised tick, used by event edges that cannot wait for the regular cadence. */
     runNow(id: DaemonServiceId): void;
-    /** Health for every registered service, keyed by service id. */
     health(): Record<string, ServiceHealth>;
     private startOne;
     private stopOne;
     private scheduleTimer;
-    /**
-     * 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 recordFailure;
-    /**
-     * 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 {};

package/dist/lib/daemon/supervisor.js

@@ -1,43 +1,5 @@
-/**
- * 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, 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 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.
- *
- * 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 { recordSubsystemOk, recordSubsystemError, recordSubsystemState, recordDaemonRestart } from '../daemon-health.js';
 import { isPeriodicService } from './service.js';
-/**
- * Exit code the supervisor uses when a deadline breach hands the daemon back to
- * its OS supervisor for a restart. 70 (`EX_SOFTWARE`) marks an internal software
- * fault, distinct from a clean shutdown (0) or a config error.
- */
 const DEADLINE_EXIT_CODE = 70;
 const DEFAULT_LIFECYCLE_DEADLINE_MS = 30_000;
 export class ServiceSupervisor {
@@ -49,13 +11,6 @@ export class ServiceSupervisor {
         this.lifecycleDeadlineMs = opts.lifecycleDeadlineMs ?? DEFAULT_LIFECYCLE_DEADLINE_MS;
         this.exit = opts.exit ?? ((code) => process.exit(code));
     }
-    /**
-     * Race `op` against a deadline. On breach the returned promise rejects with a
-     * labelled error while the real `op` is left to settle in the background —
-     * used to bound the lifecycle calls (`start`/`stop`/`restart`) so a wedged one
-     * cannot stall startup or shutdown. `Promise.race` cannot cancel `op`; the
-     * caller decides what a breach means for that service.
-     */
     async withDeadline(op, ms, label) {
         let timer;
         const deadline = new Promise((_, reject) => {
@@ -69,14 +24,6 @@ export class ServiceSupervisor {
                 clearTimeout(timer);
         }
     }
-    /**
-     * Register a service. Must be called before `startAll()`.
-     *
-     * Accepts both `PeriodicService` (ticked on a fixed interval) and
-     * lifecycle-only `DaemonService` (started once, stopped at shutdown). The
-     * supervisor uses `isPeriodicService()` to decide whether to schedule a timer
-     * for each registered entry.
-     */
     register(service, options = {}) {
         if (this.registry.has(service.id))
             throw new Error(`service '${service.id}' is already registered`);
@@ -90,11 +37,7 @@ export class ServiceSupervisor {
             idleWaiters: [],
         });
     }
-    /**
-     * Flip a tick's in-flight guard off and release every `awaitIdle()` waiter in
-     * the same synchronous step, so no waiter's continuation can run while
-     * `inFlight` is still true (PHNX-3608).
-     */
+    // Resolve idle waiters in the same step that clears inFlight, so reload cannot race the active tick.
     clearInFlight(entry) {
         entry.inFlight = false;
         const waiters = entry.idleWaiters;
@@ -102,7 +45,6 @@ export class ServiceSupervisor {
         for (const resolve of waiters)
             resolve();
     }
-    /** Start every registered service and begin ticking each on its own timer. */
     async startAll(ctx) {
         this.ctx = ctx;
         for (const [id, entry] of this.registry) {
@@ -111,16 +53,10 @@ export class ServiceSupervisor {
             await this.startOne(id);
         }
     }
-    /** Stop every registered service and clear all timers. */
     async stopAll() {
         for (const id of this.registry.keys())
             await this.stopOne(id, true);
     }
-    /**
-     * 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).
-     */
     async restartOne(id) {
         const entry = this.registry.get(id);
         if (!entry)
@@ -131,39 +67,20 @@ export class ServiceSupervisor {
         await this.stopOne(id, false);
         await this.startOne(id);
     }
-    /** Whether `id` has a lifecycle owner on this supervisor, running or stopped. */
     isRegistered(id) {
         return this.registry.has(id);
     }
-    /** Every currently registered service id. */
     registeredIds() {
         return Array.from(this.registry.keys());
     }
-    /**
-     * Resolve when the service's current tick has really settled. Daemon control
-     * edges use this to queue a requested live transition without polling.
-     */
     async awaitIdle(id) {
         const entry = this.registry.get(id);
         if (!entry)
             throw new Error(`service '${id}' is not registered`);
-        // Resolve from clearInFlight (which also flips `inFlight` false) rather than
-        // from the tick promise directly: awaiting the tick promise resumed this
-        // caller on a shorter microtask chain than the tick's own finally, so a
-        // queued `.then(stop)` could run before `inFlight` was cleared and `stop()`
-        // would throw "cannot stop while a tick is still in flight" (PHNX-3608 — the
-        // SIGHUP live-disable regression). Waiting on the guard makes it deterministic.
         if (!entry.inFlight)
             return;
         await new Promise((resolve) => { entry.idleWaiters.push(resolve); });
     }
-    /**
-     * Start one registered service live — drives `agents daemon services enable
-     * <id>` (RUSH-3193 P4). Only affects a service already registered on this
-     * supervisor. Callers that need live enable from a boot-disabled state must
-     * register the service with `{ enabled: false }`, which gives the supervisor
-     * ownership without running its startup side effects.
-     */
     async start(id) {
         const entry = this.registry.get(id);
         if (!entry)
@@ -175,7 +92,6 @@ export class ServiceSupervisor {
         }
         await this.startOne(id);
     }
-    /** Stop one registered service live — drives `agents daemon services disable <id>` (RUSH-3193 P4). */
     async stop(id) {
         const entry = this.registry.get(id);
         if (!entry)
@@ -184,13 +100,11 @@ export class ServiceSupervisor {
             return;
         await this.stopOne(id, false);
     }
-    /** Request an immediate supervised tick, used by event edges that cannot wait for the regular cadence. */
     runNow(id) {
         if (!this.registry.has(id))
             throw new Error(`service '${id}' is not registered`);
         void this.runTick(id);
     }
-    /** Health for every registered service, keyed by service id. */
     health() {
         const out = {};
         for (const [id, entry] of this.registry) {
@@ -212,9 +126,6 @@ export class ServiceSupervisor {
             await this.withDeadline(() => entry.service.start(ctx), this.lifecycleDeadlineMs, `service '${id}' start`);
         }
         catch (err) {
-            // A thrown OR wedged start()/restart() cannot leave the service silently
-            // dark, and there is no `parked` state to fall back to (PHNX-4116): record
-            // the cause and exit so systemd/launchd restart the whole daemon and retry.
             this.exitForRestart(id, err);
             return;
         }
@@ -224,9 +135,6 @@ export class ServiceSupervisor {
         if (isPeriodicService(entry.service)) {
             const startupDelayMs = entry.service.startupDelayMs ?? 0;
             if (startupDelayMs > 0) {
-                // Defer BOTH the first tick and the recurring interval's start until the
-                // delay elapses — starting the interval at t=0 would fire its own ticks
-                // on top of the staggered one instead of after it.
                 entry.startupTimer = setTimeout(() => {
                     entry.startupTimer = undefined;
                     this.scheduleTimer(id);
@@ -239,11 +147,11 @@ export class ServiceSupervisor {
             }
         }
         else {
-            // Lifecycle-only service: record health once on successful start (no ticks).
             entry.lastRunMs = Date.now();
             recordSubsystemOk(id);
         }
     }
+    // Clear deadline timers before abort: a hung tick must not turn deliberate shutdown into an OS restart.
     async stopOne(id, force) {
         const entry = this.registry.get(id);
         if (!entry)
@@ -259,25 +167,14 @@ export class ServiceSupervisor {
             clearTimeout(entry.startupTimer);
             entry.startupTimer = undefined;
         }
-        // Cancel the in-flight tick's deadline timer too — leaving it armed lets it
-        // fire `exitForRestart` mid-shutdown if the hung tick ignores the abort
-        // below (PHNX-4116). The `state === 'stopped'` guard in `runTick` is the
-        // belt to this braces.
         if (entry.deadlineTimer) {
             clearTimeout(entry.deadlineTimer);
             entry.deadlineTimer = undefined;
         }
         entry.state = 'stopped';
         recordSubsystemState(id, 'stopped');
-        // Signal any in-flight tick to unwind — a cooperating tick threads this into
-        // its I/O and returns promptly at shutdown instead of blocking on it.
         entry.activeController?.abort();
-        // Whole-daemon shutdown must not hang forever on an unresolved tick, but it
-        // also must not tear down resources the tick may still be using. Stop its
-        // timers and mark it stopped; process exit owns final cleanup in this case.
         if (entry.inFlight && force) {
-            // Release any awaitIdle waiter — the service is stopping, so no one should
-            // keep waiting on a tick that will now be abandoned at process exit.
             const waiters = entry.idleWaiters;
             entry.idleWaiters = [];
             for (const resolve of waiters)
@@ -285,9 +182,8 @@ export class ServiceSupervisor {
             return;
         }
         if (!entry.everStarted)
-            return; // start() never succeeded — nothing to stop.
+            return;
         try {
-            // A wedged stop() must not stall stopAll() at shutdown (PHNX-3608).
             await this.withDeadline(() => entry.service.stop(), this.lifecycleDeadlineMs, `service '${id}' stop`);
         }
         catch (err) {
@@ -300,25 +196,12 @@ export class ServiceSupervisor {
             return;
         entry.timer = setInterval(() => { void this.runTick(id); }, entry.service.intervalMs);
     }
-    /**
-     * 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.
-     */
+    // Thrown ticks retry; a deadline may never settle, so record it durably and exit 70 for supervised restart instead of parking.
     async runTick(id) {
         const entry = this.registry.get(id);
         const ctx = this.ctx;
         if (!entry || !ctx || entry.state !== 'running' || entry.inFlight)
             return;
-        // runTick is only called for periodic services (from scheduleTimer and startOne).
-        // The isPeriodicService guard here keeps TypeScript narrowing correct.
         if (!isPeriodicService(entry.service))
             return;
         const periodicService = entry.service;
@@ -342,27 +225,12 @@ export class ServiceSupervisor {
             recordSubsystemOk(id);
         }
         catch (err) {
-            // A stopped service must never exit the process: `stopOne` may have
-            // force-stopped this tick (aborting its signal) while the deadline timer
-            // was still armed, and a hang that ignored the abort would otherwise let
-            // that timer fire `exitForRestart` mid-shutdown — wrong exit code, a
-            // spurious restart-ledger entry, and `handleShutdown` cleanup skipped
-            // (PHNX-4116). This is the belt to `stopOne`'s clearTimeout braces. Read
-            // the state fresh: `stopOne` mutated it across the `await` above, past the
-            // narrowing the top-of-function `state !== 'running'` guard applied.
             const stoppedDuringTick = this.registry.get(id)?.state === 'stopped';
             if (timedOut && !stoppedDuringTick) {
-                // Abort the runaway tick's signal so a cooperating tick can unwind, then
-                // hand the daemon back to its OS supervisor: a hang has no in-process
-                // recovery (PHNX-4116). `exitForRestart` calls `process.exit`, so nothing
-                // below runs in production; the injected test exit returns, and the
-                // `finally` still releases the in-flight guard.
                 controller.abort();
                 this.exitForRestart(id, err);
                 return;
             }
-            // A throw is recoverable — record it and keep ticking on the next interval.
-            // A deadline breach of an already-stopped service is intentionally dropped.
             if (!timedOut)
                 this.recordFailure(entry, id, err);
         }
@@ -383,16 +251,6 @@ export class ServiceSupervisor {
         recordSubsystemError(id, message);
         this.ctx?.log('WARN', `service '${id}' failed: ${message}`);
     }
-    /**
-     * 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.
-     */
     exitForRestart(id, err) {
         const cause = err instanceof Error ? err.message : String(err);
         const entry = this.registry.get(id);
@@ -406,7 +264,6 @@ export class ServiceSupervisor {
         this.freezeTimers();
         this.exit(DEADLINE_EXIT_CODE);
     }
-    /** Clear every service's interval / startup timer — the process is exiting. */
     freezeTimers() {
         for (const entry of this.registry.values()) {
             if (entry.timer) {

package/dist/lib/daemon/testdata/process-view-daemon.js

@@ -1,5 +1,3 @@
-// Runs the production daemon entrypoint against an isolated HOME. No installed
-// CLI, service manager, scheduler, or production socket participates.
 import { runDaemon, startDaemon } from '../daemon.js';
 if (process.argv[2] === '__start-daemon') {
     try {