@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/lib/daemon.js

@@ -10,7 +10,7 @@ import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { getDaemonDir as getDaemonDirRoot } from './state.js';
+import { getDaemonDir } from './state.js';
 import { isAlive, killTree, backgroundSpawnOptions, waitForExit } from './platform/index.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { syncAllProjectRoutines } from './routines-project.js';
@@ -26,9 +26,13 @@ import { BrowserIPCServer, getSocketPath as getBrowserIpcSocketPath } from './br
 import { secretsBrokerSocketPath, brokerPidAlive } from './secrets/agent.js';
 import { redactSecrets } from './redact.js';
 import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from './cli-entry.js';
-import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled } from './device-config.js';
+import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled, getConfigValue } from './device-config.js';
 import { reapTerminalRoutineProcesses } from './routine-process-cleanup.js';
-import { recordSubsystemOk, recordSubsystemError, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC } from './daemon-health.js';
+import { recordSubsystemOk, recordSubsystemError, recordSubsystemErrorReason, readSubsystemHealth, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC, SUBSYSTEM_DAEMON_START } from './daemon-health.js';
+import { startAccountStateService } from './account-state-service.js';
+import { runActiveSessionsWarmTick, runFleetCacheWarmTick, runUsageRefreshTick } from './daemon-ticks.js';
+import { emit, emitRoutineEnd } from './events.js';
+import { readDaemonServicesConfig } from './daemon-services.js';
 const PID_FILE = 'daemon.pid';
 const LIFETIME_FILE = 'daemon.lifetime';
 const LOCK_FILE = 'daemon.lock';
@@ -47,7 +51,68 @@ const MONITOR_TICK_MS = 60_000;
  * wedge or an OS suspend the process survived.
  */
 const CATCHUP_TICK_MS = 5 * 60_000;
+/**
+ * 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). Each is a deliberate trade, not a round number:
+ *
+ * - **Self-heal** repairs slow rot (a stale non-default version, an invalid
+ *   plugin manifest), so it is cheap to be late and expensive to run often —
+ *   hence 6h, plus one staggered kickoff shortly after start so shims and PATH
+ *   settle without making launch itself busy.
+ * - **Broker self-heal** is a bare `agentPing`, and the failure it recovers
+ *   from wedges every keychain-backed secret on the box, so it runs minutely.
+ * - **Keychain reap** shells `ps` once per pass; 5 min bounds that cost while
+ *   still clearing orphans well inside a human's attention span.
+ * - **State-dir self-check** is two `fs` reads. Its env override exists for
+ *   tests, which cannot wait a minute to observe the self-terminate guard.
+ */
+const SELF_HEAL_TICK_MS = 6 * 60 * 60_000;
+const SELF_HEAL_KICKOFF_MS = 30_000;
+const BROKER_SELF_HEAL_TICK_MS = 60_000;
+const KEYCHAIN_REAP_TICK_MS = 5 * 60_000;
+// RUSH-2501: reap tmux sessions whose panes are all dead every 5 minutes.
+const DEAD_PANE_REAP_TICK_MS = 5 * 60_000;
+const STATE_DIR_CHECK_TICK_MS = 60_000;
+// Watchdog nudges this host's own stalled sessions; device-probe refreshes
+// registered devices' reachability and surfaces newly appeared tailnet nodes.
+// Both are daemon-owned housekeeping timers, NOT routines (RUSH-2495) — plain
+// in-process intervals the daemon holds directly, same cadence the old timers ran.
+const WATCHDOG_TICK_MS = 3 * 60_000;
+const DEVICE_PROBE_TICK_MS = 3 * 60_000;
+// Keep the active-session cache/journal fresh for sessions watch + Factory.
+// Matches DEFAULT_ACTIVE_CACHE_MAX_AGE_MS (15s) so long-lived watchers never
+// outlive the publisher (RUSH-2484 — CLI-owned continuous publish).
+const ACTIVE_SESSIONS_WARM_TICK_MS = 15_000;
 const WEDGE_THRESHOLD_TICKS = 3;
