@phnx-labs/agents-cli 1.21.1 → 1.21.2

package/CHANGELOG.md

@@ -1,5 +1,177 @@
 # Changelog
 
+## 1.21.2
+
+- **`agents trends` — resource and session analytics dashboard.** Baked recipes
+  (harness/model mix, tools per session, token ratio, secrets/browser hot lists)
+  read `sessions.db` plus a new value-free warehouse at
+  `~/.agents/.history/analytics/usage.db`. Secrets usage migrates once from
+  `secrets.db`; agent run and browser launch/close emit into the warehouse.
+  Quota stays on `agents usage`, latency on `agents perf`.
+  Source: `apps/cli/src/commands/trends.ts`, `apps/cli/src/lib/analytics/`.
+
+- **The macOS menu bar app is now named AGI Menu in System Settings and
+  Accessibility prompts.** Privacy & Security previously showed the executable
+  name `MenubarHelper` because the bundle had no `CFBundleDisplayName`. The
+  bundle now ships `CFBundleName` / `CFBundleDisplayName` = `AGI Menu`, and
+  `agents menubar` status/enable/disable copy uses the same name. An install
+  that was left ad-hoc-signed by an older heal path is also replaced from the
+  Developer-ID source on the next `agents` run, so Accessibility stops
+  re-prompting for a new identity every upgrade. Source:
+  `apps/cli/menubar/scripts/build.sh`, `apps/cli/src/commands/menubar.ts`,
+  `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **Cursor usage bars now show Auto/API/Total, and Cursor sessions carry live todo progress.** `agents view` reads Cursor's dashboard `get-current-period-usage` first for the Auto + Composer (`A`) / API (`API`) / Total (`T`) percent breakdown, falls back to `usage-summary` for accounts without a usable `planUsage`, and only drops to the legacy monthly request bar (`M`) for request-capped free/legacy plans. `agents sessions` also now folds a Cursor session's `TodoWrite` calls into `SessionMeta.todos`, so the checklist progress shown for Claude/Codex/Kimi sessions renders for Cursor too. Source: `apps/cli/src/lib/usage.ts`, `apps/cli/src/lib/session/discover.ts`.
+
+- **`feed.broadcast` gains an in-process `channel:` sink and an implicit owner
+  fallback (RUSH-2123).** A `feed.broadcast` sink can now declare `channel: <name>`
+  (plus `to:` for a non-owner destination) instead of `command: [argv...]` — it
+  delivers through the same channel-provider registry `agents send`/`agents notify`
+  use (`deliverEnvelope()`), no spawn. `channel: owner` is the address alias,
+  expanding to `notify.owner.{channel,to}`. When an operator has `notify.owner`
+  configured but never wrote a `feed.broadcast` block at all, an important-level
+  post (`--level important`, or any `--blocked` post) now falls back to that owner
+  address automatically instead of reaching nobody — previously a `feed post
+  --blocked` with `notify.owner` set and no `feed.broadcast` looked recorded but
+  delivered to no one. A routine milestone post still stays record-only even with
+  the fallback available, and an operator-declared `feed.broadcast` always wins
+  outright. `command:` argv sinks (the tracker/webhook escape hatch) are unchanged.
+  Source: `apps/cli/src/lib/feed-broadcast.ts`, `apps/cli/src/commands/feed.ts`.
+
+- **`agents run` no longer stalls on a live usage fetch, and the daemon keeps the
+  quota cache warm instead (RUSH-2061).** The router's candidate collection
+  (`collectRunCandidates`) used to block on a live provider HTTP read whenever an
+  account's usage snapshot was older than 5 minutes — one round trip per account
+  added to cold-start. It now reads the usage cache **cache-only** (`readOnly`) and
+  never touches the network; an unconfirmable snapshot is simply routed around by
+  the existing freshness guard (`isUsageVerified`). A new daemon refresher
+  (`runUsageRefresh`) keeps that cache fresh in the background: it refreshes only
+  accounts signed in on THIS host (sole-writer, no cross-host coordination), on an
+  adaptive cadence from each account's session-window burn rate (90s when racing
+  toward the 5h cap, up to 15min when idle), capped at ~6 provider calls per
+  account per hour and skipped entirely while a provider is under a 429 backoff.
+  Source: `apps/cli/src/lib/usage.ts`, `apps/cli/src/lib/usage-refresh.ts`,
+  `apps/cli/src/lib/rotate.ts`, `apps/cli/src/lib/daemon.ts`.
+
+- **Balanced routing now deprioritizes an account projected to cap soon, not just
+  one already maxed (RUSH-2061).** `deriveUsageHeadroom` projects minutes-to-limit
+  from the session-window burn rate; balanced weighting scales an account's
+  headroom weight down as that projection shortens (`capacityWeight`), so a launch
+  avoids an account racing toward its 5-hour cap instead of only skipping a
+  100%-maxed one. Source: `apps/cli/src/lib/usage.ts`, `apps/cli/src/lib/rotate.ts`.
+
+- **The daemon no longer SSH-probes the whole fleet every 3 minutes — fleet status
+  is publish-own / read-union now (RUSH-2061, RUSH-2114).** The daemon's fleet-cache
+  warm force-probed every registered device over ssh on every tick; with N daemons
+  each probing N devices that was N² remote resource probes across the fleet every
+  3 minutes, and the source of the orphaned fleet-doctor probe pile-up. Each daemon
+  now probes only **itself** (no ssh) and publishes its own row — resource stats
+  **plus live-agent workload** (running-agent count and a per-context / per-agent
+  breakdown) — to a shared local mirror (`~/.agents/.cache/.fleet-status.json`).
+  Cross-host rows are unioned on demand by the reader: `agents devices status`
+  gathers peers cache-first, ssh-reading a stale/missing peer via
+  `agents devices status --local --json` through a bounded, kill-on-timeout
+  fan-out. `agents devices status` (and `--json`) now shows how many agents are
+  running on each box. Source: `apps/cli/src/lib/fleet-status.ts`,
+  `apps/cli/src/lib/fleet-cache.ts`, `apps/cli/src/lib/daemon.ts`,
+  `apps/cli/src/lib/devices/health-report.ts`, `apps/cli/src/commands/ssh.ts`.
+
+- **`agents doctor --json` is no longer a ~136-second stall (RUSH-2136).** The
+  overview probed every host-CLI manifest with a blocking `spawnSync` (10s timeout
+  each) one after another, so a dozen-plus slow checks summed into minutes. The
+  checks now run concurrently (`listCliStatusAsync`), so total time is the slowest
+  single check, not their sum; the per-check 10s kill-on-timeout is preserved.
+  Source: `apps/cli/src/lib/cli-resources.ts`, `apps/cli/src/commands/doctor.ts`.
+
+- **Metrics foundation: hook/command instrumentation + routine metrics.** Every
+  hook now instruments through a generated shim — `matcher:`-only hooks like
+  git-guard/rm-guard/git-require-clean-tree previously fired with zero perf
+  samples; `agents perf hooks` now reports them. `agents perf` gains
+  `--project <key>` (scope to one repo), a `P95` column alongside P50/P99, and
+  an `ERR/TIMEOUT` rate column. New `agents perf friction` surfaces sessions
+  stuck repeatedly hitting the same guard block instead of adapting. New
+  `agents routines stats [name]` reports run count/failed/missed/avg/p50/p95
+  duration per routine; `agents routines runs --json` now includes `duration`.
+  Routine session transcripts are now archived for gemini/antigravity/droid/
+  kimi/grok routines, not just claude/codex/cursor. Source:
+  `apps/cli/src/lib/hooks.ts`, `apps/cli/src/lib/perf/db.ts`,
+  `apps/cli/src/commands/perf.ts`, `apps/cli/src/lib/routines.ts`,
+  `apps/cli/src/lib/runner.ts`.
+
+- **The Linear line on `agents projects status` is cached, and stops vanishing.** The card
+  paged every issue in a project on every invocation — up to 10 requests per project — against
+  a 2500/hour request budget that an agent running `status` in a loop exhausts. Answers are now
+  cached on disk for 10 minutes (`~/.agents/.cache/linear-projects/`, one file per project written
+  by atomic rename so concurrent agent sessions cannot clobber each other), so a repeated
+  `status` spends zero Linear requests. More importantly, a failed or rate-limited fetch now
+  serves the last good answer marked stale instead of dropping the line: a populated Linear row
+  silently disappearing on one 8s timeout was the observed defect, and it is the same rule
+  `mergeAuthHealthEntries` already keeps for account health. A 429 records its
+  `x-ratelimit-requests-reset` so later runs don't spend a request to be told there are none
+  left. Source: `apps/cli/src/lib/linear-cache.ts`.
+
+- **The compact `projects status` card shows the milestone it calls `next`.** Milestones are
+  listed in date order, and Linear can flag a later-dated one as next — so slicing the front
+  of the list showed an earlier milestone while burying the actual next under `+N more`, which
+  is the one thing that row exists to say. The next milestone now leads, and identity is
+  matched on name plus target date rather than name alone (two milestones can share a name,
+  which put the `next` label on the wrong row). Source: `apps/cli/src/commands/projects.ts`.
+
+- **`agents projects` stops reading the wrong GitHub repository.** Factory derives a
+  project's `owner/repo` from the checkout path's last two segments, so a repo cloned to
+  `~/src/github.com/<you>/agents-cli` whose origin is `phnx-labs/agents-cli` imported as
+  `<you>/agents-cli`. Both are real repositories, so nothing errored — the card's merged-PR
+  and release lines simply reported a stranger's repo (0 merges in 7 days instead of 100).
+  `import --from-factory` now reads the checkout's actual `origin` and only falls back to the
+  path guess when there is no remote to ask, and `status`/`show` print a warning with the fix
+  when a stored slug disagrees with the remote. Source: `apps/cli/src/lib/project-doctor.ts`.
+- **`agents projects set <name>` changes one field without destroying the rest.** Previously
+  the only ways to correct a field were `$EDITOR` on raw YAML or `add --force`, which rebuilds
+  the definition from flags alone and silently drops `linear`, `contexts`, and `description`.
+  `set` loads, patches the named field, and writes back. Flags: `--repo`, `--root`, `--path`,
+  `--description`. Source: `apps/cli/src/commands/projects.ts`.
+- **Merged-PR counts say when they are a lower bound.** The `gh` fetch caps at 100, and a busy
+  repo where all 100 land inside the window has more — the count now renders `100+` rather than
+  presenting the cap as a total, matching the existing Linear `2500+` contract. Source:
+  `apps/cli/src/lib/project-status.ts`.
+
+- **`agents projects view <name>`** replaces `show` (kept as an alias) and now renders the
+  project's full plan: every declared Linear milestone with its date and progress, issue
+  counts, and a warning when no issues are assigned to any milestone — a milestone nothing is
+  filed against cannot report progress, and a row of silent `0%`s hid that. Sixteen other
+  command groups already use `view <name>`; `projects` was the only one that did not. Source:
+  `apps/cli/src/commands/projects.ts`.
+- **The status headline counts live agents, not corpses.** It read `39 agents` on a project
+  where 19 had crashed. It now reads `19 live`, with a separate `dead` row breaking down what
+  finished or was lost — 19 crashed sessions is a thing to go fix, not throughput. `orphaned`
+  counts as **live**: `session/active.ts` defines it as "alive, but no client is attached", and
+  the repo's own dead rule is `closed` + `crashed` only. Source:
+  `apps/cli/src/lib/project-status.ts`.
+- **`planPct` is gone from the card and from `--json`.** It summed each matched session's most
+  recent checklist snapshot, so one agent opening a fresh 40-item plan rendered the whole
+  project `0% plan`, and a project where nobody had written a checklist showed no figure at
+  all. A cross-session sum of ad-hoc checklists does not measure project progress. `live` and
+  `dead` counts replace it in `--json`.
+- **The next milestone comes from Linear's own `status: "next"`** when Linear sets it, falling
+  back to earliest-dated-unfinished only when nothing is flagged — Linear's answer is the one
+  shown in its UI, ours is a guess.
+
+- **A regression guard for the distributed `--active --local` / `--host` session-query paths, wired into CI (#1866).** RUSH-2118 fixed a `--local` query dialing remote-host teammates over real ssh, but nothing bench-guarded the fix's latency, and the `--host` cross-fleet fan-out had no bench at all. `bench/sessions-active-perf.ts` times `AgentManager(..., localOnly=true).listAll()` against N synthetic remote-host teammates (asserting zero ssh calls and sub-500ms latency, with a positive-control run proving the ssh-PATH shim actually intercepts) and the `gatherActiveSessions({ hosts })` fan-out against N synthetic peers (asserting it stays parallel, not sequential). Wired into `.github/workflows/bench.yml` as the one gating step in that workflow — every other bench step stays `continue-on-error`. Documented with measured baselines in `apps/cli/docs/05-sessions.md#benchmarks`. Source: `apps/cli/bench/sessions-active-perf.ts`, `.github/workflows/bench.yml`.
+
+- **`agents view` columns stay aligned across agents, and usage no longer piles up (view-ui-perf).**
+  The multi-agent overview padded every row to the widest usage string — an
+  Antigravity account with four model quotas forced ~194-column lines that
+  wrapped so `rate-limited` and last-active drifted under the version column.
+  Overview now caps compact meters to two windows (`+N` for the rest), always
+  emits fixed account/usage/status/lastActive columns (empty cells space-padded),
+  and measures padding with `stringWidth` so chalk + block bars don't skew
+  gutters. Usage fetches go through one unified core: 5-minute fresh cache
+  (was 2), concurrency-capped live reads (`USAGE_FETCH_CONCURRENCY=3`),
+  single-flight per identity, and a background SWR queue capped at 2 so delayed
+  HTTP responses cannot stack. Spinner stays up through account+usage load.
+  Source: `apps/cli/src/commands/view.ts`, `apps/cli/src/lib/usage.ts`,
+  `apps/cli/src/lib/agents.ts`.
+
 ## 1.21.1
 
 - **Feed posts require a title + body; phone `{message}` ends with a Sent-from footer.** `agents feed post --title "Short subject" "body text"` — title is the phone first line (~4–5 words), body follows after a blank line, then `Sent from <agent>/<session-chunk> on <host>` (like "Sent from my iPhone"). Em/en dashes in title/body are scrubbed to ASCII ` - `. Source: `apps/cli/src/lib/feed-broadcast.ts`, `feed-post.ts`, `commands/feed.ts`.

