@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/daemon/daemon.js

@@ -1,12 +1,4 @@
 import { daemonProcessViewAllowed, recordDaemonProcessView } from '../session/process-view.js';
-/**
- * Daemon lifecycle management for the routines scheduler.
- *
- * The daemon is a long-running process that holds a JobScheduler and
- * triggers jobs on their cron schedules. It can be managed via launchd
- * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
- * log output, reload (SIGHUP), and graceful shutdown are handled here.
- */
 import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -17,7 +9,6 @@ import { isAlive, killTree, backgroundSpawnOptions, waitForExit } from '../platf
 import { listJobs as listAllJobs } from '../scheduling/routines.js';
 import { syncAllProjectRoutines } from '../routines-project.js';
 import { JobScheduler } from '../scheduler.js';
-// MonitorEngine is now owned by MonitorEngineService (daemon/monitor-engine-service.ts).
 import { executeJobDetached, listLiveRoutineChildren } from './runner.js';
 import { detectOverdueJobs, notifyOverdue } from '../overdue.js';
 import { runCatchup } from '../catchup.js';
@@ -32,18 +23,7 @@ import { ServiceSupervisor } from './supervisor.js';
 import { emit, emitAsync, emitRoutineEnd } from '../feed/events.js';
 import { readDaemonServicesConfig, drainDaemonServiceRestartQueue } from '../daemon-services.js';
 import { sleepSync } from '../fs-atomic.js';
-/**
- * The live `ServiceSupervisor` for the current `runDaemon()` invocation, or
- * `null` before boot / after shutdown. In-process only — a separate `agents
- * daemon status` process cannot see this; per-service health that must
- * survive across processes goes through `daemon-health.ts` instead (which
- * `ServiceSupervisor` already writes on every tick). This getter exists so a
- * FUTURE same-process consumer (e.g. a `daemon services` live-status IPC
- * handler) can read the supervisor's live state (`running`/`stopped`, plus the
- * failure streak) without needing its own reference to `runDaemon()`'s locals.
- */
 let activeServiceSupervisor = null;
-/** Health for every service currently registered on the live supervisor, or `null` if the daemon isn't running in this process. */
 export function getServiceSupervisorHealth() {
     return activeServiceSupervisor?.health() ?? null;
 }
@@ -52,133 +32,32 @@ const LIFETIME_FILE = 'daemon.lifetime';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
 const HEARTBEAT_FILE = 'heartbeat.json';
-const LOG_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+const LOG_MAX_SIZE = 5 * 1024 * 1024;
 const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
-/**
- * The service-manager identifiers of the REAL install's daemon — never
- * namespaced. A caller under a redirected HOME (a test/e2e harness) uses these
- * to recognize the box's production daemon as owned, where
- * `daemonSystemdUnitName()`/`daemonServiceLabel()` would name only its own
- * sandbox job (W4, PHNX-3736).
- */
+// Redirected HOME instances namespace manager ids because launchd/systemd key by label/unit, not manifest path; tests must never unload production.
 export function productionDaemonServiceNames() {
     return { systemdUnit: SYSTEMD_UNIT, launchdLabel: PLIST_NAME };
 }
-/**
- * RUSH-2639 (residual): launchd/systemd route `unload`/`load`/`list` by the
- * service identifier ALONE, never by the plist/unit file's path. Baking the
- * caller's HOME into the plist content (the earlier RUSH-2639 fix, above)
- * keeps the STARTED daemon inside its sandbox, but every hermetic-test
- * instance and every real interactive install still share the one literal
- * `PLIST_NAME`/`SYSTEMD_UNIT` string. `startDaemonLocked`'s own `unload`
- * before `load` is written to be a no-op ("not loaded, expected") for a
- * plist that has never been loaded — but confirmed on darwin: when a
- * DIFFERENT plist is already loaded under that same label, `unload
- * <this-instance's-own-never-loaded-path>` still tears down the OTHER job
- * (verified directly against real launchctl with two throwaway plists
- * sharing one label — the second job's own `unload` silently kills the
- * first, still alive under a different path). On a machine running several
- * hermetic test forks at once (CI) — or a developer's own suite next to
- * their real always-on daemon — that "other job" is a live daemon with
- * DIFFERENT baked-in state.
- *
- * Namespace the identifier itself whenever HOME has been redirected away
- * from the account's real home. `os.userInfo().homedir` reads the OS/passwd
- * record directly and ignores `$HOME` (unlike `os.homedir()`, which honors
- * it), so comparing the two detects exactly this redirection — true for
- * every hermetic test process, false for every real interactive/production
- * invocation, so a real user's daemon keeps registering under the unchanged
- * production identifier.
- *
- * The rule itself now lives in `service-manifest.ts` — the daemon was the first
- * manifest to need it, not the only one — and is re-exported here because it is
- * part of this module's published surface.
- */
 export { isolatedHomeSuffix };
-/** launchd Label for this process's daemon — namespaced under a redirected HOME. */
 export function daemonServiceLabel() {
     return namespacedServiceLabel(PLIST_NAME);
 }
-/** systemd --user unit name for this process's daemon — namespaced under a redirected HOME. */
 export function daemonSystemdUnitName() {
     const suffix = isolatedHomeSuffix();
     return suffix ? `agents-daemon-sandbox-${suffix}.service` : SYSTEMD_UNIT;
 }
-// Catch-up cadence + the supervised CatchupService live in catchup-service.ts
-// (PHNX-3608): the pass now runs under the ServiceSupervisor with a deadline +
-// AbortSignal + circuit breaker instead of a bare setInterval.
-/**
- * Cadences for the in-process background ticks, named here beside the other
- * tick constants rather than left as inline literals at their `setInterval`
- * (RUSH-2423). Self-heal, state-dir-check, watchdog, and device-probe
- * cadences moved to their own `*-service.ts` files (RUSH-3193 P3, alongside
- * session-index/account-state/etc.) — see those files for the per-service
- * trade-offs (self-heal's 6h/cheap-to-be-late repair cadence, state-dir-check's
- * env override for tests, watchdog/device-probe's shared 3min in-process
- * housekeeping cadence, NOT a routine — RUSH-2495). The secrets broker and its
- * self-heal/reap ticks moved out of this daemon entirely with the standalone
- * `secrets` engine (PHNX-3989 OWN-1) — this daemon no longer hosts that broker.
- */
-// Session-index warm interval/deadline live in session-index-service.ts now
-// (RUSH-3193 — migrated onto ServiceSupervisor).
 const WEDGE_THRESHOLD_TICKS = 3;
 const DAEMON_HEARTBEAT_TICK_MS = 60_000;
-/**
- * Crash-loop pacing and auto-start bounding (RUSH-2418, PHNX-4116). Two layers,
- * because a daemon that dies during startup must be paced but must NEVER be
- * abandoned:
- *
- * 1. **The OS supervisor paces AND always retries the respawn.** launchd's
- *    `KeepAlive` with `ThrottleInterval=30` (and systemd's `Restart=always`
- *    `RestartSec=30`) relaunch a dead daemon every ~30s. Crucially systemd's
- *    `StartLimitIntervalSec=0` REMOVES the burst cap (PHNX-4116): a repeatedly
- *    deadline-breaching daemon is restarted every ~30s indefinitely rather than
- *    parked in `failed` and left dark until a human runs `systemctl restart`.
- *    The owner requirement is that a wedged daemon always recovers on its own —
- *    "just work like systemd/launchd". A supervised deadline breach is precisely
- *    what forces the exit (see `ServiceSupervisor.exitForRestart`), so the exit
- *    is the recovery, not a failure to give up on.
- * 2. **The application-level circuit breaker** below still stops *auto*-starts
- *    from re-entering the loop from the other direction — a foreground command
- *    that calls `ensureDaemonStarted()` on every invocation. This bounds the
- *    IMPLICIT starts a busy operator would otherwise trigger; the OS-level
- *    unit-restart above is deliberately unbounded.
- */
 const DAEMON_THROTTLE_SECONDS = 30;
-/**
- * How many consecutive failed daemon starts disable the *implicit* auto-start
- * (`ensureDaemonStarted`). This bounds foreground-command auto-starts only; the
- * OS-level unit restart is deliberately unbounded (`StartLimitIntervalSec=0`) so
- * a wedged daemon always recovers (PHNX-4116). `agents daemon start` is the
- * deliberate override and is never gated by this.
- */
 export const DAEMON_AUTOSTART_FAILURE_LIMIT = 5;
 export function schedulerGateTransition(running, enabled) {
     if (running)
         return enabled ? 'reload' : 'stop';
     return enabled ? 'boot' : 'none';
 }
