@phnx-labs/agents-cli 1.21.0 → 1.21.2

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/monitors.js

@@ -57,7 +57,7 @@ function actionLabel(action) {
         case 'routine':
             return `routine ${action.routine ?? ''}`;
         case 'notify':
-            return `notify ${action.notifyChannel ?? 'telegram'}`;
+            return `notify ${action.notifyChannel ?? 'owner'}`;
         case 'webhook-out':
             return `webhook-out ${action.url ?? ''}`;
         default:
@@ -195,9 +195,11 @@ function buildAction(options) {
     if (options.routine)
         chosen.push({ type: 'routine', routine: options.routine });
     if (options.notify !== undefined) {
-        // --notify may be a bare flag (true) or carry a channel string.
-        const channel = typeof options.notify === 'string' ? options.notify : 'telegram';
-        chosen.push({ type: 'notify', notifyChannel: channel });
+        // --notify may be a bare flag (notify the owner) or carry a channel that
+        // overrides notify.owner.channel. Left unset, the send resolves the owner
+        // channel + target from notify.owner in agents.yaml (one source of truth).
+        const channel = typeof options.notify === 'string' ? options.notify : undefined;
+        chosen.push({ type: 'notify', ...(channel ? { notifyChannel: channel } : {}) });
     }
     if (options.webhookOut)
         chosen.push({ type: 'webhook-out', url: options.webhookOut });
@@ -310,7 +312,7 @@ export function registerMonitorsCommands(program) {
         .option('--effort <effort>', 'Reasoning effort for --run: low | medium | high | xhigh | max | auto')
         .option('--action-timeout <t>', 'Kill the --run action if it runs longer than this (e.g. 10m)')
         .option('--routine <name>', 'Fire an existing routine on change')
-        .option('--notify [channel]', 'Send a notification (default channel: telegram)')
+        .option('--notify [channel]', 'Notify the owner (notify.owner); [channel] overrides the owner channel')
         .option('--webhook-out <url>', 'POST the event to this URL')
         // PLACEMENT / hygiene
         .option('--device <name>', 'OWNER device — the single machine that evaluates + fires (exactly-once)')
@@ -573,7 +575,7 @@ export function registerMonitorsCommands(program) {
                 name,
                 source: { type: 'poll', command: 'echo hello', interval: '1m' },
                 condition: { mode: 'on-change' },
-                action: { type: 'notify', notifyChannel: 'telegram' },
+                action: { type: 'notify' },
             });
             fs.writeFileSync(monitorPath, template, 'utf-8');
             console.log(chalk.gray(`Created new monitor file: ${monitorPath}`));

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;

package/dist/commands/perf.js

@@ -6,6 +6,7 @@
  *   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).
@@ -13,6 +14,8 @@
 import chalk from 'chalk';
 import { aggregateSamples, perfDbPath, } from '../lib/perf/db.js';
 import { formatMs, formatCacheColumn, DEFAULT_SLOW_HOOK_WARN_MS, loadHookFireEvents, aggregateHookProfile, } from '../lib/hooks/profile.js';
+import { query } from '../lib/events.js';
+import { detectRepeatedGuardBlocks } from '../lib/friction-heuristics.js';
 function parseDays(raw) {
     const n = parseInt(raw ?? '7', 10);
     return Number.isFinite(n) && n > 0 ? n : 7;
@@ -26,11 +29,12 @@ function parseLimit(raw, fallback) {
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
 /** Map warehouse rows shaped like hook.fire into the existing HookProfileRow UI. */
-function asHookRows(rows) {
+export function asHookRows(rows) {
     return rows.map((r) => ({
         hook: r.label,
         n: r.n,
         p50Ms: r.p50Ms,
+        p95Ms: r.p95Ms,
         p99Ms: r.p99Ms,
         meanMs: r.meanMs,
         maxMs: r.maxMs,
@@ -38,6 +42,9 @@ function asHookRows(rows) {
         cacheStalePct: r.cacheStalePct ?? 0,
         cacheMissPct: r.cacheMissPct ?? 0,
         errorCount: r.errorCount ?? 0,
+        errorRate: r.errorRate,
+        timeoutRate: r.timeoutRate,
+        project: r.project,
     }));
 }
 function printTable(headers, widths, lines, slowFlags) {
@@ -50,23 +57,34 @@ function printTable(headers, widths, lines, slowFlags) {
         console.log(slowFlags[i] ? chalk.yellow(line) : line);
     }
 }
-function renderHookTable(rows, warnMs) {
+/** `err:12% to:4%` when either rate is present, else ''. */
+function formatRateColumn(r) {
+    const parts = [];
+    if (r.errorRate)
+        parts.push(`err:${Math.round(r.errorRate * 100)}%`);
+    if (r.timeoutRate)
+        parts.push(`to:${Math.round(r.timeoutRate * 100)}%`);
+    return parts.join(' ');
+}
+export function renderHookTable(rows, warnMs) {
     if (rows.length === 0) {
         console.log(chalk.gray('No hook timing samples yet.'));
         console.log(chalk.gray(`Warehouse: ${perfDbPath()}`));
         console.log(chalk.gray('Hooks write via cache/matches shims into the spool; run a session or resync hooks.'));
         return;
     }
-    const widths = { hook: 36, n: 5, p50: 7, p99: 7, mean: 7, max: 7, cache: 28 };
+    const widths = { hook: 36, n: 5, p50: 7, p95: 7, p99: 7, mean: 7, max: 7, cache: 22, rate: 14 };
     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('P95', widths.p95),
         pad('P99', widths.p99),
         pad('MEAN', widths.mean),
         pad('MAX', widths.max),
         pad('CACHE', widths.cache),
+        pad('ERR/TIMEOUT', widths.rate),
     ].join(' ');
     console.log(chalk.bold(header));
     console.log(chalk.gray('─'.repeat(header.length)));
@@ -78,10 +96,12 @@ function renderHookTable(rows, warnMs) {
             pad(r.hook, widths.hook),
             pad(String(r.n), widths.n),
             pad(formatMs(r.p50Ms), widths.p50),
+            pad(formatMs(r.p95Ms), widths.p95),
             pad(formatMs(r.p99Ms), widths.p99),
             pad(formatMs(r.meanMs), widths.mean),
             pad(formatMs(r.maxMs), widths.max),
             pad(cacheCol, widths.cache),
+            pad(formatRateColumn(r), widths.rate),
         ].join(' ') + warning;
         console.log(slow ? chalk.yellow(line) : line);
     }
@@ -92,30 +112,34 @@ function renderLabelTable(title, rows, warnMs, limit) {
         console.log(chalk.gray(`No ${title} samples yet.`));
         return;
     }
-    const widths = [40, 5, 7, 7, 7, 7];
-    printTable(['LABEL', 'N', 'P50', 'P99', 'MEAN', 'MAX'], widths, sliced.map((r) => [
+    const widths = [40, 5, 7, 7, 7, 7, 7, 14];
+    printTable(['LABEL', 'N', 'P50', 'P95', 'P99', 'MEAN', 'MAX', 'ERR/TIMEOUT'], widths, sliced.map((r) => [
         r.label,
         String(r.n),
         formatMs(r.p50Ms),
+        formatMs(r.p95Ms),
         formatMs(r.p99Ms),
         formatMs(r.meanMs),
         formatMs(r.maxMs),
+        formatRateColumn(r),
     ]), sliced.map((r) => r.p99Ms > warnMs));
 }
 /**
  * Prefer SQLite samples; fall back to the legacy daily JSONL so existing
- * instrumentation still surfaces until shims are resynced.
+ * 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).
  */
-function loadHookProfile(days) {
-    const fromDb = asHookRows(aggregateSamples({ days, kinds: ['hook.fire'] }));
-    if (fromDb.length > 0)
+export function loadHookProfile(days, project) {
+    const fromDb = asHookRows(aggregateSamples({ days, kinds: ['hook.fire'], project }));
+    if (fromDb.length > 0 || project)
         return fromDb;
     return aggregateHookProfile(loadHookFireEvents(days));
 }
 function hooksAction(opts) {
     const days = parseDays(opts.days);
     const warnMs = parseWarnMs(opts.warnMs, DEFAULT_SLOW_HOOK_WARN_MS);
-    const rows = loadHookProfile(days);
+    const rows = loadHookProfile(days, opts.project);
     if (opts.json) {
         console.log(JSON.stringify(rows, null, 2));
         return;
@@ -126,7 +150,7 @@ function commandsAction(opts) {
     const days = parseDays(opts.days);
     const warnMs = parseWarnMs(opts.warnMs, 500);
     const limit = parseLimit(opts.limit, 40);
-    const rows = aggregateSamples({ days, kinds: ['command.end'] });
+    const rows = aggregateSamples({ days, kinds: ['command.end'], project: opts.project });
     if (opts.json) {
         console.log(JSON.stringify(rows.slice(0, limit), null, 2));
         return;
@@ -137,42 +161,69 @@ function runAction(opts) {
     const days = parseDays(opts.days);
     const warnMs = parseWarnMs(opts.warnMs, 60_000);
     const limit = parseLimit(opts.limit, 40);
-    const rows = aggregateSamples({ days, kinds: ['perf.timing'] });
+    const rows = aggregateSamples({ days, kinds: ['perf.timing'], project: opts.project });
     if (opts.json) {
         console.log(JSON.stringify(rows.slice(0, limit), null, 2));
         return;
     }
     renderLabelTable('run/timing', rows, warnMs, limit);
 }
+/**
+ * Sessions stuck repeatedly hitting the SAME guard block (git-guard,
+ * rm-guard, git-require-clean-tree, …) instead of adapting after the first
+ * denial. Reads the `friction` event sink (emitFriction in events.ts) that
+ * guard hooks self-report into via `agents _internal friction` before they
+ * exit 2 — see lib/friction-heuristics.ts for the grouping.
+ */
+function frictionAction(opts) {
+    const days = parseDays(opts.days);
+    const startDate = new Date(Date.now() - days * 86_400_000);
+    const events = query({ eventTypes: ['friction'], startDate });
+    const findings = detectRepeatedGuardBlocks(events);
+    if (opts.json) {
+        console.log(JSON.stringify(findings, null, 2));
+        return;
+    }
+    if (findings.length === 0) {
+        console.log(chalk.gray(`No repeated guard blocks in the last ${days} day${days === 1 ? '' : 's'}.`));
+        return;
+    }
+    console.log(chalk.bold(`Repeated guard blocks — last ${days} day${days === 1 ? '' : 's'}\n`));
+    const widths = [14, 10, 24, 5, 22, 22];
+    printTable(['SESSION', 'SURFACE', 'FAILURE ID', 'N', 'FIRST', 'LAST'], widths, findings.map((f) => [f.session, f.surface, f.failureId, String(f.count), f.firstTs, f.lastTs]), findings.map(() => false));
+}
 function summaryAction(opts) {
     const days = parseDays(opts.days);
+    const project = opts.project;
     if (opts.json) {
         console.log(JSON.stringify({
             days,
+            project: project ?? null,
             warehouse: perfDbPath(),
-            hooks: loadHookProfile(days),
-            commands: aggregateSamples({ days, kinds: ['command.end'] }).slice(0, 20),
-            run: aggregateSamples({ days, kinds: ['perf.timing'] }).slice(0, 20),
+            hooks: loadHookProfile(days, project),
+            commands: aggregateSamples({ days, kinds: ['command.end'], project }).slice(0, 20),
+            run: aggregateSamples({ days, kinds: ['perf.timing'], project }).slice(0, 20),
         }, null, 2));
         return;
     }
-    console.log(chalk.bold(`agents perf — last ${days} day${days === 1 ? '' : 's'}`));
+    console.log(chalk.bold(`agents perf — last ${days} day${days === 1 ? '' : 's'}${project ? ` — project ${project}` : ''}`));
     console.log(chalk.gray(`warehouse: ${perfDbPath()}  (disposable; soft-join sessions via session_id/agent/machine)`));
     console.log('');
     console.log(chalk.bold('Commands (slowest by p99)'));
-    renderLabelTable('command', aggregateSamples({ days, kinds: ['command.end'] }), parseWarnMs(opts.warnMs, 500), 12);
+    renderLabelTable('command', aggregateSamples({ days, kinds: ['command.end'], project }), parseWarnMs(opts.warnMs, 500), 12);
     console.log('');
     console.log(chalk.bold('Hooks'));
-    renderHookTable(loadHookProfile(days), parseWarnMs(opts.warnMs, DEFAULT_SLOW_HOOK_WARN_MS));
+    renderHookTable(loadHookProfile(days, project), parseWarnMs(opts.warnMs, DEFAULT_SLOW_HOOK_WARN_MS));
     console.log('');
     console.log(chalk.bold('Runs (perf.timing)'));
-    renderLabelTable('run/timing', aggregateSamples({ days, kinds: ['perf.timing'] }), parseWarnMs(opts.warnMs, 60_000), 12);
+    renderLabelTable('run/timing', aggregateSamples({ days, kinds: ['perf.timing'], project }), parseWarnMs(opts.warnMs, 60_000), 12);
 }
 function attachSharedOptions(cmd) {
     return cmd
         .option('--days <n>', 'Days of samples to include', '7')
         .option('--warn-ms <n>', 'p99 above this is highlighted')
         .option('--limit <n>', 'Max rows in the table', '40')
+        .option('--project <key>', 'Scope to one project (the repo directory name a sample\'s cwd resolves to — see project-key.ts)')
         .option('--json', 'Emit JSON instead of a table');
 }
 /**
@@ -195,11 +246,13 @@ Identity columns reuse sessions/events string shapes (session_id, agent, machine
 for soft cross-reference; there are no foreign keys.
 
 Examples:
-  agents perf                     # summary: commands + hooks + runs
-  agents perf hooks               # per-hook p50/p99 + cache hit rate
-  agents perf commands --days 30  # slowest CLI entrypoints
-  agents perf run --json          # agent.run timings as JSON
+  agents perf                        # summary: commands + hooks + runs
+  agents perf hooks                  # per-hook p50/p95/p99 + cache hit rate
+  agents perf commands --days 30     # slowest CLI entrypoints
+  agents perf run --json             # agent.run timings as JSON
   agents perf hooks --warn-ms 500
+  agents perf hooks --project agents-cli  # scope to one repo's samples
+  agents perf friction               # sessions stuck retrying the same guard block
 `);
     // Options live on the parent so `agents perf --json` and
     // `agents perf commands --json` both work (see leafOpts).
@@ -218,4 +271,8 @@ Examples:
         .action(function run() {
         runAction(leafOpts(this));
     });
+    perf.command('friction').description('Sessions stuck repeatedly hitting the same guard block')
+        .action(function friction() {
+        frictionAction(leafOpts(this));
+    });
 }

package/dist/commands/projects.d.ts

@@ -20,6 +20,8 @@ export declare const PROJECTS_NO_FANOUT_ENV = "AGENTS_PROJECTS_LOCAL";
  * string when everything answered.
  */
 export declare function formatFleetSkippedNote(skipped: string[]): string;
+/** Best-effort `owner/repo` from a repo's origin remote. */
+export declare function originSlug(cwd: string): string | undefined;
 /** One `projects list` row, pre-render. */
 export interface ProjectListRow {
     name: string;
@@ -45,6 +47,15 @@ export declare function computeProjectListWidths(rows: ProjectListRow[]): {
  * read it as UTC and shift the answer by a day for anyone west of Greenwich.
  */
 export declare function formatMilestoneDue(targetDate: string, nowMs: number): string | undefined;
+/**
+ * The milestone block. `status` prints one line — the next checkpoint — because
+ * a roll-up across projects has to stay scannable. `view` prints every declared
+ * milestone, because "how many are there and when are they due" is the shape of
+ * the plan and the reason to open one project.
+ *
+ * Pure (chalk only) so the layout is testable without a Linear account.
+ */
+export declare function formatMilestoneLines(milestones: LinearMilestone[], next: LinearMilestone | undefined, nowMs: number, limit: number): string[];
 /** The `next` card line: what this project is due to hit, and how far along it is. */
 export declare function formatNextMilestone(ms: LinearMilestone, nowMs: number): string;
 export declare function registerProjectsCommands(program: Command): void;