package/README.md

@@ -875,6 +875,7 @@ agents routines add daily-digest \
 agents routines list                   # All jobs + next run times
 agents routines run daily-digest       # Test it now, ignore the schedule
 agents routines logs daily-digest      # Last execution — status + report (add --full for raw stdout)
+agents routines stats                  # Run count, failed, missed, avg/p50/p95 duration — per job or all
 
 # Routines sync to every device; restrict to an allowlist with --devices
 agents routines add nightly-drain --schedule "0 3 * * *" --agent claude \

package/dist/commands/doctor.js

@@ -25,7 +25,7 @@ import { isVersionIsolated } from '../lib/versions.js';
 import { computeDrift, checkSyncStatus, countOrphans, computeSourceBehind } from '../lib/drift.js';
 import { readAuthHealthCache, summarizeHostAuth } from '../lib/auth-health.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
-import { listCliStatus } from '../lib/cli-resources.js';
+import { listCliStatus, listCliStatusAsync } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
 import { heal, healChangedAnything } from '../lib/heal.js';
 import { getEffectiveExecutionPolicy } from '../lib/platform/winpath.js';
@@ -1291,7 +1291,10 @@ export function registerDoctorCommand(program) {
             const clis = checkAllClis();
             const syncRows = checkSyncStatus(cwd);
             const orphanRows = countOrphans();
-            const hostClis = listCliStatus(cwd);
+            // Parallel host-CLI probe (RUSH-2136): the serial spawnSync version ran a
+            // dozen+ blocking 10s-timeout checks one after another, which measured
+            // ~136s on an idle box and stalled the menu-bar helper's poll.
+            const hostClis = await listCliStatusAsync(cwd);
             const repoBehindMarkers = readRepoBehindMarkers();
             // The local inventory now carries per-version sign-in (RUSH-2069), so it
             // is the single source for both the accounts line and the logged-out

package/dist/commands/feed.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildDeclaredBlock, publishBlock, } from '../lib/feed.js';
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/activity.js';
 import { postFeedStatus } from '../lib/feed-post.js';
