@phnx-labs/agents-cli 1.22.10 → 1.22.12

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 1.22.12
+
+- Store operational events in daily history directories, retain 7 days and at most 50 MiB automatically, and make `agents logs audit` use the `agents events --audit` reader.
+
+- **`agents cli` renamed to `agents clis`; resource directory `cli/` renamed to `clis/`.** The CLI resource kind and its subdirectory are now plural throughout: `ResourceKind` changes from `'cli'` to `'clis'`, manifests live at `clis/<name>.yaml`, `agents clis` is the only command surface (no `agents cli` alias), and `agents view --clis` replaces `--cli`. A startup migration renames any existing `cli/` directory to `clis/` in the user, system, and project `.agents/` layers; if both `cli/` and `clis/` are present the migration fails with a clear error rather than silently merging. Source: `apps/cli/src/lib/resources.ts`, `apps/cli/src/lib/cli-resources.ts`, `apps/cli/src/commands/cli.ts`, `apps/cli/src/lib/startup/command-registry.ts`, `apps/cli/src/commands/repo.ts`, `apps/cli/src/commands/view.ts`, `apps/cli/src/lib/migrate.ts`.
+
+- **`agents.yaml` no longer silently loses top-level keys across a version-skewed
+  fleet.** `serializeCentral` (`lib/state.ts`) rewrote the synced `agents.yaml`
+  with a delete-any-key-not-in-the-in-memory-object pass. An **older CLI version
+  whose `Meta` type predated a key** (`beta:`, `notify.owner`, `feed:`, imported
+  `projects`) would parse the file, never surface that key, delete it on the next
+  write, and sync the deletion to every machine — the recurring "my config
+  vanished" data-loss (see the restore in commit `04295e3`). The delete pass now
+  consults a `Record<keyof Meta, 'central' | 'device'>` scope map (compile-time
+  exhaustive — a new `Meta` field that isn't classified fails the build) and
+  deletes **only keys this version knows** (a cleared central key, or a device
+  key that is legacy cruft in the synced file); a key it doesn't know is
+  preserved verbatim. Once a machine runs a CLI carrying this fix, it can never
+  drop a newer version's key again. Source: `apps/cli/src/lib/state.ts`,
+  `apps/cli/src/lib/__tests__/state.test.ts`.
+
+- **Watchdog files a feed block only when a session genuinely needs the human.**
+  When the smart brain concludes a stalled session must be left for the human
+  (`needsHuman`), the watchdog now surfaces that on the owner's feed instead of
+  dropping it in a menubar-only flag. Two cases: if the session is addressable it
+  injects a self-file reminder into the agent ("You appear stuck. File it: `agents
+  feed post … --blocked`") so the agent declares its own block; if it is
+  un-addressable — the case where the watchdog can't even reach the terminal to
+  remind it — the watchdog files a declared block on the agent's behalf so the owner
+  is still paged. Paging fires **only** on this confirmed-needs-human path: a plain
+  nudge-worthy drive-forward poke (un-addressable or under a hands-off policy) is
+  flagged for the tray but never texts the owner. Both paths are gated by the
+  existing cooldown ledger (at most once per `WATCHDOG_COOLDOWN_MS` window) and are
+  no-ops when a block for the session already exists, so no double-paging. Source:
+  `apps/cli/src/lib/watchdog/runner.ts` (`NudgeDecision.needsHuman`,
+  `WatchdogTickOptions.publishBlockFn`, the needs-human skip branch),
+  `apps/cli/src/lib/watchdog/runner.test.ts`.
+
+## 1.22.11
+
+- **`--blocked` iMessage notifications are now phone-actionable.** The forwarded message dropped the block's `--option`s, `--default`, and timeout and instead showed `agents focus <id>` — a CLI command that is useless on a phone. It now shows the choices (`Options: publish / wait`) and the safe-default fallback (`Default in 15 min: wait`) and omits the `agents focus` line, so a `--blocked` post that carries a `--default` self-resolves when the owner can't reply. Source: `apps/cli/src/lib/feed-broadcast.ts`.
+
+- Move operational event logs from the git-backed `~/.agents/` root into `~/.agents/.history/events/`, including existing numbered gzip archives.
+
+- **`agents projects` is out of beta — no `agents beta enable projects` needed.**
+  The command tree (list / add / import / status / link / …) is always registered
+  now; `projects` is dropped from the beta registry (`ALL_BETA_FEATURES`,
+  `BetaFeatureName`) and the `preAction` beta gate is removed. Any lingering
+  `beta.enabled: [projects]` entry is harmlessly ignored, and `agents beta
+  enable/disable projects` prints a friendly "graduated out of beta" note and
+  no-ops instead of erroring (so old scripts survive). Source:
+  `apps/cli/src/lib/beta.ts`, `apps/cli/src/lib/types.ts`,
+  `apps/cli/src/commands/beta.ts`, `apps/cli/src/commands/projects.ts`.
+
+- **`agents projects status` shows every project across the whole fleet by default;
+  scope it with `--device`/`--devices`.** The old `--fleet` flag is gone — status
+  now dials every registered device's workspace (presence, branch, drift) in one
+  parallel SSH round without being asked. `--device <name...>` (repeatable) or
+  `--devices a,b,c` narrows the fan-out to a subset; with no filter the whole fleet
+  is dialled. Reuses the shared `--host`/`--device` target resolution. Source:
+  `apps/cli/src/commands/projects.ts`.
+
+- **`scripts/release.sh` home-base hop: pass a single remote argv to `agents ssh`.** Multi-arg forms (`bash -lc '…'`) are joined without re-quoting by `wrapRemoteCommand`, so the remote `cd` never ran and publish failed with `fatal: not a git repository`. One shell string keeps the command intact. Source: `apps/cli/scripts/release.sh`.
+
 ## 1.22.10
 
 - **Plugins package workflows (Phase 5 packaging slice).** A plugin’s `workflows/<name>/WORKFLOW.md` is discovered and resolved by `agents run <name>` with precedence project > user > plugin > extra > system — no separate install into `~/.agents/workflows/` required. Plugin inventory / resource groups list `workflows`. Source: `apps/cli/src/lib/workflows.ts`, `apps/cli/src/lib/plugins.ts`, `apps/cli/src/lib/resources/workflows.ts`.

package/dist/commands/beta.js

@@ -2,17 +2,23 @@ import chalk from 'chalk';
 import { ALL_BETA_FEATURES, getBetaConfigLocation, getEnabledBetaFeatures, setBetaEnabled, } from '../lib/beta.js';
 const BETA_DESCRIPTIONS = {
     factory: 'Cloud-based agent dispatch via Rush Factory',
-    projects: 'Named multi-repo projects with a progress rollup (agents projects)',
 };
+// Features that used to be beta and are now always-on. `beta enable/disable` on
+// one of these is a friendly no-op, not an "Unknown beta feature" error — so
+// muscle memory and old bootstrap scripts survive the graduation.
+const GRADUATED_FEATURES = new Set(['projects']);
 function parseFeatures(values) {
     const valid = new Set(ALL_BETA_FEATURES);
-    const invalid = values.filter((value) => !valid.has(value));
-    if (invalid.length > 0) {
-        console.error(chalk.red(`Unknown beta feature: ${invalid.join(', ')}`));
+    for (const g of values.filter((v) => GRADUATED_FEATURES.has(v))) {
+        console.error(chalk.gray(`'${g}' has graduated out of beta — it is on by default; no action needed.`));
+    }
+    const unknown = values.filter((v) => !valid.has(v) && !GRADUATED_FEATURES.has(v));
+    if (unknown.length > 0) {
+        console.error(chalk.red(`Unknown beta feature: ${unknown.join(', ')}`));
         console.error(chalk.gray(`Valid features: ${ALL_BETA_FEATURES.join(', ')}`));
         process.exit(1);
     }
-    return values;
+    return values.filter((v) => valid.has(v));
 }
 export function registerBetaCommands(program) {
     const beta = program
@@ -43,16 +49,22 @@ Examples:
         .command('enable <features...>')
         .description('Enable one or more beta features.')
         .action((features) => {
-        const result = setBetaEnabled(parseFeatures(features), true);
-        console.log(chalk.green(`Enabled: ${features.join(', ')}`));
+        const parsed = parseFeatures(features);
+        if (parsed.length === 0)
+            return; // only graduated/no-op names
+        const result = setBetaEnabled(parsed, true);
+        console.log(chalk.green(`Enabled: ${parsed.join(', ')}`));
         console.log(chalk.gray(`Saved to ${result.path}`));
     });
     beta
         .command('disable <features...>')
         .description('Disable one or more beta features.')
         .action((features) => {
-        const result = setBetaEnabled(parseFeatures(features), false);
-        console.log(chalk.green(`Disabled: ${features.join(', ')}`));
+        const parsed = parseFeatures(features);
+        if (parsed.length === 0)
+            return; // only graduated/no-op names
+        const result = setBetaEnabled(parsed, false);
+        console.log(chalk.green(`Disabled: ${parsed.join(', ')}`));
         console.log(chalk.gray(`Saved to ${result.path}`));
     });
 }

package/dist/commands/cli.js

@@ -6,13 +6,13 @@ import { listCliManifests, listCliStatus, resolveCliManifest, installCli, descri
 import { getUserAgentsDir } from '../lib/state.js';
 import { isPromptCancelled } from './utils.js';
 function userCliDir() {
-    return path.join(getUserAgentsDir(), 'cli');
+    return path.join(getUserAgentsDir(), 'clis');
 }
 /** Render the status table — one row per declared CLI. */
 function printStatus(rows) {
     if (rows.length === 0) {
         console.log(chalk.gray('No CLIs declared.'));
-        console.log(chalk.gray(`Create one with: agents cli add <name>`));
+        console.log(chalk.gray(`Create one with: agents clis add <name>`));
         return;
     }
     const nameWidth = Math.max(4, ...rows.map((r) => r.manifest.name.length));
@@ -28,32 +28,32 @@ function printStatus(rows) {
 }
 export function registerCliCommands(program) {
     const cliCmd = program
-        .command('cli')
+        .command('clis')
         .description('Declare and install host CLI binaries (gh, higgsfield, glab, ...)')
         .addHelpText('after', `
-CLI manifests live in <repo>/cli/<name>.yaml and declare how to install a
-binary on the host. On a fresh machine, 'agents cli install' runs the first
+CLI manifests live in <repo>/clis/<name>.yaml and declare how to install a
+binary on the host. On a fresh machine, 'agents clis install' runs the first
 compatible method (npm > brew > script > binary) for every declared entry.
 
 Examples:
   # See which declared CLIs are installed on this host
-  agents cli list
+  agents clis list
 
   # Install everything that's missing
-  agents cli install
+  agents clis install
 
   # Install one
-  agents cli install higgsfield
+  agents clis install higgsfield
 
   # Show the manifest detail
-  agents cli view higgsfield
+  agents clis view higgsfield
 
   # Exit 0 if all declared CLIs are installed (use in CI / setup scripts)
-  agents cli check
+  agents clis check
 
 When to use:
   - After 'agents sync' on a new machine, to materialize host binaries
-  - In a team setup: commit cli/ entries so teammates get the same toolchain
+  - In a team setup: commit clis/ entries so teammates get the same toolchain
 `);
     cliCmd
         .command('list')
@@ -206,7 +206,7 @@ When to use:
     });
     cliCmd
         .command('add <name>')
-        .description('Scaffold a new manifest at ~/.agents/cli/<name>.yaml')
+        .description('Scaffold a new manifest at ~/.agents/clis/<name>.yaml')
         .option('--npm <pkg>', 'declare an npm install method')
         .option('--brew <formula>', 'declare a brew install method')
         .option('--script <url>', 'declare a curl|sh install method')

package/dist/commands/events.d.ts

@@ -1,7 +1,7 @@
 /**
  * `agents events` — read the unified event stream.
  *
- * One stream over BOTH operational events (`~/.agents/events.jsonl`: every
+ * 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
@@ -30,4 +30,23 @@ export declare function capRecords<T>(fetched: T[], limit: number | undefined):
     records: T[];
     truncated: boolean;
 };
+export interface EventsOptions {
+    module?: string;
+    command?: string;
+    event?: string[];
+    agent?: string;
+    caller?: string;
+    level?: string;
+    session?: string;
+    bundle?: string;
+    since?: string;
+    limit?: string;
+    json?: boolean;
+    follow?: boolean;
+    audit?: boolean;
+}
+/** 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`. */
+export declare function runEventsCommand(options: EventsOptions, forceAudit?: boolean): Promise<void>;
 export declare function registerEventsCommand(program: Command): void;

package/dist/commands/events.js

@@ -1,7 +1,7 @@
 /**
  * `agents events` — read the unified event stream.
  *
- * One stream over BOTH operational events (`~/.agents/events.jsonl`: every
+ * 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
@@ -184,21 +184,77 @@ function registerEmitSubcommand(events) {
     `,
     });
 }
-export function registerEventsCommand(program) {
-    const events = program
-        .command('events')
-        .description('Read the unified event stream (operational + agent activity)')
+/** 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('--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('--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')
         .option('--session <id>', 'Only events from this session (the provenance sessionId) — e.g. trace which session read a secret')
         .option('--bundle <name>', 'Only events carrying this bundle in their payload — e.g. `--module secrets --bundle share` for every read of the share bundle')
         .option('--since <time>', 'Only events newer than this (e.g. 2h, 7d, or ISO date)')
-        .option('--audit', 'Operational events only (skip agent activity)')
         .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")
+        .option('-f, --follow', "Tail today's operational log live");
+    if (includeAuditFlag)
+        command.option('--audit', 'Operational events only (skip agent activity)');
+    return command;
+}
+/** Canonical reader used by both `agents events` and `agents logs audit`. */
+export async function runEventsCommand(options, forceAudit = false) {
+    if (options.follow) {
+        await followLog();
+        return;
+    }
+    let limit;
+    let startDate;
+    try {
+        limit = resolveEventsLimit(options.limit);
+        startDate = options.since ? parseSince(options.since) : undefined;
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exitCode = 2;
+        return;
+    }
+    const fetched = readUnifiedEvents({
+        startDate,
+        eventTypes: options.event && options.event.length ? options.event : undefined,
+        level: options.level,
+        agent: options.agent,
+        sessionId: options.session,
+        bundle: options.bundle,
+        caller: options.caller,
+        command: options.command,
+        module: options.module,
+        limit: limit === undefined ? undefined : limit + 1,
+        includeActivity: !(forceAudit || options.audit),
+    });
+    const { records, truncated } = capRecords(fetched, limit);
+    const capNote = `Showing the newest ${limit} — more events matched. Pass --limit 0 for all.`;
+    if (options.json) {
+        if (truncated)
+            console.error(chalk.yellow(capNote));
+        console.log(JSON.stringify(records, null, 2));
+        return;
+    }
+    if (records.length === 0) {
+        console.log(chalk.gray('No matching events.'));
+        return;
+    }
+    for (const r of records.slice().reverse())
+        console.log(renderRow(r));
+    console.log(chalk.gray(`\n${records.length} event(s). Log: ${getLogsPath()}`));
+    if (truncated)
+        console.log(chalk.yellow(capNote));
+}
+export function registerEventsCommand(program) {
+    const events = addEventsReadOptions(program
+        .command('events')
+        .description('Read the unified event stream (operational + agent activity)'))
         .addHelpText('after', `
 Examples:
   agents events                          Everything — ops + agent activity
@@ -214,53 +270,7 @@ Examples:
   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`)
-        .action(async (options) => {
-        if (options.follow) {
-            await followLog();
-            return;
-        }
-        let limit;
-        let startDate;
-        try {
-            limit = resolveEventsLimit(options.limit);
-            startDate = options.since ? parseSince(options.since) : undefined;
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(2);
-        }
-        // Read one past the cap so we can tell a full result from a clipped one.
-        const fetched = readUnifiedEvents({
-            startDate,
-            eventTypes: options.event && options.event.length ? options.event : undefined,
-            agent: options.agent,
-            sessionId: options.session,
-            bundle: options.bundle,
-            command: options.command,
-            module: options.module,
-            limit: limit === undefined ? undefined : limit + 1,
-            includeActivity: !options.audit,
-        });
-        const { records, truncated } = capRecords(fetched, limit);
-        const capNote = `Showing the newest ${limit} — more events matched. Pass --limit 0 for all.`;
-        if (options.json) {
-            // Notice goes to stderr so `--json | jq` still receives clean JSON.
-            if (truncated)
-                console.error(chalk.yellow(capNote));
-            console.log(JSON.stringify(records, null, 2));
-            return;
-        }
-        if (records.length === 0) {
-            console.log(chalk.gray('No matching events.'));
-            return;
-        }
-        // query() returns newest-first; print oldest-first so a tail reads naturally.
-        for (const r of records.slice().reverse())
-            console.log(renderRow(r));
-        console.log(chalk.gray(`\n${records.length} event(s). Log: ${getLogsPath()}`));
-        if (truncated)
-            console.log(chalk.yellow(capNote));
-    });
+        .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);
@@ -271,7 +281,7 @@ function collect(value, previous) {
 }
 /** Tail today's event file, printing new lines as they land. */
 async function followLog() {
-    const file = getLogsPath();
+    let file = getLogsPath();
     let offset = 0;
     try {
         offset = fs.statSync(file).size;
@@ -281,6 +291,12 @@ async function followLog() {
     }
     console.log(chalk.gray(`Tailing ${file} — Ctrl-C to stop`));
     const drain = () => {
+        const nextFile = getLogsPath();
+        if (nextFile !== file) {
+            file = nextFile;
+            offset = 0;
+            console.log(chalk.gray(`Tailing ${file}`));
+        }
         let size = 0;
         try {
             size = fs.statSync(file).size;

package/dist/commands/logs.js

@@ -21,14 +21,14 @@
  * the same underlying helpers (showHostTaskLog / streamSessionTail).
  */
 import chalk from 'chalk';
-import * as fs from 'fs';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
 import { parseAgentFilter, renderSessionLog, renderSessionLogJson } from './sessions.js';
 import { streamSessionTail, isTailable } from './sessions-tail.js';
 import { showHostTaskLog, hostTaskLogJson } from '../lib/hosts/logs.js';
 import { listTasks } from '../lib/hosts/tasks.js';
 import { itemPicker } from '../lib/picker.js';
-import { query, stats, getLogsPath, rotate, levelFor, } from '../lib/events.js';
+import { stats, getLogsPath, rotate, } from '../lib/events.js';
+import { addEventsReadOptions, runEventsCommand } from './events.js';
 /** Compact one-line label used by both the picker and the non-TTY list. */
 function candidateLabel(c) {
     if (c.kind === 'task') {
@@ -178,32 +178,6 @@ function parseSince(s) {
         throw new Error(`Invalid --since value: ${s} (use e.g. 2h, 7d, or an ISO date)`);
     return new Date(ms);
 }
-function originLabel(r) {
-    if (r.transport === 'ssh') {
-        return chalk.yellow(`ssh${r.sshClientIp ? ' ' + r.sshClientIp : ''}`);
-    }
-    return chalk.gray('local');
-}
-function auditDetailFor(r) {
-    if (r.command)
-        return r.command;
-    const bits = [];
-    if (typeof r.team === 'string')
-        bits.push(`team=${r.team}`);
-    if (typeof r.bundle === 'string')
-        bits.push(`bundle=${r.bundle}`);
-    if (typeof r.skill === 'string')
-        bits.push(`skill=${r.skill}`);
-    if (typeof r.version === 'string')
-        bits.push(`v=${r.version}`);
-    if (typeof r.profile === 'string')
-        bits.push(`profile=${r.profile}`);
-    if (typeof r.server === 'string')
-        bits.push(`server=${r.server}`);
-    if (typeof r.error === 'string')
-        bits.push(chalk.red(r.error));
-    return bits.join(' ');
-}
 function levelColor(level) {
     if (level === 'audit')
         return chalk.magenta(level);
@@ -213,99 +187,6 @@ function levelColor(level) {
         return chalk.gray(level);
     return chalk.blue(level);
 }
-function renderAuditRow(r) {
-    const time = chalk.gray(r.ts.slice(0, 19).replace('T', ' '));
-    const user = `${r.osUser ?? '?'}@${r.hostname}`;
-    const ev = r.event.startsWith('error') ? chalk.red(r.event) : chalk.cyan(r.event);
-    const lvl = levelColor(r.level ?? levelFor(r.event));
-    const agent = r.agent ? chalk.gray(` ${r.agent}`) : '';
-    const caller = chalk.gray(`via ${r.caller ?? 'unknown'}${r.session ? ` ${r.session}` : ''}`);
-    return `${time}  ${lvl.padEnd(14)} ${originLabel(r).padEnd(24)} ${user.padEnd(22)} ${caller.padEnd(28)} ${ev.padEnd(26)}${agent}  ${auditDetailFor(r)}`;
-}
-function collect(value, previous) {
-    return previous.concat([value]);
-}
-async function runAudit(opts) {
-    if (opts.follow) {
-        await followAuditLog();
-        return;
-    }
-    const limit = Math.max(1, parseInt(opts.limit ?? '50', 10) || 50);
-    let startDate;
-    try {
-        startDate = opts.since ? parseSince(opts.since) : undefined;
-    }
-    catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(2);
-    }
-    const records = query({
-        startDate,
-        eventTypes: opts.event?.length ? opts.event : undefined,
-        level: opts.level,
-        agent: opts.agent,
-        caller: opts.caller,
-        command: opts.command,
-        module: opts.module,
-        limit,
-    });
-    if (opts.json) {
-        console.log(JSON.stringify(records, null, 2));
-        return;
-    }
-    if (records.length === 0) {
-        console.log(chalk.gray('No matching events.'));
-        return;
-    }
-    for (const r of records.slice().reverse())
-        console.log(renderAuditRow(r));
-    console.log(chalk.gray(`\n${records.length} event(s). Log: ${getLogsPath()}`));
-}
-async function followAuditLog() {
-    const file = getLogsPath();
-    let offset = 0;
-    try {
-        offset = fs.statSync(file).size;
-    }
-    catch {
-        // File may not exist yet — start at 0.
-    }
-    console.log(chalk.gray(`Tailing ${file} — Ctrl-C to stop`));
-    const drain = () => {
-        let size = 0;
-        try {
-            size = fs.statSync(file).size;
-        }
-        catch {
-            return;
-        }
-        if (size <= offset) {
-            if (size < offset)
-                offset = 0;
-            return;
-        }
-        const fd = fs.openSync(file, 'r');
-        try {
-            const buf = Buffer.alloc(size - offset);
-            fs.readSync(fd, buf, 0, buf.length, offset);
-            offset = size;
-            for (const line of buf.toString('utf-8').split('\n').filter(Boolean)) {
-                try {
-                    console.log(renderAuditRow(JSON.parse(line)));
-                }
-                catch {
-                    // Skip malformed lines.
-                }
-            }
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-    };
-    await new Promise(() => {
-        setInterval(drain, 500);
-    });
-}
 function humanBytes(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;
@@ -379,19 +260,9 @@ export function registerLogsCommand(program) {
         .option('-m, --full', 'Show the full raw transcript / stdout instead of the concise summary')
         .option('--json', 'Machine-readable JSON: a host task as { kind, task, log }, a session as the redacted { session, events } (same shape as `sessions <id> --json`)')
         .action((id, opts) => runLogs(id, opts));
-    logsCmd
+    addEventsReadOptions(logsCmd
         .command('audit')
-        .description('Read the structured audit/event log (who ran what, from where)')
-        .option('--module <name>', 'Only events from this command group (e.g. teams, secrets)')
-        .option('--command <path>', 'Only this command path — prefix match (e.g. "teams create")')
-        .option('--event <type>', 'Only this typed event (repeatable)', 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')
-        .option('--since <time>', 'Only events newer than this (e.g. 2h, 7d, or ISO date)')
-        .option('--limit <n>', 'Max records to show (default 50)', '50')
-        .option('--json', 'Output raw records as JSON')
-        .option('-f, --follow', "Tail today's log live")
+        .description('Alias for `agents events --audit`'), false)
         .addHelpText('after', `
 Examples:
   agents logs audit                          Recent activity across everything
@@ -401,7 +272,7 @@ Examples:
   agents logs audit --command "teams create" Just team creations
   agents logs audit --event secrets.get --since 7d --json
   agents logs audit -f                       Live tail`)
-        .action(async (options) => runAudit(options));
+        .action((_options, command) => runEventsCommand(command.optsWithGlobals(), true));
     logsCmd
         .command('stats')
         .description('Show aggregate audit statistics')
@@ -410,16 +281,21 @@ Examples:
         .action(async (opts) => runStats(opts));
     logsCmd
         .command('rotate')
-        .description('Force log rotation — remove files older than the retention period')
+        .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) => {
         const days = Math.max(1, parseInt(opts.days ?? '7', 10) || 7);
-        const removed = rotate(days);
+        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} log file${removed === 1 ? '' : 's'} older than ${days} day${days === 1 ? '' : 's'}.`);
+            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 log files to remove.'));
+            console.log(chalk.gray(`No event files removed (retention ${days} days, ceiling ${maxMb} MiB).`));
         }
     });
 }

package/dist/commands/projects.d.ts

@@ -1,8 +1,7 @@
 /**
  * `agents projects` — named, multi-repo projects and the progress
  * rollup. Definitions live in `~/.agents/projects/<name>.yaml` (see
- * `lib/projects.ts`); this registers the command tree over them. Beta-gated on
- * `isBetaEnabled('projects')`, mirroring `agents factory`.
+ * `lib/projects.ts`); this registers the command tree over them.
  *
  * The headline is `status`: instead of the vague per-agent activity line, it
  * rolls every session up by project (matched on cwd) into one card — agents by