@phnx-labs/agents-cli 1.20.90 → 1.20.91

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 1.20.91
+
+- **An agent can now say it is stuck: `agents feed post --blocked` (RUSH-2110).** The
+  feed carried benign progress but had no way to signal "I cannot proceed", so agents
+  hand-rolled it into the status text (`NEEDS MUQSIT: …`) and it reached nobody. A
+  blocked post writes `status.blocked` to the shared activity stream *and* opens an
+  answerable block in the ledger, so the ask stays open until someone resolves it
+  instead of scrolling away. It is a flag on the existing verb, not a new command —
+  one thing for an agent to learn, and one stream where most posts are benign and
+  some need a human. Blocked is a state, not a volume: it always broadcasts at
+  `important`, so passing `--level` too is a usage error rather than a silent
+  override. Pair it with `--option` for an answerable choice or `--default` for a
+  safe fallback policy may apply. Source: `apps/cli/src/commands/feed.ts`,
+  `apps/cli/src/lib/feed.ts`.
+- **Feed blocks are actually delivered.** `publishBlock` wrote every "needs you"
+  record to the ledger and stopped there — `broadcastPostedEvent` ran only for
+  `feed post`, so a block was durable and invisible at the same time. Blocks now
+  reach the configured `feed.broadcast` sinks, carrying the ask and the literal
+  `agents focus <id>` command that unblocks it, and a block that reaches nobody
+  exits non-zero instead of looking like a success. Source:
+  `apps/cli/src/lib/feed-broadcast.ts`.
+- **New `desktop` channel provider.** `agents send --channel desktop` (and
+  `notify.owner.channel: desktop`) posts a native notification through the branded
+  menu-bar helper. It is the only channel with no external dependency — no network,
+  no login, no vendor CLI — so it still reaches you at your Mac when a messaging
+  gateway is down. It reports real deliverability rather than always succeeding:
+  on Linux it probes for `notify-send` instead of trusting the platform name.
+  Source: `apps/cli/src/lib/channels/providers/desktop.ts`.
+
+- **`agents perf` — disposable SQLite latency warehouse.** Indexed p50/p99
+  rollups for hooks, CLI commands, and `agent.run` timings without scanning the
+  audit JSONL. Warehouse lives at `~/.agents/.cache/perf/perf.db` (safe to wipe);
+  identity columns reuse sessions/events string shapes (`session_id`, `agent`,
+  `machine`, …) for soft cross-reference — no foreign keys. Hook shims spool
+  into the same DB; `agents hooks profile` reads it first. Source:
+  `apps/cli/src/lib/perf/db.ts`, `apps/cli/src/commands/perf.ts`.
+
+- **A routine that misses its fire now runs late instead of being silently lost.** Fires
+  are in-process croner timers, and croner only ever schedules forward from "now" — so a
+  daemon that was down, asleep, or wedged when a routine came due dropped that fire
+  outright, and `loadAll()` rebuilt every timer looking only at the future. Detection
+  existed but ran **once, at daemon startup**, and only logged a warning plus a
+  notification; catching up was a manual `agents routines catchup`. Observed cost: zion's
+  daemon was down from 02:03Z to 08:23Z while the laptop slept, `weekly-fleet-retro` was
+  armed for exactly 04:00Z, never ran, and the restart logged `2 routine(s) overdue` and
+  did nothing. The daemon now re-scans every 5 minutes as well as at startup and runs each
+  missed routine via the same detached path `catchup` already used. Source:
+  `apps/cli/src/lib/catchup.ts`, `apps/cli/src/lib/daemon.ts`.
+- **New `catchup:` routine field, and `agents routines add --no-catchup`.** Defaults to
+  true — a routine you scheduled is one you expect to have run. Set `catchup: false` for a
+  routine whose worth expires with its slot (a 9am brief is useless at 3pm); the miss is
+  still recorded, it just is not re-run. `agents routines list --json` reports the
+  effective value as `catchup`.
+- **New `missed` run status.** A missed fire previously left no trace anywhere — no run
+  record, no log line in the routine's history — so `agents routines list` kept showing the
+  previous run's `completed` as though it were current, sometimes for weeks. A miss is now
+  written as a real run stamped at the moment the fire was due, so `agents routines runs
+  <name>` shows the gap, and the listing renders it distinctly from `failed` (a miss is an
+  infrastructure problem, not a task failure). That record is also what makes catch-up
+  idempotent: it advances the overdue comparison, so the same missed fire is never
+  reconsidered across ticks or a daemon restart storm, and its directory is created with a
+  non-recursive `mkdir` — an atomic claim, so if the daemon's timer and a manual
+  `agents routines catchup` overlap, only one of them runs the routine. Source: `apps/cli/src/lib/routines.ts` (`RunMeta`),
+  `apps/cli/src/commands/routines.ts`.
+- **A routine is never caught up for a fire that predates it.** `detectOverdueJobs` walks back
+  a week for the most recent expected occurrence, and a routine with no runs is overdue by
+  definition — so before this, `agents routines add` on any daily or weekly schedule whose slot
+  had already passed made the routine instantly "overdue". That was cosmetic while catch-up was
+  a manual command; with the daemon now catching up automatically it would have run every newly
+  created routine once, within five minutes of creating it. Routines gain a `createdAt` stamp
+  (written once, like `actor`), and overdue detection floors the expected fire at it — falling
+  back to the routine file's mtime for routines written before the field existed. Observed on
+  the live fleet: `agents-cli-updates`, created Aug 1 and never run, was flagged overdue for a
+  Jul 27 fire. Source: `apps/cli/src/lib/overdue.ts` (`routineEffectiveStart`),
+  `apps/cli/src/lib/routines.ts` (`writeJob`).
+
+- **`agents secrets list` can be filtered.** It had no filtering at all —
+  `--host` picks a machine and `--json` picks a format, but nothing selected over
+  the bundles themselves, so "which of these read with no Touch ID?", "which
+  still store a raw value inline?", "what have I not touched in three months?"
+  meant piping the table through `grep` or went unanswered. There is now an axis
+  per question: a `[query]` positional over name and description, `--policy`,
+  `--backend`, `--type`, `--kind`, `--held`/`--not-held`, `--expired`,
+  `--expiring [days]`, `--unused <duration>`, plus `--sort` and `-n/--limit`.
+  Every axis narrows independently, so they compose. Following the `agents
+  sessions` house style, an unknown value is a loud error naming the valid set
+  rather than an empty list, filters apply before `--json` so the payload is the
+  exact twin of the table, and they are forwarded over `--host` so a remote list
+  narrows the same way. `--held`/`--not-held` read live broker state and so
+  refuse to run off macOS instead of reporting every bundle as unheld. An empty
+  result names the filters that emptied it and the total it started from. Source:
+  `apps/cli/src/lib/secrets/list-filter.ts`, `apps/cli/src/commands/secrets.ts`.
+
+- **The EXPIRING column no longer hides keys that have already expired.**
+  `countExpiringSoon` counted only keys due in the next 30 days — the guard is
+  `d >= 0` — so a bundle whose token died last month rendered `-`, identical to
+  one with no expiry at all. The only places a lapsed key surfaced were
+  `agents secrets view` and a hard abort at inject time, i.e. after it had already
+  broken a run. The column now counts lapsed and upcoming together and turns red
+  once anything has lapsed, and `secrets list --json` gains an `expired` count
+  alongside the existing `expiringSoon`. Source: `apps/cli/src/commands/secrets.ts`.
+
+- **`agents secrets list` now states the hold window instead of the bare word
+  `hold`.** The `hold` tier is a duration — prompt once, then stay silent for
+  `secrets.agent.holdMs` (7 days by default) — but the POLICY column printed only
+  the tier name, so a reader could not tell it meant a window, let alone which
+  one; finding out meant running `agents secrets status`. The column now reads
+  `hold 7d`, and `hold 7d · held 6d` while the broker is actually caching the
+  bundle. It follows the configured window, so a 24-hour hold reads `hold 1d`.
+  `always` and `never` are unchanged — neither has a window, and annotating one
+  would repeat the mistake the `daily` rename fixed. Two adjacent bugs go with
+  it: `agents secrets view` printed "7d by default" as a string literal and so
+  misstated the window for anyone who had configured `holdMs`, and a stale broker
+  entry past its expiry rendered as `hold · held expired` because the column
+  tested the entry for presence rather than liveness. `secrets list --json` and
+  `secrets view --json` gain an additive `holdMs` field (null on `always`/`never`)
+  so a machine caller gets the window too. Source:
+  `apps/cli/src/commands/secrets.ts`.
+
+- **Richer session previews: skills, hooks, links, artifacts, repos, todo status.** The `agents sessions` quick preview and full summary now show the skills a session invoked (with counts), the hooks that fired (Claude transcripts, with repeat counts and failures), a clickable Links section (Linear/Jira/GitHub/GitLab URLs harvested from the conversation), the documents the session produced (`.agents/artifacts|plans|reports` and other `*.md`/`*.html` creations), the repos it worked in (via `.git` walk-up), and an error tally in the picker. The full summary's Plan section now marks checklist items `[x]`/`[>]`/`[ ]` and renders the checklist alongside the ExitPlanMode text instead of hiding it. Changes/Dirs lines collapse `.agents/worktrees/<slug>` prefixes to `⧉ <slug>/…`, are width-capped, and no longer list shell junk (`2>&1`, `$VAR` paths), `node_modules`, or agents-cli internal archives. Source: `apps/cli/src/lib/session/highlights.ts`, `apps/cli/src/lib/session/parse.ts`, `apps/cli/src/lib/session/render.ts`, `apps/cli/src/commands/sessions-picker.ts`.
+
 ## 1.20.90
 
 - **`agents sessions --active` now shows one row per agent, not one per directory.**