-import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, blockBroadcastContext, blockDeliveryFailure, } from '../lib/feed-broadcast.js';
+import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, effectiveBroadcastConfig, blockBroadcastContext, blockDeliveryFailure, } from '../lib/feed-broadcast.js';
 import { getSessionById } from '../lib/session/db.js';
 import { readMeta } from '../lib/state.js';
 import { enrichBlocksFromSessions, groupBlocksByOutcome, isUnambiguousOutcomeAnswer, openBlocksForOutcome, stampBlockOutcomes, } from '../lib/feed-outcome.js';
@@ -274,7 +274,7 @@ time. No em-dashes in title/body - they are scrubbed on the way out.
 Configure where a post is mirrored under feed.broadcast in agents.yaml - see
 docs/06-observability.md.
 `)
-        .action((textParts, opts, cmd) => {
+        .action(async (textParts, opts, cmd) => {
         // Parent `feed` also declares `--json` (for the list view). Commander
         // binds the flag on the parent, so a `feed post … --json` lands on
         // parent.opts().json — not the child. Read both.
@@ -303,6 +303,7 @@ docs/06-observability.md.
                 throw new Error('Missing --title. Usage: agents feed post --title "Short subject" "body text"');
             }
             const level = flags.blocked ? 'important' : parseFeedPostLevel(flags.level);
+            const meta = readMeta();
             const { event } = postFeedStatus({
                 title: flags.title,
                 text: Array.isArray(textParts) ? textParts.join(' ') : String(textParts ?? ''),
@@ -325,15 +326,15 @@ docs/06-observability.md.
                     safeDefault: flags.default,
                 });
                 publishBlock(block);
-                outcomes = broadcastBlock(block, {
+                outcomes = await broadcastBlock(block, {
                     project: event.project,
                     agent: event.agent,
                     title: event.title,
                     body: event.detail,
-                });
+                }, meta);
             }
             else {
-                outcomes = broadcastPostedEvent(event, level);
+                outcomes = await broadcastPostedEvent(event, level, meta);
             }
             // Fail loud when a block reached nobody. This is computed BEFORE the
             // --json early return: a machine caller is exactly the one that reads the
@@ -562,15 +563,21 @@ docs/06-observability.md.
 }
 /**
  * Mirror a written post to the configured sinks (`feed.broadcast` in
- * agents.yaml). The ticket is JOINED from the session index rather than asked
- * for as a flag — it is a domain fact about the session, and an agent that has
- * to remember a `--ticket` argument is an agent that will forget it. Returns the
- * per-sink outcomes; an empty array means nothing is configured, which is the
- * default and is not a failure.
+ * agents.yaml, or the implicit `notify.owner` fallback for an important post —
+ * see {@link effectiveBroadcastConfig}). The ticket is JOINED from the session
+ * index rather than asked for as a flag — it is a domain fact about the
+ * session, and an agent that has to remember a `--ticket` argument is an agent
+ * that will forget it. Returns the per-sink outcomes; an empty array means
+ * nothing is configured and no fallback applies, which is not a failure for a
+ * routine post (see `blockDeliveryFailure` for the `--blocked` case).
+ *
+ * `meta` is threaded in rather than read here so the fallback/config decision
+ * and the delivery are pinned to one config snapshot, and so this is testable
+ * against a real in-memory `Meta` without touching `~/.agents/agents.yaml`.
  */
-function broadcastPostedEvent(event, level) {
-    const config = readMeta().feed?.broadcast;
-    if (!config || Object.keys(config).length === 0)
+async function broadcastPostedEvent(event, level, meta) {
+    const config = effectiveBroadcastConfig(meta.feed?.broadcast, level, meta);
+    if (!config)
         return [];
     const ticket = getSessionById(event.sessionId)?.ticketId;
     const planned = planFeedBroadcast(config, {
@@ -586,22 +593,24 @@ function broadcastPostedEvent(event, level) {
             .map((a) => a.href)
             .filter((href) => /^https?:\/\//i.test(href)),
     });
-    return runFeedBroadcast(planned);
+    return runFeedBroadcast(planned, meta);
 }
 /**
- * Mirror a declared block to the same sinks a post reaches.
+ * Mirror a declared block to the same sinks a post reaches (plus the implicit
+ * `notify.owner` fallback — a block is always `important`, so it always
+ * qualifies).
  *
  * Blocks previously never broadcast at all: `broadcastPostedEvent` ran only for
  * `feed post`, while every `publishBlock` call wrote to the ledger and stopped
  * there — so a "needs you" record was durable and invisible at the same time.
  */
-function broadcastBlock(block, extras) {
-    const config = readMeta().feed?.broadcast;
-    if (!config || Object.keys(config).length === 0)
+async function broadcastBlock(block, extras, meta) {
+    const config = effectiveBroadcastConfig(meta.feed?.broadcast, 'important', meta);
+    if (!config)
         return [];
     const ticket = getSessionById(block.sessionId)?.ticketId;
     const ctx = blockBroadcastContext({ ...block, ticket: block.ticket ?? ticket }, extras);
-    return runFeedBroadcast(planFeedBroadcast(config, ctx));
+    return runFeedBroadcast(planFeedBroadcast(config, ctx), meta);
 }
 /** One line per sink that ran. Silent when nothing is configured. */
 function reportBroadcast(outcomes) {

package/dist/commands/hooks.js

@@ -617,61 +617,25 @@ Examples:
 A hook whose p99 exceeds --warn-ms gets flagged in the cache column. Add
 'cache: 5m' or 'cache: 5m-bg' to its hooks.yaml entry to fix it.
 `)
