@phnx-labs/agents-cli 1.22.34 → 1.22.37

package/dist/commands/daemon.js

@@ -19,14 +19,105 @@ import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
-import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, findSurvivingStateDirDaemons, } from '../lib/daemon.js';
+import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, findSurvivingStateDirDaemons, getDaemonLogPath, isDaemonAutostartCircuitOpen, } from '../lib/daemon.js';
 import { getConfigValue, setConfigValue, isDaemonEnabled } from '../lib/device-config.js';
-import { readSubsystemHealth, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC, } from '../lib/daemon-health.js';
+import { readSubsystemHealth, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC, SUBSYSTEM_DAEMON_START, } from '../lib/daemon-health.js';
+import { DAEMON_SERVICE_IDS, listDaemonServiceStates, setDaemonServiceEnabled, getDaemonServicesConfigPath, } from '../lib/daemon-services.js';
 import { listJobs, getLatestRun } from '../lib/routines.js';
 import { JobScheduler } from '../lib/scheduler.js';
-import { getDaemonDir } from '../lib/state.js';
 import { followFile } from '../lib/log-follow.js';
 import { parseDuration } from '../lib/hooks/cache.js';
+import { registerFunnelCommand } from './funnel.js';
+/**
+ * Provably absent, or null when unknowable.
+ *
+ * `fs.existsSync` cannot express the difference: it returns false for ANY failed
+ * stat, so `EACCES` on a parent directory is indistinguishable from deletion.
+ * The feeding scan is box-wide `ps` with no uid filter, so that gap is reachable
+ * on any shared box — `/root` is mode 700, and a stat of a root-owned daemon's
+ * entry from an ordinary uid returns false while the file is perfectly present.
+ * Reporting that would tell the user to `kill` a healthy daemon they do not own,
+ * with a command that would `EPERM` anyway.
+ *
+ * `statSync(p, { throwIfNoEntry: false })` returns `undefined` only for `ENOENT`
+ * and throws for everything else, which is exactly the distinction needed.
+ */
+function entryAbsent(p) {
+    try {
+        return fs.statSync(p, { throwIfNoEntry: false }) === undefined;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A daemon whose launch entry is provably gone from disk (RUSH-2493).
+ *
+ * This predicate answers only "is this one's code gone?". WHO may be told about
+ * it, and whether that report is actionable, is {@link staleDaemons}'s job — a
+ * separation reached the hard way: an early revision reported every box-wide
+ * `ps` match as actionable (re-opening RUSH-2368), and the correction then
+ * over-swung to registry-only, which silently excluded the very incident below.
+ *
+ * Observed 2026-08-10 on yosemite-s0: a daemon ran for 4h14m from
+ * `.agents/worktrees/rush-2431-binary-shadow/apps/cli/dist/index.js` after that
+ * worktree was deleted. `systemctl --user is-active` said `active`,
+ * `agents daemon status` reported healthy, and nothing anywhere named it —
+ * while it held a second routine scheduler, the double-fire class the
+ * one-scheduler-one-executor rule exists to prevent. A restart would also have
+ * failed, since the manifest pointed at the same missing path.
+ *
+ * ABSOLUTE PATHS ONLY. `entryFromTokens` returns the second-to-last argv token,
+ * which is the entry for a real daemon (`getDaemonLaunch` always spawns an
+ * absolute one) but is arbitrary text for anything else — `node -e '<code>'
+ * __daemon-run` yields the code blob, which of course does not exist on disk.
+ * Requiring absoluteness keeps a non-path token from being reported as deleted
+ * code, the same false-positive class RUSH-2368 had to correct for duplicates.
+ *
+ * That guard also covers an entry path containing SPACES, which `ps` renders
+ * unquoted and the tokenizer therefore splits: `/tmp/ghost space/sub/index.js`
+ * yields `space/sub/index.js`, not absolute, so a healthy daemon on such a path
+ * is never accused (verified live). The cost is a false NEGATIVE — a genuinely
+ * deleted entry containing a space is not reported either. That is the safe
+ * direction to fail: missing one detection is a silence we already lived with,
+ * whereas telling someone to `kill` a healthy shared daemon is a new harm.
+ */
+function entryIsGone(p) {
+    return p.entry !== null && path.isAbsolute(p.entry) && p.entryMissing === true;
+}
+/**
+ * Stale daemons split into two tiers, because DETECTION and ACCUSATION are
+ * different acts with different blast radii.
+ *
+ * RUSH-2368's harm was the accusation, not the sighting: a leaked fixture "was
+ * reported as a stray to `kill`". So the narrow registry scope is what gates
+ * anything actionable — a `doctor` problem, a non-zero exit, a `kill` — while a
+ * same-uid sighting is merely shown.
+ *
+ * That split is not academic. The incident this feature exists to catch was
+ * neither the tracked pid nor in the registry: it ran under an ephemeral `/tmp`
+ * cwd from a deleted worktree, and `lib/daemon.ts` documents that such a process
+ * "registers under its own state dir and is invisible here" BY DESIGN. Gating
+ * the display on the registry too would have made this command silent on the
+ * exact 4h14m ghost that motivated it.
+ *
+ *   `actionable` — this device's daemon, or this install's registry. Drives
+ *                  `doctor` problems and the `kill`/`restart` remediation.
+ *   `visible`    — additionally any daemon running as THIS uid. Shown in
+ *                  `status`, never exits non-zero, never told to kill.
+ *
+ * A different uid is never named at all: we cannot reliably stat its entry
+ * ({@link entryAbsent}), and we could not signal it if we tried.
+ */
+function staleDaemons(processes, ownerPid, registered) {
+    const isOurs = (p) => p.pid === ownerPid || registered.has(p.pid);
+    const myUid = typeof process.getuid === 'function' ? process.getuid() : null;
+    const gone = processes.filter(entryIsGone);
+    return {
+        actionable: gone.filter(isOurs),
+        visible: gone.filter((p) => isOurs(p) || (myUid !== null && p.uid === myUid)),
+    };
+}
 /**
  * Resolve the working directory a live process was started from, or null if
  * unavailable. Linux only (`/proc/<pid>/cwd`) — there is no equivalent
@@ -118,26 +209,31 @@ function scanDaemonProcesses() {
         return [];
     let out;
     try {
-        out = execFileSync('ps', ['-eo', 'pid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        out = execFileSync('ps', ['-eo', 'pid=,uid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
     }
     catch {
         return [];
     }
     const found = [];
     for (const line of out.split('\n')) {
-        const m = line.trim().match(/^(\d+)\s+(.*)$/);
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
         if (!m)
             continue;
-        const args = m[2].trim();
+        const args = m[3].trim();
         const tokens = args.split(/\s+/);
         if (tokens.length === 0 || tokens[tokens.length - 1] !== '__daemon-run')
             continue;
         const pid = parseInt(m[1], 10);
         if (isNaN(pid))
             continue;
+        const uidParsed = parseInt(m[2], 10);
+        const uid = isNaN(uidParsed) ? null : uidParsed;
         const entry = entryFromTokens(tokens);
         const version = entry ? resolveVersionNear(entry, pid) : null;
-        found.push({ pid, entry, version });
+        // Asks whether the code is on disk for the NEXT launch -- what a restart and
+        // every other reader will see -- not what this pid currently has mapped.
+        const entryMissing = entry ? entryAbsent(entry) : false;
+        found.push({ pid, entry, version, entryMissing, uid });
     }
     return found;
 }
@@ -255,6 +351,17 @@ async function runStatus(opts) {
     const processes = scanDaemonProcesses();
     const owner = pid ? processes.find((p) => p.pid === pid) : undefined;
     const duplicates = registryScopedDuplicates(processes, pid ?? null);
+    // Every daemon whose code is gone from disk, including this device's own if
+    // it is one. Not filtered by the duplicate scope — see entryIsGone.
+    // Deliberately its own read, NOT shared with registryScopedDuplicates above.
+    // That one passes `exclude` INTO findSurvivingStateDirDaemons to drop the
+    // owner, so handing it a shared empty-exclude snapshot would put ownerPid back
+    // in the set and report this device's daemon as its own duplicate. The saving
+    // would be one `ps` spawn per registered pid, at the 1-3 that actually run.
+    const registeredPids = new Set(findSurvivingStateDirDaemons(new Set()));
+    const staleTiers = staleDaemons(processes, pid ?? null, registeredPids);
+    const stale = staleTiers.visible;
+    const ownerEntryGone = owner ? entryIsGone(owner) : false;
     const [secrets, browserIpc] = await Promise.all([probeSecretsBroker(), probeBrowserIPC()]);
     const scheduler = schedulerSummary();
     if (opts.json) {
@@ -266,7 +373,18 @@ async function runStatus(opts) {
             logPath: status.logPath,
             binaryPath: owner?.entry ?? status.binaryPath,
             binaryVersion: owner?.version ?? null,
+            binaryMissing: ownerEntryGone,
             duplicates: duplicates.map((d) => ({ pid: d.pid, entry: d.entry, version: d.version })),
+            // `actionable` is part of the contract, not decoration: a routine or
+            // monitor reading this must be able to tell a ghost it may act on from one
+            // that is merely visible. Without it the machine surface re-opens exactly
+            // what the two-tier split closed for the text surface.
+            staleBinaries: stale.map((d) => ({
+                pid: d.pid,
+                entry: d.entry,
+                version: d.version,
+                actionable: staleTiers.actionable.some((a) => a.pid === d.pid),
+            })),
             daemonEnabled: enabled,
             services: {
                 secretsBroker: {
@@ -304,11 +422,36 @@ async function runStatus(opts) {
         console.log(`  Uptime:     ${humanDuration(uptime)}`);
     if (heartbeatAgeMs !== null)
         console.log(`  Heartbeat:  ${Math.round(heartbeatAgeMs / 1000)}s ago`);
-    console.log(`  Binary:     ${chalk.gray(owner?.entry ?? status.binaryPath ?? 'unknown')}`);
+    const binaryLabel = owner?.entry ?? status.binaryPath ?? 'unknown';
+    console.log(`  Binary:     ${ownerEntryGone ? chalk.red(`${binaryLabel}  (MISSING from disk)`) : chalk.gray(binaryLabel)}`);
     console.log(`  Version:    ${chalk.gray(owner?.version ?? 'unknown')}`);
     console.log(`  Log:        ${chalk.gray(status.logPath)}`);
     if (!enabled)
         console.log(chalk.yellow(`  daemon.enabled is false — nothing auto-starts it. Explicit start: agents daemon start`));
+    if (stale.length > 0) {
+        console.log(chalk.red(`\nStale code (${stale.length})\n`));
+        const actionablePids = new Set(staleTiers.actionable.map((d) => d.pid));
+        for (const d of stale) {
+            const mine = pid !== null && d.pid === pid ? ' — this is the daemon above' : '';
+            const note = mine || (actionablePids.has(d.pid) ? '' : ' — not this install; shown for visibility');
+            console.log(`  PID ${d.pid}  ${chalk.gray(d.entry ?? 'unknown entry')}${chalk.red('  (deleted)')}${chalk.gray(note)}`);
+        }
+        const advice = [
+            '\n  These run code that no longer exists on disk, so a restart fails and their',
+            '  behaviour is whatever was loaded when the file was deleted.',
+        ];
+        // Only offer a remedy when a row here is one we may act on. Printing
+        // `kill <pid>` under a section whose only rows are visibility-tier is
+        // RUSH-2368's harm re-entering through the render layer after the data
+        // layer stopped producing it.
+        if (staleTiers.actionable.length > 0) {
+            advice.push(`  Yours: ${chalk.white('agents daemon restart')}   A stray this install owns: ${chalk.white('kill <pid>')}`);
+        }
+        else {
+            advice.push('  None belong to this install — nothing for you to stop here.');
+        }
+        console.log(chalk.gray(advice.join('\n')));
+    }
     if (duplicates.length > 0) {
         console.log(chalk.red(`\nDuplicates (${duplicates.length})\n`));
         for (const d of duplicates) {
@@ -377,7 +520,7 @@ async function runLogs(opts) {
     const sinceMs = opts.since ? Date.now() - (parseDuration(opts.since) ?? 0) * 1000 : undefined;
     const lineCount = opts.lines ? parseInt(opts.lines, 10) : 50;
     if (opts.follow) {
-        const logPath = path.join(getDaemonDir(), 'logs.jsonl');
+        const logPath = getDaemonLogPath();
         for (const entry of parseLogLines(readDaemonLog(lineCount)).filter((e) => passesFilters(e, opts.level, sinceMs))) {
             if (opts.json)
                 console.log(JSON.stringify(entry));
@@ -419,10 +562,37 @@ async function runDoctor(opts) {
         problems.push('Daemon is not running. Start it: agents daemon start');
     if (status.running && isDaemonWedged())
         problems.push('Daemon is wedged (heartbeat stale). Restart: agents daemon restart');
-    const duplicates = registryScopedDuplicates(scanDaemonProcesses(), status.pid);
+    // RUSH-2418: an open auto-start circuit breaker is the FIRST thing to report
+    // for a stopped daemon — otherwise the only advice is "agents daemon start",
+    // which is the exact action the breaker just refused, with no hint that a
+    // breaker exists or what the underlying failure was. This is where the
+    // breaker's own message sends the operator, so it has to answer them.
+    const startHealth = readSubsystemHealth(SUBSYSTEM_DAEMON_START);
+    if (isDaemonAutostartCircuitOpen()) {
+        problems.push(`Daemon auto-start is disabled after ${startHealth?.consecutiveFailures ?? 0} consecutive starts that never reported healthy: ` +
+            `${startHealth?.lastError ?? 'no reason recorded'}. Fix the cause, then retry with: agents daemon start`);
+    }
+    else if (!status.running && startHealth && startHealth.consecutiveFailures > 0) {
+        // Only while the daemon is DOWN. A start is marked as failed the moment it
+        // is issued and cleared once the daemon finishes booting, so a running
+        // daemon with a non-zero streak is just the boot window (or a daemon
+        // launched outside startDaemon) — reporting it there is a false alarm that
+        // clears itself a second later.
+        problems.push(`Daemon start has ${startHealth.consecutiveFailures} consecutive failure(s): ${startHealth.lastError}`);
+    }
+    const healthProcesses = scanDaemonProcesses();
+    const duplicates = registryScopedDuplicates(healthProcesses, status.pid);
     if (duplicates.length > 0) {
         problems.push(`${duplicates.length} duplicate daemon process(es) running: ${duplicates.map((d) => d.pid).join(', ')}. Stop the stray(s).`);
     }
+    // A daemon whose entry is gone from disk is a problem even when it answers
+    // every probe: it cannot restart, and it is running whatever was loaded
+    // before the file was deleted (RUSH-2493).
+    for (const p of staleDaemons(healthProcesses, status.pid, new Set(findSurvivingStateDirDaemons(new Set()))).actionable) {
+        const own = status.pid !== null && p.pid === status.pid;
+        problems.push(`Daemon pid ${p.pid} runs code deleted from disk (${p.entry}). ` +
+            (own ? 'Restart it: agents daemon restart' : 'Stray from a removed install/worktree. Stop it: kill ' + p.pid));
+    }
     const secrets = await probeSecretsBroker();
     if (!secrets.reachable)
         problems.push('Secrets broker is unreachable.');
@@ -468,7 +638,7 @@ export function registerDaemonCommand(program) {
       # Identity, duplicates, and per-service health in one view
       agents daemon status
 
-      # Machine-readable status (for scripts / Factory)
+      # Machine-readable status (for scripts / AGI EXT)
       agents daemon status --json
 
       # Start / stop / restart the daemon process
@@ -486,6 +656,10 @@ export function registerDaemonCommand(program) {
       # Just the two hosted services (secrets broker, browser IPC)
       agents daemon services
 
+      # Manage public ingress for daemon-world webhook receivers
+      agents daemon funnel status yosemite-s0
+      agents daemon funnel up yosemite-s0 --local-port 8787 --port 443
+
       # Tail the daemon's own log, warnings and up, from the last hour
       agents daemon logs -f --level warn --since 1h
 
@@ -504,7 +678,7 @@ export function registerDaemonCommand(program) {
     `,
     });
     cmd.command('status')
-        .description('Identity (state/pid/uptime/binary), duplicate daemon processes, and per-service health.')
+        .description('Identity (state/pid/uptime/binary), duplicate daemons, daemons running deleted code, and per-service health.')
         .option('--json', 'Emit as JSON')
         .action(async (opts, command) => {
         await runStatus({ json: command.optsWithGlobals().json === true });
@@ -595,12 +769,67 @@ export function registerDaemonCommand(program) {
         const ok = signalDaemonReload();
         console.log(ok ? chalk.green('Daemon reloaded') : chalk.yellow('Reload signal not delivered (unsupported on this platform, or the daemon just exited)'));
     });
-    cmd.command('services')
-        .description('The two hosted services (secrets broker, browser IPC): bound state, socket path, and health.')
+    const servicesCmd = cmd
+        .command('services')
+        .description('The hosted services: health, bound state, socket path, and per-service toggles.')
         .option('--json', 'Emit as JSON')
         .action(async (opts, command) => {
         await runServices({ json: command.optsWithGlobals().json === true });
     });
+    servicesCmd
+        .command('list')
+        .description('List every daemon service and whether it is enabled.')
+        .option('--json', 'Emit as JSON')
+        .action(async (opts, command) => {
+        const json = command.optsWithGlobals().json === true;
+        const states = listDaemonServiceStates();
+        if (json) {
+            console.log(JSON.stringify(states.map((s) => ({
+                id: s.id,
+                title: s.title,
+                enabled: s.enabled,
+                description: s.description,
+            })), null, 2));
+            return;
+        }
+        console.log(chalk.bold('Daemon services'));
+        for (const s of states) {
+            const state = s.enabled ? chalk.green('enabled') : chalk.gray('disabled');
+            console.log(`  ${s.id.padEnd(18)} ${state}`);
+            console.log(`    ${chalk.gray(s.description)}`);
+        }
+        console.log(chalk.gray(`\nConfig: ${getDaemonServicesConfigPath()}`));
+        console.log(chalk.gray('Changes take effect on the next daemon reload or restart.'));
+    });
+    servicesCmd
+        .command('enable <service>')
+        .description('Enable a daemon service.')
+        .action((service) => {
+        if (!DAEMON_SERVICE_IDS.includes(service)) {
+            console.error(chalk.red(`Unknown service '${service}'. Run 'agents daemon services list' for valid services.`));
+            process.exit(1);
+        }
+        setDaemonServiceEnabled(service, true);
+        console.log(chalk.green(`Enabled '${service}'.`));
+        if (isDaemonRunning()) {
+            console.log(chalk.gray('Run `agents daemon reload` (or restart) to apply.'));
+        }
+    });
+    servicesCmd
+        .command('disable <service>')
+        .description('Disable a daemon service.')
+        .action((service) => {
+        if (!DAEMON_SERVICE_IDS.includes(service)) {
+            console.error(chalk.red(`Unknown service '${service}'. Run 'agents daemon services list' for valid services.`));
+            process.exit(1);
+        }
+        setDaemonServiceEnabled(service, false);
+        console.log(chalk.green(`Disabled '${service}'.`));
+        if (isDaemonRunning()) {
+            console.log(chalk.gray('Run `agents daemon reload` (or restart) to apply.'));
+        }
+    });
+    registerFunnelCommand(cmd);
     cmd.command('logs')
         .description('Read the daemon\'s own log (lifecycle + subsystem errors — not routine run output).')
         .option('-n, --lines <number>', 'Show this many recent lines', '50')

package/dist/commands/detach-core.d.ts

@@ -3,7 +3,7 @@
  * resolver. Kept import-light (only a type import) so it is unit-tested without
  * loading the live-session discovery graph.
  */
-import type { ActiveSession } from '../lib/session/active.js';
+import { type ActiveSession } from '../lib/session/active.js';
 /**
  * The prompt the backgrounded run resumes with. Its whole job is to stop a
  * now-unwatched agent from stalling on a confirmation nobody will answer: it

package/dist/commands/detach-core.js

@@ -1,3 +1,9 @@
+/**
+ * Pure core of `agents sessions detach` — the nudge, the resumed-run argv, and the id
+ * resolver. Kept import-light (only a type import) so it is unit-tested without
+ * loading the live-session discovery graph.
+ */
+import { sessionProcessHost } from '../lib/session/active.js';
 /**
  * The prompt the backgrounded run resumes with. Its whole job is to stop a
  * now-unwatched agent from stalling on a confirmation nobody will answer: it
@@ -40,8 +46,12 @@ export function resolveDetachTarget(s, self) {
     if (!sessionId) {
         return { kind: 'refuse', reason: 'That session has no id to resume, so it cannot be detached.' };
     }
-    if (s.machine && s.machine !== self) {
-        return { kind: 'remote', machine: s.machine, sessionId };
+    // The box to hop to is where the PROCESS is (a shim lives on its dispatcher),
+    // which is not always `machine`. `sessionProcessHost` returns undefined when
+    // the process is here, so a value means a genuine remote takeover.
+    const processHost = sessionProcessHost(s, self);
+    if (processHost) {
+        return { kind: 'remote', machine: processHost, sessionId };
     }
     return { kind: 'local', sessionId };
 }

package/dist/commands/detach.js

@@ -166,6 +166,6 @@ export async function detachAction(id, opts = {}) {
         detachedAtMs: Date.now(),
     });
     console.log(chalk.green(`◒ Backgrounded ${agent} ${short}`) +
-        chalk.gray(` — running headless (pid ${pid}). Bring it back: agents sessions attach ${short}`));
+        chalk.gray(` — running headless (pid ${pid}). Bring it back: agents sessions resume ${short}`));
     console.log(chalk.gray(`  logs: ${logFile}`));
 }

package/dist/commands/doctor.js

@@ -38,7 +38,12 @@ import { auditWindowsSshEnrollment, diagnoseWindowsSshFailure } from '../lib/dev
 import { scanUserRcFiles, masterPassphraseInEnv } from '../lib/secrets/rc-hygiene.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 import { readRepoBehindMarkers } from '../lib/auto-pull.js';
+import { detectAgentsBinaryShadows } from '../lib/binary-shadow.js';
+import { remediateStaleAgentsCliInstalls, resolveRunningPackageRoot, } from '../lib/self-update.js';
 import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+const __doctorDirname = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
 function collapseWhitespace(s) {
@@ -450,6 +455,7 @@ async function runDevicesDoctor(opts) {
                 // Can the owner-delivery lane escalate a block from THIS box? Local only —
                 // remote boxes self-report it in their own `agents doctor --json`.
                 ownerSink: await probeOwnerSink(readMeta()),
+                binaryShadows: detectAgentsBinaryShadows(),
             }));
             accounts[localName] = r.inventory?.signIn ?? {};
             continue;
@@ -1160,6 +1166,40 @@ function renderHookRuntimeRepairText(repair) {
         console.log(`  ${chalk.red('hold  ')}  ${chalk.gray(unresolved)}`);
     }
 }
+/**
+ * RUSH-2415: delete npx-cache / unsafe-legacy / pre-1.22.30 agents-cli copies
+ * when a fixed peer already exists. Bare `doctor --fix` is the remediation
+ * surface the multi-install warning points at; a targeted
+ * `doctor <agent>@<version> --fix` only heals that version home and must not
+ * touch other CLI installs on the box.
+ */
+function purgeStaleAgentsCliCopies(_opts) {
+    let runningRoot;
+    try {
+        // dist/commands/doctor.js (or src/commands/doctor.ts under vitest) —
+        // resolveRunningPackageRoot walks up until package.json names this package.
+        runningRoot = resolveRunningPackageRoot(__doctorDirname);
+    }
+    catch {
+        return null;
+    }
+    return remediateStaleAgentsCliInstalls({
+        runningRoot,
+        runningVersion: getCliVersion(),
+    });
+}
+function renderStaleInstallPurgeText(purge) {
+    if (purge.removed.length === 0 && purge.failed.length === 0)
+        return;
+    console.log(chalk.bold('\nStale agents-cli installs'));
+    for (const r of purge.removed) {
+        const why = r.reasons.join(', ');
+        console.log(`  ${chalk.green('purged')} ${chalk.gray(`${r.packageRoot}  ${r.version}  (${why})`)}`);
+    }
+    for (const f of purge.failed) {
+        console.log(`  ${chalk.red('hold  ')} ${chalk.gray(`${f.packageRoot}  ${f.version}  — ${f.error}`)}`);
+    }
+}
 async function runFix(parsed, opts) {
     // Heal targets the global install — project layer is irrelevant, so cwd is
     // left to heal's neutral default rather than process.cwd().
@@ -1180,23 +1220,41 @@ async function runFix(parsed, opts) {
     // repair have settled. This routine never calls sync/register and never
     // retries; unresolved wrappers remain an explicit non-zero doctor outcome.
     const hookRuntimeRepair = repairManagedHookRuntimeArtifacts({ filter: runtimeRepairFilter(parsed) });
+    // Bare doctor --fix also purges latent pre-fix / legacy agents-cli copies
+    // that only warn today (RUSH-2415). A scoped agent@version fix leaves them
+    // alone — the multi-install surface is machine-wide, not per-agent.
+    const staleInstallPurge = parsed === null ? purgeStaleAgentsCliCopies(opts) : null;
     const rewireFailed = rewired.some((entry) => entry.failure !== undefined);
     if (healChangedAnything(result) ||
         rewired.some((entry) => entry.rewired > 0 || entry.remaining > 0 || entry.failure !== undefined) ||
-        hookRuntimeRepair.attempts.length > 0) {
+        hookRuntimeRepair.attempts.length > 0 ||
+        (staleInstallPurge !== null && (staleInstallPurge.removed.length > 0 || staleInstallPurge.failed.length > 0))) {
         invalidateDoctorOverviewCache();
     }
     if (opts.json) {
-        console.log(JSON.stringify({ ...result, hookRewire: rewired, hookRuntimeRepair }, null, 2));
-        if (rewireFailed || hookRuntimeRepair.needsAttention.length > 0)
+        console.log(JSON.stringify({
+            ...result,
+            hookRewire: rewired,
+            hookRuntimeRepair,
+            ...(staleInstallPurge ? { staleInstallPurge } : {}),
+        }, null, 2));
+        if (rewireFailed
+            || hookRuntimeRepair.needsAttention.length > 0
+            || (staleInstallPurge !== null && staleInstallPurge.failed.length > 0)) {
             process.exitCode = 1;
+        }
         return;
     }
     renderHealText(result);
     renderHookRewireText(rewired);
     renderHookRuntimeRepairText(hookRuntimeRepair);
-    if (rewireFailed || hookRuntimeRepair.needsAttention.length > 0)
+    if (staleInstallPurge)
+        renderStaleInstallPurgeText(staleInstallPurge);
+    if (rewireFailed
+        || hookRuntimeRepair.needsAttention.length > 0
+        || (staleInstallPurge !== null && staleInstallPurge.failed.length > 0)) {
         process.exitCode = 1;
+    }
 }
 function checkLabel(row) {
     return `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
@@ -1374,7 +1432,7 @@ export function registerDoctorCommand(program) {
         .description('Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version]).')
         .option('--json', 'Output machine-readable JSON')
         .option('--diff', 'In target mode, include unified diffs for divergent files')
-        .option('--fix', 'Heal gaps: install missing resources, repair invalid plugin manifests, refresh stale plugins, and reconcile drift (all installed versions, or just the target)')
+        .option('--fix', 'Heal gaps: install missing resources, repair invalid plugin manifests, refresh stale plugins, reconcile drift, and purge stale/legacy agents-cli installs (npx-cache, pre-1.22.30, unsafe helper installer) when a fixed peer exists')
         .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,promptcuts)')
         .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
         .option('--adopt <agent>', "Take over the agent's native launcher that shadows the shim (symlink it to the version-managed shim; reversible with --release)")
@@ -1591,6 +1649,7 @@ export function registerDoctorCommand(program) {
                 .map((r) => `${r.agent}@${r.version}`);
             const findings = buildLocalFindings({
                 device: localName,
+                binaryShadows: detectAgentsBinaryShadows(),
                 syncRows,
                 orphanRows,
                 repoBehind: repoBehindMarkers,

package/dist/commands/events.d.ts

@@ -1,17 +1,16 @@
 /**
- * `agents events` — read the unified event stream.
+ * `agents events` — read the unified event stream (the one ops/timeline product).
  *
- * One stream over BOTH operational events (`~/.agents/.history/events/YYYY-MM-DD/`: every
- * `agents <module> <cmd>` invocation plus typed events like secrets access,
- * version installs) AND agent-semantic events (the per-session activity logs:
- * plans, PRs, worktrees, sub-agents, artifacts). Each is stamped with who ran
- * it and from where. This is the audit trail for "who accessed a secret /
- * created a team" AND the activity trail for "what did the agents just do".
+ * One stream over BOTH operational events (`~/.agents/.history/events/YYYY-MM-DD/`:
+ * every `agents <module> <cmd>` invocation plus typed events like secrets access,
+ * browser/computer, daemon lifecycle, version installs) AND agent-semantic events
+ * (per-session activity: plans, PRs, worktrees, sub-agents, artifacts). Run-dispatch
+ * outcomes land here as `run.dispatched` (readable via `--include runs`).
  *
- * Filter by `--module` (top-level group, e.g. teams; `activity` for agent
- * events), `--command` (path prefix), `--event` (typed event), `--agent`, and
- * `--since`. `--audit` restricts to operational events only. `--follow` tails
- * today's operational log live.
+ * `agents audit` and `agents logs` are thin aliases of this command.
+ *
+ * Filter with sessions-style `--include` / `--exclude` families (ops, activity,
+ * commands, runs, security) plus field filters (`--module`, `--event`, …).
  */
 import type { Command } from 'commander';
 /**
@@ -43,10 +42,23 @@ export interface EventsOptions {
     limit?: string;
     json?: boolean;
     follow?: boolean;
+    /** @deprecated Prefer --include ops / --exclude activity */
     audit?: boolean;
+    include?: string;
+    exclude?: string;
 }
 /** Add the one canonical event-reader option surface to a command or alias. */
 export declare function addEventsReadOptions(command: Command, includeAuditFlag?: boolean): Command;
-/** Canonical reader used by both `agents events` and `agents logs audit`. */
+/** Canonical reader used by `agents events`, `agents audit`, and `agents logs`. */
 export declare function runEventsCommand(options: EventsOptions, forceAudit?: boolean): Promise<void>;
+/** Shared by `events stats` and the `logs stats` alias. */
+export declare function runEventsStats(opts: {
+    since?: string;
+    json?: boolean;
+}): Promise<void>;
 export declare function registerEventsCommand(program: Command): void;
+/** Shared by `events rotate` and the `logs rotate` alias. */
+export declare function runEventsRotate(opts: {
+    days?: string;
+    maxMb?: string;
+}): void;