-/**
- * Wrap an async routine so it runs AT MOST ONCE, however many callers fire it.
- *
- * Extracted rather than left as a `let shuttingDown = false` inside runDaemon so
- * the property can actually be tested (RUSH-2423). The daemon's shutdown is
- * reachable from SIGTERM, SIGINT, and the state-dir self-check, but a real
- * shutdown completes in ~26ms, so the re-entrant window is not reachable from
- * outside the process — an end-to-end "send three signals" test passes with the
- * guard removed and proves nothing. The mechanism is what is testable, so the
- * mechanism is what is separated out.
- *
- * The flag is set synchronously before the first `await`, which is what makes
- * this safe: two callers in the same tick cannot both get past it.
- *
- * A rejected `fn` leaves the guard SET — one attempt is all there is, and the
- * rejection propagates to the caller that made it. That is right for shutdown
- * (a failed shutdown must not be silently retried by the next signal) but is
- * the thing to re-examine before giving this a second consumer.
- */
+// Latch before the first await and never retry after rejection: daemon shutdown is single-shot.
 export function singleShot(fn) {
     let ran = false;
     return async () => {
@@ -199,11 +78,7 @@ function getPidPath() {
 function getLockPath() {
     return path.join(ensureDaemonDir(), LOCK_FILE);
 }
-/**
- * Acquire an exclusive start lock. Returns a release function on success,
- * or null if another process already holds the lock. Uses O_EXCL to
- * atomically create the file — no TOCTOU window.
- */
+// Start, claim, and stop share this O_EXCL lifecycle lock; unreadable live identity is unverified, never stale.
 function acquireStartLock() {
     const lockPath = getLockPath();
     try {
@@ -214,38 +89,30 @@ function acquireStartLock() {
             try {
                 fs.unlinkSync(lockPath);
             }
-            catch { /* already removed */ }
+            catch { }
         };
     }
     catch (err) {
         if (err.code === 'EEXIST') {
-            // Lock file exists — check if the holder is still alive (stale lock recovery)
             try {
                 const holderPid = parseInt(fs.readFileSync(lockPath, 'utf-8').trim(), 10);
                 if (!isNaN(holderPid)) {
                     try {
                         process.kill(holderPid, 0);
-                        return null; // holder is alive, lock is valid
+                        return null;
                     }
                     catch {
-                        // holder is dead, remove stale lock and retry once
                         fs.unlinkSync(lockPath);
                         return acquireStartLock();
                     }
                 }
             }
-            catch { /* can't read lock file — treat as held */ }
+            catch { }
             return null;
         }
         throw err;
     }
 }
-/**
- * Stop is a lifecycle mutation just like start/claim, so it must cross the same
- * lock. A claim can legitimately hold the lock through the incumbent's 5s
- * graceful window plus the 2s hard-kill backstop; wait beyond that complete
- * takeover window before failing loud instead of running teardown unlocked.
- */
 const STOP_LOCK_WAIT_MS = 10_000;
 const STOP_LOCK_POLL_MS = 50;
 function acquireLifecycleLock() {
@@ -259,14 +126,6 @@ function acquireLifecycleLock() {
         sleepSync(Math.min(STOP_LOCK_POLL_MS, deadline - Date.now()));
     }
 }
-/**
- * Absolute path to the daemon's structured log.
- *
- * Exported because two commands rebuilt the same path from a hardcoded
- * `'logs.jsonl'` literal (`commands/daemon.ts`, `commands/routines.ts`), so
- * renaming the file would have silently pointed them at nothing (RUSH-2423).
- * One definition, three callers.
- */
 export function getDaemonLogPath() {
     return path.join(ensureDaemonDir(), LOG_FILE);
 }
@@ -276,7 +135,6 @@ function getLaunchdPlistPath() {
 function getSystemdUnitPath() {
     return path.join(os.homedir(), '.config', 'systemd', 'user', daemonSystemdUnitName());
 }
-/** Read the stored daemon PID from disk. Returns null if not present or invalid. */
 export function readDaemonPid(daemonDir) {
     const pidPath = daemonDir ? path.join(daemonDir, PID_FILE) : getPidPath();
     if (!fs.existsSync(pidPath))
@@ -289,25 +147,23 @@ export function readDaemonPid(daemonDir) {
         return null;
     }
 }
-/** Write the daemon PID to the pid file. */
 export function writeDaemonPid(pid) {
     fs.writeFileSync(getPidPath(), String(pid), 'utf-8');
 }
-/** Remove the daemon PID file. */
 export function removeDaemonPid() {
     const pidPath = getPidPath();
     if (fs.existsSync(pidPath)) {
         fs.unlinkSync(pidPath);
     }
 }
-/** Remove the pid registration only while it still names the owner we observed. */
+// Remove registration only while it still names the owner observed by this cleanup.
 function removeDaemonPidIfOwned(pid) {
     if (readDaemonPid() !== pid)
         return false;
     try {
         fs.unlinkSync(getPidPath());
     }
-    catch { /* already removed */ }
+    catch { }
     return readDaemonPid() !== pid;
 }
 function getHeartbeatPath() {
@@ -318,7 +174,7 @@ export function writeHeartbeat(pid = process.pid) {
     try {
         fs.writeFileSync(getHeartbeatPath(), JSON.stringify(hb), 'utf-8');
     }
-    catch { /* best effort */ }
+    catch { }
 }
 export function readHeartbeat() {
     try {
@@ -336,43 +192,15 @@ export function removeHeartbeat() {
     try {
         fs.unlinkSync(getHeartbeatPath());
     }
-    catch { /* already removed */ }
-}
-/**
- * A heartbeat is "fresh" when its last tick falls inside the freshness window. A
- * fresh heartbeat whose pid is alive is proof of a live, ticking daemon even
- * when the pid file has been lost, which is why `resolveLiveDaemonPid` trusts it.
- *
- * There is no separate "wedged" verdict any more (PHNX-4116): a daemon whose
- * event loop stalls no longer sits `wedged` waiting for a human — a supervised
- * service that breaches its deadline exits the process, and systemd/launchd
- * restart it. So the daemon is simply `running` or `stopped`.
- */
+    catch { }
+}
 function isHeartbeatFresh(hb) {
     const elapsed = Date.now() - Date.parse(hb.lastTick);
     return elapsed <= WEDGE_THRESHOLD_TICKS * DAEMON_HEARTBEAT_TICK_MS;
 }
-/** How long stopDaemon waits for a SIGTERMed daemon to exit before escalating. */
 const STOP_GRACE_MS = 5000;
-/** How long it waits after the hard tree-kill before giving up. */
 const STOP_KILL_GRACE_MS = 2000;
-/**
- * Resolve the PID of the live daemon, tolerant of a pid-file/heartbeat desync.
- *
- * The daemon writes the pid file once (on claim/start) but rewrites the
- * heartbeat every tick. If the pid file is lost while the daemon keeps ticking
- * — e.g. an earlier isDaemonRunning() found a stale/reused/dead pid and cleared
- * the file, or it was removed out from under a live daemon — the pid file reads
- * empty even though a daemon is genuinely alive and firing jobs. Reading only
- * the pid file then reports "stopped" for a running scheduler, and (worse) lets
- * claimDaemonInstance() start a SECOND daemon that double-fires every routine.
- *
- * So: trust the pid file only when its pid is a live `__daemon-run`; otherwise
- * trust a FRESH heartbeat whose pid passes the same identity check. Callers that
- * already own daemon.lock may request repair, re-adopting the heartbeat pid or
- * removing the exact stale pid they observed. Read-only liveness probes never
- * mutate shared state outside that lock.
- */
+// A fresh heartbeat may repair a lost pid record; unknown identity is preserved so inspection failure cannot create a second daemon.
 function resolveLiveDaemonPid(repair = false) {
     const pid = readDaemonPid();
     const pidIdentity = pid !== null ? daemonProcessIdentity(pid) : 'dead';
@@ -381,17 +209,13 @@ function resolveLiveDaemonPid(repair = false) {
     const hb = readHeartbeat();
     if (hb && isHeartbeatFresh(hb) && daemonProcessIdentity(hb.pid) === 'daemon') {
         if (repair && pid !== hb.pid)
-            writeDaemonPid(hb.pid); // lock owner heals the desync
+            writeDaemonPid(hb.pid);
         return hb.pid;
     }
-    // A failed command-line inspection is not proof the pid is stale. Leave the
-    // registration intact so a sandbox/permission failure cannot erase the only
-    // owner record and trigger a duplicate daemon.
     if (repair && pid !== null && pidIdentity !== 'unknown')
         removeDaemonPidIfOwned(pid);
     return null;
 }
-/** A live recorded pid whose command identity could not be inspected. */
 function unverifiedLiveDaemonPid() {
     const pid = readDaemonPid();
     if (pid !== null && daemonProcessIdentity(pid) === 'unknown')
@@ -401,17 +225,7 @@ function unverifiedLiveDaemonPid() {
         return hb.pid;
     return null;
 }
-/**
- * Check whether a daemon is alive — via the pid file, or a fresh heartbeat when
- * the pid file has been lost (see resolveLiveDaemonPid). The observation itself
- * is read-only; when it finds desync it opportunistically acquires daemon.lock
- * and repeats the observation there before repairing. A contended probe still
- * returns the observed liveness without mutating another lifecycle operation's
- * state.
- */
 export function isDaemonRunning() {
-    // Fail safe for reporting/start suppression: inability to inspect a live pid
-    // is never permission to declare it dead and launch a duplicate.
     if (unverifiedLiveDaemonPid() !== null)
         return true;
     const recordedPid = readDaemonPid();
@@ -428,63 +242,22 @@ export function isDaemonRunning() {
         release();
     }
 }
-/**
- * Single-instance claim for the daemon foreground entrypoint.
- *
- * `agents __daemon-run` is reachable directly — a manual invocation, or a
- * service-manager restart that races a still-alive predecessor — bypassing the
- * start lock in startDaemon(). Without this guard runDaemon() would call
- * writeDaemonPid() unconditionally, clobber a live daemon's recorded PID, and
- * run a second JobScheduler concurrently, so every cron routine fires twice.
- *
- * LAST-WINS takeover (SING-11, RUSH-2352): when a live daemon already owns the
- * pid file, this does NOT defer to it — it evicts the incumbent and becomes the
- * survivor, so a second install can never leave two daemons running. Returns true
- * and records our PID once the incumbent is provably dead (its resources
- * released). Returns false when another `__daemon-run` currently holds the
- * O_EXCL start lock, or when the incumbent cannot be safely identified/evicted,
- * in which case the caller must exit without touching further state.
- * The read-evict-write is serialized behind the same start lock startDaemon()
- * uses, so two `_run` processes can't both claim in the window between the
- * liveness check and the write.
- */
 export function claimDaemonInstance() {
-    // A nested caller cannot interpret legacy numeric lock/PID files. Authenticate
-    // before acquiring the lock (whose stale-PID cleanup itself mutates state).
     if (!daemonProcessViewAllowed()) {
         console.error('Daemon startup requires the owning process namespace. Automatic reuse of a private-container HOME across namespaces is unsupported; run in its owning namespace or use a fresh HOME.');
         return false;
     }
-    // A stop owns this same lock through teardown. Waiting here is load-bearing:
-    // returning false while stopDaemon() holds it lets this replacement exit 0,
-    // then the stop completes with no singleton left alive. The bounded lifecycle
-    // acquisition also preserves concurrent-start serialization: after the first
-    // claimer publishes its pid, the waiter takes the lock and performs the normal
-    // last-wins takeover rather than ever running the read-evict-write unlocked.
     const release = acquireLifecycleLock();
     if (!release)
         return false;
     try {
-        // Recheck under lifecycle serialization; invocation is not provenance.
         if (!daemonProcessViewAllowed())
             return false;
         recordDaemonProcessView();
-        // Do not overwrite a live-but-uninspectable owner. This is the non-
-        // destructive side of the same fail-closed rule stopDaemon applies.
         if (unverifiedLiveDaemonPid() !== null)
             return false;
-        // resolveLiveDaemonPid() also consults a fresh heartbeat, so a live daemon
-        // whose pid file was lost is still found and evicted — otherwise a missing
-        // pid file would let both this instance AND the orphaned incumbent run a
-        // JobScheduler at once and double-fire every routine.
         const existing = resolveLiveDaemonPid(true);
         if (existing !== null && existing !== process.pid) {
-            // Evict, and WAIT for the incumbent to be provably dead — its graceful
-            // handleShutdown releasing its socket bindings (feed-stream hub, monitor)
-            // — before we write our pid and (later, in runDaemon) bind our own.
-            // Binding before the release recreates the two-owners-on-one-socket orphan
-            // documented at stopDaemon below, so the pid file is not written until the
-            // prior owner is gone.
             if (!evictIncumbentDaemon(existing))
                 return false;
         }
@@ -495,21 +268,6 @@ export function claimDaemonInstance() {
         release();
     }
 }
-/**
- * SIGTERM a live incumbent daemon and block until it is provably dead, so its
- * graceful handleShutdown has released its socket bindings (the feed-stream hub,
- * the monitor socket) BEFORE the newcomer binds anything of its own (SING-11) —
- * the daemon no longer hosts a secrets broker socket (the standalone `secrets`
- * CLI owns it, PHNX-3989 OWN-1) nor a browser IPC socket (the standalone
- * `browser` CLI owns it, PHNX-4101). Escalates
- * to killTree after the grace window. Passes the POSITIVE pid so the kill reaches
- * only the incumbent daemon — never its detached routine children, which run in
- * their own process groups and must survive takeover (SING-11a); the new daemon
- * re-adopts them via monitorRunningJobs. Synchronous to match claimDaemonInstance's
- * read-evict-write, which runs under the O_EXCL start lock; mirrors stopDaemon's
- * grace-then-escalate shape and constants exactly, because the same
- * proof-of-release requirement applies.
- */
 function evictIncumbentDaemon(pid) {
     const beforeSignal = daemonProcessIdentity(pid);
     if (beforeSignal === 'dead' || beforeSignal === 'other')
@@ -517,9 +275,6 @@ function evictIncumbentDaemon(pid) {
     if (beforeSignal === 'unknown')
         return false;
     if (process.platform === 'win32') {
-        // No graceful termination signal on Windows — take the incumbent down and
-        // still wait for the kill to land before the caller binds anything (mirrors
-        // stopDaemon's win32 branch).
         killTree(pid);
         if (waitForExit(pid, STOP_KILL_GRACE_MS))
             return true;
@@ -534,67 +289,39 @@ function evictIncumbentDaemon(pid) {
         return afterSignal === 'dead' || afterSignal === 'other';
     }
     if (waitForExit(pid, STOP_GRACE_MS))
-        return true; // graceful release complete
+        return true;
     const beforeKill = daemonProcessIdentity(pid);
     if (beforeKill === 'dead' || beforeKill === 'other')
         return true;
     if (beforeKill === 'unknown')
         return false;
-    killTree(pid); // positive pid: SIGKILL reaches the daemon, not its job children
+    killTree(pid);
     if (waitForExit(pid, STOP_KILL_GRACE_MS))
         return true;
     const afterKill = daemonProcessIdentity(pid);
     return afterKill === 'dead' || afterKill === 'other';
 }
-/** Directory that registers every live daemon of THIS device (one per state dir). */
 function getDaemonInstancesDir() {
     return path.join(getDaemonDir(), 'instances');
 }
-/**
- * Record this daemon in the device's instance registry — a marker file named by
- * pid under `<daemonDir>/instances/`. The registry, not a process scan, is how
- * the reaper enumerates the device singleton: because the dir lives INSIDE the
- * state dir (`AGENTS_DAEMON_DIR` ?? `<HOME>/.agents/.cache/helpers/daemon`), every
- * daemon of one device — however it was launched — registers in the same place,
- * while a genuinely separate install/home or a test fixture registers under its
- * own state dir and is invisible here. This is what fixes the two-entry pile-up:
- * the compiled `dist/bin/agents` binary and the `node <shim>` JS entry have
- * different `process.argv[1]`, so the old launch-entry-scoped `ps` match never
- * reaped across them and duplicates accumulated (78 observed on one box), every
- * routine double-firing. Best-effort — the reaper self-heals a missing/stale
- * marker, and reading another process's ENV to key on the state dir directly is
- * not portable (hardened macOS hides it from `ps`), so identity rides the shared
- * on-disk registry instead. No-op on Windows (POSIX-only reaper).
- */
 export function registerDaemonInstance(pid = process.pid) {
     if (process.platform === 'win32')
         return;
     try {
         const dir = getDaemonInstancesDir();
         fs.mkdirSync(dir, { recursive: true });
-        // The command line is stored for diagnostics; the filename (pid) is identity.
         fs.writeFileSync(path.join(dir, String(pid)), process.argv.slice(1).join(' '), 'utf-8');
     }
-    catch { /* best effort — the reaper self-heals a missing marker */ }
+    catch { }
 }
-/** Remove this daemon's registry marker on graceful shutdown. */
 export function unregisterDaemonInstance(pid = process.pid) {
     if (process.platform === 'win32')
         return;
     try {
         fs.rmSync(path.join(getDaemonInstancesDir(), String(pid)), { force: true });
     }
-    catch { /* ignore */ }
-}
-/**
- * Reap stray duplicate daemons of THIS device — every registrant in the instance
- * registry that is a live `agents __daemon-run` and is neither this process nor
- * the current pid-file owner. A predecessor SIGKILLed/OOM-ed without cleanup, or a
- * duplicate that lost the pid-file write race, would otherwise keep a second
- * scheduler alive and double-fire jobs even after claimDaemonInstance() hands the
- * pid file to the survivor. Also garbage-collects markers whose pid is dead or was
- * reused by an unrelated process. No-op on Windows (POSIX-only).
- */
+    catch { }
+}
 export function reapStrayDaemons(keepPid = process.pid) {
     const details = [];
     let reaped = 0;
@@ -606,28 +333,25 @@ export function reapStrayDaemons(keepPid = process.pid) {
         entries = fs.readdirSync(dir);
     }
     catch {
-        return { reaped, details }; // no registry yet — nothing to reap
+        return { reaped, details };
     }
     const ownerPid = resolveLiveDaemonPid();
     const dropMarker = (name) => {
         try {
             fs.rmSync(path.join(dir, name), { force: true });
         }
-        catch { /* ignore */ }
+        catch { }
     };
     for (const name of entries) {
         const pid = parseInt(name, 10);
         if (isNaN(pid) || String(pid) !== name)
-            continue; // not a pid marker
+            continue;
         if (pid === keepPid || pid === process.pid || pid === ownerPid)
             continue;
-        // Dead registrant → stale marker.
         if (!isAlive(pid)) {
             dropMarker(name);
             continue;
         }
-        // Live pid, but guard against pid reuse: only a real `__daemon-run` is ours.
-        // Process ARGS are readable cross-platform (unlike ENV on hardened macOS).
         const identity = daemonProcessIdentity(pid);
         if (identity === 'unknown') {
             details.push(`could not verify stray daemon pid ${pid}; marker retained`);
@@ -640,16 +364,13 @@ export function reapStrayDaemons(keepPid = process.pid) {
         try {
             process.kill(pid, 'SIGTERM');
         }
-        catch { /* already gone between the alive check and the signal */ }
+        catch { }
         if (waitForExit(pid, STOP_GRACE_MS)) {
             reaped++;
             details.push(`reaped stray daemon pid ${pid}`);
             dropMarker(name);
             continue;
         }
-        // The pid may have been recycled during the grace window. Never hard-kill
-        // it unless it still identifies as a daemon; a stale registry marker is all
-        // we own when the command identity changed.
         const beforeKill = daemonProcessIdentity(pid);
         if (beforeKill === 'unknown') {
             details.push(`could not reverify stray daemon pid ${pid}; marker retained`);
@@ -666,8 +387,6 @@ export function reapStrayDaemons(keepPid = process.pid) {
             dropMarker(name);
         }
         else {
-            // Keep the only marker for a process that survived both signals so the
-            // next reaper/doctor can still see it.
             details.push(`stray daemon pid ${pid} survived SIGKILL`);
         }
     }
@@ -683,9 +402,6 @@ function daemonProcessIdentity(pid) {
                 encoding: 'utf-8',
                 stdio: ['ignore', 'pipe', 'ignore'],
             });
-        // getDaemonLaunch always places __daemon-run last. Matching it anywhere in
-        // the command line mistakes an agent prompt or shell script that merely
-        // mentions the token for the shared daemon.
         return /(?:^|\s)["']?__daemon-run["']?\s*$/.test(out.trim()) ? 'daemon' : 'other';
     }
     catch {
@@ -711,7 +427,6 @@ function rotateLogsIfNeeded(logPath) {
     }
     catch { }
 }
-/** Append a JSONL log entry to the daemon log file (owner-only permissions). */
 export function log(level, message) {
     const logPath = getDaemonLogPath();
     rotateLogsIfNeeded(logPath);
@@ -720,30 +435,21 @@ export function log(level, message) {
     try {
         fs.chmodSync(logPath, 0o600);
     }
-    catch { /* best effort */ }
-    // Mirror into the unified event stream so `agents events --module daemon` sees
-    // always-on process lifecycle the same way secrets/browser/computer do.
-    // Fail soft — the daemon log file remains the primary sink for `daemon logs`.
+    catch { }
     try {
         const lvl = level.toUpperCase();
         const event = lvl === 'ERROR' || lvl === 'FATAL' ? 'daemon.error'
             : lvl === 'START' || /starting|started/i.test(message) ? 'daemon.start'
                 : lvl === 'STOP' || /stopping|stopped|shutting down/i.test(message) ? 'daemon.stop'
                     : 'daemon.info';
-        // Fire-and-forget the event mirror: `log()` is a synchronous primitive on
-        // every daemon tick's `ctx.log`, and the mirror's event-log lock would
-        // otherwise block the shared event loop for up to 30s under contention
-        // (PHNX-3695). The daemon-log append above is the primary, synchronous sink;
-        // the mirror is best-effort, so a fire-and-forget async write is correct.
         void emitAsync(event, {
             module: 'daemon',
             detail: redactSecrets(message).slice(0, 500),
             status: lvl,
         }).catch(() => { });
     }
-    catch { /* never crash the daemon on event-log failure */ }
+    catch { }
 }
-/** Keep synchronous signal-handler failures inside the daemon's crash barrier. */
 export function guardSignalHandler(handler, onError) {
     return () => {
         try {
@@ -754,24 +460,6 @@ export function guardSignalHandler(handler, onError) {
         }
     };
 }
-/** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
-/**
- * Anchor the daemon's working directory to a stable, always-present path.
- *
- * The daemon is long-lived and inherits whatever cwd it was launched from — often
- * a git worktree (e.g. a `.agents/worktrees/<slug>/` a session happened to be in).
- * When that directory is later removed (`git worktree remove`, `rm -rf`), the
- * daemon keeps the deleted inode as its cwd — a process cannot chdir out of a
- * deleted directory on its own — and every job it spawns inherits the dead cwd
- * (`spawnJobAttempt` and command runs pass no explicit `cwd`, so the child uses
- * the parent's). Bun then fails `getcwd()` during startup and every routine crashes
- * at 0 seconds with `ENOENT: Bun could not find a file` before the agent even runs.
- *
- * Re-anchoring to the home directory once, at daemon startup, makes the daemon
- * immune regardless of how it was launched (systemd unit, launchd, or a manual
- * `agents __daemon-run` from any directory). Returns the resolved cwd, or null if
- * anchoring failed (logged, non-fatal).
- */
 export function anchorDaemonCwd() {
     const home = os.homedir();
     try {
@@ -783,22 +471,6 @@ export function anchorDaemonCwd() {
         return null;
     }
 }
-/**
- * Surface, at the daemon's OWN startup, that it was launched from an ephemeral
- * root that will wedge it if the directory is removed. This is the runtime
- * companion to the launch-time check in validateDaemonBinary (which only runs
- * when the daemon is *spawned* via getDaemonLaunch): a direct
- * `agents __daemon-run` from a temp or worktree build — e.g. a review/verify
- * checkout under /tmp — never passes through that path, so without this the
- * wedge risk stays invisible until jobs start ENOENT-ing on their dynamic
- * imports. Best-effort and non-fatal; the cwd is already handled by
- * anchorDaemonCwd, but a deleted module root can only be flagged, not repaired.
- *
- * `resolveBin` is injectable (defaults to getAgentsBinPath) so the wiring — the
- * predicate call, the WARN, and the non-fatal guard around a throwing resolver —
- * is testable. Returns the warning message it logged, or null when the launch
- * root is stable (or could not be resolved).
- */
 export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
     try {
         const bin = resolveBin();
@@ -816,27 +488,6 @@ export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
         return null;
     }
 }
-/**
- * Test-home tripwire (PHNX-2545). The routines/daemon test suite spawns real
- * `agents __daemon-run` processes against an isolated /tmp HOME. If that HOME
- * override fails to reach the child — an `env: {...process.env}` spawn that
- * forgot to set it, a login shell that reset HOME — the daemon resolves its
- * state dir under the operator's REAL home and its scheduler/watchdog then tick
- * against shared production state. That is the exact leak the ticket reports:
- * real test daemons found alive on a fleet box, each a second live scheduler
- * racing the legitimate one, in violation of the execution-singularity spec.
- *
- * A test that spawns a daemon sets AGENTS_DAEMON_TEST_HOME to the isolated home
- * it provisioned. When that marker is present, this daemon's resolved state dir
- * MUST sit under it; otherwise the daemon refuses to boot — failing loud before
- * it claims an instance, writes a pid, or fires a single tick (the throw is
- * caught in index.ts's `__daemon-run` handler, logged, and exits non-zero) —
- * rather than running in the wrong directory against the real host. In
- * production the marker is never set, so this is a no-op there.
- *
- * `daemonDir`/`testHome` are injectable so the pure guard is unit-testable
- * without spawning a process; the defaults read the live daemon dir and env.
- */
 export function assertTestDaemonHome(daemonDir = getDaemonDir(), testHome = process.env.AGENTS_DAEMON_TEST_HOME) {
     if (!testHome)
         return;
@@ -850,28 +501,8 @@ export function assertTestDaemonHome(daemonDir = getDaemonDir(), testHome = proc
         throw new Error(msg);
     }
 }
-// ---------------------------------------------------------------------------
-// Module-level periodic maintenance helpers (RUSH-2422)
-//
-// These were inline closures inside runDaemon(). Moved here so they are
-// named in stack traces, readable without scrolling through runDaemon's
-// 500-line body, and not recreated on every function invocation.
-//
-// self-heal moved to SelfHealService on the ServiceSupervisor (RUSH-3193 P3)
-// — the supervisor's own per-tick deadline + inFlight guard replaces its local
-// `healing` flag. state-dir-check moved to StateDirCheckService (RUSH-3193
-// P3), registered after `handleShutdown` is declared — see its registration
-// site below. The secrets broker (self-heal, reap, and hosting) moved out of
-// this daemon entirely with the standalone `secrets` engine (PHNX-3989 OWN-1).
-// ---------------------------------------------------------------------------
 export async function runDaemon() {
-    // PHNX-2545 test-home tripwire — FIRST, before this daemon claims an instance,
-    // writes a pid, or fires any tick. A test-spawned daemon that lost its isolated
-    // HOME override must refuse to run against the operator's real state rather than
-    // schedule against the real host. No-op in production (the marker is never set).
     assertTestDaemonHome();
-    // Lifecycle readers and launchers do not run services. Load their code only
-    // in the daemon process, before it claims or publishes lifecycle state.
     const [{ SessionIndexService }, { SessionSummarizerService }, { SessionTitleService }, { MonitorEngineService }, { AccountUsageService, AccountAuthService }, { CatchupService }, { WatchdogService }, { DeviceProbeService }, { SelfHealService }, { SelfUpdateService }, { HarnessUpdateService }, { AuthSyncService }, { UsageSyncService }, { StateDirCheckService }, { SessionStateService }, { FeedStreamService }, { AttentionNotifyService }, { WebhookReceiverService }, { HeartbeatService }, { TmuxReapService },] = await Promise.all([
         import('./session-index-service.js'),
         import('./session-summarizer-service.js'),
@@ -894,13 +525,6 @@ export async function runDaemon() {
         import('./heartbeat-service.js'),
         import('./tmux-reap-service.js'),
     ]);
-    // Install the shared-daemon reload signal boundary BEFORE publishing our PID
-    // in claimDaemonInstance(). Browser/routines clients use that PID to decide a
-    // daemon exists and may request a service reload immediately. POSIX otherwise
-    // applies its default SIGHUP action during the rest of startup and terminates
-    // the whole process — exactly the client-caused eviction PHNX-3605 forbids.
-    // Requests received before services are ready coalesce into one reload and are
-    // applied through the normal guarded handler once startup completes.
     let reloadRequestedDuringStartup = false;
     let liveReloadHandler = null;
     const dispatchReloadSignal = () => {
@@ -911,22 +535,12 @@ export async function runDaemon() {
     };
     if (process.platform !== 'win32')
         process.on('SIGHUP', dispatchReloadSignal);
-    // Single-instance guard (last-wins, SING-11): a direct `agents __daemon-run`
-    // (manual, or a service-manager restart racing a live predecessor) EVICTS the
-    // incumbent and becomes the survivor. claimDaemonInstance returns false only
-    // when a concurrent `__daemon-run` currently holds the start lock — that peer
-    // is mid-takeover and will be the singleton, so this instance stands down.
     if (!claimDaemonInstance()) {
         if (process.platform !== 'win32')
             process.removeListener('SIGHUP', dispatchReloadSignal);
         log('WARN', `Another daemon owns lifecycle state or is mid-takeover; this instance (PID ${process.pid}) is exiting`);
-        // Exit cleanly (0) so a service manager treats it as an orderly no-op
-        // rather than a failure to restart-flap on.
         process.exit(0);
     }
-    // Deterministic integration-test seam for the PID-published/startup-complete
-    // signal window above. It is honored only inside an explicitly isolated test
-    // HOME; production daemons never pause here.
     const startupDelayRaw = process.env.AGENTS_DAEMON_TEST_STARTUP_DELAY_MS;
     if (process.env.AGENTS_DAEMON_TEST_HOME && startupDelayRaw) {
         const startupDelayMs = Number(startupDelayRaw);
@@ -935,21 +549,12 @@ export async function runDaemon() {
         }
         await new Promise((resolve) => setTimeout(resolve, startupDelayMs));
     }
-    // Unlike the pid and heartbeat files, this marker is written exactly once
-    // for this daemon lifetime. Status probes deliberately repair those other
-    // files, so they cannot prove that the original state dir still exists.
     const lifetimePath = path.join(getDaemonDir(), LIFETIME_FILE);
     const lifetimeToken = `${process.pid}:${Date.now()}`;
     fs.writeFileSync(lifetimePath, lifetimeToken, 'utf-8');
     log('INFO', `Daemon started (PID: ${process.pid})`);
     anchorDaemonCwd();
     warnEphemeralDaemonRoot();
-    // Converge the device-config/pins stores (legacy central block /
-    // auto-launch.json / tracked-doc pins → per-device docs + pins file).
-    // Idempotent, cheap no-op once folded. The daemon boots via
-    // `agents __daemon-run`, which bypasses bootstrap's migration sentinel — so
-    // the daemon runs this itself so its scheduler/watchdog gates read the
-    // converged store.
     try {
         const { migrateDeviceConfigStores } = await import('../devices/config-migration.js');
         migrateDeviceConfigStores();
@@ -957,12 +562,6 @@ export async function runDaemon() {
     catch (err) {
         log('WARN', `device config migration failed: ${err.message}`);
     }
-    // Version-skew one-shot (RUSH-2435): retrofit the current pane-died hook onto
-    // any managed tmux session a pre-fix binary left with a stale one. The 5-min
-    // `tmux-reconcile` routine that used to run this on a poll was deleted
-    // (RUSH-2495) — startup + `ensureSessionHookRepaired` at attach time
-    // (tmux/session.ts) now cover what that poll used to. Idempotent and
-    // non-destructive: a session already at the current schema is a no-op.
     try {
         const { reconcileSessionHooks } = await import('../tmux/session.js');
         const { isTmuxInstalled } = await import('../tmux/binary.js');
@@ -975,21 +574,8 @@ export async function runDaemon() {
     catch (err) {
         log('WARN', `tmux hook reconcile failed: ${err.message}`);
     }
-    // Per-service toggles live outside device-config so they can be checked by
-    // service clients (e.g. secrets) without loading the whole config stack.
     let servicesConfig = readDaemonServicesConfig();
     const isEnabled = (id) => servicesConfig.services[id] !== false;
-    // The daemon holds NO Claude credential of its own. Routine runs authenticate
-    // exactly like an interactive `agents run`: through the per-account
-    // CLAUDE_CONFIG_DIR login on this device (its own auto-refreshing
-    // .credentials.json). Claude Code's interactive access token is short-lived but
-    // refreshes itself per-device; a routine whose account login has gone dead is
-    // skipped up front by the auth-health preflight (runner.ts) with a re-login
-    // hint, rather than papered over by an injected fallback token.
-    // Register this daemon in the device instance registry, then reap any stray
-    // duplicate that slipped past the start lock or was orphaned by a hard-crash —
-    // before it can double-fire jobs. Registration comes first so a racing peer's
-    // reaper can see this pid, and so this reaper never mistakes itself for a stray.
     registerDaemonInstance();
     try {
         const strays = reapStrayDaemons();
@@ -1002,19 +588,12 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Stray daemon reaper failed: ${err.message}`);
     }
-    // Socket services: monitor engine, account-state, and the feed-stream hub are
-    // all managed by the ServiceSupervisor (RUSH-3193 P2). The secrets broker moved
-    // with the standalone `secrets` engine (PHNX-3989 OWN-1) and the browser IPC
-    // service with the standalone `browser` CLI (PHNX-4101) — this daemon no longer
-    // hosts either; each standalone owns its own lifecycle exclusively.
     const supervisor = new ServiceSupervisor();
     if (isEnabled('session-state')) {
         supervisor.register(new SessionStateService(() => supervisor.runNow('session-state')));
     }
     else
         log('INFO', 'Live session-state service disabled');
-    // The shared feed fan-out. Registered even when disabled at boot so a later
-    // `agents daemon services enable feed-stream` brings it up over SIGHUP.
     supervisor.register(new FeedStreamService(), { enabled: isEnabled('feed-stream') });
     if (!isEnabled('feed-stream'))
         log('INFO', 'Shared feed stream service disabled');
@@ -1023,9 +602,6 @@ export async function runDaemon() {
         supervisor.register(monitorEngineSvc);
     else
         log('INFO', 'Monitor engine disabled');
-    // Usage and auth refresh are two INDEPENDENT supervised services (PHNX-3608)
-    // so a run of usage-refresh throws is recorded against usage alone and never
-    // starves the slower auth refresh — each keeps ticking on its own interval.
     if (isEnabled('account-state'))
         supervisor.register(new AccountUsageService());
     else
@@ -1034,19 +610,7 @@ export async function runDaemon() {
         supervisor.register(new AccountAuthService());
     else
         log('INFO', 'Account-auth service disabled');
-    // The routine scheduler handle. Declared HERE — before the CatchupService
-    // registration — because `supervisor.startAll()` below fires each service's
-    // first tick synchronously, so the `catchup` tick reads `scheduler` during
-    // startAll, BEFORE this `let` would initialise if it lived at its old textual
-    // position further down. That was a real TDZ `ReferenceError` on every boot
-    // ("Cannot access 'scheduler' before initialization"), not a race (PHNX-3608).
-    // `bootScheduler`/`stopScheduler` (hoisted below) assign this same binding.
     let scheduler = null;
-    // Catch-up recovery under the supervisor (PHNX-3608). The closures reference
-    // `scheduler` (declared just above) and `catchupPass` (a hoisted function
-    // declaration). The tick self-gates on the scheduler being booted, so it is a
-    // cheap no-op — including on its immediate first tick during startAll, when
-    // `scheduler` is still null — on a device whose scheduler.enabled gate is off.
     if (isEnabled('catchup')) {
         supervisor.register(new CatchupService({
             isSchedulerBooted: () => scheduler !== null,
@@ -1056,40 +620,22 @@ export async function runDaemon() {
     else {
         log('INFO', 'Catch-up recovery service disabled');
     }
-    // The browser IPC service and its task reaper are the standalone `browser`
-    // CLI's now (@phnx-labs/browser-cli, PHNX-4101): it hosts its own IPC service
-    // and runs its own `prune` reaper. agents-cli no longer constructs a
-    // BrowserService, binds a browser socket, or reaps browser tasks — see
-    // `commands/browser.ts` and `docs/browser.md`.
     if (isEnabled('session-index'))
         supervisor.register(new SessionIndexService());
     else
         log('INFO', 'Session-index warm service disabled');
-    // Session summarizer (PHNX-3939) — registered when the service toggle is on,
-    // but each tick is a no-op unless the operator also set summarizer.enabled and
-    // a model endpoint, so registering it costs nothing while unconfigured.
     if (isEnabled('session-summarizer'))
         supervisor.register(new SessionSummarizerService());
     else
         log('INFO', 'Session summarizer service disabled');
-    // Attention desktop banners (PHNX-4004) — posts one actionable native banner
-    // per new attention key. Reader-independent: it fires whether or not a
-    // `sessions watch` reader is present, and the notified-ledger is its
-    // idempotency truth across daemon restarts.
     if (isEnabled('attention-notify'))
         supervisor.register(new AttentionNotifyService());
     else
         log('INFO', 'Attention-notify service disabled');
-    // Session titles (PHNX-3797) — generates each session row's headline once,
-    // with a cheap model, off the request path.
     if (isEnabled('session-title'))
         supervisor.register(new SessionTitleService());
     else
         log('INFO', 'Session-title service disabled');
-    // Watchdog, device-probe, and self-heal are all periodic services managed
-    // by the ServiceSupervisor (RUSH-3193 P3). Each is gated the same way as
-    // the socket services above; state-dir-check is registered separately,
-    // later, after `handleShutdown` exists (see below).
     if (isEnabled('watchdog'))
         supervisor.register(new WatchdogService());
     else
@@ -1132,15 +678,6 @@ export async function runDaemon() {
         log('INFO', 'Tmux reap service disabled');
     await supervisor.startAll({ log });
     activeServiceSupervisor = supervisor;
-    // scheduler.enabled=false in this machine's device doc means NO routines fire
-    // here — the scheduler and its catchup recovery simply never start, while the
-    // daemon keeps its other duties (feed stream, session sync).
-    // The refusal message is the same one the start surfaces
-    // (`routines add` auto-start, manual `routines start`) raise. The gate is
-    // re-evaluated on every SIGHUP reload (handleReload below) via
-    // schedulerGateTransition, so flipping the key never needs a daemon restart.
-    // Also honour the daemon-services toggle so `agents daemon services disable scheduler`
-    // has a single, obvious effect.
     const schedulerEnabledAtBoot = isSchedulerEnabled() && isEnabled('scheduler');
     if (!schedulerEnabledAtBoot) {
         try {
@@ -1166,15 +703,10 @@ export async function runDaemon() {
             ...(config.agent ? { agent: config.agent } : {}),
             ...(config.workflow ? { workflow: config.workflow } : {}),
         });
-        // RUSH-2030: branded desktop notification on start (agent/workflow routines;
-        // suppressed for command housekeeping). Finish/output is fired from the
-        // onFinish hook below — executeJobDetached finalizes the run in-process, so
-        // the monitor tick never sees the live transition. Never let a notification
-        // failure break the trigger.
         try {
             notifyRoutineStart(config);
         }
-        catch { /* best-effort */ }
+        catch { }
         try {
             const meta = await executeJobDetached(config, {
                 onFinish: (final) => {
@@ -1182,11 +714,7 @@ export async function runDaemon() {
                     try {
                         notifyRoutineFinish(final);
                     }
-                    catch { /* best-effort */ }
-                    // RUSH-2288: a failed/timed-out routine also reaches the OWNER's phone
-                    // (in-process owner channel stack), not just the local desktop. Green
-                    // runs are silent — the builder returns early. Async + swallowed so a
-                    // delivery hiccup never blocks the finish path.
+                    catch { }
                     void notifyOwnerRoutineFinish(final)
                         .then((r) => {
                         if (r.attempts.length && !r.delivered)
@@ -1205,17 +733,10 @@ export async function runDaemon() {
                 status: 'failed',
                 detail: redactSecrets(message).slice(0, 500),
             });
-            // RUSH-2030: the START ping already fired unconditionally above. A pre-spawn
-            // failure produces no run record and thus no onFinish, so send a synthetic
-            // "failed to start" finish here — otherwise the user is left with an orphaned
-            // "Routine started" and never told it failed.
             try {
                 notifyRoutineStartFailed(config, message);
             }
-            catch { /* best-effort */ }
-            // RUSH-2288: the pre-spawn failure (e.g. auth_failed) is exactly the one the
-            // per-routine `agents send --to owner` prompt can never send — its agent never ran —
-            // so the daemon reaches the owner directly.
+            catch { }
             void notifyOwnerRoutineStartFailed(config, message)
                 .then((r) => {
                 if (r.attempts.length && !r.delivered)
@@ -1224,13 +745,6 @@ export async function runDaemon() {
                 .catch(() => { });
         }
     };
-    // `scheduler` is declared earlier (before the CatchupService registration) to
-    // avoid a TDZ read during supervisor.startAll — see the comment there.
-    // Boot the scheduler. Called at daemon start when the gate allows, and again
-    // from handleReload when the gate flips on. Catch-up recovery is a separate
-    // supervised service (CatchupService, registered above) that self-gates on
-    // `scheduler !== null`; here we just kick an immediate supervised pass so a
-    // fresh boot catches up missed fires without waiting a full CATCHUP_TICK_MS.
     function bootScheduler() {
         scheduler = new JobScheduler(triggerJob);
         scheduler.loadAll();
@@ -1242,14 +756,10 @@ export async function runDaemon() {
         if (supervisor.isRegistered('catchup'))
             supervisor.runNow('catchup');
     }
-    // Stop the scheduler (gate flipped off on reload). The CatchupService keeps its
-    // supervised timer but its tick no-ops once `scheduler` is null.
     function stopScheduler() {
         scheduler?.stopAll();
         scheduler = null;
     }
-    // Materialise opted-in project routines into the user layer on every start
-    // so a fresh daemon picks up project YAML without a separate sync step.
     try {
         const result = syncAllProjectRoutines();
         const n = result.projects.reduce((acc, p) => acc + p.synced.length, 0);
@@ -1261,36 +771,6 @@ export async function runDaemon() {
     }
     if (schedulerEnabledAtBoot)
         bootScheduler();
-    // Live-session metadata publishing is owned by SessionStateService. Its
-    // presence watcher requests an immediate supervised tick when a reader
-    // connects; callers consume the journal instead of duplicating the gather.
-    // Session-index warm (RUSH-2682) is registered on the supervisor above
-    // (RUSH-3193 P2) alongside the socket services.
-    // Watchdog and device-probe are now managed by WatchdogService /
-    // DeviceProbeService on the supervisor (RUSH-3193 P3), registered above
-    // alongside the socket services. The supervisor fires an immediate first
-    // tick on start, which replaces device-probe's old `void
-    // runDeviceProbeTick()` kick-off (the 3-minute lag that used to leave the
-    // menubar showing 20 phantom NEW DEVICES after a hermetic leak).
-    // Monitor engine is now managed by MonitorEngineService on the supervisor
-    // (RUSH-3193 P2). Access it via monitorEngineSvc.getEngine() in handleReload.
-    // Backlog recovery: any enabled recurring job whose most-recent expected fire
-    // is older than its most-recent recorded run was missed — the laptop slept,
-    // the machine was off, or the daemon crashed through the fire. croner only
-    // schedules forward from "now", so nothing replays it on its own.
-    //
-    // Every miss is RECORDED as a `missed` run and, unless the routine sets
-    // `catchup: false`, RUN late. Runs on a timer as well as at startup: a startup
-    // pass alone misses a fire lost while the daemon stayed up but its event loop
-    // was wedged, or one lost across an OS suspend that the process survived.
-    // A pass awaits executeJobDetached per job and an off-box (host/cloud)
-    // dispatch can block for a while. Overlap is now guarded by the supervisor's
-    // per-service inFlight guard (CatchupService) — a slow pass never overlaps the
-    // next supervised tick — rather than a local `catchingUp` flag; and the
-    // idempotency of the `missed` record still guards across passes and daemon
-    // restarts. `signal` aborts at the CatchupService deadline, so a wedged pass is
-    // abandoned + restarted instead of latching (PHNX-3608). Function declaration
-    // (hoisted) so the CatchupService registration above can reference it.
     async function catchupPass(signal) {
         try {
             const overdue = detectOverdueJobs();
@@ -1306,9 +786,6 @@ export async function runDaemon() {
             notifyOverdue(overdue);
             const outcomes = await runCatchup({ overdue });
             for (const o of outcomes) {
-                // Every variant handled explicitly: a catch-all else would log the
-                // benign 'claimed-elsewhere' (another process legitimately won the
-                // claim) as an ERROR with an undefined reason.
                 switch (o.result) {
                     case 'ran':
                         log('INFO', `Caught up '${o.name}' (run: ${o.runId})`);
@@ -1323,9 +800,6 @@ export async function runDaemon() {
                         log('ERROR', `Catchup for '${o.name}' failed: ${o.error}`);
                         break;
                     default: {
-                        // Compile-time exhaustiveness: a new CatchupOutcome variant fails
-                        // typecheck here rather than silently landing in the wrong log level,
-                        // which is exactly how 'claimed-elsewhere' was first missed.
                         const unhandled = o.result;
                         log('ERROR', `Catchup for '${o.name}' returned an unhandled result: ${String(unhandled)}`);
                     }
@@ -1333,76 +807,23 @@ export async function runDaemon() {
             }
         }
         catch (err) {
-            // Ordinary pass errors are logged, not re-thrown: a transient catchup
-            // failure should not be counted as a service failure. A HANG is still
-            // caught — the CatchupService deadline aborts the tick and the supervisor
-            // exits the daemon for an OS restart regardless of this swallow (PHNX-4116).
             log('ERROR', `Catchup pass failed: ${err.message}`);
         }
     }
-    // The browser IPC server and its orphan reap left this daemon with the
-    // standalone `browser` CLI (PHNX-4101) — it hosts its own IPC service now.
-    // Webhook receivers: signed webhook receiver(s) + their funnel (RUSH-2548).
-    // Resolves each receiver's signing secret headlessly through the standalone
-    // `secrets` CLI (an agentOnly secrets-client read) — no AGENTS_SECRETS_PASSPHRASE,
-    // no nohup. Binds nothing unless daemon/webhooks.yaml declares a receiver, so an
-    // unconfigured box no-ops.
-    // Signed webhook ingress is owned by WebhookReceiverService, including
-    // per-service failure isolation, measured health, and shutdown cleanup.
-    // Resource self-heal is now managed by SelfHealService on the supervisor
-    // (RUSH-3193 P3), registered above alongside the socket services. The
-    // supervisor's immediate first tick on start replaces the old
-    // SELF_HEAL_KICKOFF_MS (30s) delayed kickoff timer — see self-heal-service.ts.
-    // The secrets broker's self-heal and keychain-reap ticks (formerly
-    // SecretsBrokerService / KeychainReapService, RUSH-1817 / RUSH-2232) moved
-    // out of this daemon entirely with the standalone `secrets` engine
-    // (PHNX-3989 OWN-1) — the standalone owns its own broker lifecycle.
-    // RUSH-2501: reap tmux sessions whose panes are all dead. Daemon-only
-    // (single executor). Dead managed panes and their orphan helpers are
-    // reaped by TmuxReapService.
-    // Abandoned browser-task reaping (RUSH-2622) left this daemon with the
-    // standalone `browser` CLI (PHNX-4101) — its own `prune` reaper owns it now.
-    // RUSH-2367 / RUSH-3193 P3: state-dir-check (self-terminate guard) is
-    // registered on the supervisor further below, once `handleShutdown` exists
-    // — see the registration site after its declaration for why.
-    // RUSH-2418: startup is over — the scheduler, feed stream, monitor engine and
-    // every background tick are up. Only NOW does this daemon
-    // clear the auto-start failure streak `ensureDaemonStarted` reads. Clearing it
-    // at claim time instead would reset the breaker for a process that dies while
-    // initializing a subsystem, which is exactly the crash loop it exists to stop.
+    // Clear the start-failure streak only after every startup subsystem is live.
     recordSubsystemOk(SUBSYSTEM_DAEMON_START);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
-        // Re-read per-service toggles so `agents daemon services enable|disable`
-        // followed by `agents daemon reload` is truthful. Most services require a
-        // restart to start/stop safely; log those instead of pretending they applied.
         const reloadedConfig = readDaemonServicesConfig();
         const reloadedEnabled = (id) => reloadedConfig.services[id] !== false;
         for (const id of Object.keys(servicesConfig.services)) {
             const was = servicesConfig.services[id] !== false;
             const now = reloadedEnabled(id);
             if (was !== now) {
-                // The scheduler is not a supervised service — its gate is re-evaluated
-                // live later in this handler, so don't tell the user to restart for it.
                 if (id === 'scheduler') {
                     continue;
                 }
-                // RUSH-3193 P4: a service the supervisor already owns takes the toggle
-                // live via supervisor.start/stop — no restart needed. monitors is a
-                // supervised service (PHNX-3608): its enable/disable takes effect through
-                // that generic supervisor.start/stop path, so a disabled monitors service
-                // actually stops dispatching (its supervised tick is torn down) instead of
-                // being ticked with the last-loaded set. browser-ipc is deliberately
-                // registered in a stopped state too (PHNX-3605), so a later browser client
-                // can enable that service without restarting the shared daemon. Most other
-                // services are only registered when enabled at boot; one disabled at boot
-                // was never registered, so it falls through to the same "restart to apply"
-                // advice as before.
                 if (supervisor.isRegistered(id)) {
-                    // A periodic service may be inside a real tick when SIGHUP arrives.
-                    // Queue the desired transition behind that exact promise: deadlines
-                    // detect a wedge but cannot cancel arbitrary work, and polling here
-                    // would create another lifecycle timer outside the supervisor.
                     const action = supervisor.awaitIdle(id).then(() => now ? supervisor.start(id) : supervisor.stop(id));
                     void action
                         .then(() => log('INFO', `Service '${id}' ${now ? 'started' : 'stopped'} live (SIGHUP reload)`))
@@ -1413,9 +834,7 @@ export async function runDaemon() {
                 }
             }
         }
-        // Remember the reloaded state so subsequent reloads log transitions truthfully.
         servicesConfig = reloadedConfig;
-        // Drain queued `agents daemon services restart <id>` requests (RUSH-3193 P4).
         for (const id of drainDaemonServiceRestartQueue()) {
             if (supervisor.isRegistered(id)) {
                 void supervisor.awaitIdle(id).then(() => supervisor.restartOne(id))
@@ -1426,9 +845,6 @@ export async function runDaemon() {
                 log('WARN', `Restart requested for '${id}' but it is not supervisor-managed on this daemon — restart the daemon instead`);
             }
         }
-        // Refresh user-layer copies of opted-in project routines BEFORE the
-        // scheduler reloads, so YAML edits under `<project>/.agents/routines/`
-        // take effect on the next fire without a manual `routines sync`.
         try {
             const result = syncAllProjectRoutines();
             const n = result.projects.reduce((acc, p) => acc + p.synced.length, 0);
@@ -1439,11 +855,6 @@ export async function runDaemon() {
         catch (err) {
             log('WARN', `Project routines sync failed: ${err.message}`);
         }
-        // Re-evaluate the scheduler.enabled gate: flipping the key takes effect on
-        // this reload, no daemon restart needed. A `routines add` on a re-enabled
-        // box signals exactly this reload, which boots the scheduler — the
-        // "Scheduler reloaded" it prints is then truthful, not a dead-end.
-        // Also honour the daemon-services toggle.
         const schedulerEnabledNow = isSchedulerEnabled() && reloadedEnabled('scheduler');
         const transition = schedulerGateTransition(scheduler !== null, schedulerEnabledNow);
         if (transition === 'boot') {
@@ -1459,12 +870,6 @@ export async function runDaemon() {
             const reloaded = scheduler.listScheduled();
             log('INFO', `Reloaded ${reloaded.length} jobs`);
         }
-        // Refresh monitor CONFIGS when the engine is live and monitors stays enabled
-        // (the common `monitors add/edit` + SIGHUP case). The enable/disable
-        // TRANSITION itself is handled by the generic supervisor.start/stop loop
-        // above (PHNX-3608) — a disabled monitors service is supervisor.stop()'d
-        // there, which tears down its supervised tick so nothing dispatches; an
-        // off-transition leaves getEngine() null, so this reload is correctly skipped.
         const liveMonitorEngine = monitorEngineSvc.getEngine();
         if (liveMonitorEngine && reloadedEnabled('monitors')) {
             try {
@@ -1475,18 +880,9 @@ export async function runDaemon() {
             }
         }
     };
-    // Structurally single-shot (RUSH-2423). Shutdown is reachable from SIGTERM,
-    // SIGINT, and StateDirCheckService's independent `onMissing` callback (which
-    // calls this same handler), and two of those can arrive together — a
-    // service manager that SIGTERMs a daemon whose state dir was just removed.
-    // It was only INCIDENTALLY safe before (every step inside happens to be
-    // idempotent); the guard makes single-shot a property of the function
-    // rather than one that every step added later has to re-earn.
+    // Cleanup removes lifetime, pid, heartbeat, and registry state only when each still belongs to this instance.
     const handleShutdown = singleShot(async () => {
         log('INFO', 'Daemon shutting down');
-        // supervisor.stopAll() stops every registered service, including socket
-        // hosts, session publishers/indexers, monitor/account work, and every
-        // maintenance timer; state-dir-check joins the registry just below.
         await supervisor.stopAll();
         activeServiceSupervisor = null;
         stopScheduler();
@@ -1495,7 +891,6 @@ export async function runDaemon() {
                 fs.unlinkSync(lifetimePath);
         }
         catch {
-            // Already removed with the state dir, or replaced by a newer owner.
         }
         removeDaemonPidIfOwned(process.pid);
         if (readHeartbeat()?.pid === process.pid)
@@ -1503,14 +898,6 @@ export async function runDaemon() {
         unregisterDaemonInstance();
         process.exit(0);
     });
-    // State-dir self-check (RUSH-2367 self-terminate guard) is registered on
-    // the supervisor here — AFTER `handleShutdown` above — rather than
-    // alongside watchdog/device-probe/self-heal earlier. The
-    // supervisor fires an immediate first tick on `register()`+`start()`; doing
-    // that before `handleShutdown` exists would reference the const in its
-    // temporal dead zone the moment a mismatch is ever detected. Registering it
-    // here, once `handleShutdown` is a real function, removes that risk
-    // entirely rather than relying on the marker always matching on tick one.
     if (isEnabled('state-dir-check')) {
         supervisor.register(new StateDirCheckService({
             lifetimePath,
@@ -1523,13 +910,10 @@ export async function runDaemon() {
         log('INFO', 'State-dir self-check disabled');
     }
     liveReloadHandler = guardSignalHandler(handleReload, (err) => {
-        // Signal callbacks sit outside the supervisor's service barriers. A
-        // reload failure must be observable without reaching the process-wide
-        // uncaughtException handler and taking down every daemon service.
         try {
             log('ERROR', `SIGHUP reload failed: ${err.message}`);
         }
-        catch { /* logging must not crash the daemon */ }
+        catch { }
     });
     if (reloadRequestedDuringStartup) {
         reloadRequestedDuringStartup = false;
@@ -1540,22 +924,13 @@ export async function runDaemon() {
     process.on('SIGINT', () => handleShutdown());
     await new Promise(() => { });
 }
-/** Escape a string for safe inclusion in an XML <string> node. */
 function xmlEscape(s) {
     return s
         .replace(/&/g, '&amp;')
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
-/**
- * Write a launchd plist or systemd unit with owner-only permissions atomically.
- *
- * `writeFileSync`'s `mode` is honored only when the file is *created*, so we
- * unlink any pre-existing manifest first. That guarantees every write is a
- * fresh 0600 create — closing the TOCTOU window on new files AND re-locking a
- * stale world-readable manifest left by an older install — since these files
- * embed long-lived credentials.
- */
+// Manifests are owner-only and carry only the canonical HOME/AGENTS_REAL_HOME/PATH surface.
 export function writeOwnerOnlyServiceManifest(filePath, content) {
     const dir = path.dirname(filePath);
     if (!fs.existsSync(dir)) {
@@ -1564,29 +939,6 @@ export function writeOwnerOnlyServiceManifest(filePath, content) {
     fs.rmSync(filePath, { force: true });
     fs.writeFileSync(filePath, content, { encoding: 'utf-8', mode: 0o600 });
 }
-/**
- * Generate a macOS launchd plist for auto-starting the daemon.
- *
- * The plist never embeds a Claude OAuth token: the daemon holds no Claude
- * credential at all. Routine runs authenticate through the per-account
- * CLAUDE_CONFIG_DIR login on this device, exactly like an interactive
- * `agents run`, so no credential ever touches the service manifest.
- *
- * RUSH-2639: launchd does NOT inherit `launchctl load`'s caller's process
- * environment — a spawned daemon only ever sees the login session's default
- * env plus whatever this dict adds/overrides. Before this fix the dict carried
- * only PATH, so HOME resolved to the launchd session's own value regardless of
- * what HOME the process that generated (and loaded) the plist was running
- * under. In production that's a no-op (the login session's HOME already is the
- * real HOME), but under a hermetic test harness that redirects HOME to a
- * fork-private sandbox, a launchd-started daemon silently escaped the sandbox
- * and bootstrapped `~/.agents` (.cache/.history/.system/routines) in the
- * developer's/runner's REAL home. Baking HOME (and the AGENTS_REAL_HOME seam
- * every version-home consumer honors, see tests/setup.ts) into the plist at
- * generation time makes the launchd child inherit the SAME home the caller
- * resolved, exactly like the plain detached-spawn path already does via
- * `env: {...process.env}`.
- */
 export function generateLaunchdPlist(agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
     const logPath = getDaemonLogPath();
@@ -1623,25 +975,9 @@ ${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</
 </dict>
 </plist>`;
 }
-/** Quote one systemd ExecStart argument without delegating parsing to a shell. */
 function systemdExecArg(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
-/**
- * Generate a Linux systemd user unit for auto-starting the daemon.
- *
- * The unit never embeds a Claude OAuth token: the daemon holds no Claude
- * credential at all. Routine runs authenticate through the per-account
- * CLAUDE_CONFIG_DIR login on this device, exactly like an interactive
- * `agents run`, so no credential ever touches the unit file.
- *
- * RUSH-2639: same seam as `generateLaunchdPlist` — a systemd --user unit is
- * started by the user's systemd instance, not the process that generated the
- * unit, so HOME is whatever that session provides unless this file pins it.
- * Baking HOME (and AGENTS_REAL_HOME) in at generation time keeps a
- * hermetic-test-started unit inside its sandbox instead of resolving against
- * the real account home.
- */
 export function generateSystemdUnit(agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
     const execStart = [launch.command, ...launch.args].map(systemdExecArg).join(' ');
@@ -1664,26 +1000,9 @@ Environment=AGENTS_REAL_HOME=${realHome}
 [Install]
 WantedBy=default.target`;
 }
-// Binary-resolution helpers (getAgentsBinPath / isNodeScriptEntry / getCliLaunch)
-// live in ./cli-entry.js — a leaf module. Re-exported so existing
-// `from './daemon.js'` importers of getAgentsBinPath keep resolving.
 export { getAgentsBinPath };
-/**
- * Ask the service manager for the daemon's live PID. Used as a fallback when
- * the daemon hasn't yet written its pid file but launchd/systemd already report
- * it running — so a start never has to surface a null PID for a daemon that is
- * in fact up. Returns null when the service isn't running or the query fails.
- *
- * `names` defaults to THIS process's (possibly sandbox-namespaced) job; a
- * caller under a redirected HOME passes `productionDaemonServiceNames()` to
- * ask after the real install's unit instead. Read-only either way.
- */
 export function readServiceManagerPid(platform = os.platform(), names) {
     const resolved = names ?? { systemdUnit: daemonSystemdUnitName(), launchdLabel: daemonServiceLabel() };
-    // The registration gate exists because a sandboxed process must not REGISTER
-    // or tear down jobs in the real per-user service manager. Asking after an
-    // explicitly named job is read-only — in particular the production unit from
-    // a redirected-HOME caller (W4) — and mutates nothing, so it is let through.
     if (names === undefined && !serviceManagerRegistrationAllowed().allowed)
         return null;
     try {
@@ -1701,32 +1020,13 @@ export function readServiceManagerPid(platform = os.platform(), names) {
             }
         }
     }
-    catch { /* not running / manager unavailable */ }
+    catch { }
     return null;
 }
-/**
- * Thrown when a daemon LAUNCH is attempted under a redirected HOME without the
- * explicit test opt-in (W4, PHNX-3736). `bootstrap.ts` prints the message
- * without a stack — this is user-actionable, not an engineering bug.
- */
 export class RedirectedHomeDaemonError extends Error {
     name = 'RedirectedHomeDaemonError';
 }
-/**
- * W4 (PHNX-3736): never LAUNCH a daemon under a redirected (sandbox/test) HOME
- * without an explicit opt-in. A daemon started there keeps its own pid file
- * under the temp home, so the real install's pid-file takeover can never see
- * it — the leaked `HOME=/tmp/pin-e2e-<pid>` daemon that ran 4+ days on
- * yosemite-s1 was launched exactly this way by a headless e2e session that
- * never cleaned up. RUSH-3021 closed this for `ensureDaemonStarted`'s
- * AUTO-start path but left the explicit `startDaemon()` open, which is the
- * path the e2e harness took.
- *
- * Placed after the `already-running` early-return: reporting a live daemon (so
- * `daemon stop` can still kill a leaked one) must stay possible under any
- * HOME. `AGENTS_ALLOW_TEST_DAEMON=1` is the deliberate test/e2e seam — a
- * harness that sets it owns stopping what it starts.
- */
+// A redirected HOME daemon is invisible to production takeover and can outlive its sandbox, so explicit test opt-in is required.
 function assertDaemonLaunchHomeAllowed() {
     const suffix = isolatedHomeSuffix();
     if (!suffix)
@@ -1738,10 +1038,7 @@ function assertDaemonLaunchHomeAllowed() {
         `install's pid-file takeover, and outlives whatever launched it (PHNX-3736). ` +
         `For a deliberate test/e2e launch set AGENTS_ALLOW_TEST_DAEMON=1 — and stop the daemon when done.`);
 }
-/** Start the daemon via launchd, systemd, or as a detached process. */
 export function startDaemon(agentsBin) {
-    // The public launcher must obey the same namespace boundary as its child:
-    // even probing/repairing legacy PID state or pruning a lock can mutate it.
     if (!daemonProcessViewAllowed())
         throw new Error('Daemon startup requires the owning process namespace. Automatic reuse of a private-container HOME across namespaces is unsupported; run in its owning namespace or use a fresh HOME.');
     if (isDaemonRunning()) {
@@ -1751,14 +1048,9 @@ export function startDaemon(agentsBin) {
     assertDaemonLaunchHomeAllowed();
     const releaseLock = acquireStartLock();
     if (!releaseLock) {
-        // Another process is already starting the daemon
         const pid = waitForPid(3000);
         return { pid, method: 'already-starting' };
     }
-    // Released by startDaemonLocked the moment the launch has been ISSUED, and
-    // again here as the backstop for every path that returned before reaching
-    // that point (a throw, or the platform default branch). Idempotent so the
-    // double call is a no-op rather than unlinking a lock a later claimer owns.
     let released = false;
     const releaseOnce = () => {
         if (released)
@@ -1766,26 +1058,11 @@ export function startDaemon(agentsBin) {
         released = true;
         releaseLock();
     };
-    // RUSH-2418: count starts PESSIMISTICALLY, and let a daemon that reaches
-    // steady state clear the streak itself (`recordSubsystemOk` at the end of
-    // runDaemon's startup). Recording a failure only on an observable error would
-    // miss the crash loop entirely: a daemon that spawns and then dies returns a
-    // perfectly real `child.pid`, so the launcher has no error to see. Every path
-    // out of startDaemonLocked is either pid-truthy or a throw, so an
-    // outcome-shaped check here can only ever catch an unspawnable binary — not
-    // the failure this breaker exists for. Marking the attempt up front and
-    // clearing on proven health inverts that: the streak grows exactly when
-    // starts stop producing a daemon that lives.
-    //
-    // The no-launch returns above (`already-running`, `already-starting`) return
-    // before this point on purpose — they attempted nothing, so they count nothing.
     recordSubsystemError(SUBSYSTEM_DAEMON_START, 'start issued; no daemon has reported healthy since');
     try {
         return startDaemonLocked(agentsBin ?? getAgentsBinPath(), releaseOnce);
     }
     catch (err) {
-        // Replace the provisional reason with the real one — the streak is already
-        // counted, this just makes `agents daemon doctor` name the actual cause.
         recordSubsystemErrorReason(SUBSYSTEM_DAEMON_START, `start failed: ${err?.message ?? String(err)}`);
         throw err;
     }
@@ -1793,60 +1070,17 @@ export function startDaemon(agentsBin) {
         releaseOnce();
     }
 }
-/**
- * Is the auto-start circuit breaker open (RUSH-2418)? True once
- * {@link DAEMON_AUTOSTART_FAILURE_LIMIT} consecutive starts have failed to
- * produce a daemon that reported healthy. Pure read of the persisted health
- * record, and `agents daemon doctor` reports the same record — the message the
- * breaker prints has to lead somewhere that can explain it.
- */
 export function isDaemonAutostartCircuitOpen() {
     const health = readSubsystemHealth(SUBSYSTEM_DAEMON_START);
     return (health?.consecutiveFailures ?? 0) >= DAEMON_AUTOSTART_FAILURE_LIMIT;
 }
-/**
- * Bring the always-on daemon up as a side effect of a background-adjacent
- * command (secrets unlock, browser start, ...), not only from `routines add`.
- *
- * Delegates to the single `startDaemon` entrypoint, so it honors the
- * single-instance start lock and is a no-op when a daemon is already running
- * (returns `already-running`). Best-effort: any failure is swallowed and null
- * returned, so ensuring the daemon can never break the foreground command that
- * happened to bring it up. See issue #415.
- */
 export function ensureDaemonStarted() {
-    // RUSH-2354: honor daemon.enabled — a background-adjacent caller (secrets
-    // unlock, browser start, ...) must not resurrect a daemon the owner
-    // explicitly turned off. `agents daemon start` is the deliberate override
-    // and calls startDaemon() directly instead of going through this helper.
     if (!isDaemonEnabled())
         return null;
-    // A live daemon is the answer whatever the failure history says — the breaker
-    // gates LAUNCHING one, never reporting one that is already up. Checked first
-    // so a stale failure streak can't make a healthy daemon read as absent to
-    // callers that branch on this return (e.g. secrets/agent.ts).
     if (isDaemonRunning())
         return startDaemon();
-    // RUSH-3021: never LAUNCH a daemon from a redirected (sandbox/test) HOME.
-    // #2860 gated service-manager registration on this signal but left the
-    // detached spawn itself ungated, so a test-spawned CLI could fork a daemon
-    // into the test's temp HOME; the child outlives the test and races its
-    // recursive teardown rm (ENOTEMPTY). Placed after the already-running branch
-    // — reporting a live daemon stays allowed, same as the circuit breaker.
-    // AGENTS_SERVICE_MANAGER_ALLOW_REDIRECTED_HOME=1 is the test seam for suites
-    // that exercise daemon startup deliberately. The explicit `agents daemon
-    // start` path is gated separately by startDaemon's own redirected-HOME
-    // refusal (AGENTS_ALLOW_TEST_DAEMON=1, W4/PHNX-3736).
     if (!serviceManagerRegistrationAllowed().allowed)
         return null;
-    // RUSH-2418: the auto-start circuit breaker. A daemon that dies during
-    // startup would otherwise be relaunched by EVERY foreground command that
-    // wants one (secrets unlock, browser start, watchdog, ...) — an
-    // application-level crash loop the OS supervisor's throttle cannot see,
-    // because each attempt is a fresh service start rather than a respawn. After
-    // DAEMON_AUTOSTART_FAILURE_LIMIT consecutive failures, refuse and say why.
-    // Deliberately NOT applied in startDaemon(): `agents daemon start` is the
-    // operator's override and must always be able to retry.
     if (isDaemonAutostartCircuitOpen()) {
         process.stderr.write(`[agents] daemon auto-start disabled after ${DAEMON_AUTOSTART_FAILURE_LIMIT} consecutive failed starts. ` +
             `Run 'agents daemon doctor' to diagnose, or 'agents daemon start' to retry anyway.\n`);
@@ -1859,29 +1093,9 @@ export function ensureDaemonStarted() {
         return null;
     }
 }
-/**
- * Issue the launch, then wait for the child to record its pid.
- *
- * RUSH-2417: the wait phase MUST NOT hold the start lock. `acquireStartLock`
- * and `claimDaemonInstance` resolve the same `<daemonDir>/daemon.lock`, so a
- * parent that busy-waits on `waitForPid` while still holding it deterministically
- * defeats the child it just launched: the child's `claimDaemonInstance` hits
- * EEXIST, reads a holder pid that IS alive (this process), and exits with the
- * false "another daemon is mid-takeover" warning — every launchd/systemd start
- * on a fresh install. The lock's job is to keep two concurrent `startDaemon()`
- * calls from both launching, and that is done once `launchctl load` /
- * `systemctl start` / the detached spawn has been issued, so `releaseLock()` is
- * called there rather than in the caller's `finally`.
- *
- * Releasing early cannot produce two daemons: launchd (one plist label) and
- * systemd (one unit) are singletons that no-op a second start, and the detached
- * path is covered by `claimDaemonInstance`'s last-wins takeover (SING-11) —
- * a second claimer evicts the incumbent rather than running beside it.
- */
+// Release the start lock before the child claims it; manager success is not health until pid/heartbeat proof appears.
 function startDaemonLocked(agentsBin, releaseLock) {
     const platform = os.platform();
-    // Same contract on the fallback path: the spawn IS the launch, so the lock is
-    // dropped before the child exists rather than in a `finally` the child races.
     const detachedFallback = () => {
         releaseLock();
         return startDetached({ agentsBin });
@@ -1895,28 +1109,18 @@ function startDaemonLocked(agentsBin, releaseLock) {
                 if (!fs.existsSync(plistDir)) {
                     fs.mkdirSync(plistDir, { recursive: true });
                 }
-                // The plist carries no credential (RUSH-1759 — the daemon reads the OAuth
-                // token itself at startup); still create owner-only atomically to match the
-                // detached path and keep the log/PATH surface owner-private.
                 writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist(agentsBin));
                 try {
                     execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
                 }
-                catch { /* not loaded, expected */ }
-                // launchctl prints `Load failed:` and exits 0 when the label is in a
-                // stuck state from a prior session — so a zero exit code isn't proof
-                // of success. If no pid materializes within the window, give up on
-                // launchd and fall through to a plain detached spawn.
+                catch { }
                 execFileSync('launchctl', ['load', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-                // Launch issued — the child needs this lock to claim (RUSH-2417).
                 releaseLock();
                 const pid = waitForPid(3000) ?? readServiceManagerPid();
                 if (pid)
                     return { pid, method: 'launchd' };
-                // launchctl claimed success but nothing ran. Fall through.
             }
             catch {
-                // load threw — fall through to detached spawn
             }
         }
         else {
@@ -1932,22 +1136,16 @@ function startDaemonLocked(agentsBin, releaseLock) {
                 if (!fs.existsSync(unitDir)) {
                     fs.mkdirSync(unitDir, { recursive: true });
                 }
-                // Carries no credential (RUSH-1759 — the daemon reads the OAuth token
-                // itself at startup); owner-only to keep the PATH/log surface private.
                 writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit(agentsBin));
                 execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
                 execFileSync('systemctl', ['--user', 'enable', daemonSystemdUnitName()], { encoding: 'utf-8' });
                 execFileSync('systemctl', ['--user', 'start', daemonSystemdUnitName()], { encoding: 'utf-8' });
-                // Launch issued — the child needs this lock to claim (RUSH-2417).
                 releaseLock();
                 const pid = waitForPid(3000) ?? readServiceManagerPid();
                 if (pid)
                     return { pid, method: 'systemd' };
-                // systemctl returned success but no PID surfaced — fall through to a
-                // plain detached spawn rather than reporting a null PID.
             }
             catch {
-                // start threw — fall through to detached spawn
             }
         }
         else {
@@ -1957,74 +1155,19 @@ function startDaemonLocked(agentsBin, releaseLock) {
     }
     return startDetached({ agentsBin });
 }
-/**
- * Resolve how to launch the daemon: `node <entry> __daemon-run`, matching the
- * exact form that works under a direct `__daemon-run`.
- *
- * We spawn the Node runtime (`process.execPath`) with the CLI entry as an
- * argument rather than executing the entry path directly. Executing the `.js`
- * path relies on its shebang on POSIX, and on Windows CreateProcess can't run a
- * `.js`/shim directly at all — it gets launched through a transient
- * console-owning wrapper (cmd.exe / the npm shim). When that wrapper exits it
- * closes its console, and the detached daemon sharing that console receives a
- * console-close event that trips its shutdown handler — the daemon comes up,
- * binds its sockets, then tears itself down ~36ms later (#556).
- * Going through `process.execPath` means a real PE/binary is spawned with
- * `detached: true` and no console, so nothing signals the daemon after launch.
- *
- * When the entry isn't a Node script (e.g. a native compiled launcher), run it
- * directly — it owns its own runtime resolution.
- */
 export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
     const { warnings } = validateDaemonBinary(agentsBin);
     for (const w of warnings)
         process.stderr.write(`[agents] ${w}\n`);
     return getCliLaunch(['__daemon-run'], agentsBin);
 }
-/**
- * The directory of the Node runtime that generated this service manifest, kept
- * first on the daemon's PATH. Both the shim's shebang and any child routine
- * process then resolve the exact Node that installed the service — never an
- * ancient system node or a pruned nvm version. Replaces the old hardcoded
- * `~/.nvm/versions/node/v24.0.0/bin`, which went stale the moment that patch
- * release was upgraded away and bricked the daemon fleet-wide.
- */
 function daemonNodeBinDir() {
     return path.dirname(process.execPath);
 }
-/**
- * Login-shell user-bin dirs a service-manager-started daemon would otherwise
- * miss. systemd/launchd pin PATH and never source `~/.profile`, so they never
- * see `~/.rush/bin` (where `rush` lands) or `~/.local/bin` (XDG user-bin).
- * Monitor `notify` and dispatched `agents run` children inherit this PATH;
- * without these dirs the rush-backed owner channel fails with
- * `rush CLI not found on PATH` (PHNX-3075) while an interactive shell on the
- * same box succeeds. Uses the same HOME the manifest bakes (RUSH-2639).
- */
 function daemonUserBinDirs() {
     const home = serviceManifestHomeEnv().HOME;
     return [path.join(home, '.rush', 'bin'), localBinDir(home)];
 }
-/**
- * The full PATH value the daemon service manifest pins, in order: the directory
- * of the `agents` shim itself FIRST, then the Node runtime dir, then login-shell
- * user-bin dirs (`~/.rush/bin`, `~/.local/bin`), then the platform's system dirs.
- *
- * The shim's own dir must lead so a scheduled `command` routine that shells out
- * to the bare name `agents` (`/bin/sh -c 'agents repo pull system'`) resolves the
- * SAME binary the daemon is running. When the Node runtime dir came first, a
- * stale `agents` install inside that dir (common with nvm or an npm global in the
- * same Node prefix) shadowed the current binary and routines failed with an
- * `unknown command` error against the wrong build.
- *
- * The Node runtime dir stays second so the shim's shebang (`#!/usr/bin/env node`)
- * still resolves the exact Node that installed the service — never an ancient
- * system node or a pruned nvm version. User-bin dirs sit after that pair so a
- * `~/.local/bin/agents` cannot shadow the daemon binary, but `rush` (and other
- * login-shell CLIs) still resolve. Deduped across the whole list, so a
- * Node/shim dir that already appears among the system dirs (e.g. a
- * `/usr/local/bin` install) never doubles.
- */
 function daemonPathValue(agentsBin, systemDirs) {
     return [...new Set([
             path.dirname(agentsBin),
@@ -2033,34 +1176,9 @@ function daemonPathValue(agentsBin, systemDirs) {
             ...systemDirs,
         ])].join(':');
 }
-/**
- * Build the argv to relaunch the `agents` CLI with the given subcommand args.
- *
- * Resolves the real on-disk binary via getAgentsBinPath(), then dispatches: a
- * `.js` entry runs under node (`node <entry> …`), a native/compiled binary runs
- * directly (`<bin> …`).
- *
- * Callers MUST route self-spawns through this rather than hand-rolling
- * `[process.execPath, process.argv[1], …]`: under the compiled standalone binary
- * (#315) `process.argv[1]` is the bun virtual entry `/$bunfs/root/agents`, so the
- * hand-rolled form becomes `agents /$bunfs/root/agents …` → the CLI receives the
- * bunfs path as a subcommand and dies with "unknown command '/$bunfs/root/agents'".
- * getAgentsBinPath() resolves that virtual entry to the physical process.execPath.
- */
 export function getAgentsInvocation(subArgs, agentsBin = getAgentsBinPath()) {
     return getCliLaunch(subArgs, agentsBin);
 }
-/**
- * A daemon binary living under an ephemeral path — a git worktree, or a temp
- * directory (`/tmp`, `/var/folders`, `/dev/shm`) — is a latent wedge. The daemon
- * is long-lived but resolves its own job modules by dynamic `import()` rooted at
- * this entry (getAgentsBinPath → process.argv[1]). If that directory is later
- * removed (`git worktree remove`, a `/tmp` cleanup, a review/verify checkout
- * teardown) the running daemon keeps ENOENT-ing on every job it loads —
- * `anchorDaemonCwd` rescues the cwd, but nothing can re-root a deleted module
- * tree. Returns a human phrase naming the ephemeral kind, or null for a stable
- * install path (version home, a global npm prefix, a normal source checkout).
- */
 export function describeEphemeralDaemonRoot(binPath) {
     if (/[/\\]\.agents[/\\]worktrees[/\\]/.test(binPath))
         return 'a git worktree';
@@ -2090,25 +1208,14 @@ export function startDetached(opts = {}) {
     const logPath = opts.logPath ?? getDaemonLogPath();
     const logFd = fs.openSync(logPath, 'a');
     const { command, args } = getDaemonLaunch(agentsBin);
-    // fdStdio: the log-file fds make windowsHide inert (libuv skips
-    // CREATE_NO_WINDOW when a stdio fd is inherited), so on Windows the daemon
-    // must DETACH to own no console — otherwise it shares the launcher's console
-    // and a console-close event tears it down when the launcher exits (#556).
     const child = spawn(command, args, {
         stdio: ['ignore', logFd, logFd],
         ...backgroundSpawnOptions({ cwd: os.homedir(), fdStdio: true }),
         env: opts.env ?? process.env,
     });
-    // A failed spawn (ENOENT/EACCES) emits 'error' asynchronously; without a
-    // listener that would crash the parent as an unhandled EventEmitter error.
-    // The synchronous `!child.pid` guard below is what reports the failure loudly.
     child.on('error', () => { });
     child.unref();
     fs.closeSync(logFd);
-    // `spawn` leaves `pid` undefined only when the process could not be created.
-    // Returning null here (the old `child.pid || null`) let callers report
-    // "PID: null" as if the daemon had started — a start with no PID is a failed
-    // start, so fail loudly instead of manufacturing a phantom success.
     if (!child.pid) {
         throw new Error(`Failed to start daemon: spawning '${command}' produced no PID (binary missing or not executable?)`);
     }
@@ -2125,11 +1232,6 @@ function waitForPid(timeoutMs) {
     }
     return readDaemonPid();
 }
-/**
- * Read the pid a state file claims, or null when it is absent/unreadable/not
- * pid-shaped. The lifetime marker stores `<pid>:<epochMs>`; the heartbeat
- * stores JSON with a `pid`.
- */
 function claimedPid(read) {
     try {
         return read();
@@ -2138,17 +1240,6 @@ function claimedPid(read) {
         return null;
     }
 }
-/**
- * The lifetime marker, heartbeat, and instance-registry entry, described so
- * {@link stopDaemon} can assert them the same way it asserts the two sockets.
- *
- * Ownership, not mere presence, decides: a file naming a pid that is alive and
- * is not the daemon we just stopped belongs to a DIFFERENT daemon (a successor
- * that started during the stop, or a peer serving this state dir), and deleting
- * it would break that live daemon — the same reasoning the broker-socket branch
- * above uses for a standalone owner. Everything else is residue from a provably
- * dead owner and is reclaimed.
- */
 export function stopResidueArtifacts(stoppedPid, survivors = []) {
     const artifacts = [];
     const lifetimePath = path.join(getDaemonDir(), LIFETIME_FILE);
@@ -2165,7 +1256,7 @@ export function stopResidueArtifacts(stoppedPid, survivors = []) {
         reclaim: () => { try {
             fs.unlinkSync(lifetimePath);
         }
-        catch { /* raced with a fresh start */ } },
+        catch { } },
         stillPresent: () => fs.existsSync(lifetimePath),
     });
     const heartbeatPath = getHeartbeatPath();
@@ -2173,33 +1264,16 @@ export function stopResidueArtifacts(stoppedPid, survivors = []) {
     artifacts.push({
         label: 'daemon heartbeat',
         present: fs.existsSync(heartbeatPath),
-        // A stale heartbeat is not cosmetic: resolveLiveDaemonPid() trusts a FRESH
-        // one to re-adopt a daemon whose pid file was lost, so leaving one behind
-        // can make a dead daemon read as running.
         ownedByLiveOther: hb !== null && (survivors.includes(hb.pid)
             || (hb.pid !== stoppedPid && isAlive(hb.pid))),
         reclaim: () => removeHeartbeat(),
         stillPresent: () => fs.existsSync(heartbeatPath),
     });
-    // POSIX-only, matching registerDaemonInstance/unregisterDaemonInstance.
     if (process.platform !== 'win32' && stoppedPid !== null) {
         const markerPath = path.join(getDaemonInstancesDir(), String(stoppedPid));
         artifacts.push({
             label: 'daemon instance registry entry',
             present: fs.existsSync(markerPath),
-            // The marker is named by pid, so it is unambiguously this daemon's — but
-            // "this daemon" is only residue once it is actually DEAD. If the kill did
-            // not land, deleting the marker erases the very record
-            // `findSurvivingStateDirDaemons` enumerates, so the next `agents daemon
-            // stop` would find an empty registry and a cleared pid file and report
-            // `ok: true` with the daemon still running.
-            //
-            // "Dead" is decided by the caller's OWN survivor scan, not by `isAlive`:
-            // a SIGKILLed child is a zombie until its parent reaps it, and `kill(pid,
-            // 0)` succeeds on a zombie. Keyed off `isAlive` this kept the entry of a
-            // daemon that was already gone, so the stop stopped being able to report
-            // its own state truthfully. The survivor scan matches a live
-            // `__daemon-run`, which a zombie is not.
             ownedByLiveOther: survivors.includes(stoppedPid),
             reclaim: () => unregisterDaemonInstance(stoppedPid),
             stillPresent: () => fs.existsSync(markerPath),
@@ -2207,22 +1281,6 @@ export function stopResidueArtifacts(stoppedPid, survivors = []) {
     }
     return artifacts;
 }
-/**
- * Live `__daemon-run` processes still registered in THIS state dir's instance
- * registry, excluding `exclude`. State-dir-scoped by construction: the registry
- * lives inside this state dir, so a daemon serving a DIFFERENT state dir (a test
- * fixture with its own HOME, a separate install/home) registers elsewhere and is
- * invisible here — it is never a stop/takeover target. POSIX-only (the registry
- * and its `ps` liveness probe are); `[]` on Windows.
- *
- * Exported for `agents daemon status`/`doctor`/`services` (RUSH-2368): those
- * commands previously flagged every `__daemon-run` on the box (a raw `ps` scan)
- * as a "duplicate" of this daemon, which misreported test fixtures under their
- * own HOME — and therefore their own state dir and registry — as strays to
- * kill. This registry read is the same scope the reaper (`reapStrayDaemons`)
- * and the stop postcondition (`stopDaemon`) already use, so the display and the
- * reaper agree on what a duplicate is.
- */
 function findStateDirDaemonProcesses(exclude) {
     const live = [];
     const unverified = [];
@@ -2239,7 +1297,7 @@ function findStateDirDaemonProcesses(exclude) {
     for (const name of entries) {
         const pid = parseInt(name, 10);
         if (isNaN(pid) || String(pid) !== name)
-            continue; // not a pid marker
+            continue;
         if (exclude.has(pid))
             continue;
         const identity = daemonProcessIdentity(pid);
@@ -2253,17 +1311,7 @@ function findStateDirDaemonProcesses(exclude) {
 export function findSurvivingStateDirDaemons(exclude) {
     return findStateDirDaemonProcesses(exclude).live;
 }
-/**
- * Stop the daemon and ASSERT its postcondition (SING-12, RUSH-2355), unloading it
- * from launchd/systemd if applicable.
- *
- * The SIGTERM → grace → killTree sequence is unchanged; what it adds is
- * verification: after the daemon is gone it checks that no `__daemon-run` for
- * THIS state dir survives and reclaims the state files a killTree escalation
- * (which skips the graceful handleShutdown) can leave stale. The browser IPC
- * socket is no longer among them — it left with the standalone `browser` CLI
- * (PHNX-4101). It never reports success on an unverified stop.
- */
+// Stop crosses the same lifecycle lock as start and claim, preventing teardown from racing takeover.
 export function stopDaemon() {
     const releaseLock = acquireLifecycleLock();
     if (!releaseLock) {
@@ -2296,7 +1344,6 @@ function pathIdentityMatches(filePath, expected) {
     const current = readPathIdentity(filePath);
     return current !== null && current.dev === expected.dev && current.ino === expected.ino;
 }
-/** daemon.lock is held for this entire read-signal-verify-cleanup transaction. */
 function stopDaemonLocked() {
     const platform = os.platform();
     const released = [];
@@ -2314,9 +1361,6 @@ function stopDaemonLocked() {
             detachedChildren: listLiveRoutineChildren(),
         };
     }
-    // Capture the target and its path-bound resources while lifecycle writers are
-    // excluded. resolveLiveDaemonPid(true) rejects a reused/non-daemon pid before
-    // any service-manager teardown or direct signal and repairs only under lock.
     const pid = resolveLiveDaemonPid(true);
     if (platform === 'darwin') {
         const plistPath = getLaunchdPlistPath();
@@ -2337,7 +1381,7 @@ function stopDaemonLocked() {
             try {
                 fs.unlinkSync(plistPath);
             }
-            catch { /* plist already removed */ }
+            catch { }
         }
     }
     if (platform === 'linux') {
@@ -2360,14 +1404,11 @@ function stopDaemonLocked() {
             try {
                 fs.unlinkSync(unitPath);
             }
-            catch { /* unit file already removed */ }
+            catch { }
         }
     }
     if (pid) {
         if (process.platform === 'win32') {
-            // Windows has no graceful termination signal — terminate the daemon and
-            // its job/browser child tree in one shot (taskkill /T), so stop doesn't
-            // report success while children keep running.
             if (isLiveDaemon(pid)) {
                 killTree(pid);
                 escalated = true;
@@ -2375,22 +1416,11 @@ function stopDaemonLocked() {
             }
         }
         else {
-            // Revalidate immediately before the signal: the pid may have exited and
-            // been reused since the ownership snapshot above.
             if (isLiveDaemon(pid)) {
                 try {
                     process.kill(pid, 'SIGTERM');
                 }
-                catch { /* process already exited */ }
-                // Wait for it to actually go. This used to be a setTimeout escalation plus
-                // an immediate removeDaemonPid(), which had two failure modes: in a
-                // short-lived process (the npm postinstall) the timer never fired at all,
-                // and clearing the pid file while the old daemon still ran made
-                // isDaemonRunning() report false, so startDaemon() launched a SECOND
-                // daemon. Its hosted broker then unlinked the live socket and rebound,
-                // orphaning the first broker with every unlocked bundle still in its RAM
-                // and unreachable — two brokers on one socket path, seen on a real machine
-                // after an install into a second prefix.
+                catch { }
                 if (!waitForExit(pid, STOP_GRACE_MS) && isLiveDaemon(pid)) {
                     killTree(pid);
                     escalated = true;
@@ -2399,13 +1429,9 @@ function stopDaemonLocked() {
             }
         }
     }
-    // ── Assert the postcondition (SING-12) ────────────────────────────────────
-    // No `__daemon-run` for this state dir may survive the stop.
     const stateDirProcesses = findStateDirDaemonProcesses(new Set([process.pid]));
     const survivors = stateDirProcesses.live;
     const unverifiedSurvivors = stateDirProcesses.unverified;
-    // The registry is best-effort and may be missing, so always re-check the
-    // direct target as well. This is the only check available on Windows.
     if (pid && !survivors.includes(pid) && !unverifiedSurvivors.includes(pid)) {
         const identity = daemonProcessIdentity(pid);
         if (identity === 'daemon')
@@ -2425,9 +1451,6 @@ function stopDaemonLocked() {
     if (pid && !targetStillOwnsResources) {
         released.push('daemon process');
     }
-    // Delete the registration only after the target is provably gone, and only
-    // if the file still names that target. A replacement value belongs to a
-    // successor (or another writer) and is both preserved and reported.
     const currentPid = readDaemonPid();
     if (pid !== null && !targetStillOwnsResources) {
         if (removeDaemonPidIfOwned(pid))
@@ -2443,19 +1466,6 @@ function stopDaemonLocked() {
     else if (pid === null && currentPid !== null) {
         surviving.push(`daemon pid registration changed to ${currentPid} during stop`);
     }
-    // The browser IPC socket is the standalone `browser` CLI's now (PHNX-4101):
-    // the daemon no longer binds it, so there is nothing to reclaim here. browser-cli
-    // owns its own socket lifecycle under `~/.agents/.cache/helpers/browser/`.
-    // ── The state files a killed daemon cannot clean up itself (RUSH-2421) ─────
-    // handleShutdown removes the lifetime marker, the heartbeat and this pid's
-    // instance-registry entry — but it only runs on the GRACEFUL path. Every
-    // escalation above (killTree, and the whole win32 branch) skips it, so those
-    // three outlive the daemon and the stop reported `ok: true` while its state
-    // dir still described a daemon that no longer exists. Each is stale metadata
-    // with real consequences: a leftover heartbeat is what `resolveLiveDaemonPid`
-    // consults to re-adopt a "live" daemon, and a leftover registry entry is what
-    // `reapStrayDaemons` enumerates. Same shape as the sockets above — reclaim
-    // what a provably dead owner left, never touch what a live one owns.
     for (const artifact of stopResidueArtifacts(pid, [...survivors, ...unverifiedSurvivors])) {
         if (!artifact.present) {
             released.push(artifact.label);
@@ -2471,8 +1481,6 @@ function stopDaemonLocked() {
         else
             released.push(`${artifact.label} (reclaimed)`);
     }
-    // In-flight detached routine children survive on purpose (SING-11a) — report,
-    // never kill: severing a live agent mid-run is worse than a daemon restart.
     const detachedChildren = listLiveRoutineChildren();
     return {
         ok: surviving.length === 0,
@@ -2483,14 +1491,6 @@ function stopDaemonLocked() {
         detachedChildren,
     };
 }
-/**
- * Get current daemon status including running state, PID, enabled job count, and
- * the supervised-restart history `agents daemon status` renders (PHNX-4116).
- *
- * There is no `wedged` state: a stalled daemon exits for a supervised
- * systemd/launchd restart rather than sitting unresponsive, so the daemon is
- * simply `running` or `stopped`, and its recent restarts are reported instead.
- */
 export function getDaemonStatus() {
     const running = isDaemonRunning();
     const pid = readDaemonPid();
@@ -2498,12 +1498,12 @@ export function getDaemonStatus() {
     try {
         jobCount = listAllJobs().filter((j) => j.enabled).length;
     }
-    catch { /* job listing failed */ }
+    catch { }
     let binaryPath = null;
     try {
         binaryPath = getAgentsBinPath();
     }
-    catch { /* resolution failed */ }
+    catch { }
     const recentRestarts = readRecentDaemonRestarts(Date.now() - 24 * 60 * 60 * 1000);
     const lastRestart = recentRestarts.length > 0 ? recentRestarts[recentRestarts.length - 1] : null;
     return {
@@ -2519,7 +1519,6 @@ export function getDaemonStatus() {
         lastRestartAt: lastRestart ? lastRestart.at : null,
     };
 }
-/** Read the daemon log, optionally limited to the last N lines. */
 export function readDaemonLog(lines) {
     const logPath = getDaemonLogPath();
     if (!fs.existsSync(logPath))
@@ -2530,15 +1529,11 @@ export function readDaemonLog(lines) {
     const allLines = content.split('\n');
     return allLines.slice(-lines).join('\n');
 }
-/** Send SIGHUP to the daemon to trigger a job reload. */
 export function signalDaemonReload() {
     const pid = readDaemonPid();
     if (!pid)
         return false;
     if (process.platform === 'win32') {
-        // Windows has no SIGHUP, so signal-based live reload isn't available. Sending
-        // it would throw; instead report "not reloaded" so callers tell the user to
-        // restart the daemon to pick up job changes.
         return false;
     }
     try {