+        .option('--project <key>', 'Scope to one project (see agents perf --help)')
         .action(async (options) => {
-        const { aggregateHookProfile, loadHookFireEvents, formatMs, formatCacheColumn, DEFAULT_SLOW_HOOK_WARN_MS } = await import('../lib/hooks/profile.js');
-        const { aggregateSamples } = await import('../lib/perf/db.js');
+        const { DEFAULT_SLOW_HOOK_WARN_MS } = await import('../lib/hooks/profile.js');
+        // Same rollup as `agents perf hooks` — this command predates the `perf`
+        // surface and is kept as a documented alias; delegate instead of
+        // duplicating the SQLite-vs-legacy-JSONL fallback and table rendering.
+        const { loadHookProfile, renderHookTable } = await import('./perf.js');
         const days = Math.max(1, parseInt(options.days, 10) || 7);
         const warnMs = Math.max(0, parseInt(options.warnMs, 10) || DEFAULT_SLOW_HOOK_WARN_MS);
-        // Prefer the indexed warehouse; fall back to legacy JSONL for pre-warehouse shims.
-        const fromDb = aggregateSamples({ days, kinds: ['hook.fire'] }).map((r) => ({
-            hook: r.label,
-            n: r.n,
-            p50Ms: r.p50Ms,
-            p99Ms: r.p99Ms,
-            meanMs: r.meanMs,
-            maxMs: r.maxMs,
-            cacheHitPct: r.cacheHitPct ?? 0,
-            cacheStalePct: r.cacheStalePct ?? 0,
-            cacheMissPct: r.cacheMissPct ?? 0,
-            errorCount: r.errorCount ?? 0,
-        }));
-        const rows = fromDb.length > 0 ? fromDb : aggregateHookProfile(loadHookFireEvents(days));
+        const rows = loadHookProfile(days, options.project);
         if (options.json) {
             console.log(JSON.stringify(rows, null, 2));
             return;
         }
         if (rows.length === 0) {
             console.log(chalk.gray(`No hook.fire samples in the last ${days} day${days === 1 ? '' : 's'}.`));
-            console.log(chalk.gray('Add \'cache: 5m\' to a hook (or matches:) so a shim instruments it, then resync.'));
+            console.log(chalk.gray('Every hook now instruments via a generated shim (cache:, matches:, or a bare matcher:) — resync hooks if this is unexpectedly empty.'));
             return;
         }
-        const widths = { hook: 36, n: 5, p50: 7, p99: 7, mean: 7, max: 7, cache: 30 };
-        const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
-        const header = [
-            pad('HOOK', widths.hook),
-            pad('N', widths.n),
-            pad('P50', widths.p50),
-            pad('P99', widths.p99),
-            pad('MEAN', widths.mean),
-            pad('MAX', widths.max),
-            pad('CACHE', widths.cache),
-        ].join(' ');
-        console.log(chalk.bold(header));
-        console.log(chalk.gray('─'.repeat(header.length)));
-        for (const r of rows) {
-            const slow = r.p99Ms > warnMs;
-            const cacheCol = formatCacheColumn(r);
-            const warning = slow && r.cacheHitPct + r.cacheStalePct === 0 ? '  ← add cache: 5m' : '';
-            const line = [
-                pad(r.hook, widths.hook),
-                pad(String(r.n), widths.n),
-                pad(formatMs(r.p50Ms), widths.p50),
-                pad(formatMs(r.p99Ms), widths.p99),
-                pad(formatMs(r.meanMs), widths.mean),
-                pad(formatMs(r.maxMs), widths.max),
-                pad(cacheCol, widths.cache),
-            ].join(' ') + warning;
-            console.log(slow ? chalk.yellow(line) : line);
-        }
+        renderHookTable(rows, warnMs);
     });
 }