package/dist/commands/feed.js

@@ -1,8 +1,8 @@
 import chalk from 'chalk';
-import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified } from '../lib/feed.js';
+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, } from '../lib/feed-broadcast.js';
+import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, 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';
@@ -238,6 +238,9 @@ export function registerFeedCommand(program) {
         .option('--session <id>', 'Session id escape hatch (default: auto from env / pid registry)')
         .option('--attach <path-or-url...>', 'Attach an artifact (local file or URL); repeatable')
         .option('--level <level>', 'How loudly to broadcast: milestone (default) or important. Configured sinks with minLevel: important only fire on the latter.', 'milestone')
+        .option('--blocked', 'You are STUCK and need the user. Opens an answerable block and always broadcasts at important — do not also pass --level.')
+        .option('--option <label...>', 'With --blocked: an answer the user can pick; repeatable')
+        .option('--default <answer>', 'With --blocked: a safe default policy may apply if nobody answers in time')
         .option('--json', 'Emit the written event as JSON')
         .addHelpText('after', `
 Examples:
@@ -249,6 +252,17 @@ Examples:
   # Worth interrupting someone over — reaches sinks gated on minLevel: important:
   agents feed post "release blocked: npm token expired" --level important
 
+  # You are STUCK and cannot proceed. Opens an answerable block that stays in
+  # 'agents feed' until someone resolves it, and always reaches the owner —
+  # do NOT also pass --level:
+  agents feed post "force-push denied by git-guard on PR #1749" --blocked
+  agents feed post "publish to npm or wait for review?" --blocked --option publish --option wait
+  agents feed post "delete the stale preview env?" --blocked --default "leave it"
+
+  # Exhaust self-serve FIRST. A block is for what you genuinely cannot do:
+  # a credential only the user holds, a decision only they can make, an
+  # approval only they can give. Not "should I do the obvious next step?".
+
   # Outside a run, pass the session explicitly:
   agents feed post "manual note" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47
 
@@ -268,22 +282,66 @@ docs/06-observability.md.
             session: opts?.session ?? cmd?.opts?.()?.session,
             attach: opts?.attach ?? cmd?.opts?.()?.attach,
             level: opts?.level ?? cmd?.opts?.()?.level,
+            blocked: Boolean(opts?.blocked ?? cmd?.opts?.()?.blocked),
+            option: opts?.option ?? cmd?.opts?.()?.option,
+            default: opts?.default ?? cmd?.opts?.()?.default,
             json: Boolean(opts?.json ?? cmd?.opts?.()?.json ?? cmd?.parent?.opts?.()?.json),
         };
         try {
-            const level = parseFeedPostLevel(flags.level);
+            // Blocked is a state, not a volume: it always broadcasts at `important`,
+            // so an agent has exactly one thing to say. Passing both is a usage
+            // error rather than a silent override -- an agent that thinks it chose
+            // the level should not be quietly ignored.
+            if (flags.blocked && flags.level && flags.level !== 'milestone') {
+                throw new Error('--blocked already broadcasts at important; drop --level.');
+            }
+            if (!flags.blocked && (flags.option?.length || flags.default)) {
+                throw new Error('--option/--default only apply with --blocked.');
+            }
+            const level = flags.blocked ? 'important' : parseFeedPostLevel(flags.level);
             const { event } = postFeedStatus({
                 text: Array.isArray(textParts) ? textParts.join(' ') : String(textParts ?? ''),
                 sessionId: flags.session,
                 attach: flags.attach,
+                blocked: flags.blocked,
             });
-            const outcomes = broadcastPostedEvent(event, level);
+            // A blocked post lands in BOTH stores: the event in the shared activity
+            // stream (what happened) and an OpenBlock in the ledger (what is still
+            // open). The ledger is what makes it answerable and clearable -- without
+            // it the ask would scroll away like any other update.
+            let outcomes;
+            if (flags.blocked) {
+                const block = buildDeclaredBlock(event, {
+                    text: event.detail ?? '',
+                    options: flags.option,
+                    safeDefault: flags.default,
+                });
+                publishBlock(block);
+                outcomes = broadcastBlock(block, { project: event.project, agent: event.agent });
+            }
+            else {
+                outcomes = broadcastPostedEvent(event, level);
+            }
+            // 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
+            // exit code, so returning 0 there while a human gets 1 would make the
+            // undelivered block invisible to the caller most likely to act on it —
+            // reintroducing, behind a flag, the silent failure this exists to remove.
+            // One sink failing among several stays a warning: the channels are
+            // redundant by design.
+            const undelivered = blockDeliveryFailure(flags.blocked, outcomes);
+            if (undelivered)
+                process.exitCode = 1;
             if (flags.json) {
                 console.log(JSON.stringify(outcomes.length ? { ...event, broadcast: outcomes } : event, null, 2));
+                if (undelivered)
+                    console.error(chalk.red(undelivered));
                 return;
             }
             console.log(formatProgressUpdate(event));
             reportBroadcast(outcomes);
+            if (undelivered)
+                console.error(chalk.red(undelivered));
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -516,6 +574,21 @@ function broadcastPostedEvent(event, level) {
     });
     return runFeedBroadcast(planned);
 }
+/**
+ * Mirror a declared block to the same sinks a post reaches.
+ *
+ * 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)
+        return [];
+    const ticket = getSessionById(block.sessionId)?.ticketId;
+    const ctx = blockBroadcastContext({ ...block, ticket: block.ticket ?? ticket }, extras);
+    return runFeedBroadcast(planFeedBroadcast(config, ctx));
+}
 /** One line per sink that ran. Silent when nothing is configured. */
 function reportBroadcast(outcomes) {
     for (const o of outcomes) {

package/dist/commands/hooks.js

@@ -603,30 +603,46 @@ Examples:
         .option('--warn-ms <n>', 'p99 threshold above which a hook is flagged as slow', '2000')
         .option('--json', 'Emit raw JSON rows instead of the table')
         .addHelpText('after', `
-Shows aggregated stats for every hook that emitted a hook.fire event into
-~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl. Only hooks with \`cache:\` in
-their manifest are instrumented today — the generated shim writes the events.
+Shows aggregated stats for every hook that fired through a generated shim.
+Primary source: disposable SQLite warehouse ~/.agents/.cache/perf/perf.db
+(same data as \`agents perf hooks\`). Falls back to the legacy daily JSONL under
+~/.agents/.cache/logs/ when the warehouse is empty.
 
 Examples:
   agents hooks profile                # last 7 days, table form
   agents hooks profile --days 30      # roll up the full month
   agents hooks profile --json | jq    # pipe somewhere
+  agents perf hooks                   # same rollup under the perf surface
 
 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.
 `)
         .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 days = Math.max(1, parseInt(options.days, 10) || 7);
         const warnMs = Math.max(0, parseInt(options.warnMs, 10) || DEFAULT_SLOW_HOOK_WARN_MS);
-        const rows = aggregateHookProfile(loadHookFireEvents(days));
+        // 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));
         if (options.json) {
             console.log(JSON.stringify(rows, null, 2));
             return;
         }
         if (rows.length === 0) {
-            console.log(chalk.gray(`No hook.fire events in the last ${days} day${days === 1 ? '' : 's'}.`));
-            console.log(chalk.gray('Add \'cache: 5m\' to a hook in hooks.yaml to start collecting stats.'));
+            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.'));
             return;
         }
         const widths = { hook: 36, n: 5, p50: 7, p99: 7, mean: 7, max: 7, cache: 30 };

package/dist/commands/perf.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents perf` — latency rollups over the disposable perf SQLite warehouse.
+ *
+ * Subcommands:
+ *   agents perf              multi-section summary (commands + hooks + runs)
+ *   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
+ *
+ * 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';
+export declare function registerPerfCommand(program: Command): void;

package/dist/commands/perf.js

@@ -0,0 +1,221 @@
+/**
+ * `agents perf` — latency rollups over the disposable perf SQLite warehouse.
+ *
+ * Subcommands:
+ *   agents perf              multi-section summary (commands + hooks + runs)
+ *   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
+ *
+ * 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 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';
+function parseDays(raw) {
+    const n = parseInt(raw ?? '7', 10);
+    return Number.isFinite(n) && n > 0 ? n : 7;
+}
+function parseWarnMs(raw, fallback) {
+    const n = parseInt(raw ?? String(fallback), 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+function parseLimit(raw, fallback) {
+    const n = parseInt(raw ?? String(fallback), 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Map warehouse rows shaped like hook.fire into the existing HookProfileRow UI. */
+function asHookRows(rows) {
+    return rows.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,
+    }));
+}
+function printTable(headers, widths, lines, slowFlags) {
+    const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
+    const header = headers.map((h, i) => pad(h, widths[i])).join(' ');
+    console.log(chalk.bold(header));
+    console.log(chalk.gray('─'.repeat(header.length)));
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].map((c, j) => pad(c, widths[j])).join(' ');
+        console.log(slowFlags[i] ? chalk.yellow(line) : line);
+    }
+}
+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 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);
+    }
+}
+function renderLabelTable(title, rows, warnMs, limit) {
+    const sliced = rows.slice(0, limit);
+    if (sliced.length === 0) {
+        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) => [
+        r.label,
+        String(r.n),
+        formatMs(r.p50Ms),
+        formatMs(r.p99Ms),
+        formatMs(r.meanMs),
+        formatMs(r.maxMs),
+    ]), 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.
+ */
+function loadHookProfile(days) {
+    const fromDb = asHookRows(aggregateSamples({ days, kinds: ['hook.fire'] }));
+    if (fromDb.length > 0)
+        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);
+    if (opts.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    renderHookTable(rows, warnMs);
+}
+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'] });
+    if (opts.json) {
+        console.log(JSON.stringify(rows.slice(0, limit), null, 2));
+        return;
+    }
+    renderLabelTable('command', rows, warnMs, limit);
+}
+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'] });
+    if (opts.json) {
+        console.log(JSON.stringify(rows.slice(0, limit), null, 2));
+        return;
+    }
+    renderLabelTable('run/timing', rows, warnMs, limit);
+}
+function summaryAction(opts) {
+    const days = parseDays(opts.days);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            days,
+            warehouse: perfDbPath(),
+            hooks: loadHookProfile(days),
+            commands: aggregateSamples({ days, kinds: ['command.end'] }).slice(0, 20),
+            run: aggregateSamples({ days, kinds: ['perf.timing'] }).slice(0, 20),
+        }, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`agents perf — last ${days} day${days === 1 ? '' : 's'}`));
+    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);
+    console.log('');
+    console.log(chalk.bold('Hooks'));
+    renderHookTable(loadHookProfile(days), 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);
+}
+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('--json', 'Emit JSON instead of a table');
+}
+/**
+ * Commander binds a flag declared on both parent and child to the *parent*.
+ * Merge so `agents perf commands --json` still sees json:true on the leaf.
+ */
+function leafOpts(cmd) {
+    const parent = cmd.parent && typeof cmd.parent.opts === 'function'
+        ? cmd.parent.opts()
+        : {};
+    return { ...parent, ...cmd.opts() };
+}
+export function registerPerfCommand(program) {
+    const perf = program
+        .command('perf')
+        .description('Latency rollups from the disposable perf warehouse (hooks, commands, runs)')
+        .addHelpText('after', `
+The warehouse is SQLite at ~/.agents/.cache/perf/perf.db — safe to delete.
+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 hooks --warn-ms 500
+`);
+    // Options live on the parent so `agents perf --json` and
+    // `agents perf commands --json` both work (see leafOpts).
+    attachSharedOptions(perf).action(function summary() {
+        summaryAction(this.opts());
+    });
+    perf.command('hooks').description('Per-hook timing + cache stats')
+        .action(function hooks() {
+        hooksAction(leafOpts(this));
+    });
+    perf.command('commands').description('Slowest CLI command paths (command.end samples)')
+        .action(function commands() {
+        commandsAction(leafOpts(this));
+    });
+    perf.command('run').description('agent.run / perf.timing label rollups')
+        .action(function run() {
+        runAction(leafOpts(this));
+    });
+}