@phnx-labs/agents-cli 1.22.29 → 1.22.31

package/dist/lib/daemon.js

@@ -16,18 +16,19 @@ import { listJobs as listAllJobs } from './routines.js';
 import { syncAllProjectRoutines } from './routines-project.js';
 import { JobScheduler } from './scheduler.js';
 import { MonitorEngine } from './monitors/engine.js';
-import { executeJobDetached, monitorRunningJobs } from './runner.js';
+import { executeJobDetached, monitorRunningJobs, listLiveRoutineChildren } from './runner.js';
 import { detectOverdueJobs, notifyOverdue } from './overdue.js';
 import { runCatchup } from './catchup.js';
 import { notifyRoutineStart, notifyRoutineFinish, notifyRoutineStartFailed } from './routine-notify.js';
 import { notifyOwnerRoutineFinish, notifyOwnerRoutineStartFailed } from './routine-notify-owner.js';
 import { BrowserService } from './browser/service.js';
-import { BrowserIPCServer } from './browser/ipc.js';
+import { BrowserIPCServer, getSocketPath as getBrowserIpcSocketPath } from './browser/ipc.js';
+import { secretsBrokerSocketPath, brokerPidAlive } from './secrets/agent.js';
 import { redactSecrets } from './redact.js';
 import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from './cli-entry.js';
-import { getConfigValue, isSchedulerEnabled, assertSchedulerEnabled } from './device-config.js';
+import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled } from './device-config.js';
 import { reapTerminalRoutineProcesses } from './routine-process-cleanup.js';
-import { runWatchdogPass } from './watchdog/service.js';
+import { recordSubsystemOk, recordSubsystemError, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC } from './daemon-health.js';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
@@ -37,7 +38,6 @@ const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
 const MONITOR_TICK_MS = 60_000;