package/dist/commands/menubar.js

@@ -11,7 +11,7 @@ import { setHelpSections } from '../lib/help.js';
 import { enableMenubarService, disableMenubarService, getMenubarStatus, runMenubarSetup, } from '../lib/menubar/install-menubar.js';
 function notMac() {
     if (process.platform !== 'darwin') {
-        console.log(chalk.yellow('The menu bar helper is macOS only.'));
+        console.log(chalk.yellow('AGI Menu is macOS only.'));
         return true;
     }
     return false;
@@ -19,7 +19,7 @@ function notMac() {
 /** Shared status readout — `status`, bare `menubar`, and `setup --check` all end here. */
 function printStatus(s, opts = {}) {
     const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
-    console.log(chalk.bold('Menu bar helper\n'));
+    console.log(chalk.bold('AGI Menu\n'));
     console.log(`  running            ${yn(s.running)}`);
     console.log(`  service installed  ${yn(s.serviceInstalled)}`);
     if (opts.brief) {
@@ -34,7 +34,7 @@ function printStatus(s, opts = {}) {
     // Two copies of the INSTALLED bundle is the duplicate the user sees as two
     // agents marks in the menu bar. It used to read as a healthy `running: yes`.
     if (s.instances.length > 1) {
-        console.log(chalk.yellow(`\n  ${s.instances.length} copies of the installed helper are running — that is the duplicate menu-bar icon:`));
+        console.log(chalk.yellow(`\n  ${s.instances.length} copies of AGI Menu are running — that is the duplicate menu-bar icon:`));
         for (const p of s.instances)
             console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
         console.log(chalk.gray('  Fix it with `agents menubar setup`.'));
@@ -45,20 +45,20 @@ function printStatus(s, opts = {}) {
         // was — only that a rival exists — so report the conflict, not a winner.
         // The loser has no other symptom: its chords simply never fire.
         const n = s.foreignInstances.length;
-        console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
+        console.log(chalk.yellow(`\n  ${n} other AGI Menu process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
         for (const p of s.foreignInstances)
             console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
         console.log(chalk.gray('  End them with `agents menubar setup`.'));
     }
     if (s.stale) {
-        console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar setup` now.'));
+        console.log(chalk.yellow('\n  Installed AGI Menu is stale — runs on next `agents` startup, or `agents menubar setup` now.'));
     }
     else if (!s.serviceInstalled && !s.disabledByUser) {
         console.log(chalk.gray('\n  Set it up with `agents menubar setup`.'));
     }
 }
 function printSetupResult(r) {
-    console.log(chalk.bold('Menu bar setup\n'));
+    console.log(chalk.bold('AGI Menu setup\n'));
     for (const step of r.steps) {
         const mark = step.outcome === 'failed' ? chalk.red('✗')
             : step.outcome === 'changed' ? chalk.green('+') : chalk.green('✓');
@@ -66,22 +66,22 @@ function printSetupResult(r) {
     }
     console.log();
     if (r.configured) {
-        console.log(chalk.green('Menu bar configured.') + chalk.gray('  One agents mark, started at login.'));
+        console.log(chalk.green('AGI Menu configured.') + chalk.gray('  One agents mark, started at login.'));
     }
     else {
-        console.log(chalk.red('Menu bar not fully configured.') + chalk.gray('  See the failed step above.'));
+        console.log(chalk.red('AGI Menu not fully configured.') + chalk.gray('  See the failed step above.'));
     }
 }
 export function registerMenubarCommands(program) {
     const menubar = program
         .command('menubar')
-        .description('Manage the macOS menu-bar helper (running sessions, agents awaiting input, routines)');
+        .description('Manage AGI Menu (running sessions, agents awaiting input, routines)');
     // `setup` is the one command that gets a machine to the intended state:
     // exactly one status item, started at login. `enable` stays the narrow
     // install+start; setup adds duplicate cleanup and verifies the end state.
     const setup = menubar
         .command('setup')
-        .description('Configure the menu bar end-to-end: one instance, started at login')
+        .description('Configure AGI Menu end-to-end: one instance, started at login')
         .option('--check', 'Report the current state, change nothing')
         .option('--json', 'Emit machine-readable JSON')
         .action((options) => {
@@ -110,7 +110,7 @@ export function registerMenubarCommands(program) {
     });
     setHelpSections(setup, {
         examples: `
-      # Configure the menu bar end-to-end (idempotent — safe to re-run)
+      # Configure AGI Menu end-to-end (idempotent — safe to re-run)
       agents menubar setup
 
       # Two agents marks in the menu bar? This ends the duplicate.
@@ -120,44 +120,44 @@ export function registerMenubarCommands(program) {
       agents menubar setup --check
     `,
         notes: `
-      Configures, in order: every running helper ended, the helper bundle at
-      ~/Library/Application Support/agents-cli, its code signature, the launchd
-      login item (com.phnx-labs.agents-menubar — RunAtLoad + KeepAlive), then
-      verifies exactly one helper came back up.
+      Configures, in order: every running helper ended, AGI Menu at
+      ~/Library/Application Support/agents-cli/MenubarHelper.app, its code
+      signature, the launchd login item (com.phnx-labs.agents-menubar —
+      RunAtLoad + KeepAlive), then verifies exactly one helper came back up.
 
       Every running helper is ended and launchd restarts one, so the survivor is
       always the login-managed copy. Exits nonzero if it cannot reach that state.
 
-      Setup clears a previous \`agents menubar disable\`. To turn the menu bar off
+      Setup clears a previous \`agents menubar disable\`. To turn AGI Menu off
       again, run \`agents menubar disable\`.
     `,
     });
     menubar
         .command('enable')
-        .description('Install and start the menu-bar helper (launches at login)')
+        .description('Install and start AGI Menu (launches at login)')
         .action(() => {
         if (notMac())
             return;
         const ok = enableMenubarService({ clearOptOut: true });
         if (!ok) {
-            console.log(chalk.red('Could not enable: no menu-bar helper bundle ships with this install.'));
+            console.log(chalk.red('Could not enable: no AGI Menu bundle ships with this install.'));
             console.log(chalk.gray('  This build may predate the helper, or be a non-macOS package.'));
             return;
         }
-        console.log(chalk.green('Menu bar helper enabled.') + chalk.gray('  Look for the agents mark in your menu bar.'));
+        console.log(chalk.green('AGI Menu enabled.') + chalk.gray('  Look for the agents mark in your menu bar.'));
     });
     menubar
         .command('disable')
-        .description('Stop and remove the menu-bar helper (stays off across upgrades)')
+        .description('Stop and remove AGI Menu (stays off across upgrades)')
         .action(() => {
         if (notMac())
             return;
         disableMenubarService();
-        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar setup`.'));
+        console.log(chalk.green('AGI Menu disabled.') + chalk.gray('  Re-enable any time with `agents menubar setup`.'));
     });
     menubar
         .command('status')
-        .description('Show whether the menu-bar helper is installed and running')
+        .description('Show whether AGI Menu is installed and running')
         .option('--json', 'Emit machine-readable JSON')
         .action((options) => {
         const s = getMenubarStatus();
@@ -166,7 +166,7 @@ export function registerMenubarCommands(program) {
             return;
         }
         if (s.platform !== 'darwin') {
-            console.log(chalk.yellow('The menu bar helper is macOS only.'));
+            console.log(chalk.yellow('AGI Menu is macOS only.'));
             return;
         }
         printStatus(s);
@@ -175,7 +175,7 @@ export function registerMenubarCommands(program) {
     menubar.action(() => {
         const s = getMenubarStatus();
         if (s.platform !== 'darwin') {
-            console.log(chalk.yellow('The menu bar helper is macOS only.'));
+            console.log(chalk.yellow('AGI Menu is macOS only.'));
             return;
         }
         printStatus(s, { brief: true });

package/dist/commands/message.js

@@ -12,6 +12,7 @@ import { blockIdForSession, listBlocks, readBlock, recordAnswer, recordMessageRe
 import { verifyOperatorIdentity } from '../lib/operator.js';
 import { resolveAnswerRoute, resumeArgv, } from '../lib/answer-router.js';
 import { injectIntoTerminal } from '../lib/terminal/inject.js';
+import { setHelpSections } from '../lib/help.js';
 /** Find the still-open block addressed to `mailboxId`, if any. */
 function findOpenBlockForMailbox(mailboxId) {
     // Fast path: the mailbox id is usually the session id, so the block id is
@@ -111,15 +112,34 @@ async function deliverViaResume(route, mailboxId) {
     console.log(chalk.green(`Resumed ${mailboxId} with answer. `) +
         chalk.dim(route.reason));
 }
+/**
+ * `message` is the agent-control plane (RUSH-2123): the answer/keystroke/
+ * injected input a running agent consumes, never a notification a human reads.
+ * Mirrors SHARED_NOTES in commands/send.ts so an agent reading either --help
+ * sees the same three-plane map and doesn't reach for `message` when it means
+ * `send`/`notify`.
+ */
+const CONTROL_PLANE_NOTES = `
+  Planes (do not mix them up):
+    message / sessions inject  - CONTROL a running agent (mailbox answer, PTY keystroke, or resume by runtime)
+    send / notify              - DELIVER a message to a human recipient over a channel provider
+    feed post                  - RECORD progress / milestones (optional broadcast may call send/notify)
+
+  <text> here is consumed BY THE TARGET AGENT (an answer, a keystroke, or the
+  argument to a resume) -- it is not a notification a person reads on their
+  phone. To reach the operator instead, use \`agents send\` / \`agents notify\`
+  (or a feed.broadcast \`channel:\` sink).
+`;
 export function registerMessageCommand(program) {
-    program
+    const messageCmd = program
         .command('message <target> <text>')
         .description('Send a message to a running or parked agent (mailbox / PTY-select / resume by runtime).')
         .option('--from <who>', 'Label recorded as the sender of this message')
         .option('--as <operator>', 'Verified operator id answering a high-consequence block')
         .option('--surface <surface>', 'Surface that is sending this answer (feed, terminal, etc.)', 'cli')
-        .option('--ttl <dur>', 'Delivery TTL if the message is not consumed (e.g. 30m, 1h, 24h); 0 disables expiry')
-        .action(async (target, text, opts) => {
+        .option('--ttl <dur>', 'Delivery TTL if the message is not consumed (e.g. 30m, 1h, 24h); 0 disables expiry');
+    setHelpSections(messageCmd, { notes: CONTROL_PLANE_NOTES });
+    messageCmd.action(async (target, text, opts) => {
         if (!target.trim()) {
             die('Target must be a session/agent id or cloud task id. Run `agents sessions --active` to list running agents.');
         }

package/dist/commands/perf.d.ts

@@ -6,9 +6,22 @@
  *   agents perf hooks        per-hook p50/p99 + cache hit rates
  *   agents perf commands     slowest CLI command paths (from command.end)
  *   agents perf run          agent.run / perf.timing labels
+ *   agents perf friction     sessions stuck repeatedly hitting the same guard
  *
  * Soft-joins sessions.db via shared string keys (session_id, agent, machine) —
  * no foreign keys. Warehouse lives at ~/.agents/.cache/perf/perf.db (safe to wipe).
  */
 import type { Command } from 'commander';
+import { type PerfAggregateRow } from '../lib/perf/db.js';
+import { type HookProfileRow } from '../lib/hooks/profile.js';
+/** Map warehouse rows shaped like hook.fire into the existing HookProfileRow UI. */
+export declare function asHookRows(rows: PerfAggregateRow[]): HookProfileRow[];
+export declare function renderHookTable(rows: HookProfileRow[], warnMs: number): void;
+/**
+ * Prefer SQLite samples; fall back to the legacy daily JSONL so existing
+ * instrumentation still surfaces until shims are resynced. `project` only
+ * narrows the SQLite path — the legacy JSONL log has no cwd, so a fallback
+ * hit ignores it (a caller filtering by project has no legacy rows to miss).
+ */
+export declare function loadHookProfile(days: number, project?: string): HookProfileRow[];
 export declare function registerPerfCommand(program: Command): void;