@phnx-labs/agents-cli 1.22.35 → 1.22.38

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;

package/dist/commands/events.js

@@ -1,22 +1,22 @@
 /**
- * `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 chalk from 'chalk';
 import * as fs from 'fs';
-import { getLogsPath } from '../lib/events.js';
+import { getLogsPath, stats, rotate } from '../lib/events.js';
 import { readUnifiedEvents } from '../lib/event-stream.js';
+import { parseFamilyList, EVENT_FAMILIES } from '../lib/event-families.js';
 import { ingestBatch } from '../lib/events-ingest.js';
 import { setHelpSections } from '../lib/help.js';
 /**
@@ -86,6 +86,15 @@ function detailFor(r) {
         bits.push(`skill=${r.skill}`);
     if (typeof r.version === 'string')
         bits.push(`v=${r.version}`);
+    // run.dispatched (and similar) — mode / outcome / exit / repo are the audit line.
+    if (typeof r.mode === 'string')
+        bits.push(`mode=${r.mode}`);
+    if (typeof r.outcome === 'string')
+        bits.push(`outcome=${r.outcome}`);
+    if (typeof r.exitCode === 'number')
+        bits.push(`exit=${r.exitCode}`);
+    if (typeof r.repo === 'string')
+        bits.push(chalk.gray(r.repo));
     if (typeof r.profile === 'string')
         bits.push(`profile=${r.profile}`);
     if (typeof r.error === 'string')
@@ -187,9 +196,11 @@ function registerEmitSubcommand(events) {
 /** Add the one canonical event-reader option surface to a command or alias. */
 export function addEventsReadOptions(command, includeAuditFlag = true) {
     command
-        .option('--module <name>', 'Only events from this group (e.g. teams, secrets, activity)')
+        .option('--include <families>', `Only these families (comma-sep): ${EVENT_FAMILIES.join(', ')}`)
+        .option('--exclude <families>', `Drop these families (comma-sep): ${EVENT_FAMILIES.join(', ')}`)
+        .option('--module <name>', 'Only events from this group (e.g. teams, secrets, activity, daemon, routine, watchdog, browser)')
         .option('--command <path>', 'Only this command path — prefix match (e.g. "teams create")')
-        .option('--event <type>', 'Only this typed event (repeatable, e.g. secrets.get, secrets.unlocked, pr.opened)', collect, [])
+        .option('--event <type>', 'Only this typed event (repeatable, e.g. secrets.get, run.dispatched, pr.opened)', collect, [])
         .option('--agent <name>', 'Only events tagged with this agent')
         .option('--caller <kind>', 'Only this caller kind (claude-code, codex, gemini, cursor, terminal, script)')
         .option('--level <level>', 'Only this level: audit, warn, info, debug')
@@ -199,11 +210,12 @@ export function addEventsReadOptions(command, includeAuditFlag = true) {
         .option('--limit <n>', 'Max records to show; 0 for no cap (default 50)', '50')
         .option('--json', 'Output raw records as JSON')
         .option('-f, --follow', "Tail today's operational log live");
-    if (includeAuditFlag)
-        command.option('--audit', 'Operational events only (skip agent activity)');
+    if (includeAuditFlag) {
+        command.option('--audit', 'Deprecated: operational events only — prefer --include ops or --exclude activity');
+    }
     return command;
 }
-/** Canonical reader used by both `agents events` and `agents logs audit`. */
+/** Canonical reader used by `agents events`, `agents audit`, and `agents logs`. */
 export async function runEventsCommand(options, forceAudit = false) {
     if (options.follow) {
         await followLog();
@@ -211,15 +223,29 @@ export async function runEventsCommand(options, forceAudit = false) {
     }
     let limit;
     let startDate;
+    let includeFamilies;
+    let excludeFamilies;
     try {
         limit = resolveEventsLimit(options.limit);
         startDate = options.since ? parseSince(options.since) : undefined;
+        if (options.include && options.exclude) {
+            throw new Error('--include and --exclude are mutually exclusive');
+        }
+        if (options.include)
+            includeFamilies = parseFamilyList(options.include, '--include');
+        if (options.exclude)
+            excludeFamilies = parseFamilyList(options.exclude, '--exclude');
     }
     catch (err) {
         console.error(chalk.red(err.message));
         process.exitCode = 2;
         return;
     }
+    // --audit / forceAudit = ops-only when no family flags. Families own the
+    // source selection via applyFamilies — never override includeActivity after.
+    const includeActivity = (includeFamilies !== undefined || excludeFamilies !== undefined)
+        ? true
+        : !(forceAudit || options.audit);
     const fetched = readUnifiedEvents({
         startDate,
         eventTypes: options.event && options.event.length ? options.event : undefined,
@@ -231,7 +257,9 @@ export async function runEventsCommand(options, forceAudit = false) {
         command: options.command,
         module: options.module,
         limit: limit === undefined ? undefined : limit + 1,
-        includeActivity: !(forceAudit || options.audit),
+        includeActivity,
+        includeFamilies,
+        excludeFamilies,
     });
     const { records, truncated } = capRecords(fetched, limit);
     const capNote = `Showing the newest ${limit} — more events matched. Pass --limit 0 for all.`;
@@ -251,29 +279,117 @@ export async function runEventsCommand(options, forceAudit = false) {
     if (truncated)
         console.log(chalk.yellow(capNote));
 }
+function humanBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function levelColor(level) {
+    if (level === 'audit')
+        return chalk.magenta(level);
+    if (level === 'warn')
+        return chalk.yellow(level);
+    if (level === 'debug')
+        return chalk.gray(level);
+    return chalk.blue(level);
+}
+/** Shared by `events stats` and the `logs stats` alias. */
+export async function runEventsStats(opts) {
+    let days = 7;
+    if (opts.since) {
+        try {
+            const d = parseSince(opts.since);
+            days = Math.max(1, Math.ceil((Date.now() - d.getTime()) / 86_400_000));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 2;
+            return;
+        }
+    }
+    const s = stats({ days });
+    if (opts.json) {
+        console.log(JSON.stringify(s, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`Event statistics (last ${days} day${days === 1 ? '' : 's'})\n`));
+    console.log(`  Total events:  ${s.totalEvents}`);
+    console.log(`  Log files:     ${s.fileCount} (${humanBytes(s.totalBytes)})`);
+    console.log(`  Log path:      ${chalk.gray(getLogsPath())}`);
+    if (Object.keys(s.byLevel).length) {
+        console.log(chalk.bold('\n  By level:'));
+        for (const [k, v] of Object.entries(s.byLevel).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${levelColor(k).padEnd(20)} ${v}`);
+        }
+    }
+    if (Object.keys(s.byEvent).length) {
+        console.log(chalk.bold('\n  By event (top 15):'));
+        for (const [k, v] of Object.entries(s.byEvent).sort((a, b) => b[1] - a[1]).slice(0, 15)) {
+            console.log(`    ${chalk.cyan(k).padEnd(30)} ${v}`);
+        }
+    }
+    if (Object.keys(s.byModule).length) {
+        console.log(chalk.bold('\n  By module:'));
+        for (const [k, v] of Object.entries(s.byModule).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${k.padEnd(20)} ${v}`);
+        }
+    }
+    console.log();
+}
 export function registerEventsCommand(program) {
     const events = addEventsReadOptions(program
         .command('events')
-        .description('Read the unified event stream (operational + agent activity)'))
+        .description('Read the unified event stream (ops + activity + run dispatch)'))
         .addHelpText('after', `
 Examples:
   agents events                          Everything — ops + agent activity
-  agents events --module activity        Agent activity only (plans / PRs / worktrees)
-  agents events --audit                  Operational events only (secrets / teams / ...)
-  agents events --event pr.opened --since 7d
+  agents events --exclude commands       Drop CLI command.start/end noise
+  agents events --include runs           Dispatched-run outcomes (was audit list)
+  agents events --include activity       Agent milestones only
+  agents events --include ops            Operational events only
+  agents events --include security       Audit-level (secrets, command.*, daemon, …)
   agents events --module secrets         Every secret accessed or revealed
   agents events --module secrets --bundle share
-                                         Every read of the share bundle (which agent, which session)
-  agents events --bundle share --session <id>
-                                         Trace one session's reads of a bundle
+  agents events --event pr.opened --since 7d
   agents events -f                       Live tail (operational)
-  agents events --event pr.opened --since 30d --limit 0 --json
-                                         Every match — use --limit 0 whenever you
-                                         aggregate, or you rank only the newest 50`)
+  agents events stats
+  agents events rotate --days 7
+
+  agents audit                           Alias of: events --include runs
+  agents logs                            Alias of: events`)
         .action((_options, command) => runEventsCommand(command.optsWithGlobals()));
     // `events` both reads (its own action, above) and writes (this subcommand) —
     // the same shape as `feed` / `feed post`.
     registerEmitSubcommand(events);
+    events
+        .command('stats')
+        .description('Show aggregate event statistics')
+        .option('--since <time>', 'Window size (e.g. 7d, 30d; default 7d)')
+        .option('--json', 'Output stats as JSON')
+        .action(async (opts) => runEventsStats(opts));
+    events
+        .command('rotate')
+        .description('Apply event retention and the storage ceiling immediately')
+        .option('--days <n>', 'Retention period in days (default 7)', '7')
+        .option('--max-mb <n>', 'Total event storage ceiling in MiB (default 50)', '50')
+        .action((opts) => runEventsRotate(opts));
+}
+/** Shared by `events rotate` and the `logs rotate` alias. */
+export function runEventsRotate(opts) {
+    const days = Math.max(1, parseInt(opts.days ?? '7', 10) || 7);
+    const maxMb = Math.max(1, parseInt(opts.maxMb ?? '50', 10) || 50);
+    const result = rotate(days, maxMb * 1024 * 1024);
+    const removed = result.removedByAge + result.removedBySize;
+    if (removed > 0) {
+        console.log(`Removed ${removed} event file${removed === 1 ? '' : 's'} ` +
+            `(${result.removedByAge} by age, ${result.removedBySize} by size); ` +
+            `reclaimed ${humanBytes(result.bytesReclaimed)}.`);
+    }
+    else {
+        console.log(chalk.gray(`No event files removed (retention ${days} days, ceiling ${maxMb} MiB).`));
+    }
 }
 /** commander repeatable-option collector. */
 function collect(value, previous) {