@phnx-labs/agents-cli 1.22.11 → 1.22.13

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 1.22.13
+
+- **`agents sessions` accepts direct live-state flags and remains fleet-wide by default.** `--working`, `--idle`, `--waiting`, `--orphan`/`--orphaned`, `--crashed`, `--closed`, `--abandoned`, `--queued`, and `--unknown` each imply the live scan; multiple flags form a union. `--working` is narrower than `--active`: it excludes idle, waiting, and lifecycle-failure rows. Cross-device collection was already the default and stays that way; `--local` opts out, while `--all` continues to widen historical directory and time scope. Source: `apps/cli/src/commands/sessions.ts`, `apps/cli/src/commands/sessions.test.ts`.
+
+- **Workflows: `name@source` disambiguation (Phase 5 packaging).** When two plugins (or a plugin and an extra repo) ship the same workflow name, pin the source: `agents run deploy@ship-tools` or `agents run workflow:deploy@social`. Bare names keep layered precedence (project > user > plugin > extra > system); a missing source returns no match instead of silently falling back. Source: `apps/cli/src/lib/workflows.ts`, `apps/cli/src/lib/resources/workflows.ts`.
+
+## 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`.

package/README.md

@@ -292,6 +292,10 @@ Search is the past tense. `--active` is the present -- it infers what each runni
 
 ```bash
 agents sessions --active            # every live run across the fleet, with state
+agents sessions --working           # actively producing work (fleet-wide)
+agents sessions --idle              # stopped between turns (fleet-wide)
+agents sessions --orphan            # agent outlived its terminal client
+agents sessions --crashed           # terminal and agent disappeared uncleanly
 agents sessions focus a1b2c3d4      # jump back into one — attach in place, or resume
 ```
 
@@ -322,7 +326,7 @@ Filters **stack** (they AND together), the active set shows in the header, and t
 | --- | --- |
 | ![sessions browser, preview hidden](assets/demos/sessions-preview-before.png) | ![sessions browser, preview open with a links line](assets/demos/sessions-preview-after.png) |
 
-Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), or `idle`, alongside badges for the PR it opened, the worktree it sits in, and the ticket it's working. `agents sessions focus [id]` attaches the live pane in place -- the tmux split locally or over SSH, or its Ghostty tab -- and falls back to a fresh tab + resume when the terminal is gone.
+Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), `idle`, or a lifecycle state such as `orphaned`, `crashed`, `closed`, `abandoned`, `queued`, or `unknown`. Pass the matching flag (`--working`, `--idle`, `--waiting`, `--orphan`, `--crashed`, `--closed`, `--abandoned`, `--queued`, `--unknown`) directly; each implies `--active`, and several flags form a union. The fleet fan-out is already the default; `--local` opts out. `--all` instead widens historical directory and time scope. Rows also carry badges for the PR, worktree, and ticket. `agents sessions focus [id]` attaches the live pane in place -- the tmux split locally or over SSH, or its Ghostty tab -- and falls back to a fresh tab + resume when the terminal is gone.
 
 Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work (including parsed Bash commands -- `git`, `npm`, `ffmpeg`, `ssh`, and so on), and the last test verdict -- the signals to reload a task in seconds.
 

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/.history/events/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/.history/events/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/repo.d.ts

@@ -17,7 +17,7 @@ import type { Command } from 'commander';
  * unit a user reasons about: one skill, one command, one plugin — even if it
  * spans several files on disk.
  */
-type RepoResourceKind = 'skill' | 'command' | 'plugin' | 'hook' | 'mcp' | 'subagent' | 'rule' | 'workflow' | 'routine' | 'profile' | 'permission' | 'cli' | 'config' | 'other';
+type RepoResourceKind = 'skill' | 'command' | 'plugin' | 'hook' | 'mcp' | 'subagent' | 'rule' | 'workflow' | 'routine' | 'profile' | 'permission' | 'clis' | 'config' | 'other';
 export type ChangeAction = 'new' | 'changed' | 'removed';
 /**
  * Map a repo-relative path to the resource unit it belongs to. Directory-based

package/dist/commands/repo.js

@@ -78,7 +78,7 @@ const RESOURCE_DIRS = {
     skills: 'skill', commands: 'command', prompts: 'command', plugins: 'plugin',
     hooks: 'hook', mcp: 'mcp', subagents: 'subagent', rules: 'rule',
     workflows: 'workflow', routines: 'routine', profiles: 'profile',
-    permissions: 'permission', cli: 'cli',
+    permissions: 'permission', clis: 'clis',
 };
 /** [singular, plural] display labels per kind. */
 const RESOURCE_LABELS = {
@@ -87,13 +87,13 @@ const RESOURCE_LABELS = {
     subagent: ['subagent', 'subagents'], rule: ['rule', 'rules'],
     workflow: ['workflow', 'workflows'], routine: ['routine', 'routines'],
     profile: ['profile', 'profiles'], permission: ['permission', 'permissions'],
-    cli: ['CLI', 'CLIs'], config: ['config file', 'config files'],
+    clis: ['CLI', 'CLIs'], config: ['config file', 'config files'],
     other: ['other file', 'other files'],
 };
 /** Display order — the resources a user cares about most come first. */
 const RESOURCE_ORDER = [
     'skill', 'command', 'plugin', 'hook', 'mcp', 'subagent', 'rule',
-    'workflow', 'routine', 'profile', 'permission', 'cli', 'config', 'other',
+    'workflow', 'routine', 'profile', 'permission', 'clis', 'config', 'other',
 ];
 /**
  * Map a repo-relative path to the resource unit it belongs to. Directory-based

package/dist/commands/sessions.d.ts

@@ -46,6 +46,16 @@ interface SessionsOptions extends SessionFilterOptions {
     flat?: boolean;
     /** With --active: show only sessions waiting on user input; exit 1 if any. */
     waiting?: boolean;
+    /** Live-state shorthand filters. Any one implies --active; several compose as OR. */
+    working?: boolean;
+    idle?: boolean;
+    orphan?: boolean;
+    orphaned?: boolean;
+    crashed?: boolean;
+    closed?: boolean;
+    abandoned?: boolean;
+    queued?: boolean;
+    unknown?: boolean;
     /** Show only favorited (starred) sessions — the `f` key's flag twin. */
     favorites?: boolean;
     /** Enrich the listing with live glyphs/preview for running rows. Default on;
@@ -311,6 +321,11 @@ export declare function gatherActiveSessions(opts?: {
     sessions: ActiveSession[];
     remoteDeviceCount: number;
 }>;
+export type LiveStatusFilter = 'working' | 'idle' | 'waiting' | 'orphaned' | 'crashed' | 'closed' | 'abandoned' | 'queued' | 'unknown';
+/** Match the status words users see, preserving activity's richer working signal. */
+export declare function matchesLiveStatus(session: ActiveSession, status: LiveStatusFilter): boolean;
+/** Resolve convenience flags once. Multiple flags intentionally form a union. */
+export declare function requestedLiveStatuses(options: SessionsOptions): LiveStatusFilter[];
 /**
  * A bare interactive fleet listing — no query, no render/filter flag — that the
  * `runSessionBrowser` picker can represent. The single predicate shared by the