+/**
+ * Crash-loop prevention (RUSH-2418). Three layers, because none of them alone
+ * bounds a daemon that dies during startup:
+ *
+ * 1. **The OS supervisor paces the respawn.** `KeepAlive` with no
+ *    `ThrottleInterval` lets launchd relaunch on its ~10s default, so a daemon
+ *    that dies while booting is restarted six times a minute forever — the exact
+ *    failure the menu-bar helper hit (`menubar/install-menubar.ts`: 38 orphaned
+ *    `agents doctor` children, load average 490). systemd's `Restart=always`
+ *    with no `StartLimit*` is the same uncapped loop.
+ * 2. **`StartLimitBurst` gives systemd a real cap** — after this many starts
+ *    inside the interval the unit is put in `failed` and stops respawning, so a
+ *    genuinely broken install stops burning the box and `systemctl --user status`
+ *    names it. launchd has no burst equivalent; the throttle is its whole answer.
+ * 3. **The application-level circuit breaker** below stops *auto*-starts from
+ *    re-entering the loop from the other direction — a foreground command that
+ *    calls `ensureDaemonStarted()` on every invocation.
+ */
+const DAEMON_THROTTLE_SECONDS = 30;
+const DAEMON_START_LIMIT_INTERVAL_SECONDS = 300;
+const DAEMON_START_LIMIT_BURST = 5;
+/**
+ * How many consecutive failed daemon starts disable the *implicit* auto-start
+ * (`ensureDaemonStarted`). Matches `DAEMON_START_LIMIT_BURST` so the two layers
+ * give up together rather than one silently masking the other. `agents daemon
+ * start` is the deliberate override and is never gated by this.
+ */
+export const DAEMON_AUTOSTART_FAILURE_LIMIT = 5;
 /**
  * RUSH-1817: decide whether the daemon should (re)take over hosting the secrets
  * broker. The startup host decision is one-shot; this drives the periodic
@@ -64,16 +129,44 @@ export function schedulerGateTransition(running, enabled) {
         return enabled ? 'reload' : 'stop';
     return enabled ? 'boot' : 'none';
 }
-function getDaemonDir() {
-    const dir = getDaemonDirRoot();
+/**
+ * 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.
+ */
+export function singleShot(fn) {
+    let ran = false;
+    return async () => {
+        if (ran)
+            return;
+        ran = true;
+        await fn();
+    };
+}
+function ensureDaemonDir() {
+    const dir = getDaemonDir();
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
 function getPidPath() {
-    return path.join(getDaemonDir(), PID_FILE);
+    return path.join(ensureDaemonDir(), PID_FILE);
 }
 function getLockPath() {
-    return path.join(getDaemonDir(), LOCK_FILE);
+    return path.join(ensureDaemonDir(), LOCK_FILE);
 }
 /**
  * Acquire an exclusive start lock. Returns a release function on success,
@@ -116,8 +209,16 @@ function acquireStartLock() {
         throw err;
     }
 }
-function getLogPath() {
-    return path.join(getDaemonDir(), LOG_FILE);
+/**
+ * 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);
 }
 function getLaunchdPlistPath() {
     return path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_NAME}.plist`);
@@ -150,7 +251,7 @@ export function removeDaemonPid() {
     }
 }
 function getHeartbeatPath() {
-    return path.join(getDaemonDir(), HEARTBEAT_FILE);
+    return path.join(ensureDaemonDir(), HEARTBEAT_FILE);
 }
 export function writeHeartbeat(pid = process.pid) {
     const hb = { lastTick: new Date().toISOString(), pid };
@@ -327,23 +428,23 @@ function evictIncumbentDaemon(pid) {
     killTree(pid); // positive pid: SIGKILL reaches the daemon, not its job children
     waitForExit(pid, STOP_KILL_GRACE_MS);
 }
-/** Directory that registers every live daemon of THIS device (one per daemon dir). */
+/** Directory that registers every live daemon of THIS device (one per state dir). */
 function getDaemonInstancesDir() {
-    return path.join(getDaemonDirRoot(), 'instances');
+    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
- * daemon dir (`AGENTS_DAEMON_DIR` ?? `<HOME>/.agents/.cache/helpers/daemon`), every
+ * 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 daemon dir and is invisible here. This is what fixes the two-entry pile-up:
+ * 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 daemon dir directly is
+ * 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).
  */
@@ -461,7 +562,7 @@ function rotateLogsIfNeeded(logPath) {
 }
 /** Append a JSONL log entry to the daemon log file (owner-only permissions). */
 export function log(level, message) {
-    const logPath = getLogPath();
+    const logPath = getDaemonLogPath();
     rotateLogsIfNeeded(logPath);
     const entry = { ts: new Date().toISOString(), level: level.toUpperCase(), message: redactSecrets(message) };
     fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf-8');
@@ -469,6 +570,22 @@ export function log(level, message) {
         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`.
+    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';
+        emit(event, {
+            module: 'daemon',
+            detail: redactSecrets(message).slice(0, 500),
+            status: lvl,
+        });
+    }
+    catch { /* never crash the daemon on event-log failure */ }
 }
 /** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 /**
@@ -532,6 +649,129 @@ export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
         return null;
     }
 }
+// ---------------------------------------------------------------------------
+// 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.
+//
+// Two functions (runBrokerSelfHeal, runStateDirSelfCheck) remain inline:
+//   • runBrokerSelfHeal closes over `hostedBroker` — a mutable runDaemon-
+//     local var also used by handleShutdown; lifting it requires both vars to
+//     be module-level, which is wider scope than this ticket.
+//   • runStateDirSelfCheck closes over `lifetimePath` and `lifetimeToken` —
+//     per-boot constants that cannot be pre-computed at module load time.
+// ---------------------------------------------------------------------------
+// In-flight guards: each flag prevents a slow tick from being re-entered
+// by the next timer fire before the previous one finishes.
+let healing = false;
+let reapingKeychain = false;
+let reapingDeadPanes = false;
+/**
+ * Resource self-heal: fill missing resources, repair invalid manifests, and
+ * fast-forward pristine stale plugins. Conservative 'safe' mode: never
+ * overwrites hand-edited content. Runs ~every 6h plus once ~30s after startup.
+ *
+ * Does not run when the daemon's state directory no longer exists — that is the
+ * self-terminate guard's signal to shut down; background maintenance must not
+ * recreate the tree while it is mid-exit.
+ */
+async function runHealCheck() {
+    if (healing)
+        return;
+    if (!fs.existsSync(getDaemonDir()))
+        return;
+    healing = true;
+    try {
+        const { runSelfHeal, selfHealChangedAnything, selfHealNeedsAttention, summarizeSelfHeal } = await import('./self-heal/registry.js');
+        if (!fs.existsSync(getDaemonDir()))
+            return;
+        const report = await runSelfHeal({ mode: 'safe' });
+        if (selfHealChangedAnything(report) || selfHealNeedsAttention(report)) {
+            log('INFO', `self-heal: ${summarizeSelfHeal(report)}`);
+        }
+    }
+    catch (err) {
+        log('ERROR', `self-heal check failed: ${err.message}`);
+    }
+    finally {
+        healing = false;
+    }
+}
+/**
+ * Keychain orphan reaper: kill stuck keychain helper and `agents` processes
+ * whose keychain call never returned. Runs every 5 min. Single-executor: only
+ * the daemon runs this, so no cross-device race.
+ */
+async function runKeychainReap() {
+    if (reapingKeychain)
+        return;
+    reapingKeychain = true;
+    try {
+        const { reapOrphanedKeychainProcesses } = await import('./secrets/reaper.js');
+        const result = reapOrphanedKeychainProcesses();
+        if (result.reaped > 0) {
+            log('WARN', `Reaped ${result.reaped} keychain orphan/stuck process(es)`);
+            for (const d of result.details)
+                log('WARN', `  ${d}`);
+        }
+    }
+    catch (err) {
+        log('ERROR', `Keychain reaper failed: ${err.message}`);
+    }
+    finally {
+        reapingKeychain = false;
+    }
+}
+/**
+ * RUSH-2501: kill tmux sessions on the helper socket whose panes are ALL dead.
+ * RUSH-2521: and terminate the helper processes (MCP servers, harness background
+ * daemons) whose owning agent has exited — killing the pane only SIGHUPs its
+ * foreground process group, so anything that left that group outlives it.
+ *
+ * Runs every DEAD_PANE_REAP_TICK_MS (5 min). The daemon is the single executor
+ * so no UI surface can race it.
+ */
+async function runDeadPaneReap() {
+    if (reapingDeadPanes)
+        return;
+    reapingDeadPanes = true;
+    try {
+        const { reapDeadTmuxPanes } = await import('./tmux/session.js');
+        const { getDefaultSocketPath } = await import('./tmux/paths.js');
+        const result = await reapDeadTmuxPanes(getDefaultSocketPath());
+        for (const w of result.warnings)
+            log('WARN', `Dead-pane reaper: ${w}`);
+        if (result.processes > 0) {
+            log('INFO', `Dead-pane reaper: terminated ${result.processes} orphaned helper process(es)`);
+            for (const d of result.processDetails)
+                log('INFO', `  ${d}`);
+        }
+        if (result.reaped > 0) {
+            log('INFO', `Dead-pane reaper: reaped ${result.reaped} session(s)`);
+            for (const d of result.details)
+                log('INFO', `  killed ${d}`);
+        }
+    }
+    catch (err) {
+        log('ERROR', `Dead-pane reaper failed: ${err.message}`);
+    }
+    finally {
+        reapingDeadPanes = false;
+    }
+}
+/**
+ * One monitor tick: write heartbeat + drain the running-job monitor + reap
+ * stale terminal routine process groups. Runs on MONITOR_TICK_MS.
+ */
+function runMonitorTick() {
+    writeHeartbeat();
+    monitorRunningJobs();
+    const reaped = reapTerminalRoutineProcesses();
+    if (reaped.length > 0)
+        log('WARN', `Reaped ${reaped.length} terminal routine process group(s): ${reaped.join(', ')}`);
+}
 export async function runDaemon() {
     // Single-instance guard (last-wins, SING-11): a direct `agents __daemon-run`
     // (manual, or a service-manager restart racing a live predecessor) EVICTS the
@@ -546,13 +786,29 @@ export async function runDaemon() {
     }
     // 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 tree still exists.
-    const lifetimePath = path.join(getDaemonDirRoot(), LIFETIME_FILE);
+    // 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();
+    // Fold legacy per-device config stores into the central
+    // fleet.devices.<name>.config block (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 { migrateDeviceConfigToCentral } = await import('./devices/config-migration.js');
+        migrateDeviceConfigToCentral();
+    }
+    catch (err) {
+        log('WARN', `device config migration 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
@@ -584,22 +840,27 @@ export async function runDaemon() {
     // here must not stop the daemon. Retiring the standalone launchd service is
     // the follow-on (#416 step 2 / #417).
     let hostedBroker = null;
-    try {
-        const { agentPing, startHostedBroker } = await import('./secrets/agent.js');
-        if ((await agentPing()).reachable) {
-            log('INFO', 'Secrets broker already running (standalone); daemon not hosting it');
+    if (isEnabled('secrets-broker')) {
+        try {
+            const { agentPing, startHostedBroker } = await import('./secrets/agent.js');
+            if ((await agentPing()).reachable) {
+                log('INFO', 'Secrets broker already running (standalone); daemon not hosting it');
+            }
+            else {
+                hostedBroker = await startHostedBroker();
+                if (hostedBroker)
+                    log('INFO', 'Secrets broker hosted in daemon (socket-first)');
+            }
+            recordSubsystemOk(SUBSYSTEM_SECRETS_BROKER);
         }
-        else {
-            hostedBroker = await startHostedBroker();
-            if (hostedBroker)
-                log('INFO', 'Secrets broker hosted in daemon (socket-first)');
+        catch (err) {
+            const message = err.message;
+            log('WARN', `Secrets broker host skipped: ${message}`);
+            recordSubsystemError(SUBSYSTEM_SECRETS_BROKER, message);
         }
-        recordSubsystemOk(SUBSYSTEM_SECRETS_BROKER);
     }
-    catch (err) {
-        const message = err.message;
-        log('WARN', `Secrets broker host skipped: ${message}`);
-        recordSubsystemError(SUBSYSTEM_SECRETS_BROKER, message);
+    else {
+        log('INFO', 'Secrets broker service disabled; daemon not hosting it');
     }
     // 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
@@ -608,7 +869,9 @@ export async function runDaemon() {
     // (`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.
-    const schedulerEnabledAtBoot = isSchedulerEnabled();
+    // 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 {
             assertSchedulerEnabled();
@@ -616,6 +879,8 @@ export async function runDaemon() {
         catch (err) {
             log('WARN', err.message);
         }
+        if (!isEnabled('scheduler'))
+            log('INFO', 'Scheduler service disabled; no routines will fire');
     }
     const triggerJob = async (config, ctx) => {
         const jobLabel = config.command
@@ -624,6 +889,13 @@ export async function runDaemon() {
                 ? `workflow: ${config.workflow}`
                 : `agent: ${config.agent}`;
         log('INFO', `Triggering job '${config.name}' (${jobLabel})`);
+        emit('routine.start', {
+            module: 'routine',
+            name: config.name,
+            kind: config.command ? 'command' : config.workflow ? 'workflow' : 'agent',
+            ...(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
@@ -636,6 +908,7 @@ export async function runDaemon() {
         try {
             const meta = await executeJobDetached(config, {
                 onFinish: (final) => {
+                    emitRoutineEnd(final);
                     try {
                         notifyRoutineFinish(final);
                     }
@@ -657,6 +930,11 @@ export async function runDaemon() {
         catch (err) {
             const message = err.message;
             log('ERROR', `Job '${config.name}' failed to spawn: ${message}`);
+            emitRoutineEnd({
+                jobName: config.name,
+                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
@@ -718,22 +996,137 @@ export async function runDaemon() {
     }
     if (schedulerEnabledAtBoot)
         bootScheduler();
-    // watchdog, device-probe, tmux-reconcile, launch-health, fleet-cache-warm,
-    // session-cache-warm, usage-refresh, and auto-dispatch used to be hardcoded
-    // setInterval ticks here (RUSH-2353). They are now shipped system routines
-    // (gh:phnx-labs/.agents-system routines/*.yml), invoked one-shot via
-    // `agents __daemon-tick <name>` (see daemon-ticks.ts) and fired by the
-    // JobScheduler above like any other routine — declared, listed, run-tracked,
-    // pausable, and device-pinnable, instead of a second unowned scheduling path.
+    // Usage and authentication are first-party device state, so the daemon owns
+    // their timers directly rather than scheduling them as built-in routines.
+    // Explicit CLI refreshes converge on the same cross-process refresh leases.
+    const accountStateService = isEnabled('account-state')
+        ? startAccountStateService({
+            refreshUsage: runUsageRefreshTick,
+            refreshAuth: runFleetCacheWarmTick,
+            onError: (area, error) => log('WARN', `${area} state refresh failed: ${error.message}`),
+        })
+        : null;
+    if (!accountStateService)
+        log('INFO', 'Account-state service disabled');
+    // Active-sessions publish-own: continuous journal writer for `sessions watch`.
+    // Fire once immediately so a cold daemon does not leave watchers on
+    // "awaiting publisher" for a full tick (RUSH-2484).
+    let activeSessionsWarmInFlight = false;
+    const runActiveSessionsWarm = async () => {
+        if (activeSessionsWarmInFlight)
+            return;
+        activeSessionsWarmInFlight = true;
+        try {
+            await runActiveSessionsWarmTick();
+        }
+        catch (err) {
+            log('WARN', `active-sessions warm failed: ${err.message}`);
+        }
+        finally {
+            activeSessionsWarmInFlight = false;
+        }
+    };
+    void runActiveSessionsWarm();
+    const activeSessionsWarmInterval = setInterval(() => { void runActiveSessionsWarm(); }, ACTIVE_SESSIONS_WARM_TICK_MS);
+    // Watchdog: nudge this host's own stalled agent sessions. Gated on the
+    // `watchdog.enabled` device-config flag (`agents watchdog enable`), so the
+    // timer always fires but only does work when the user opted in. Overlap-safe
+    // via the in-flight guard (a slow pass never overlaps the next tick).
+    let watchdogInterval;
+    if (isEnabled('watchdog')) {
+        let watchdogInFlight = false;
+        const runWatchdogTick = async () => {
+            if (watchdogInFlight)
+                return;
+            watchdogInFlight = true;
+            try {
+                if (getConfigValue('watchdog.enabled').value !== true)
+                    return;
+                const { runWatchdogPass } = await import('./watchdog/service.js');
+                const result = await runWatchdogPass({ nudge: true });
+                log('INFO', `watchdog: ${result.counts.total} live, ${result.counts.stalled} stalled, ${result.counts.nudged} nudged`);
+                emit('watchdog.action', {
+                    module: 'watchdog',
+                    total: result.counts.total,
+                    stalled: result.counts.stalled,
+                    nudged: result.counts.nudged,
+                });
+            }
+            catch (err) {
+                log('WARN', `watchdog tick failed: ${err.message}`);
+            }
+            finally {
+                watchdogInFlight = false;
+            }
+        };
+        watchdogInterval = setInterval(() => { void runWatchdogTick(); }, WATCHDOG_TICK_MS);
+    }
+    else {
+        log('INFO', 'Watchdog service disabled');
+    }
+    // Device probe: refresh registered devices' reachability and detect newly
+    // appeared tailnet nodes, dropping a sentinel per pending device so the
+    // menu-bar helper can surface "NEW DEVICES → Register / Ignore". Refresh mode
+    // never auto-registers a newcomer; a machine without tailscale is a clean
+    // no-op. `reconcilePendingSentinels` re-subtracts the ignore-list AND the
+    // registered roster, so a dismissed or already-known device is never
+    // re-surfaced (RUSH-2495 + registry-empty pollution). On soft-fail (no
+    // tailscale) we still prune registered/ignored sentinels so a hermetic test
+    // leak cannot leave fleet boxes in NEW DEVICES forever.
+    let deviceProbeInterval;
+    if (isEnabled('device-probe')) {
+        let deviceProbeInFlight = false;
+        const runDeviceProbeTick = async () => {
+            if (deviceProbeInFlight)
+                return;
+            deviceProbeInFlight = true;
+            try {
+                const { runDeviceSync } = await import('./devices/sync.js');
+                const { reconcilePendingSentinels, pruneDismissedPendingSentinels, } = await import('./devices/pending.js');
+                const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
+                if (!dev.ok) {
+                    await pruneDismissedPendingSentinels();
+                    if (dev.reason)
+                        log('WARN', `device probe soft-fail: ${dev.reason}`);
+                    return;
+                }
+                await reconcilePendingSentinels(dev.pending);
+                if (dev.pending.length) {
+                    log('INFO', `devices: ${dev.pending.length} new pending (${dev.pending.map((p) => p.name).join(', ')})`);
+                }
+            }
+            catch (err) {
+                log('WARN', `device probe tick failed: ${err.message}`);
+            }
+            finally {
+                deviceProbeInFlight = false;
+            }
+        };
+        // Fire once on start so a leftover pollution set is cleared without waiting
+        // for the first interval tick (the 3-minute lag is how the menubar sat on
+        // 20 phantom NEW DEVICES after a hermetic leak).
+        void runDeviceProbeTick();
+        deviceProbeInterval = setInterval(() => { void runDeviceProbeTick(); }, DEVICE_PROBE_TICK_MS);
+    }
+    else {
+        log('INFO', 'Device-probe service disabled');
+    }
     // Monitor engine: event-triggered watchers, beside the cron scheduler. Same
     // daemon, same dispatch seam — a monitor is a routine whose trigger is a
     // watched source instead of a clock. Reloads on SIGHUP alongside the scheduler.
-    const monitorEngine = new MonitorEngine((level, message) => log(level, message));
-    try {
-        monitorEngine.start();
+    const monitorEngine = isEnabled('monitors')
+        ? new MonitorEngine((level, message) => log(level, message))
+        : null;
+    if (monitorEngine) {
+        try {
+            monitorEngine.start();
+        }
+        catch (err) {
+            log('ERROR', `Monitor engine failed to start: ${err.message}`);
+        }
     }
-    catch (err) {
-        log('ERROR', `Monitor engine failed to start: ${err.message}`);
+    else {
+        log('INFO', 'Monitor engine disabled');
     }
     // Backlog recovery: any enabled recurring job whose most-recent expected fire
     // is older than its most-recent recorded run was missed — the laptop slept,
@@ -744,7 +1137,7 @@ export async function runDaemon() {
     // `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.
-    // Overlap guard, same shape as runHealCheck below. A pass
+    // Overlap guard, same shape as runHealCheck (above). A pass
     // awaits executeJobDetached per job and an off-box (host/cloud) dispatch can
     // block for a while, so a slow pass could still be working when the next tick
     // fires. Both passes would then see a job the first has not yet reached as
@@ -822,66 +1215,36 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Orphan reaper failed: ${err.message}`);
     }
-    const browserService = new BrowserService();
-    const browserIPC = new BrowserIPCServer(browserService);
-    try {
-        await browserIPC.start();
-        log('INFO', 'Browser IPC server started');
-        recordSubsystemOk(SUBSYSTEM_BROWSER_IPC);
-    }
-    catch (err) {
-        const message = err.message;
-        log('ERROR', `Browser IPC failed to start: ${message}`);
-        recordSubsystemError(SUBSYSTEM_BROWSER_IPC, message);
-    }
-    writeHeartbeat();
-    const monitorInterval = setInterval(() => {
-        writeHeartbeat();
-        monitorRunningJobs();
-        const reaped = reapTerminalRoutineProcesses();
-        if (reaped.length > 0)
-            log('WARN', `Reaped ${reaped.length} terminal routine process group(s): ${reaped.join(', ')}`);
-    }, MONITOR_TICK_MS);
-    // Resource safety check: heal gaps between what DotAgents repos define and
-    // what's actually installed in each agent home — the slow rot that nothing
-    // else catches (a non-default version left stale, a Claude-invalid plugin
-    // manifest silently rejecting a whole plugin). Conservative 'safe' mode: it
-    // fills missing resources, repairs invalid manifests, and fast-forwards
-    // provably-unmodified stale plugins, but never overwrites hand-edited content
-    // or a plugin it can't prove is pristine — those it reports for `doctor --fix`.
-    // Runs ~every 6h plus once ~30s after startup (staggered so launch isn't busy).
-    let healing = false;
-    const runHealCheck = async () => {
-        if (healing)
-            return;
-        // The daemon's state directory is its liveness boundary. Once that tree is
-        // removed, background maintenance must not recreate it while the
-        // self-terminate guard is shutting the process down.
-        if (!fs.existsSync(getDaemonDirRoot()))
-            return;
-        healing = true;
+    const browserService = isEnabled('browser-ipc') ? new BrowserService() : null;
+    const browserIPC = browserService ? new BrowserIPCServer(browserService) : null;
+    if (browserIPC) {
         try {
-            const { runSelfHeal, selfHealChangedAnything, selfHealNeedsAttention, summarizeSelfHeal } = await import('./self-heal/registry.js');
-            if (!fs.existsSync(getDaemonDirRoot()))
-                return;
-            // Background heal is conservative (mode: 'safe'): fixes low-risk drift (shims,
-            // symlink adoption, PATH, missing resources) and only reports risky ones. The
-            // 30s kickoff means shims/PATH settle shortly after the daemon starts. No
-            // desktop toast here — background heal is silent by design; the log is the record.
-            const report = await runSelfHeal({ mode: 'safe' });
-            if (selfHealChangedAnything(report) || selfHealNeedsAttention(report)) {
-                log('INFO', `self-heal: ${summarizeSelfHeal(report)}`);
-            }
+            await browserIPC.start();
+            log('INFO', 'Browser IPC server started');
+            recordSubsystemOk(SUBSYSTEM_BROWSER_IPC);
         }
         catch (err) {
-            log('ERROR', `self-heal check failed: ${err.message}`);
-        }
-        finally {
-            healing = false;
+            const message = err.message;
+            log('ERROR', `Browser IPC failed to start: ${message}`);
+            recordSubsystemError(SUBSYSTEM_BROWSER_IPC, message);
         }
-    };
-    const healInterval = setInterval(() => { void runHealCheck(); }, 6 * 60 * 60_000);
-    const healKickoff = setTimeout(() => { void runHealCheck(); }, 30_000);
+    }
+    else {
+        log('INFO', 'Browser IPC service disabled');
+    }
+    runMonitorTick();
+    const monitorInterval = setInterval(runMonitorTick, MONITOR_TICK_MS);
+    // Resource safety check: see runHealCheck above. Runs ~every 6h plus once
+    // ~30s after startup so shims/PATH settle shortly after the daemon starts.
+    let healInterval;
+    let healKickoff;
+    if (isEnabled('self-heal')) {
+        healInterval = setInterval(() => { void runHealCheck(); }, SELF_HEAL_TICK_MS);
+        healKickoff = setTimeout(() => { void runHealCheck(); }, SELF_HEAL_KICKOFF_MS);
+    }
+    else {
+        log('INFO', 'Self-heal service disabled');
+    }
     // RUSH-1817: the startup host decision above is one-shot. If a standalone
     // broker answered agentPing() at daemon start, the daemon declined to host —
     // but should that standalone later die or crash-loop, nothing takes over and
@@ -890,93 +1253,121 @@ export async function runDaemon() {
     // Re-probe on a cadence: whenever the daemon is NOT itself hosting AND no
     // healthy broker answers a ping, take over hosting. startHostedBroker binds
     // the socket only when it is free, so a take-over never races a live broker.
-    let selfHealingBroker = false;
-    const runBrokerSelfHeal = async () => {
-        if (selfHealingBroker)
-            return;
-        selfHealingBroker = true;
-        try {
-            const { agentPing, startHostedBroker } = await import('./secrets/agent.js');
-            const reachable = (await agentPing()).reachable;
-            if (!shouldTakeOverBroker(hostedBroker != null, reachable))
+    // Inline (not module-level): closes over `hostedBroker`, a mutable runDaemon-
+    // local var also closed over by handleShutdown. Lifting it would require
+    // hostedBroker to be module-level state too — wider than this refactor's scope.
+    let brokerSelfHealInterval;
+    if (isEnabled('secrets-broker')) {
+        let selfHealingBroker = false;
+        const runBrokerSelfHeal = async () => {
+            if (selfHealingBroker)
                 return;
-            hostedBroker = await startHostedBroker();
-            if (hostedBroker) {
-                log('WARN', 'Secrets broker was unreachable; daemon took over hosting (self-heal)');
+            selfHealingBroker = true;
+            try {
+                const { agentPing, startHostedBroker } = await import('./secrets/agent.js');
+                const reachable = (await agentPing()).reachable;
+                if (!shouldTakeOverBroker(hostedBroker != null, reachable))
+                    return;
+                hostedBroker = await startHostedBroker();
+                if (hostedBroker) {
+                    log('WARN', 'Secrets broker was unreachable; daemon took over hosting (self-heal)');
+                }
             }
-        }
-        catch (err) {
-            log('WARN', `Secrets broker self-heal skipped: ${err.message}`);
-        }
-        finally {
-            selfHealingBroker = false;
-        }
-    };
-    const brokerSelfHealInterval = setInterval(() => { void runBrokerSelfHeal(); }, 60_000);
+            catch (err) {
+                log('WARN', `Secrets broker self-heal skipped: ${err.message}`);
+            }
+            finally {
+                selfHealingBroker = false;
+            }
+        };
+        brokerSelfHealInterval = setInterval(() => { void runBrokerSelfHeal(); }, BROKER_SELF_HEAL_TICK_MS);
+    }
     // RUSH-2232: reap orphaned keychain helpers and `agents` processes stuck on a
     // keychain call. Runs as a 5-min interval in the daemon (the single executor)
-    // so no UI surface can race it. The reaper shells `ps` once, plans kills in a
-    // pure function, and executes via killTree.
-    let reapingKeychain = false;
-    const runKeychainReap = async () => {
-        if (reapingKeychain)
-            return;
-        reapingKeychain = true;
-        try {
-            const { reapOrphanedKeychainProcesses } = await import('./secrets/reaper.js');
-            const result = reapOrphanedKeychainProcesses();
-            if (result.reaped > 0) {
-                log('WARN', `Reaped ${result.reaped} keychain orphan/stuck process(es)`);
-                for (const d of result.details)
-                    log('WARN', `  ${d}`);
-            }
-        }
-        catch (err) {
-            log('ERROR', `Keychain reaper failed: ${err.message}`);
-        }
-        finally {
-            reapingKeychain = false;
-        }
-    };
-    const keychainReapInterval = setInterval(() => { void runKeychainReap(); }, 5 * 60_000);
+    // so no UI surface can race it. See runKeychainReap above.
+    let keychainReapInterval;
+    if (isEnabled('keychain-reap')) {
+        keychainReapInterval = setInterval(() => { void runKeychainReap(); }, KEYCHAIN_REAP_TICK_MS);
+    }
+    else {
+        log('INFO', 'Keychain-reap service disabled');
+    }
+    // RUSH-2501: reap tmux sessions whose panes are all dead. Runs on the same
+    // 5-min cadence as the keychain reaper. Daemon-only (single executor).
+    void runDeadPaneReap(); // kick-off on startup so the backlog clears immediately
+    const deadPaneReapInterval = setInterval(() => { void runDeadPaneReap(); }, DEAD_PANE_REAP_TICK_MS);
     // RUSH-2367: self-terminate if this daemon's own state dir has been removed
     // out from under it — the shape of a leaked test-fixture daemon whose /tmp
     // HOME was deleted by its test's own cleanup while the process itself
     // somehow survived (lost the SIGTERM/SIGKILL race, or outlived a killed
     // test runner before its `finally` ever ran). Nothing else can reach a
     // daemon in that state: no `agents daemon` command targets it, since a
-    // different HOME resolves a different getDaemonDir() and therefore a
+    // different HOME resolves a different ensureDaemonDir() and therefore a
     // different instance registry — without this it runs forever. Reads
-    // Reads the lifetime marker directly, never the local getDaemonDir() wrapper,
+    // the lifetime marker directly, never the local ensureDaemonDir() wrapper,
     // which recreates the directory as a side effect and would defeat the check.
     // Heartbeat/status paths may recreate the directory and pid file after a
     // deletion; they never recreate this per-lifetime token.
-    let checkingStateDir = false;
-    const runStateDirSelfCheck = () => {
-        if (checkingStateDir)
-            return;
-        checkingStateDir = true;
-        try {
-            let markerMatches = false;
+    // Inline (not module-level): closes over `lifetimePath` and `lifetimeToken`,
+    // per-boot constants computed once at runDaemon() start that cannot be
+    // pre-computed at module load time.
+    let stateDirCheckInterval;
+    if (isEnabled('state-dir-check')) {
+        let checkingStateDir = false;
+        const runStateDirSelfCheck = () => {
+            if (checkingStateDir)
+                return;
+            checkingStateDir = true;
             try {
-                markerMatches = fs.readFileSync(lifetimePath, 'utf-8') === lifetimeToken;
-            }
-            catch {
-                // A missing state tree or marker is the condition this guard detects.
+                let markerMatches = false;
+                try {
+                    markerMatches = fs.readFileSync(lifetimePath, 'utf-8') === lifetimeToken;
+                }
+                catch {
+                    // A missing state dir or marker is the condition this guard detects.
+                }
+                if (!markerMatches) {
+                    log('WARN', `Daemon state dir ${getDaemonDir()} no longer exists; exiting (self-terminate guard)`);
+                    void handleShutdown();
+                }
             }
-            if (!markerMatches) {
-                log('WARN', `Daemon state dir ${getDaemonDirRoot()} no longer exists; exiting (self-terminate guard)`);
-                void handleShutdown();
+            finally {
+                checkingStateDir = false;
             }
-        }
-        finally {
-            checkingStateDir = false;
-        }
-    };
-    const stateDirCheckMs = Number(process.env.AGENTS_DAEMON_STATE_DIR_CHECK_MS) || 60_000;
-    const stateDirCheckInterval = setInterval(runStateDirSelfCheck, stateDirCheckMs);
+        };
+        const stateDirCheckMs = Number(process.env.AGENTS_DAEMON_STATE_DIR_CHECK_MS) || STATE_DIR_CHECK_TICK_MS;
+        stateDirCheckInterval = setInterval(runStateDirSelfCheck, stateDirCheckMs);
+    }
+    else {
+        log('INFO', 'State-dir self-check disabled');
+    }
+    // RUSH-2418: startup is over — the scheduler, browser IPC, broker decision,
+    // 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.
+    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) {
+                // scheduler and monitors are re-evaluated live later in this handler,
+                // so don't tell the user they need a restart for those.
+                if (id === 'scheduler' || (id === 'monitors' && !now)) {
+                    continue;
+                }
+                log('INFO', `Service '${id}' toggled ${now ? 'on' : 'off'} — restart daemon to apply`);
+            }
+        }
+        // Remember the reloaded state so subsequent reloads log transitions truthfully.
+        servicesConfig = reloadedConfig;
         // 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`.
@@ -994,7 +1385,9 @@ export async function runDaemon() {
         // 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.
-        const transition = schedulerGateTransition(scheduler !== null, isSchedulerEnabled());
+        // Also honour the daemon-services toggle.
+        const schedulerEnabledNow = isSchedulerEnabled() && reloadedEnabled('scheduler');
+        const transition = schedulerGateTransition(scheduler !== null, schedulerEnabledNow);
         if (transition === 'boot') {
             log('INFO', 'scheduler.enabled is now on — booting the scheduler');
             bootScheduler();
@@ -1008,37 +1401,69 @@ export async function runDaemon() {
             const reloaded = scheduler.listScheduled();
             log('INFO', `Reloaded ${reloaded.length} jobs`);
         }
-        try {
-            monitorEngine.reload();
-        }
-        catch (err) {
-            log('ERROR', `Monitor engine reload failed: ${err.message}`);
+        // Monitor engine can be stopped on reload if disabled; starting it requires
+        // a restart, so we only handle the off transition here.
+        if (monitorEngine) {
+            if (!reloadedEnabled('monitors')) {
+                log('WARN', 'monitors service is now disabled — stopping monitor engine; restart daemon to re-enable');
+                try {
+                    monitorEngine.stop();
+                }
+                catch { /* best-effort */ }
+            }
+            else {
+                try {
+                    monitorEngine.reload();
+                }
+                catch (err) {
+                    log('ERROR', `Monitor engine reload failed: ${err.message}`);
+                }
+            }
         }
     };
-    const handleShutdown = async () => {
+    // Structurally single-shot (RUSH-2423). Shutdown is reachable from SIGTERM,
+    // SIGINT, and the state-dir self-check's independent `void handleShutdown()`,
+    // 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.
+    const handleShutdown = singleShot(async () => {
         log('INFO', 'Daemon shutting down');
+        accountStateService?.stop();
+        clearInterval(activeSessionsWarmInterval);
+        if (watchdogInterval)
+            clearInterval(watchdogInterval);
+        if (deviceProbeInterval)
+            clearInterval(deviceProbeInterval);
         stopScheduler();
-        monitorEngine.stop();
-        await browserIPC.stop();
+        monitorEngine?.stop();
+        await browserIPC?.stop();
         clearInterval(monitorInterval);
-        clearInterval(healInterval);
-        clearTimeout(healKickoff);
-        clearInterval(brokerSelfHealInterval);
-        clearInterval(keychainReapInterval);
-        clearInterval(stateDirCheckInterval);
+        if (healInterval)
+            clearInterval(healInterval);
+        if (healKickoff)
+            clearTimeout(healKickoff);
+        if (brokerSelfHealInterval)
+            clearInterval(brokerSelfHealInterval);
+        if (keychainReapInterval)
+            clearInterval(keychainReapInterval);
+        clearInterval(deadPaneReapInterval);
+        if (stateDirCheckInterval)
+            clearInterval(stateDirCheckInterval);
         try {
             if (fs.readFileSync(lifetimePath, 'utf-8') === lifetimeToken)
                 fs.unlinkSync(lifetimePath);
         }
         catch {
-            // Already removed with the state tree, or replaced by a newer owner.
+            // Already removed with the state dir, or replaced by a newer owner.
         }
         hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();
         unregisterDaemonInstance();
         process.exit(0);
-    };
+    });
     process.on('SIGHUP', handleReload);
     process.on('SIGTERM', () => handleShutdown());
     process.on('SIGINT', () => handleShutdown());
@@ -1078,7 +1503,7 @@ export function writeOwnerOnlyServiceManifest(filePath, content) {
  */
 export function generateLaunchdPlist(agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
-    const logPath = getLogPath();
+    const logPath = getDaemonLogPath();
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1093,6 +1518,8 @@ ${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</
   <true/>
   <key>KeepAlive</key>
   <true/>
+  <key>ThrottleInterval</key>
+  <integer>${DAEMON_THROTTLE_SECONDS}</integer>
   <key>StandardOutPath</key>
   <string>${logPath}</string>
   <key>StandardErrorPath</key>
@@ -1123,12 +1550,14 @@ export function generateSystemdUnit(agentsBin = getAgentsBinPath()) {
     return `[Unit]
 Description=Agents Daemon - Scheduled Job Runner
 After=network.target
+StartLimitIntervalSec=${DAEMON_START_LIMIT_INTERVAL_SECONDS}
+StartLimitBurst=${DAEMON_START_LIMIT_BURST}
 
 [Service]
 Type=simple
 ExecStart=${execStart}
 Restart=always
-RestartSec=10
+RestartSec=${DAEMON_THROTTLE_SECONDS}
 Environment=PATH=${daemonPathValue(agentsBin, ['/usr/local/bin', '/usr/bin', '/bin'])}
 
 [Install]
@@ -1187,13 +1616,44 @@ 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;
+    }
     finally {
         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`.
@@ -1211,6 +1671,25 @@ export function ensureDaemonStarted() {
     // 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-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`);
+        return null;
+    }
     try {
         return startDaemon();
     }
@@ -1341,19 +1820,25 @@ function daemonNodeBinDir() {
     return path.dirname(process.execPath);
 }
 /**
- * The full PATH value the daemon service manifest pins, in order: the Node runtime
- * dir (so the shim's shebang and any child resolve the exact installing Node — see
- * {@link daemonNodeBinDir}), then the directory of the `agents` shim itself, then
- * the platform's system dirs. The shim's own dir matters because a scheduled
- * `command` routine shells out to the bare name `agents`
- * (`/bin/sh -c 'agents watchdog --nudge'`): when the shim lives outside the Node
- * bin dir — a `~/.local/bin` global install, a separate npm prefix — a PATH
- * carrying only the Node dir resolves `agents` to nothing and every routine dies
- * with `exit 127`. 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.
+ * 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 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. 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([daemonNodeBinDir(), path.dirname(agentsBin), ...systemDirs])].join(':');
+    return [...new Set([path.dirname(agentsBin), daemonNodeBinDir(), ...systemDirs])].join(':');
 }
 /**
  * Build the argv to relaunch the `agents` CLI with the given subcommand args.
@@ -1409,7 +1894,7 @@ export function validateDaemonBinary(binPath) {
 }
 export function startDetached(opts = {}) {
     const agentsBin = opts.agentsBin ?? getAgentsBinPath();
-    const logPath = opts.logPath ?? getLogPath();
+    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
@@ -1447,10 +1932,90 @@ 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();
+    }
+    catch {
+        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);
+    const lifetimeOwner = claimedPid(() => {
+        const raw = fs.readFileSync(lifetimePath, 'utf-8').split(':')[0];
+        const n = parseInt(raw, 10);
+        return isNaN(n) ? null : n;
+    });
+    artifacts.push({
+        label: 'daemon lifetime marker',
+        present: fs.existsSync(lifetimePath),
+        ownedByLiveOther: lifetimeOwner !== null && lifetimeOwner !== stoppedPid && isAlive(lifetimeOwner),
+        reclaim: () => { try {
+            fs.unlinkSync(lifetimePath);
+        }
+        catch { /* raced with a fresh start */ } },
+        stillPresent: () => fs.existsSync(lifetimePath),
+    });
+    const heartbeatPath = getHeartbeatPath();
+    const hb = readHeartbeat();
+    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 && 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),
+        });
+    }
+    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 daemon dir, so a daemon serving a DIFFERENT state dir (a test
+ * 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.
@@ -1624,6 +2189,31 @@ export function stopDaemon() {
                 released.push('secrets broker socket (reclaimed)');
         }
     }
+    // ── 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)) {
+        if (!artifact.present) {
+            released.push(artifact.label);
+            continue;
+        }
+        if (artifact.ownedByLiveOther) {
+            released.push(`${artifact.label} (owned by a live daemon)`);
+            continue;
+        }
+        artifact.reclaim();
+        if (artifact.stillPresent())
+            surviving.push(`${artifact.label} not released`);
+        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();
@@ -1656,14 +2246,14 @@ export function getDaemonStatus() {
         running,
         pid,
         jobCount,
-        logPath: getLogPath(),
+        logPath: getDaemonLogPath(),
         binaryPath,
         heartbeat: readHeartbeat(),
     };
 }
 /** Read the daemon log, optionally limited to the last N lines. */
 export function readDaemonLog(lines) {
-    const logPath = getLogPath();
+    const logPath = getDaemonLogPath();
     if (!fs.existsSync(logPath))
         return '(no log file)';
     const content = fs.readFileSync(logPath, 'utf-8');