@phnx-labs/agents-cli 1.20.90 → 1.20.91

package/dist/lib/feed.js

@@ -236,6 +236,44 @@ export function clearBlockLifecycle(blockId, root) {
         }
     }
 }
+/**
+ * Build the block record for `agents feed post --blocked` — pure, so the shape is testable
+ * without touching the store or the broadcast layer.
+ *
+ * Class is derived, not asked for: a `--default` means the user could be absent
+ * and policy could still resolve it (approval); no default means only a human can
+ * choose (decision). `feed-policy.ts` reads exactly that distinction, so deriving
+ * it here keeps one rule in one place instead of letting a caller set a class that
+ * contradicts its own safeDefault.
+ *
+ * `costOfDelay: high` because a declared block is, by definition, an agent that
+ * has already stopped making progress — that is what makes it worth interrupting
+ * someone over, and what `feed --dispatch`'s urgency filter keys off.
+ */
+export function buildDeclaredBlock(agent, input) {
+    const text = input.text.trim().replace(/\s+/g, ' ');
+    if (!text) {
+        throw new Error('Block text is empty. Usage: agents feed post "what you need from the user" --blocked');
+    }
+    const options = (input.options ?? [])
+        .map((label) => label.trim())
+        .filter(Boolean)
+        .map((label) => ({ label }));
+    return {
+        blockId: blockIdForSession(agent.sessionId),
+        sessionId: agent.sessionId,
+        mailboxId: agent.mailboxId,
+        host: agent.host,
+        runtime: agent.runtime,
+        ts: input.ts ?? new Date().toISOString(),
+        kind: 'declared',
+        questions: [{ text, header: 'Needs you', ...(options.length ? { options } : {}) }],
+        blockClass: input.safeDefault ? 'approval' : 'decision',
+        costOfDelay: 'high',
+        ...(input.safeDefault ? { safeDefault: input.safeDefault } : {}),
+        ...(input.timeoutMinutes !== undefined ? { timeoutMinutes: input.timeoutMinutes } : {}),
+    };
+}
 /** Atomic write a block record to the feed store. Clears stale lifecycle state. */
 export function publishBlock(block, root) {
     const dir = root ?? getFeedDir();

package/dist/lib/hooks/cache.d.ts

@@ -26,6 +26,8 @@ export interface HookShimPaths {
     shimsDir?: string;
     cacheDir?: string;
     logsDir?: string;
+    /** Directory for the disposable perf warehouse + spool (default ~/.agents/.cache/perf). */
+    perfDir?: string;
 }
 /**
  * Generate (or refresh) the shim script for a hook. Idempotent — only writes

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/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;

package/dist/lib/perf/spool.js

@@ -0,0 +1,79 @@
+/**
+ * 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 * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getPerfSpoolPath } from '../state.js';
+import { localMachineId } from '../session/origin-machine.js';
+let _spoolOverride = null;
+let _disabled = false;
+/** Test seam — pair with db._resetPerfDbForTest. */
+export function _resetPerfSpoolForTest(spoolPath) {
+    _spoolOverride = spoolPath === undefined ? null : spoolPath;
+    _disabled = false;
+}
+export function resolveSpoolPath() {
+    if (process.env.AGENTS_PERF_SPOOL)
+        return process.env.AGENTS_PERF_SPOOL;
+    if (_spoolOverride)
+        return _spoolOverride;
+    return getPerfSpoolPath();
+}
+function isDisabled() {
+    if (_disabled)
+        return true;
+    const v = process.env.AGENTS_DISABLE_PERF;
+    return v === '1' || v === 'true';
+}
+/** Short session id: first 8 chars (sessions.short_id shape). */
+export function shortSessionId(sessionId) {
+    if (!sessionId)
+        return undefined;
+    const cleaned = sessionId.replace(/^session_/, '');
+    return cleaned.length >= 8 ? cleaned.slice(0, 8) : cleaned || undefined;
+}
+/**
+ * Append one sample to the spool. Never throws. Never opens SQLite.
+ */
+export function recordSample(sample) {
+    if (isDisabled())
+        return;
+    if (!sample.label || !Number.isFinite(sample.durationMs))
+        return;
+    try {
+        const tsMs = sample.tsMs ?? Date.now();
+        const sessionId = sample.sessionId;
+        const sessionShort = sample.sessionShort ?? shortSessionId(sessionId);
+        const machine = sample.machine ?? localMachineId();
+        const hostname = sample.hostname ?? os.hostname();
+        const line = JSON.stringify({
+            ts_ms: tsMs,
+            kind: sample.kind,
+            label: sample.label,
+            duration_ms: sample.durationMs,
+            session_id: sessionId,
+            session_short: sessionShort,
+            agent: sample.agent,
+            agent_version: sample.agentVersion,
+            machine,
+            hostname,
+            actor: sample.actor,
+            cwd: sample.cwd,
+            cache: sample.cache,
+            exit_code: sample.exitCode,
+            status: sample.status,
+            meta_json: sample.metaJson,
+        });
+        const spool = resolveSpoolPath();
+        fs.mkdirSync(path.dirname(spool), { recursive: true, mode: 0o700 });
+        fs.appendFileSync(spool, line + '\n', { mode: 0o600 });
+    }
+    catch {
+        // Fail soft.
+    }
+}