@phnx-labs/agents-cli 1.22.11 → 1.22.12

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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`.

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/view.d.ts

@@ -32,7 +32,7 @@ export interface ViewSectionFilter {
     rules?: boolean;
     hooks?: boolean;
     promptcuts?: boolean;
-    cli?: boolean;
+    clis?: boolean;
 }
 /** Trim a description to a column-friendly snippet. Strips newlines, collapses whitespace. */
 export declare function summarizeDescription(desc: string | undefined, maxLen?: number): string;

package/dist/commands/view.js

@@ -154,7 +154,7 @@ function getProjectVersionFromCwd(agent) {
         return null;
     }
 }
-const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts', 'cli'];
+const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts', 'clis'];
 /**
  * Decide whether a section should render given the filter. If no flags are set,
  * everything renders (current behavior). If any flag is set, only those sections
@@ -231,7 +231,7 @@ function hostCliSourceTag(source) {
 }
 /**
  * Render the host-CLI section. Host CLIs are host-global: declared in any
- * DotAgents repo's `cli/` (project > user > system > extras), installed to PATH
+ * DotAgents repo's `clis/` (project > user > system > extras), installed to PATH
  * rather than copied into a version home. They render identically in the overview
  * and in a per-agent detail view because every agent on the host shares them.
  * The source tag shows which repo layer declared each — so user-level and
@@ -241,7 +241,7 @@ function renderHostClisSection(cwd) {
     const { statuses, errors } = listCliStatus(cwd);
     console.log(chalk.bold('\nHost CLIs\n'));
     if (statuses.length === 0) {
-        console.log(`  ${chalk.gray('none declared')} ${chalk.gray('— add one with `agents cli add <name>`')}`);
+        console.log(`  ${chalk.gray('none declared')} ${chalk.gray('— add one with `agents clis add <name>`')}`);
     }
     else {
         const nameWidth = Math.max(...statuses.map((s) => s.manifest.name.length));
@@ -258,7 +258,7 @@ function renderHostClisSection(cwd) {
             console.log(prefix + desc);
         }
         if (anyMissing) {
-            console.log(chalk.gray('  Install missing with `agents cli install`'));
+            console.log(chalk.gray('  Install missing with `agents clis install`'));
         }
     }
     for (const err of errors) {
@@ -1100,7 +1100,7 @@ async function showAgentResources(agentId, requestedVersion, filter) {
     if (shouldRenderSection('promptcuts', filter)) {
         renderPromptcuts();
     }
-    if (shouldRenderSection('cli', filter)) {
+    if (shouldRenderSection('clis', filter)) {
         renderHostClisSection(cwd);
     }
     // Show legend at the end if git repo exists and we showed all sections.
@@ -1565,7 +1565,7 @@ export async function viewAction(agentArg, options) {
         rules: options?.rules,
         hooks: options?.hooks,
         promptcuts: options?.promptcuts,
-        cli: options?.cli,
+        clis: options?.clis,
     };
     const filterIsSet = SECTION_KEYS.some((k) => filter[k]);
     // RUSH-1320: fold any stale literal `latest` version-home into its concrete
@@ -1684,7 +1684,7 @@ export function registerViewCommand(program) {
         .option('--rules', 'Show only rules in the detail view.')
         .option('--hooks', 'Show only hooks in the detail view.')
         .option('--promptcuts', 'Show only promptcuts in the detail view.')
-        .option('--cli', 'Show only host CLIs (declared in cli/, installed to PATH).')
+        .option('--clis', 'Show only host CLIs (declared in clis/, installed to PATH).')
         .option('--merged', 'Show the merged, first-wins resource surface across all layers (project, user, extras, system) in one table with the winning layer per row.')
         .addHelpText('after', `
 Examples:

package/dist/lib/cli-resources.js

@@ -217,7 +217,7 @@ export function parseCliManifest(contents, opts) {
  * manifests and any parse errors separately so the CLI can show both.
  */
 export function listCliManifests(cwd) {
-    const resolved = listResources('cli', cwd);
+    const resolved = listResources('clis', cwd);
     const manifests = [];
     const errors = [];
     for (const entry of resolved) {
@@ -240,7 +240,7 @@ export function listCliManifests(cwd) {
 }
 /** Resolve a single CLI manifest by name. Returns null when not declared. */
 export function resolveCliManifest(name, cwd) {
-    const resolved = resolveResource('cli', name, cwd);
+    const resolved = resolveResource('clis', name, cwd);
     if (!resolved)
         return null;
     if (!resolved.path.endsWith('.yaml') && !resolved.path.endsWith('.yml'))

package/dist/lib/event-stream.d.ts

@@ -1,6 +1,6 @@
 /**
  * The unified event reader -- one stream over BOTH operational events
- * (`~/.agents/.history/events/events.jsonl` via events.ts: secrets, commands, teams, ...) and
+ * (`~/.agents/.history/events/YYYY-MM-DD/` via events.ts: secrets, commands, teams, ...) and
  * agent-semantic events (the per-session activity logs via activity.ts: plans,
  * PRs, worktrees, sub-agents, artifacts). They share one {@link EventType}
  * vocabulary and one {@link EventRecord} shape, so `agents events` and any