@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/lib/hooks/cache.js

@@ -18,7 +18,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { getHookCacheDir, getHookShimsDir, getLogsDir } from '../state.js';
+import { getHookCacheDir, getHookShimsDir, getLogsDir, getPerfDir } from '../state.js';
 /**
  * Parse a `cache:` value from hooks.yaml into the canonical config form.
  * Accepts the shorthand string ("5m", "30s-bg") or the full object form.
@@ -116,8 +116,9 @@ export function generateHookShim(args) {
     const shimsDir = args.paths?.shimsDir ?? getHookShimsDir();
     const cacheDir = args.paths?.cacheDir ?? getHookCacheDir();
     const logsDir = args.paths?.logsDir ?? getLogsDir();
+    const perfDir = args.paths?.perfDir ?? getPerfDir();
     const shimPath = resolveContainedHookShimPath(shimsDir, args.name);
-    const content = renderShim(args.name, args.scriptPath, args.cache ?? null, args.matches, { cacheDir, logsDir });
+    const content = renderShim(args.name, args.scriptPath, args.cache ?? null, args.matches, { cacheDir, logsDir, perfDir });
     fs.mkdirSync(shimsDir, { recursive: true });
     let existing = null;
     if (fs.existsSync(shimPath)) {
@@ -303,6 +304,12 @@ TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
 printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%d}\\n' \\
   "$TS" "$HOOK_NAME" "$MS" "none" "$EXIT" >>"$LOG_FILE" 2>/dev/null || true
+# Disposable perf spool → drained into ~/.agents/.cache/perf/perf.db on next agents perf/open.
+mkdir -p "$PERF_DIR" 2>/dev/null || true
+TS_MS=$("$PY" -c 'import time; print(int(time.time()*1000))' 2>/dev/null || echo 0)
+HOST=$(hostname 2>/dev/null || echo unknown)
+printf '{"ts_ms":%s,"kind":"hook.fire","label":"%s","duration_ms":%d,"cache":"%s","exit_code":%d,"hostname":"%s"}\\n' \\
+  "$TS_MS" "$HOOK_NAME" "$MS" "none" "$EXIT" "$HOST" >>"$PERF_SPOOL" 2>/dev/null || true
 
 exit "$EXIT"`;
 /**
@@ -322,7 +329,8 @@ function renderShim(name, scriptPath, cache, matches, paths) {
     const ttl = cache ? (typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0)) : 0;
     const key = cache?.key ?? 'global';
     const prefetch = cache?.prefetch ?? 'none';
-    const { cacheDir, logsDir } = paths;
+    const { cacheDir, logsDir, perfDir } = paths;
+    const perfSpool = path.join(perfDir, 'spool.jsonl');
     const hasMatches = matches != null && Object.keys(matches).length > 0;
     const matchesJson = hasMatches ? JSON.stringify(matches) : '';
     // sh-escape: wrap in single quotes, escape any embedded single quotes.
@@ -342,12 +350,14 @@ HOOK_NAME=${q(name)}
 SOURCE=${q(scriptPath)}
 CACHE_DIR=${q(cacheDir)}
 LOGS_DIR=${q(logsDir)}
+PERF_DIR=${q(perfDir)}
+PERF_SPOOL=${q(perfSpool)}
 TTL=${ttl}
 PREFETCH=${q(prefetch)}
 KEY_MODE=${q(key)}
 MATCHES_JSON=${q(matchesJson)}
 
-mkdir -p "$CACHE_DIR" "$LOGS_DIR"
+mkdir -p "$CACHE_DIR" "$LOGS_DIR" "$PERF_DIR"
 
 # Resolve a real Python. On Windows, bare python3 is often a Microsoft Store
 # app-execution alias stub that prints to stderr and exits non-zero (0 bytes on
@@ -380,6 +390,11 @@ if [ -n "$MATCHES_JSON" ]; then
     _LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
     printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":0,"cache":"skip","exit":0}\\n' \\
       "$_TS" "$HOOK_NAME" >>"$_LOG_FILE" 2>/dev/null || true
+    mkdir -p "$PERF_DIR" 2>/dev/null || true
+    _TS_MS=$("$PY" -c 'import time; print(int(time.time()*1000))' 2>/dev/null || echo 0)
+    _HOST=$(hostname 2>/dev/null || echo unknown)
+    printf '{"ts_ms":%s,"kind":"hook.fire","label":"%s","duration_ms":0,"cache":"skip","exit_code":0,"hostname":"%s"}\\n' \\
+      "$_TS_MS" "$HOOK_NAME" "$_HOST" >>"$PERF_SPOOL" 2>/dev/null || true
     exit 0
   fi
 fi
@@ -477,6 +492,11 @@ TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
 printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%d}\\n' \\
   "$TS" "$HOOK_NAME" "$MS" "$CACHE_STATUS" "$EXIT" >>"$LOG_FILE" 2>/dev/null || true
+# Disposable perf spool → drained into perf.db (see lib/perf/db.ts). Soft keys only.
+TS_MS=$("$PY" -c 'import time; print(int(time.time()*1000))' 2>/dev/null || echo 0)
+HOST=$(hostname 2>/dev/null || echo unknown)
+printf '{"ts_ms":%s,"kind":"hook.fire","label":"%s","duration_ms":%d,"cache":"%s","exit_code":%d,"hostname":"%s"}\\n' \\
+  "$TS_MS" "$HOOK_NAME" "$MS" "$CACHE_STATUS" "$EXIT" "$HOST" >>"$PERF_SPOOL" 2>/dev/null || true
 
 exit "$EXIT"
 `;

package/dist/lib/hosts/remote-cmd.js

@@ -88,6 +88,7 @@ export const RUN_OPTION_FORWARDING = {
     autoSecrets: 'forward', // workflow frontmatter secrets resolve on the REMOTE keychain
     emitSessionId: 'forward', // remote prints its session id as a stdout sentinel the launcher captures (session-marker.ts)
     // rejected — cannot cross the SSH boundary; fail loud, never degrade
+    terminal: 'reject', // opens a tab on THIS machine's desktop; a remote tab is a different request
     secrets: 'reject',
     secretsKeys: 'reject',
     allowExpired: 'reject',
@@ -126,6 +127,9 @@ export const RUN_OPTION_FORWARDING = {
 };
 /** Actionable messages for value-aware rejections, keyed by attribute name. */
 export const RUN_OPTION_REJECT_MESSAGES = {
+    terminal: '--terminal opens a tab on THIS machine; it cannot be combined with --host. ' +
+        'Drop --terminal to dispatch to the host, or drop --host to open the tab here. ' +
+        'To watch a remote run in a terminal, dispatch it and follow with `agents sessions focus <id>`.',
     secrets: '--secrets cannot cross the SSH boundary — Keychain values are never sent to a host implicitly. ' +
         'Provision the bundle on the host first (agents secrets export --host <name>), then run without --secrets; ' +
         'workflow frontmatter secrets resolve from the HOST\'s own keychain.',

package/dist/lib/menubar/install-menubar.d.ts

@@ -30,7 +30,16 @@ export declare function menubarServiceInstalled(): boolean;
 /** True when the bundle carries a signature the kernel will accept at launch. */
 export declare function codesignVerifies(appPath: string): boolean;
 /**
- * Guarantee the installed bundle has a valid signature on THIS machine.
+ * True when Gatekeeper will let the bundle execute on this machine.
+ * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
+ * which macOS surfaces as "the app is damaged" and can crash AppKit during
+ * launch. This is separate from `codesign --verify`: a signature can be valid
+ * while Gatekeeper still refuses to run it.
+ */
+export declare function gatekeeperAssesses(appPath: string): boolean;
+/**
+ * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
+ * machine.
  *
  * npm's pack/extract strips the ad-hoc/linker signature the release baked into
  * the helper, leaving `code object is not signed at all`. On macOS 26+ the
@@ -42,9 +51,10 @@ export declare function codesignVerifies(appPath: string): boolean;
  * matching cdhash, which the kernel accepts.
  *
  * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — so we leave it alone and only re-sign when verification
- * fails. Returns whether the bundle ends up validly signed. No-op cost on the
- * common (already-valid) path is a single `codesign --verify`.
+ * still verifies — but if the release was not notarized, Gatekeeper rejects it.
+ * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
+ * can launch locally. The stable fix is to notarize the release build; this
+ * fallback just prevents a crash-loop while the user is on an un-notarized cut.
  */
 export declare function ensureValidSignature(appPath: string): boolean;
 /**

package/dist/lib/menubar/install-menubar.js

@@ -177,7 +177,19 @@ export function codesignVerifies(appPath) {
     return r.status === 0;
 }
 /**
- * Guarantee the installed bundle has a valid signature on THIS machine.
+ * True when Gatekeeper will let the bundle execute on this machine.
+ * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
+ * which macOS surfaces as "the app is damaged" and can crash AppKit during
+ * launch. This is separate from `codesign --verify`: a signature can be valid
+ * while Gatekeeper still refuses to run it.
+ */
+export function gatekeeperAssesses(appPath) {
+    const r = spawnSync('spctl', ['--assess', '--type', 'exec', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+    return r.status === 0;
+}
+/**
+ * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
+ * machine.
  *
  * npm's pack/extract strips the ad-hoc/linker signature the release baked into
  * the helper, leaving `code object is not signed at all`. On macOS 26+ the
@@ -189,15 +201,17 @@ export function codesignVerifies(appPath) {
  * matching cdhash, which the kernel accepts.
  *
  * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — so we leave it alone and only re-sign when verification
- * fails. Returns whether the bundle ends up validly signed. No-op cost on the
- * common (already-valid) path is a single `codesign --verify`.
+ * still verifies — but if the release was not notarized, Gatekeeper rejects it.
+ * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
+ * can launch locally. The stable fix is to notarize the release build; this
+ * fallback just prevents a crash-loop while the user is on an un-notarized cut.
  */
 export function ensureValidSignature(appPath) {
-    if (codesignVerifies(appPath))
+    if (codesignVerifies(appPath) && gatekeeperAssesses(appPath))
         return true;
     // Drop any quarantine/xattrs the tarball round-trip added (they can break
-    // codesign), then re-sign ad-hoc under the helper's stable bundle identifier.
+    // both codesign and Gatekeeper), then re-sign ad-hoc under the helper's
+    // stable bundle identifier.
     spawnSync('xattr', ['-cr', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
     spawnSync('codesign', ['--force', '--sign', '-', '--identifier', SERVICE_LABEL, appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
     return codesignVerifies(appPath);

package/dist/lib/overdue.d.ts

@@ -11,6 +11,7 @@
  * Surfaced two ways: a desktop notification on daemon startup, and a
  * `agents routines catchup` command that runs them on demand.
  */
+import { type JobConfig } from './routines.js';
 export interface OverdueJob {
     name: string;
     /** Most recent expected fire time per the cron expression. */
@@ -18,6 +19,19 @@ export interface OverdueJob {
     /** Start time of the most recent recorded run, or null if never run. */
     lastRanAt: Date | null;
 }
+/**
+ * When a routine started existing, and therefore the earliest fire it can
+ * sensibly be judged against.
+ *
+ * `createdAt` is stamped by `writeJob`. Routines written before that field
+ * existed have none, so the file's own mtime stands in — it is the closest
+ * honest answer available on disk, and it only ever moves the floor later,
+ * never earlier, so it cannot manufacture a false "overdue".
+ *
+ * Returns null when neither is available, which leaves the routine unfloored
+ * (previous behaviour) rather than silently skipping it.
+ */
+export declare function routineEffectiveStart(job: JobConfig): Date | null;
 /** Return every enabled, recurring job whose most recent expected fire was
  *  missed. One-shot jobs are excluded — they fire at most once. */
 export declare function detectOverdueJobs(now?: Date): OverdueJob[];

package/dist/lib/overdue.js

@@ -11,8 +11,9 @@
  * Surfaced two ways: a desktop notification on daemon startup, and a
  * `agents routines catchup` command that runs them on demand.
  */
+import * as fs from 'fs';
 import { Cron } from 'croner';
-import { listJobs, getLatestRun, jobRunsOnThisDevice } from './routines.js';
+import { listJobs, getLatestRun, getJobPath, jobRunsOnThisDevice } from './routines.js';
 import { notifyDesktop } from './menubar/notify-desktop.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
@@ -36,6 +37,34 @@ function previousExpectedFire(cron, now) {
     }
     return last;
 }
+/**
+ * When a routine started existing, and therefore the earliest fire it can
+ * sensibly be judged against.
+ *
+ * `createdAt` is stamped by `writeJob`. Routines written before that field
+ * existed have none, so the file's own mtime stands in — it is the closest
+ * honest answer available on disk, and it only ever moves the floor later,
+ * never earlier, so it cannot manufacture a false "overdue".
+ *
+ * Returns null when neither is available, which leaves the routine unfloored
+ * (previous behaviour) rather than silently skipping it.
+ */
+export function routineEffectiveStart(job) {
+    if (job.createdAt) {
+        const stamped = new Date(job.createdAt);
+        if (!isNaN(stamped.getTime()))
+            return stamped;
+    }
+    const path = getJobPath(job.name);
+    if (!path)
+        return null;
+    try {
+        return new Date(fs.statSync(path).mtimeMs);
+    }
+    catch {
+        return null;
+    }
+}
 /** Return every enabled, recurring job whose most recent expected fire was
  *  missed. One-shot jobs are excluded — they fire at most once. */
 export function detectOverdueJobs(now = new Date()) {
@@ -66,6 +95,13 @@ export function detectOverdueJobs(now = new Date()) {
         }
         if (!expected)
             continue;
+        // A fire that predates the routine never could have happened, so it is not
+        // a miss. Without this, any newly created routine on a daily/weekly cron is
+        // instantly "overdue" for the previous occurrence — and with auto-catchup
+        // that means `agents routines add` runs the routine once, immediately.
+        const start = routineEffectiveStart(job);
+        if (start && expected.getTime() < start.getTime())
+            continue;
         const latest = getLatestRun(job.name);
         const lastRanAt = latest ? new Date(latest.startedAt) : null;
         const isOverdue = !lastRanAt || lastRanAt.getTime() < expected.getTime() - GRACE_MS;

package/dist/lib/perf/db.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
+ *
+ * Opened only by `agents perf` / `hooks profile` (read path). Writers use
+ * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
+ */
+import Database from '../sqlite.js';
+import type { AggregateOptions, PerfAggregateRow } from './types.js';
+export type { AggregateOptions, PerfAggregateRow, PerfSample } from './types.js';
+export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
+export declare const PERF_SCHEMA_VERSION = 1;
+export declare const DEFAULT_RETENTION_DAYS = 30;
+/** Test seam — redirect the warehouse path (like AGENTS_EVENTS_PATH). */
+export declare function _resetPerfDbForTest(overridePath?: string | null): void;
+/** Drain the NDJSON spool into samples. Idempotent; truncates on success. */
+export declare function drainSpool(db?: Database.Database): number;
+/** Percentile of a sorted-ascending array. p in [0,100]. */
+export declare function percentile(sorted: number[], p: number): number;
+/**
+ * Aggregate samples by (kind, label) with p50/p99. Drains the spool first.
+ */
+export declare function aggregateSamples(opts?: AggregateOptions): PerfAggregateRow[];
+export declare function perfDbPath(): string;
+export declare function perfSpoolPath(): string;
+export declare function ensurePerfDir(): string;

package/dist/lib/perf/db.js

@@ -0,0 +1,290 @@
+/**
+ * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
+ *
+ * Opened only by `agents perf` / `hooks profile` (read path). Writers use
+ * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from '../sqlite.js';
+import { getPerfDbPath, getPerfDir } from '../state.js';
+import { localMachineId } from '../session/origin-machine.js';
+import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';
+export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
+export const PERF_SCHEMA_VERSION = 1;
+export const DEFAULT_RETENTION_DAYS = 30;
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS samples (
+  id INTEGER PRIMARY KEY,
+  ts_ms INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  label TEXT NOT NULL,
+  duration_ms REAL NOT NULL,
+  session_id TEXT,
+  session_short TEXT,
+  agent TEXT,
+  agent_version TEXT,
+  machine TEXT,
+  hostname TEXT,
+  actor TEXT,
+  cwd TEXT,
+  cache TEXT,
+  exit_code INTEGER,
+  status TEXT,
+  meta_json TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_perf_ts ON samples(ts_ms);
+CREATE INDEX IF NOT EXISTS idx_perf_kind_ts ON samples(kind, ts_ms);
+CREATE INDEX IF NOT EXISTS idx_perf_label_ts ON samples(label, ts_ms);
+CREATE INDEX IF NOT EXISTS idx_perf_machine_ts ON samples(machine, ts_ms);
+CREATE INDEX IF NOT EXISTS idx_perf_session ON samples(session_id);
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+let _db = null;
+let _dbPath = null;
+let _disabled = false;
+/** Test seam — redirect the warehouse path (like AGENTS_EVENTS_PATH). */
+export function _resetPerfDbForTest(overridePath) {
+    if (_db) {
+        try {
+            _db.close();
+        }
+        catch { /* ignore */ }
+    }
+    _db = null;
+    _dbPath = overridePath === undefined ? null : overridePath;
+    _disabled = false;
+    if (overridePath) {
+        _resetPerfSpoolForTest(path.join(path.dirname(overridePath), 'spool.jsonl'));
+    }
+    else if (overridePath === null) {
+        _resetPerfSpoolForTest(null);
+    }
+}
+function resolveDbPath() {
+    return process.env.AGENTS_PERF_DB || _dbPath || getPerfDbPath();
+}
+function isDisabled() {
+    if (_disabled)
+        return true;
+    const v = process.env.AGENTS_DISABLE_PERF;
+    return v === '1' || v === 'true';
+}
+function openDb() {
+    if (isDisabled())
+        return null;
+    const dbPath = resolveDbPath();
+    if (_db && _dbPath === dbPath)
+        return _db;
+    if (_db) {
+        try {
+            _db.close();
+        }
+        catch { /* ignore */ }
+        _db = null;
+    }
+    try {
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true, mode: 0o700 });
+        const db = new Database(dbPath);
+        db.pragma('journal_mode = WAL');
+        db.pragma('synchronous = NORMAL');
+        db.pragma('busy_timeout = 2000');
+        db.exec(SCHEMA);
+        const row = db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
+        if (!row) {
+            db.prepare(`INSERT INTO meta(key, value) VALUES ('schema_version', ?)`).run(String(PERF_SCHEMA_VERSION));
+        }
+        _db = db;
+        _dbPath = dbPath;
+        drainSpool(db);
+        maybeRetain(db);
+        return db;
+    }
+    catch {
+        _disabled = true;
+        return null;
+    }
+}
+/** Drain the NDJSON spool into samples. Idempotent; truncates on success. */
+export function drainSpool(db) {
+    const spool = resolveSpoolPath();
+    if (!fs.existsSync(spool))
+        return 0;
+    let raw;
+    try {
+        raw = fs.readFileSync(spool, 'utf-8');
+    }
+    catch {
+        return 0;
+    }
+    if (!raw.trim()) {
+        try {
+            fs.writeFileSync(spool, '');
+        }
+        catch { /* ignore */ }
+        return 0;
+    }
+    const target = db ?? openDb();
+    if (!target)
+        return 0;
+    let n = 0;
+    const insert = target.prepare(`
+    INSERT INTO samples (
+      ts_ms, kind, label, duration_ms,
+      session_id, session_short, agent, agent_version,
+      machine, hostname, actor, cwd,
+      cache, exit_code, status, meta_json
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const txn = target.transaction((lines) => {
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let o;
+            try {
+                o = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const label = String(o.label ?? o.hook ?? '');
+            const durationMs = Number(o.duration_ms ?? o.durationMs ?? o.ms);
+            if (!label || !Number.isFinite(durationMs))
+                continue;
+            const sessionId = o.session_id != null ? String(o.session_id)
+                : o.sessionId != null ? String(o.sessionId) : null;
+            const tsMs = Number(o.ts_ms ?? o.tsMs) || (typeof o.ts === 'string' ? Date.parse(o.ts) : Date.now());
+            insert.run(Number.isFinite(tsMs) ? tsMs : Date.now(), String(o.kind ?? 'hook.fire'), label, durationMs, sessionId, o.session_short != null ? String(o.session_short) : shortSessionId(sessionId) ?? null, o.agent != null ? String(o.agent) : null, o.agent_version != null ? String(o.agent_version) : o.agentVersion != null ? String(o.agentVersion) : null, o.machine != null ? String(o.machine) : localMachineId(), o.hostname != null ? String(o.hostname) : null, o.actor != null ? String(o.actor) : null, o.cwd != null ? String(o.cwd) : null, o.cache != null ? String(o.cache) : null, o.exit_code != null ? Number(o.exit_code) : o.exit != null ? Number(o.exit) : null, o.status != null ? String(o.status) : null, o.meta_json != null ? String(o.meta_json) : null);
+            n++;
+        }
+    });
+    try {
+        txn(raw.split('\n'));
+        fs.writeFileSync(spool, '');
+    }
+    catch {
+        return 0;
+    }
+    return n;
+}
+function maybeRetain(db) {
+    try {
+        const last = db.prepare(`SELECT value FROM meta WHERE key = 'last_retain_ms'`).get();
+        const lastMs = last ? parseInt(last.value, 10) : 0;
+        const now = Date.now();
+        if (now - lastMs < 3_600_000)
+            return;
+        const cutoff = now - DEFAULT_RETENTION_DAYS * 86_400_000;
+        db.prepare(`DELETE FROM samples WHERE ts_ms < ?`).run(cutoff);
+        db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES ('last_retain_ms', ?)`).run(String(now));
+    }
+    catch {
+        // ignore
+    }
+}
+/** Percentile of a sorted-ascending array. p in [0,100]. */
+export function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    if (sorted.length === 1)
+        return sorted[0];
+    const rank = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+/**
+ * Aggregate samples by (kind, label) with p50/p99. Drains the spool first.
+ */
+export function aggregateSamples(opts = {}) {
+    const db = openDb();
+    if (!db)
+        return [];
+    drainSpool(db);
+    const days = opts.days ?? 7;
+    const sinceMs = Date.now() - days * 86_400_000;
+    const minN = opts.minN ?? 1;
+    const clauses = ['ts_ms >= ?'];
+    const params = [sinceMs];
+    if (opts.kinds && opts.kinds.length > 0) {
+        clauses.push(`kind IN (${opts.kinds.map(() => '?').join(',')})`);
+        params.push(...opts.kinds);
+    }
+    if (opts.label) {
+        clauses.push('label = ?');
+        params.push(opts.label);
+    }
+    if (opts.machine) {
+        clauses.push('machine = ?');
+        params.push(opts.machine);
+    }
+    if (opts.agent) {
+        clauses.push('agent = ?');
+        params.push(opts.agent);
+    }
+    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code
+     FROM samples WHERE ${clauses.join(' AND ')}`).all(...params);
+    const map = new Map();
+    for (const r of rows) {
+        const key = `${r.kind}\0${r.label}`;
+        let b = map.get(key);
+        if (!b) {
+            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0 };
+            map.set(key, b);
+        }
+        b.durations.push(Number(r.duration_ms));
+        if (r.cache === 'hit')
+            b.hits++;
+        else if (r.cache === 'stale-prefetch')
+            b.stale++;
+        else if (r.cache === 'miss' || r.cache === 'none')
+            b.misses++;
+        if (typeof r.exit_code === 'number' && r.exit_code !== 0)
+            b.errors++;
+    }
+    const out = [];
+    for (const b of map.values()) {
+        if (b.durations.length < minN)
+            continue;
+        const sorted = b.durations.slice().sort((a, c) => a - c);
+        const n = sorted.length;
+        const sum = sorted.reduce((a, c) => a + c, 0);
+        const row = {
+            kind: b.kind,
+            label: b.label,
+            n,
+            p50Ms: Math.round(percentile(sorted, 50)),
+            p99Ms: Math.round(percentile(sorted, 99)),
+            meanMs: Math.round(sum / n),
+            maxMs: sorted[n - 1],
+            minMs: sorted[0],
+        };
+        if (b.hits + b.stale + b.misses > 0) {
+            row.cacheHitPct = Math.round((b.hits / n) * 100);
+            row.cacheStalePct = Math.round((b.stale / n) * 100);
+            row.cacheMissPct = Math.round((b.misses / n) * 100);
+        }
+        if (b.errors > 0)
+            row.errorCount = b.errors;
+        out.push(row);
+    }
+    out.sort((a, b) => b.p99Ms - a.p99Ms);
+    return out;
+}
+export function perfDbPath() {
+    return resolveDbPath();
+}
+export function perfSpoolPath() {
+    return resolveSpoolPath();
+}
+export function ensurePerfDir() {
+    const dir = process.env.AGENTS_PERF_DIR || (_dbPath ? path.dirname(_dbPath) : getPerfDir());
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}

package/dist/lib/perf/spool.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hot-path perf writers — append-only NDJSON spool, no SQLite.
+ *
+ * Loaded from the CLI root `postAction` and from `events.ts` timing helpers.
+ * Must stay free of `../sqlite.js` so ordinary commands never load node:sqlite
+ * (which emits ExperimentalWarning on stderr).
+ */
+import type { PerfSample } from './types.js';
+export type { PerfSample } from './types.js';
+/** Test seam — pair with db._resetPerfDbForTest. */
+export declare function _resetPerfSpoolForTest(spoolPath?: string | null): void;
+export declare function resolveSpoolPath(): string;
+/** Short session id: first 8 chars (sessions.short_id shape). */
+export declare function shortSessionId(sessionId: string | undefined | null): string | undefined;
+/**
+ * Append one sample to the spool. Never throws. Never opens SQLite.
+ */
+export declare function recordSample(sample: PerfSample): void;