-const WATCHDOG_TICK_MS = 3 * 60_000;
 /**
  * How often to re-scan for missed fires. Deliberately slower than the monitor
  * tick: detection walks a week of cron occurrences per routine
@@ -250,30 +250,42 @@ export function isDaemonRunning() {
  * writeDaemonPid() unconditionally, clobber a live daemon's recorded PID, and
  * run a second JobScheduler concurrently, so every cron routine fires twice.
  *
- * Returns true and records our PID when no other live daemon owns the pid file;
- * returns false when a live daemon already holds it (the caller must exit
- * without touching any further state). The read-decide-write is serialized
- * behind the same O_EXCL start lock startDaemon() uses, so two _run processes
- * can't both claim in the window between the liveness check and the write.
+ * 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 ONLY when another `__daemon-run` currently holds the
+ * O_EXCL start lock — i.e. a concurrent claimer is mid-takeover and will be the
+ * singleton — 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() {
     const release = acquireStartLock();
     // acquireStartLock() returns null only when another __daemon-run currently
     // holds the O_EXCL lock — a dead holder's lock is reclaimed and retried inside
     // acquireStartLock, so null means a *live* claimer is mid-claim. Bail rather
-    // than run the read-decide-write unlocked: otherwise two first-start processes
+    // than run the read-evict-write unlocked: otherwise two first-start processes
     // could each see no pid file (before either writes one) and both claim,
-    // running the concurrent JobScheduler this guard exists to prevent.
+    // running the concurrent JobScheduler this guard exists to prevent. The live
+    // claimer we bailed for becomes the singleton, so last-wins still holds.
     if (!release)
         return false;
     try {
         // resolveLiveDaemonPid() also consults a fresh heartbeat, so a live daemon
-        // whose pid file was lost still blocks a second claim — otherwise a missing
-        // pid file would let this instance start a concurrent JobScheduler and
-        // double-fire every routine.
+        // 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();
         if (existing !== null && existing !== process.pid) {
-            return false; // another live daemon already owns the instance
+            // Evict, and WAIT for the incumbent to be provably dead — its graceful
+            // handleShutdown releasing the browser IPC binding and the secrets broker
+            // socket — before we write our pid and (later, in runDaemon) bind our own.
+            // Binding before the release recreates the two-brokers-on-one-socket orphan
+            // documented at stopDaemon below, so the pid file is not written until the
+            // prior owner is gone.
+            evictIncumbentDaemon(existing);
         }
         writeDaemonPid(process.pid);
         return true;
@@ -283,56 +295,153 @@ export function claimDaemonInstance() {
     }
 }
 /**
- * Reap stray duplicate daemon processes — a `__daemon-run` of THIS install that
- * isn't this process and isn't the pid-file owner. Mirrors the browser orphan
- * reaper (below): a predecessor that was SIGKILLed/OOM-ed without cleaning up,
- * 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.
- *
- * Scoped to our own launch entry (process.argv[1]) so it only ever targets
- * daemons of the same installation — a daemon from a different install / home
- * (e.g. a side-by-side dev build, or a test fixture) is a legitimately separate
- * instance and is left untouched. POSIX-only (uses `ps`); a no-op on Windows.
+ * SIGTERM a live incumbent daemon and block until it is provably dead, so its
+ * graceful handleShutdown has released the browser IPC binding and the secrets
+ * broker socket BEFORE the newcomer binds anything of its own (SING-11). 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) {
+    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);
+        waitForExit(pid, STOP_KILL_GRACE_MS);
+        return;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return; // already gone between resolveLiveDaemonPid() and here
+    }
+    if (waitForExit(pid, STOP_GRACE_MS))
+        return; // graceful release complete
+    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). */
+function getDaemonInstancesDir() {
+    return path.join(getDaemonDirRoot(), '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
+ * 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:
+ * 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
+ * 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 */ }
+}
+/** 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).
  */
 export function reapStrayDaemons(keepPid = process.pid) {
     const details = [];
     let reaped = 0;
     if (process.platform === 'win32')
         return { reaped, details };
-    const selfEntry = process.argv[1];
-    if (!selfEntry)
-        return { reaped, details };
-    let out;
+    const dir = getDaemonInstancesDir();
+    let entries;
     try {
-        out = execFileSync('ps', ['-eo', 'pid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        entries = fs.readdirSync(dir);
     }
     catch {
-        return { reaped, details }; // no `ps` — best effort
+        return { reaped, details }; // no registry yet — nothing to reap
     }
     const ownerPid = readDaemonPid();
-    for (const line of out.split('\n')) {
-        const m = line.trim().match(/^(\d+)\s+(.*)$/);
-        if (!m)
-            continue;
-        const pid = parseInt(m[1], 10);
-        const args = m[2];
-        if (isNaN(pid) || pid === keepPid || pid === process.pid || pid === ownerPid)
+    const dropMarker = (name) => {
+        try {
+            fs.rmSync(path.join(dir, name), { force: true });
+        }
+        catch { /* ignore */ }
+    };
+    for (const name of entries) {
+        const pid = parseInt(name, 10);
+        if (isNaN(pid) || String(pid) !== name)
+            continue; // not a pid marker
+        if (pid === keepPid || pid === process.pid || pid === ownerPid)
             continue;
-        // Same install (same launch entry) AND a `__daemon-run` command line.
-        if (!args.includes(selfEntry))
+        // Dead registrant → stale marker.
+        if (!isAlive(pid)) {
+            dropMarker(name);
             continue;
-        if (!/\b__daemon-run\b/.test(args))
+        }
+        // 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).
+        if (!isDaemonRunProcess(pid)) {
+            dropMarker(name);
             continue;
+        }
         try {
             process.kill(pid, 'SIGTERM');
             reaped++;
             details.push(`reaped stray daemon pid ${pid}`);
         }
-        catch { /* already gone */ }
+        catch { /* already gone between the alive check and the signal */ }
+        dropMarker(name);
     }
     return { reaped, details };
 }
+/**
+ * Whether `pid` is a live `agents __daemon-run` process. Reads the process's
+ * command line (`ps -p <pid> -o command=`), which — unlike its environment — is
+ * visible cross-platform, including on hardened macOS. Guards the reaper against
+ * killing an unrelated process that reused a dead registrant's pid.
+ */
+function isDaemonRunProcess(pid) {
+    if (process.platform === 'win32')
+        return false;
+    try {
+        const out = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return /\b__daemon-run\b/.test(out);
+    }
+    catch {
+        return false;
+    }
+}
 function rotateLogsIfNeeded(logPath) {
     try {
         const stat = fs.statSync(logPath);
@@ -423,12 +532,13 @@ export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
     }
 }
 export async function runDaemon() {
-    // Single-instance guard: a direct `agents __daemon-run` (manual, or a
-    // service-manager restart racing a live predecessor) must not clobber a
-    // running daemon's pid file and start a second scheduler.
+    // 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()) {
-        const owner = readDaemonPid();
-        log('WARN', `Another daemon already owns the pid file (PID: ${owner}); this instance (PID ${process.pid}) is exiting`);
+        log('WARN', `Another daemon is mid-takeover (holds the start lock); 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);
@@ -443,8 +553,11 @@ export async function runDaemon() {
     // 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.
-    // Reap any stray duplicate daemon of this install that slipped past the start
-    // lock or was orphaned by a hard-crash — before it can double-fire jobs.
+    // 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();
         if (strays.reaped > 0) {
@@ -474,9 +587,12 @@ export async function runDaemon() {
             if (hostedBroker)
                 log('INFO', 'Secrets broker hosted in daemon (socket-first)');
         }
+        recordSubsystemOk(SUBSYSTEM_SECRETS_BROKER);
     }
     catch (err) {
-        log('WARN', `Secrets broker host skipped: ${err.message}`);
+        const message = err.message;
+        log('WARN', `Secrets broker host skipped: ${message}`);
+        recordSubsystemError(SUBSYSTEM_SECRETS_BROKER, message);
     }
     // 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
@@ -595,24 +711,13 @@ export async function runDaemon() {
     }
     if (schedulerEnabledAtBoot)
         bootScheduler();
-    let watchdogInFlight = false;
-    const runDaemonWatchdog = async () => {
-        if (watchdogInFlight || getConfigValue('watchdog.enabled').value !== true)
-            return;
-        watchdogInFlight = true;
-        try {
-            const result = await runWatchdogPass({ nudge: true });
-            log('INFO', `watchdog: ${result.counts.total} live, ${result.counts.stalled} stalled, ${result.counts.nudged} nudged`);
-        }
-        catch (err) {
-            log('ERROR', `watchdog tick failed: ${err.message}`);
-        }
-        finally {
-            watchdogInFlight = false;
-        }
-    };
-    const watchdogInterval = setInterval(() => { void runDaemonWatchdog(); }, WATCHDOG_TICK_MS);
-    const watchdogKickoff = setTimeout(() => { void runDaemonWatchdog(); }, 30_000);
+    // 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.
     // 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.
@@ -715,9 +820,12 @@ export async function runDaemon() {
     try {
         await browserIPC.start();
         log('INFO', 'Browser IPC server started');
+        recordSubsystemOk(SUBSYSTEM_BROWSER_IPC);
     }
     catch (err) {
-        log('ERROR', `Browser IPC failed to start: ${err.message}`);
+        const message = err.message;
+        log('ERROR', `Browser IPC failed to start: ${message}`);
+        recordSubsystemError(SUBSYSTEM_BROWSER_IPC, message);
     }
     writeHeartbeat();
     const monitorInterval = setInterval(() => {
@@ -760,253 +868,6 @@ export async function runDaemon() {
     };
     const healInterval = setInterval(() => { void runHealCheck(); }, 6 * 60 * 60_000);
     const healKickoff = setTimeout(() => { void runHealCheck(); }, 30_000);
-    // Auto-dispatch: for any managed project that has opted in (autoDispatch:true +
-    // maxAgents>0 in ~/.agents/factory/projects.json), pick up Linear tickets that
-    // are delegated to an agent and still in Todo, and DISPATCH each through
-    // agents-cli's own cloud-provider layer (resolveProvider().dispatch(), same as
-    // `agents cloud run`) — then mark it Doing so it isn't re-picked. Capped at
-    // maxAgents concurrent per project. No hidden Prix dependency: Rush is one
-    // provider among rush/codex/factory, pinned per-project via `provider`. OFF
-    // unless a project opts in; no opted-in project or no LINEAR_API_KEY is a clean
-    // no-op. Overlap-guarded like the probes above. ~every 3 min.
-    let autoDispatching = false;
-    const runAutoDispatch = async () => {
-        if (autoDispatching)
-            return;
-        autoDispatching = true;
-        try {
-            const { readAutoDispatchProjects, isEligible, autoDispatchTick } = await import('./auto-dispatch.js');
-            const projects = readAutoDispatchProjects();
-            if (!projects.some(isEligible))
-                return; // opt-in: nothing enabled → skip
-            const { createLinearGateway } = await import('./auto-dispatch-linear.js');
-            const linear = createLinearGateway();
-            if (!linear)
-                return; // no LINEAR_API_KEY configured → skip
-            const { createProviderDispatcher } = await import('./auto-dispatch-provider.js');
-            const dispatcher = createProviderDispatcher();
-            const dispatched = await autoDispatchTick({ projects, linear, dispatcher, log: (lvl, m) => log(lvl, m) });
-            if (dispatched.length) {
-                log('INFO', `auto-dispatch: started ${dispatched.length} delegated ticket(s): ${dispatched.map((d) => d.identifier).join(', ')}`);
-            }
-        }
-        catch (err) {
-            log('ERROR', `auto-dispatch failed: ${err.message}`);
-        }
-        finally {
-            autoDispatching = false;
-        }
-    };
-    const autoDispatchInterval = setInterval(() => { void runAutoDispatch(); }, 3 * 60_000);
-    const autoDispatchKickoff = setTimeout(() => { void runAutoDispatch(); }, 45_000);
-    // 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. Soft + overlap-guarded like session sync;
-    // a machine without tailscale is a clean no-op. ~every 3 min.
-    let probingDevices = false;
-    const runDeviceProbe = async () => {
-        if (probingDevices)
-            return;
-        probingDevices = true;
-        try {
-            const { runDeviceSync } = await import('./devices/sync.js');
-            const { reconcilePendingSentinels } = await import('./devices/pending.js');
-            const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
-            if (dev.ok) {
-                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('ERROR', `device probe failed: ${err.message}`);
-        }
-        finally {
-            probingDevices = false;
-        }
-    };
-    const deviceProbeInterval = setInterval(() => { void runDeviceProbe(); }, 3 * 60_000);
-    const deviceProbeKickoff = setTimeout(() => { void runDeviceProbe(); }, 15_000);
-    // tmux hook reconcile: retrofit the guarded `pane-died` hook onto managed
-    // `agents run` sessions a pre-fix binary left with the old unconditional hook
-    // (which detached the whole client — kicking the user out of the view — when
-    // they exited a split they'd opened). Non-destructive: set-hook only, never a
-    // kill or detach. A per-session schema marker makes steady-state a no-op, so
-    // this stays cheap at ~every 5 min, plus once ~20s after startup so a
-    // just-upgraded daemon heals still-running sessions without waiting for them to
-    // cycle or the shared server to be recycled.
-    let reconcilingTmux = false;
-    const runTmuxReconcile = async () => {
-        if (reconcilingTmux)
-            return;
-        reconcilingTmux = true;
-        try {
-            const { isTmuxInstalled } = await import('./tmux/binary.js');
-            if (!isTmuxInstalled())
-                return;
-            const { reconcileSessionHooks } = await import('./tmux/session.js');
-            const r = await reconcileSessionHooks();
-            if (r.reconciled > 0)
-                log('INFO', `tmux: retrofitted pane-died hook on ${r.reconciled} session(s)`);
-        }
-        catch (err) {
-            log('ERROR', `tmux reconcile failed: ${err.message}`);
-        }
-        finally {
-            reconcilingTmux = false;
-        }
-    };
-    const tmuxReconcileInterval = setInterval(() => { void runTmuxReconcile(); }, 5 * 60_000);
-    const tmuxReconcileKickoff = setTimeout(() => { void runTmuxReconcile(); }, 20_000);
-    // Launch-health self-heal: probe that each agent's DEFAULT version actually
-    // LAUNCHES (not just that its files exist), and repair a gutted install — the
-    // JS wrapper present but its native binary renamed/missing (a vendor
-    // auto-update that never landed its replacement, or a partially-extracted
-    // tarball) — BEFORE the user's next `agents run` dies with a raw ENOENT. This
-    // is the proactive companion to the run-time heal (ensureAgentRunnable), which
-    // only fires once a run is already starting. Cheap steady-state: one
-    // `--version` probe per default version; a clean reinstall runs only on a real
-    // launch failure. ~every 6h, plus once ~90s after startup (staggered off launch).
-    let checkingLaunchHealth = false;
-    const runLaunchHealthCheck = async () => {
-        if (checkingLaunchHealth)
-            return;
-        checkingLaunchHealth = true;
-        try {
-            const { healBrokenDefaultLaunches } = await import('./versions.js');
-            // Unattended pass: repair the current default in place, but NEVER repoint
-            // the global default (allowDefaultSwitch: false). A background default
-            // switch installs a fresh version home → a fresh empty Claude credential
-            // scope, i.e. a silent logout uncorrelated with anything the user did.
-            const { repaired, unhealed } = await healBrokenDefaultLaunches((m) => log('INFO', `launch-health: ${m}`), { allowDefaultSwitch: false });
-            if (repaired.length)
-                log('INFO', `launch-health: repaired ${repaired.join(', ')}`);
-            if (unhealed.length) {
-                log('WARN', `launch-health: ${unhealed.join(', ')} won't launch and will not be auto-switched — choose a version with \`agents use <agent> <version>\` or \`agents add <agent>@latest\``);
-            }
-        }
-        catch (err) {
-            log('ERROR', `launch-health check failed: ${err.message}`);
-        }
-        finally {
-            checkingLaunchHealth = false;
-        }
-    };
-    const launchHealthInterval = setInterval(() => { void runLaunchHealthCheck(); }, 6 * 60 * 60_000);
-    const launchHealthKickoff = setTimeout(() => { void runLaunchHealthCheck(); }, 90_000);
-    // Fleet cache warm: publish THIS host's row for the caches `agents fleet
-    // status` / `agents devices list` read. PUBLISH-OWN / READ-UNION (RUSH-2061):
-    // each daemon probes only ITSELF and never SSHes another box, so the fleet no
-    // longer pays N² SSH resource probes every 3 minutes (N daemons × N devices) —
-    // the source of the fan-out storm AND the orphaned-probe pile-up. Two cheap
-    // self-only refreshes: (1) this host's auth-health verdicts (also feeds the
-    // `doctor --json` Auth rollup other hosts read), and (2) its fleet-status row
-    // (local resource probe + live-agent workload). Cross-host rows are unioned on
-    // demand by the reader (`agents fleet status`), not pushed by every daemon.
-    // Best-effort + overlap-guarded like the probes above; ~every 3 min, once ~60s
-    // after startup.
-    let warmingFleetCache = false;
-    const runFleetCacheWarm = async () => {
-        if (warmingFleetCache)
-            return;
-        warmingFleetCache = true;
-        try {
-            const { machineId } = await import('./machine-id.js');
-            const self = machineId();
-            const { probeLocalFleetAuth, writeFleetAuthRows } = await import('./auth-health.js');
-            const { getCliVersion } = await import('./version.js');
-            const authRows = await probeLocalFleetAuth({ cliVersion: getCliVersion() });
-            writeFleetAuthRows(self, authRows);
-            const { publishLocalFleetStatus } = await import('./fleet-status.js');
-            const row = await publishLocalFleetStatus(self);
-            log('INFO', `fleet cache warm: ${authRows.length} auth row(s), ${row.agents.running} running agent(s) on ${self}`);
-        }
-        catch (err) {
-            log('ERROR', `fleet cache warm failed: ${err.message}`);
-        }
-        finally {
-            warmingFleetCache = false;
-        }
-    };
-    const fleetCacheInterval = setInterval(() => { void runFleetCacheWarm(); }, 3 * 60_000);
-    const fleetCacheKickoff = setTimeout(() => { void runFleetCacheWarm(); }, 60_000);
-    // Session-status cache warm (RUSH-2062): publish THIS host's local active
-    // sessions so menubar / Factory / watchdog / CLI share one warm snapshot
-    // instead of each re-running a full ~9s / ~170MB gather. Publish-own only
-    // (no cross-host SSH — same N² lesson as RUSH-2061). Short interval keeps
-    // live status fresh; forceRefresh still re-gathers. Additive sibling of
-    // fleetCacheInterval — does not touch the reaper tick.
-    let warmingSessionCache = false;
-    // Import once so the interval/kickoff constants stay the single source of truth
-    // (SESSION_CACHE_WARM_* in session-cache.ts). Dynamic import of the warm fn
-    // itself stays inside the tick so a cold daemon boot does not pay the load.
-    const sessionCacheWarmTiming = import('./session/session-cache.js').then((m) => ({
-        intervalMs: m.SESSION_CACHE_WARM_INTERVAL_MS,
-        kickoffMs: m.SESSION_CACHE_WARM_KICKOFF_MS,
-        publish: m.publishLocalActiveSessions,
-    }));
-    const runSessionCacheWarm = async () => {
-        if (warmingSessionCache)
-            return;
-        warmingSessionCache = true;
-        try {
-            const { publish } = await sessionCacheWarmTiming;
-            const r = await publish();
-            log('INFO', `session cache warm: ${r.sessions.length} local session(s)`);
-        }
-        catch (err) {
-            log('ERROR', `session cache warm failed: ${err.message}`);
-        }
-        finally {
-            warmingSessionCache = false;
-        }
-    };
-    // Intervals resolved from the module constants (fallback matches the defaults
-    // if the import is still pending — the first tick uses the live import).
-    let sessionCacheInterval;
-    let sessionCacheKickoff;
-    void sessionCacheWarmTiming.then(({ intervalMs, kickoffMs }) => {
-        sessionCacheInterval = setInterval(() => { void runSessionCacheWarm(); }, intervalMs);
-        sessionCacheKickoff = setTimeout(() => { void runSessionCacheWarm(); }, kickoffMs);
-    });
-    // Usage refresh: keep the usage cache the `agents run` router reads
-    // (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
-    // This host is the sole writer for its own local accounts. The tick wakes
-    // every 60s (USAGE_REFRESH_TICK_MS) to consider due accounts; each account
-    // is scheduled at a fixed 5-minute cadence (REFRESH_INTERVAL_MS), capped at
-    // ~12 provider calls/account/hour, skipped under 429 backoff, and fetched
-    // with fileOnly credentials so a background tick never pops macOS Touch ID.
-    // Overlap-guarded: a slow pass cannot stack concurrent refresh loops.
-    let refreshingUsage = false;
-    const runUsageRefreshTick = async () => {
-        if (refreshingUsage)
-            return;
-        refreshingUsage = true;
-        try {
-            const { runUsageRefresh, buildLocalUsageAccounts } = await import('./usage-refresh.js');
-            const { writeClaudeUsageCache } = await import('./usage.js');
-            const { usageRateLimitedUntil } = await import('./usage-backoff.js');
-            const r = await runUsageRefresh({
-                listAccounts: buildLocalUsageAccounts,
-                writeUsageCache: writeClaudeUsageCache,
-                backoffUntil: usageRateLimitedUntil,
-            });
-            // Always log a compact summary so "is refresh working?" is greppable even
-            // when every account was not-due (proves the tick ran).
-            log('INFO', `usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped`);
-        }
-        catch (err) {
-            log('ERROR', `usage refresh failed: ${err.message}`);
-        }
-        finally {
-            refreshingUsage = false;
-        }
-    };
-    // 60s wake matches USAGE_REFRESH_TICK_MS in usage-refresh.ts (keep in sync).
-    const usageRefreshInterval = setInterval(() => { void runUsageRefreshTick(); }, 60_000);
-    const usageRefreshKickoff = setTimeout(() => { void runUsageRefreshTick(); }, 30_000);
     // 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
@@ -1110,31 +971,14 @@ export async function runDaemon() {
         monitorEngine.stop();
         await browserIPC.stop();
         clearInterval(monitorInterval);
-        clearInterval(watchdogInterval);
-        clearTimeout(watchdogKickoff);
         clearInterval(healInterval);
         clearTimeout(healKickoff);
-        clearInterval(autoDispatchInterval);
-        clearTimeout(autoDispatchKickoff);
-        clearInterval(deviceProbeInterval);
-        clearTimeout(deviceProbeKickoff);
-        clearInterval(tmuxReconcileInterval);
-        clearTimeout(tmuxReconcileKickoff);
-        clearInterval(launchHealthInterval);
-        clearTimeout(launchHealthKickoff);
-        clearInterval(fleetCacheInterval);
-        clearTimeout(fleetCacheKickoff);
-        if (sessionCacheInterval)
-            clearInterval(sessionCacheInterval);
-        if (sessionCacheKickoff)
-            clearTimeout(sessionCacheKickoff);
-        clearInterval(usageRefreshInterval);
-        clearTimeout(usageRefreshKickoff);
         clearInterval(brokerSelfHealInterval);
         clearInterval(keychainReapInterval);
         hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();
+        unregisterDaemonInstance();
         process.exit(0);
     };
     process.on('SIGHUP', handleReload);
@@ -1292,6 +1136,12 @@ export function startDaemon(agentsBin) {
  * 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;
     try {
         return startDaemon();
     }
@@ -1499,9 +1349,59 @@ function waitForPid(timeoutMs) {
     }
     return readDaemonPid();
 }
-/** Stop the daemon, unloading it from launchd/systemd if applicable. */
+/**
+ * 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
+ * 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.
+ */
+function findSurvivingStateDirDaemons(exclude) {
+    if (process.platform === 'win32')
+        return [];
+    const dir = getDaemonInstancesDir();
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of entries) {
+        const pid = parseInt(name, 10);
+        if (isNaN(pid) || String(pid) !== name)
+            continue; // not a pid marker
+        if (exclude.has(pid))
+            continue;
+        if (!isAlive(pid))
+            continue; // dead marker — reaper self-heals it
+        if (!isDaemonRunProcess(pid))
+            continue; // pid reused by an unrelated process
+        found.push(pid);
+    }
+    return found;
+}
+/**
+ * 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 the secrets broker socket
+ * and browser IPC binding actually released — a stale socket present on disk but
+ * with no live owner is the orphan that keeps clients holding unlocked bundles
+ * hanging (`daemon.ts` broker-hosting; the two-brokers-on-one-socket bug) — and
+ * that no `__daemon-run` for THIS state dir survives. A killTree escalation exits
+ * without running the daemon's graceful handleShutdown, so those sockets can be
+ * left stale; this reclaims each (the owner is provably dead) and reports it. It
+ * never reports success on an unverified stop.
+ */
 export function stopDaemon() {
     const platform = os.platform();
+    const released = [];
+    const surviving = [];
+    let escalated = false;
     if (platform === 'darwin') {
         const plistPath = getLaunchdPlistPath();
         if (fs.existsSync(plistPath)) {
@@ -1541,6 +1441,7 @@ export function stopDaemon() {
             // its job/browser child tree in one shot (taskkill /T), so stop doesn't
             // report success while children keep running.
             killTree(pid);
+            escalated = true;
         }
         else {
             try {
@@ -1558,12 +1459,76 @@ export function stopDaemon() {
             // after an install into a second prefix.
             if (!waitForExit(pid, STOP_GRACE_MS)) {
                 killTree(pid);
+                escalated = true;
                 waitForExit(pid, STOP_KILL_GRACE_MS);
             }
         }
     }
     removeDaemonPid();
-    return true;
+    // ── Assert the postcondition (SING-12) ────────────────────────────────────
+    // No `__daemon-run` for this state dir may survive the stop.
+    const survivors = findSurvivingStateDirDaemons(new Set([process.pid]));
+    if (pid && process.platform === 'win32' && isAlive(pid) && !survivors.includes(pid)) {
+        survivors.push(pid); // registry is POSIX-only; check the killed pid directly
+    }
+    if (survivors.length > 0) {
+        for (const s of survivors)
+            surviving.push(`__daemon-run pid ${s} still alive`);
+    }
+    else if (pid) {
+        released.push('daemon process');
+    }
+    // Browser IPC binding: on POSIX the listening socket is a filesystem object.
+    // A graceful handleShutdown unlinks it; if it survives, the daemon exited
+    // ungracefully (killTree) and left a stale binding — the owner is provably
+    // dead, so reclaim it and report.
+    if (process.platform !== 'win32') {
+        const browserSock = getBrowserIpcSocketPath();
+        if (fs.existsSync(browserSock)) {
+            try {
+                fs.unlinkSync(browserSock);
+            }
+            catch { /* raced with a fresh start */ }
+            if (fs.existsSync(browserSock))
+                surviving.push('browser IPC socket not released');
+            else
+                released.push('browser IPC socket (reclaimed)');
+        }
+        else {
+            released.push('browser IPC socket');
+        }
+        // Secrets broker socket: released when it is gone, or still owned by a
+        // DIFFERENT live broker (a standalone service the daemon never hosted). A
+        // socket present with NO live owner is the orphan — reclaim it.
+        const brokerSock = secretsBrokerSocketPath();
+        if (!fs.existsSync(brokerSock)) {
+            released.push('secrets broker socket');
+        }
+        else if (brokerPidAlive()) {
+            released.push('secrets broker socket (standalone owner)');
+        }
+        else {
+            try {
+                fs.unlinkSync(brokerSock);
+            }
+            catch { /* raced with a fresh bind */ }
+            if (fs.existsSync(brokerSock))
+                surviving.push('secrets broker socket not released');
+            else
+                released.push('secrets broker socket (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,
+        stoppedPid: pid,
+        escalated,
+        released,
+        surviving,
+        detachedChildren,
+    };
 }
 /** Get current daemon status including running state, PID, and enabled job count. */
 export function getDaemonStatus() {