@phnx-labs/agents-cli 1.21.0 → 1.21.2

package/dist/lib/fleet-status.js

@@ -0,0 +1,120 @@
+/**
+ * Per-host fleet-status rows: this machine's resource stats PLUS its live agent
+ * workload (running-agent count + per-context / per-agent breakdown), published
+ * to a shared local mirror.
+ *
+ * ## Why this exists (RUSH-2061)
+ *
+ * The daemon's fleet-cache warm used to `loadFleetStats({ forceRefresh: true })`
+ * every 3 minutes — an SSH resource probe of EVERY device. With N daemons each
+ * probing N devices that is N² SSH round trips across the fleet every 3 minutes,
+ * each a remote `uptime;vm_stat;nproc` compute with a timeout that (pre-RUSH-2114)
+ * could orphan the remote child. This module replaces that with a
+ * **publish-own / read-union** model:
+ *
+ *  - Each daemon probes ONLY ITSELF (`probeLocalFleetStatus`, no SSH) and writes
+ *    its own row into the mirror. Zero cross-host SSH from the daemon → the N²
+ *    probe is gone.
+ *  - A READER (the `agents fleet status` command) unions the fleet's rows on
+ *    demand — a bounded, kill-on-timeout SSH read of each peer's already-computed
+ *    `--local` row (a cheap `cat`-equivalent, not a fresh remote probe) — and
+ *    writes them into the same mirror. `readFleetStatus` then serves the union
+ *    synchronously with no network at all.
+ *
+ * The mirror file matches the `stats-cache` / `auth-health` convention exactly:
+ * `{ version: 1, entries: Record<host, FleetStatusRow> }` under `getCacheDir()`,
+ * keyed by `machineId()`, best-effort read/write that never throws.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from './state.js';
+import { probeLocalStats } from './devices/health.js';
+import { getActiveSessions } from './session/active.js';
+/**
+ * Tally running-agent workload from a host's live sessions. "running" is the
+ * actively-working set (`status === 'running'`); `live` is every session the
+ * host is tracking. Pure so the tally is unit-tested without a live scan.
+ */
+export function computeAgentCounts(sessions) {
+    const byContext = {};
+    const byAgent = {};
+    let running = 0;
+    let live = 0;
+    for (const s of sessions) {
+        live += 1;
+        if (s.status !== 'running')
+            continue;
+        running += 1;
+        const ctx = s.context ?? 'unknown';
+        const agent = s.kind ?? 'unknown';
+        byContext[ctx] = (byContext[ctx] ?? 0) + 1;
+        byAgent[agent] = (byAgent[agent] ?? 0) + 1;
+    }
+    return { running, live, byContext, byAgent };
+}
+/**
+ * Probe THIS host's status — resource stats locally (no SSH) and agent workload
+ * from the local live-session set (`getActiveSessions({ localOnly: true })`,
+ * which never dials a remote host). Never throws: a failed sub-probe degrades to
+ * null stats / zero counts.
+ */
+export async function probeLocalFleetStatus(host, now = Date.now()) {
+    const [stats, sessions] = await Promise.all([
+        probeLocalStats(host).catch(() => null),
+        getActiveSessions({ localOnly: true }).catch(() => []),
+    ]);
+    return {
+        host,
+        agents: computeAgentCounts(sessions),
+        stats: stats ?? null,
+        capturedAt: now,
+    };
+}
+/** Test seam for the mirror path (see usage.ts `setClaudeUsageCachePathForTest`). */
+let mirrorPathOverride = null;
+export function setFleetStatusMirrorPathForTest(mirrorPath) {
+    const prev = mirrorPathOverride;
+    mirrorPathOverride = mirrorPath;
+    return prev;
+}
+function mirrorPath() {
+    return mirrorPathOverride ?? path.join(getCacheDir(), '.fleet-status.json');
+}
+/** Read the whole fleet-status mirror (best-effort; missing/corrupt → empty). */
+export function readFleetStatus() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(mirrorPath(), 'utf-8'));
+        if (parsed && parsed.entries && typeof parsed.entries === 'object')
+            return parsed.entries;
+    }
+    catch {
+        // missing or corrupt — treat as empty
+    }
+    return {};
+}
+/** Merge rows into the mirror (best-effort; preserves other hosts' rows). */
+export function writeFleetStatusRows(entries) {
+    try {
+        const dir = getCacheDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const merged = {
+            version: 1,
+            entries: { ...readFleetStatus(), ...entries },
+        };
+        fs.writeFileSync(mirrorPath(), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // best-effort; a failed write just means the reader sees an older union
+    }
+}
+/**
+ * Publish THIS host's row into the mirror (probe self, no SSH). The daemon calls
+ * this on its warm tick; it is the whole of the daemon's fleet-status duty now
+ * that cross-host probing is gone.
+ */
+export async function publishLocalFleetStatus(host) {
+    const row = await probeLocalFleetStatus(host);
+    writeFleetStatusRows({ [host]: row });
+    return row;
+}

package/dist/lib/friction-heuristics.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cheap heuristic readers over the `friction` event sink (emitFriction in
+ * events.ts). Guard hooks (git-guard, rm-guard, git-require-clean-tree) call
+ * `agents _internal friction --surface guard --id <failureId>` when they block
+ * a destructive command, so it exists in the log — but nothing reads it back
+ * yet. This is a starting point: one detector for the most actionable pattern,
+ * an agent stuck retrying the SAME denied action instead of adapting.
+ */
+import type { EventRecord } from './events.js';
+export interface RepeatedGuardBlockFinding {
+    /** Session id the repeated blocks happened in, or 'unknown' when the
+     *  friction event carried no session (e.g. a guard fired outside any
+     *  tracked agent session). */
+    session: string;
+    surface: string;
+    failureId: string;
+    /** Number of times this exact (session, surface, failureId) blocked. */
+    count: number;
+    firstTs: string;
+    lastTs: string;
+}
+/**
+ * Group `friction` events by (session, surface, failureId) and flag groups
+ * that repeat at least `minRepeats` times — the signature of an agent hitting
+ * the same guard over and over rather than changing approach after the first
+ * block. `events` is expected to already be filtered/queried for
+ * `eventTypes: ['friction']` (see events.ts `query()`); non-friction records
+ * are ignored defensively rather than assumed absent.
+ */
+export declare function detectRepeatedGuardBlocks(events: EventRecord[], opts?: {
+    minRepeats?: number;
+}): RepeatedGuardBlockFinding[];

package/dist/lib/friction-heuristics.js

@@ -0,0 +1,47 @@
+function asNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/**
+ * Group `friction` events by (session, surface, failureId) and flag groups
+ * that repeat at least `minRepeats` times — the signature of an agent hitting
+ * the same guard over and over rather than changing approach after the first
+ * block. `events` is expected to already be filtered/queried for
+ * `eventTypes: ['friction']` (see events.ts `query()`); non-friction records
+ * are ignored defensively rather than assumed absent.
+ */
+export function detectRepeatedGuardBlocks(events, opts = {}) {
+    const minRepeats = opts.minRepeats ?? 3;
+    const groups = new Map();
+    for (const e of events) {
+        if (e.event !== 'friction')
+            continue;
+        const surface = asNonEmptyString(e.surface);
+        const failureId = asNonEmptyString(e.failureId);
+        if (!surface || !failureId)
+            continue;
+        const session = e.session ?? 'unknown';
+        const key = `${session}\0${surface}\0${failureId}`;
+        const bucket = groups.get(key);
+        if (bucket)
+            bucket.push(e);
+        else
+            groups.set(key, [e]);
+    }
+    const out = [];
+    for (const [key, evs] of groups) {
+        if (evs.length < minRepeats)
+            continue;
+        const [session, surface, failureId] = key.split('\0');
+        const sortedTs = evs.map((e) => e.ts).sort();
+        out.push({
+            session,
+            surface,
+            failureId,
+            count: evs.length,
+            firstTs: sortedTs[0],
+            lastTs: sortedTs[sortedTs.length - 1],
+        });
+    }
+    out.sort((a, b) => b.count - a.count);
+    return out;
+}

package/dist/lib/hooks/cache.js

@@ -308,8 +308,8 @@ printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%
 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
+printf '{"ts_ms":%s,"kind":"hook.fire","label":"%s","duration_ms":%d,"cache":"%s","exit_code":%d,"hostname":"%s"%s}\\n' \\
+  "$TS_MS" "$HOOK_NAME" "$MS" "none" "$EXIT" "$HOST" "$HOOK_EXTRA_JSON" >>"$PERF_SPOOL" 2>/dev/null || true
 
 exit "$EXIT"`;
 /**
@@ -375,6 +375,28 @@ done
 # Read stdin once (Claude/Codex/Gemini pass JSON on stdin to every hook).
 STDIN_PAYLOAD="$(cat || true)"
 
+# cwd + session_id from the hook's own stdin JSON, pre-escaped as a ready-to-
+# splice JSON fragment (e.g. ,"cwd":"/repo","session_id":"abc") so every
+# hook.fire perf-spool line below can carry them without re-parsing stdin per
+# site. This is what lets \`agents perf --project\` (project-key.ts resolves
+# cwd -> project) and session-scoped rollups work for hook.fire samples.
+# Fail-safe: any parse error yields an empty fragment, never breaks the write.
+HOOK_EXTRA_JSON="$(printf '%s' "$STDIN_PAYLOAD" | "$PY" -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    d = {}
+out = {}
+cwd = d.get("cwd")
+if isinstance(cwd, str) and cwd:
+    out["cwd"] = cwd
+sid = d.get("session_id") or d.get("sessionId")
+if isinstance(sid, str) and sid:
+    out["session_id"] = sid
+print("".join("," + json.dumps(k) + ":" + json.dumps(v) for k, v in out.items()))
+' 2>/dev/null || true)"
+
 # --- matches: gate (issue #744 / RUSH-1506) -------------------------------
 # Enforce the hook's declared \`matches:\` predicates at fire time. Mirrors
 # shouldFire() in src/lib/hooks/match.ts: all declared predicates AND together;
@@ -393,8 +415,8 @@ if [ -n "$MATCHES_JSON" ]; then
     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
+    printf '{"ts_ms":%s,"kind":"hook.fire","label":"%s","duration_ms":0,"cache":"skip","exit_code":0,"hostname":"%s"%s}\\n' \\
+      "$_TS_MS" "$HOOK_NAME" "$_HOST" "$HOOK_EXTRA_JSON" >>"$PERF_SPOOL" 2>/dev/null || true
     exit 0
   fi
 fi
@@ -495,8 +517,8 @@ printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%
 # 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
+printf '{"ts_ms":%s,"kind":"hook.fire","label":"%s","duration_ms":%d,"cache":"%s","exit_code":%d,"hostname":"%s"%s}\\n' \\
+  "$TS_MS" "$HOOK_NAME" "$MS" "$CACHE_STATUS" "$EXIT" "$HOST" "$HOOK_EXTRA_JSON" >>"$PERF_SPOOL" 2>/dev/null || true
 
 exit "$EXIT"
 `;

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

@@ -2,6 +2,7 @@ export interface HookProfileRow {
     hook: string;
     n: number;
     p50Ms: number;
+    p95Ms: number;
     p99Ms: number;
     meanMs: number;
     maxMs: number;
@@ -9,6 +10,13 @@ export interface HookProfileRow {
     cacheStalePct: number;
     cacheMissPct: number;
     errorCount: number;
+    /** Fraction (0-1) of fires with a nonzero exit code. */
+    errorRate?: number;
+    /** Fraction (0-1) of fires that hit their configured timeout. */
+    timeoutRate?: number;
+    /** Project key the row is scoped to (see project-key.ts) — set only when
+     *  a `--project` filter narrowed the underlying query. */
+    project?: string;
 }
 interface RawFireEvent {
     event?: string;

package/dist/lib/hooks/profile.js

@@ -3,10 +3,11 @@
  * generated shims (see `cache.ts`) emit on every invocation, and aggregates
  * per-hook timing + cache stats.
  *
- * Only hooks declared with `cache:` get instrumented today, because only those
- * are wrapped by a generated shim. Hooks without `cache:` are not in the
- * profile output — that's deliberate: opting into the primitive is what
- * surfaces the data.
+ * Every hook gets a generated shim now (resolveHookCommand in hooks.ts) —
+ * `cache:`, `matches:`, or a bare `matcher:` (e.g. git-guard/rm-guard) are all
+ * enough to opt in. The only hooks NOT in this profile are ones with none of
+ * the three, since a pure lifecycle hook with nothing to gate/cache/match runs
+ * the raw script path with no timing wrapper at all.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -89,6 +90,7 @@ export function aggregateHookProfile(events) {
             hook,
             n,
             p50Ms: Math.round(percentile(sortedMs, 50)),
+            p95Ms: Math.round(percentile(sortedMs, 95)),
             p99Ms: Math.round(percentile(sortedMs, 99)),
             meanMs: Math.round(sum / n),
             maxMs: sortedMs[sortedMs.length - 1],
@@ -96,6 +98,14 @@ export function aggregateHookProfile(events) {
             cacheStalePct: Math.round((stale / n) * 100),
             cacheMissPct: Math.round((misses / n) * 100),
             errorCount: errors,
+            ...(errors > 0 ? { errorRate: Math.round((errors / n) * 1000) / 1000 } : {}),
+            // timeoutRate is not derivable here: the daily JSONL a shim writes only
+            // covers fires that reached their own trailing printf — an externally
+            // enforced timeout (the agent harness killing the process) never gets
+            // that far, so this log has no timeout signal at all. The warehouse
+            // path (asHookRows in commands/perf.ts) is the one that can see it,
+            // via the perf-spool `status:"timeout"` sample OpenCode's generated
+            // plugin writes directly (hooks.ts's recordTimeoutSample).
         });
     }
     rows.sort((a, b) => b.p99Ms - a.p99Ms);

package/dist/lib/hooks.d.ts

@@ -198,6 +198,19 @@ export declare function installHooksCentrally(source: string): Promise<{
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralHooks(): HookEntry[];
+/**
+ * Normalize a hook `timeout` from agents.yaml into a whole number of seconds.
+ *
+ * A bare number stays seconds (`timeout: 30` → 30) for backward compatibility.
+ * A Go-style duration string is parsed into seconds: `5s`, `2m`, `1h30m`,
+ * `90s`, `1h`. This intentionally does NOT reuse {@link parseTimeout} from
+ * routines.ts — that one returns milliseconds, has no seconds (`s`) unit, and
+ * floors at one minute, none of which fit hook timeouts (typically 5–600s).
+ *
+ * Returns the seconds value, or `null` when the input is not a positive number
+ * or a parseable duration string — the caller decides how to surface that.
+ */
+export declare function normalizeHookTimeoutSeconds(value: unknown): number | null;
 /**
  * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
  * (npm-shipped defaults) and user hooks from the `hooks:` section of
@@ -205,7 +218,9 @@ export declare function listCentralHooks(): HookEntry[];
  * A user entry with `enabled: false` disables the system-shipped hook of
  * the same name without forking the system file.
  *
- * Hooks marked `enabled: false` are dropped from the returned map.
+ * Hooks marked `enabled: false` are dropped from the returned map. A hook
+ * `timeout` written as a duration string (`5s`, `2m`) is normalized to a
+ * seconds number here, so every downstream serializer keeps reading a number.
  */
 export declare function parseHookManifest(opts?: {
     warn?: boolean;

package/dist/lib/hooks.js

@@ -15,7 +15,7 @@ import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
 import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
 import { supports, explainSkip, capableAgents } from './capabilities.js';
-import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir } from './state.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPerfDir } from './state.js';
 import { collectSubruleHooksFromState } from './rules/compose.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
 /**
@@ -256,12 +256,20 @@ export function inspectDuplicateVersionHooks(cwd = process.cwd()) {
 /**
  * Resolve the command path to register for a hook.
  *
- * Returns either the raw script path (neither `cache:` nor `matches:` set,
- * legacy behavior) or the path to a generated wrapper shim. The shim is written
- * as a side effect when `cache:` and/or `matches:` is configured — it enforces
- * the `matches:` gate at fire time and layers the caching/timing machinery when
- * `cache:` is set. The agent-native settings file gets the same shape either
- * way — just a different command path.
+ * Returns either the raw script path (no `cache:`, `matches:`, or `matcher:`
+ * set — a bare lifecycle hook with nothing to gate or time) or the path to a
+ * generated wrapper shim. The shim is written as a side effect when `cache:`
+ * and/or `matches:` is configured — it enforces the `matches:` gate at fire
+ * time and layers the caching/timing machinery when `cache:` is set.
+ *
+ * A hook that declares only `matcher:` (e.g. git-guard/rm-guard scoped to the
+ * `Bash` tool, no `cache:`/`matches:`) also gets a shim now — a pass-through
+ * one with no gate and no cache, whose only job is the trailing timing sample
+ * (see PASSTHROUGH_TAIL in hooks/cache.ts). Before this, a matcher-only hook
+ * took the raw-path branch and fired completely uninstrumented: `agents perf
+ * hooks` showed zero samples for it no matter how often it ran. The agent-
+ * native settings file gets the same shape either way — just a different
+ * command path.
  */
 function resolveHookCommand(name, hookDef, resolveScript) {
     const scriptPath = resolveScript(hookDef.script);
@@ -272,17 +280,20 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     const cache = parseCacheConfig(hookDef.cache);
     const matches = hookDef.matches;
     const hasMatches = matches != null && Object.keys(matches).length > 0;
-    if (!cache && !hasMatches) {
-        // No caching and no matches: gate opted in — make sure a previously
-        // generated shim from an earlier `cache:`/`matches:` config is gone so the
-        // JSONL doesn't keep claiming hits.
+    const hasMatcher = !!hookDef.matcher;
+    if (!cache && !hasMatches && !hasMatcher) {
+        // Nothing to gate, cache, or time: make sure a previously generated shim
+        // from an earlier cache:/matches:/matcher config is gone so the JSONL
+        // doesn't keep claiming hits.
         removeHookShim(name);
         return toPortableCommand(scriptPath);
     }
-    // A shim is generated when the hook opts into caching and/or declares
-    // `matches:` predicates. The shim enforces the `matches:` gate at fire time
-    // (skipping the script when predicates don't hold) and, when `cache:` is set,
-    // layers the cache/timing machinery on top.
+    // A shim is generated when the hook opts into caching, declares `matches:`
+    // predicates, or declares a `matcher:` (even alone — see the doc comment
+    // above). The shim enforces the `matches:` gate at fire time (skipping the
+    // script when predicates don't hold) and, when `cache:` is set, layers the
+    // cache/timing machinery on top; with neither, it is a pure pass-through
+    // timing wrapper.
     return toPortableCommand(generateHookShim({ name, scriptPath, cache, matches }));
 }
 /**
@@ -645,7 +656,7 @@ export function checkVersionHookWiring(agent, version) {
             return null;
         const cache = parseCacheConfig(hookDef.cache);
         const hasMatches = hookDef.matches != null && Object.keys(hookDef.matches).length > 0;
-        if (!cache && !hasMatches)
+        if (!cache && !hasMatches && !hookDef.matcher)
             return toPortableCommand(scriptPath);
         return toPortableCommand(getHookShimPath(name));
     };
@@ -952,6 +963,44 @@ export function listCentralHooks() {
     }
     return results;
 }
+/**
+ * Normalize a hook `timeout` from agents.yaml into a whole number of seconds.
+ *
+ * A bare number stays seconds (`timeout: 30` → 30) for backward compatibility.
+ * A Go-style duration string is parsed into seconds: `5s`, `2m`, `1h30m`,
+ * `90s`, `1h`. This intentionally does NOT reuse {@link parseTimeout} from
+ * routines.ts — that one returns milliseconds, has no seconds (`s`) unit, and
+ * floors at one minute, none of which fit hook timeouts (typically 5–600s).
+ *
+ * Returns the seconds value, or `null` when the input is not a positive number
+ * or a parseable duration string — the caller decides how to surface that.
+ */
+export function normalizeHookTimeoutSeconds(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) && value > 0 ? value : null;
+    }
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (s === '')
+            return null;
+        // A bare integer string means seconds, matching the bare-number form.
+        if (/^\d+$/.test(s)) {
+            const n = Number(s);
+            return n > 0 ? n : null;
+        }
+        const m = s.match(/^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/i);
+        if (!m)
+            return null;
+        const weeks = Number(m[1] || 0);
+        const days = Number(m[2] || 0);
+        const hours = Number(m[3] || 0);
+        const minutes = Number(m[4] || 0);
+        const seconds = Number(m[5] || 0);
+        const total = ((weeks * 7 + days) * 24 + hours) * 3600 + minutes * 60 + seconds;
+        return total > 0 ? total : null;
+    }
+    return null;
+}
 /**
  * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
  * (npm-shipped defaults) and user hooks from the `hooks:` section of
@@ -959,7 +1008,9 @@ export function listCentralHooks() {
  * A user entry with `enabled: false` disables the system-shipped hook of
  * the same name without forking the system file.
  *
- * Hooks marked `enabled: false` are dropped from the returned map.
+ * Hooks marked `enabled: false` are dropped from the returned map. A hook
+ * `timeout` written as a duration string (`5s`, `2m`) is normalized to a
+ * seconds number here, so every downstream serializer keeps reading a number.
  */
 export function parseHookManifest(opts = {}) {
     const warn = opts.warn !== false;
@@ -1026,6 +1077,26 @@ export function parseHookManifest(opts = {}) {
         if (def.enabled === false)
             delete merged[name];
     }
+    // Normalize each surviving hook's timeout to a seconds number, so the raw
+    // agents.yaml can express it as a duration string (`5s`, `2m`) while every
+    // downstream serializer keeps consuming a plain number. An unparseable value
+    // is dropped with a warning rather than silently coerced to a wrong duration.
+    for (const [name, def] of Object.entries(merged)) {
+        const raw = def.timeout;
+        if (raw === undefined)
+            continue;
+        const seconds = normalizeHookTimeoutSeconds(raw);
+        if (seconds === null) {
+            if (warn) {
+                console.warn(`[agents hooks] Hook '${name}' has an invalid timeout ${JSON.stringify(raw)}; ` +
+                    `expected seconds or a duration string like '5s', '2m', '1h30m'. Ignoring it.`);
+            }
+            delete def.timeout;
+        }
+        else {
+            def.timeout = seconds;
+        }
+    }
     return merged;
 }
 export function selectHookManifest(manifest, selected) {
@@ -1204,7 +1275,17 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         return resolveHookScriptPath(script);
     };
     const managedPrefixes = overrideRoots
-        ? [path.join(overrideRoots[0], 'hooks') + path.sep]
+        ? [
+            path.join(overrideRoots[0], 'hooks') + path.sep,
+            // The shim dir is one global location regardless of which hooks
+            // source (agentsDirOverride vs the normal user/system dirs) resolved
+            // the underlying script, so it belongs in every managedPrefixes
+            // shape — omitting it here left a shim path unrecognized as managed
+            // under the override branch, so a hook's matcher/event change never
+            // GC'd its stale shim-path entry (only reachable via a caller that
+            // passes agentsDirOverride; no production call site does today).
+            getHookShimsDir() + path.sep,
+        ]
         : [
             ...getManagedHookPrefixes(),
             ...(localHooksDir ? [localHooksDir + path.sep] : []),
@@ -1313,9 +1394,42 @@ function registerHooksForOpenCode(versionHome, manifest, resolveScript) {
     }
     const serializedDirect = JSON.stringify(Object.fromEntries(direct), null, 2);
     const serializedLifecycle = JSON.stringify(Object.fromEntries(lifecycle), null, 2);
+    // Same disposable perf spool the bash shims (hooks/cache.ts) append to — see
+    // the timedOut branch below for why OpenCode needs its own writer.
+    const perfSpoolPath = path.join(getPerfDir(), 'spool.jsonl');
     const pluginSource = `// Generated by agents-cli. Re-run agents sync to update.
+import fs from "node:fs"
+import os from "node:os"
+
 const directHooks = ${serializedDirect}
 const lifecycleHooks = ${serializedLifecycle}
+const PERF_SPOOL = ${JSON.stringify(perfSpoolPath)}
+
+function recordTimeoutSample(hook, payload) {
+  // hook.command already ran through a generated shim (hooks/cache.ts) that
+  // writes its own hook.fire sample on exit — but Bun.spawn's child.kill()
+  // below (SIGTERM) tears the shim down before it reaches that trailing
+  // printf, so a timed-out fire would otherwise leave ZERO trace in the
+  // warehouse. Write the sample ourselves from the side that knows it timed out.
+  try {
+    fs.mkdirSync(PERF_SPOOL.slice(0, PERF_SPOOL.lastIndexOf("/")), { recursive: true })
+    const line = JSON.stringify({
+      ts_ms: Date.now(),
+      kind: "hook.fire",
+      label: hook.name,
+      duration_ms: hook.timeout * 1000,
+      cache: "none",
+      exit_code: null,
+      status: "timeout",
+      cwd: payload && typeof payload.cwd === "string" ? payload.cwd : undefined,
+      session_id: payload && typeof payload.session_id === "string" ? payload.session_id : undefined,
+      hostname: (() => { try { return os.hostname() } catch { return "unknown" } })(),
+    }) + "\\n"
+    fs.appendFileSync(PERF_SPOOL, line)
+  } catch {
+    // best effort — never let sample recording break the timeout error path
+  }
+}
 
 function matches(hook, tool) {
   if (!hook.matcher) return true
@@ -1355,6 +1469,7 @@ async function runHooks(hooks, payload, $, matchTool = false) {
       const exitCode = await child.exited.finally(() => clearTimeout(timer))
       const stderr = await new Response(child.stderr).text()
       if (timedOut) {
+        recordTimeoutSample(hook, payload)
         throw new Error(\`\${hook.name} timed out after \${hook.timeout} seconds\`)
       }
       if (exitCode !== 0) {

package/dist/lib/linear-cache.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Disk TTL cache for the Linear answers behind the `agents projects` card.
+ *
+ * Linear meters two budgets independently, and only one of them binds. Observed
+ * on this account's response headers:
+ *
+ *   x-ratelimit-requests-limit:   2500      remaining: 2
+ *   x-ratelimit-complexity-limit: 3000000   remaining: 2999987
+ *
+ * Requests are scarce; complexity is 99.999% untouched. So the thing to
+ * optimize is the NUMBER of calls, not their cost — and the way to spend 2500
+ * of them is an agent (or a watch loop) running `projects status` repeatedly.
+ * A human typing it is not the exhauster.
+ *
+ * The CLI is a short-lived process, so an in-memory memo would only help within
+ * one invocation, which is the case that never needed help. This caches to disk.
+ *
+ * **One file per key, written by atomic rename.** A single JSON document holding
+ * every entry has to be read, modified, and written back, and that sequence is
+ * not atomic across processes — measured on this machine, two concurrent writers
+ * of 40 distinct keys each left **8 of 80** surviving. This box routinely runs a
+ * dozen agent sessions, so that is the normal case, not a corner. Per-key files
+ * remove the shared mutable document entirely: two processes caching different
+ * projects never touch the same path, and two caching the SAME project race only
+ * to write identical data. `writeFileSync` to a temp path followed by `rename`
+ * makes each file appear whole or not at all, so a reader never sees a partial
+ * write.
+ *
+ * The load-bearing behavior is what happens on FAILURE: a stale entry keeps
+ * being served, marked stale, instead of the line vanishing. That rule is
+ * borrowed from `mergeAuthHealthEntries` — one 8s timeout must not flip a
+ * populated chip to empty — and it is the fix for the card silently losing its
+ * Linear line mid-session when the request budget ran out.
+ */
+/** Matches `SKILL_INDEX_TTL_MS` (`lib/registry.ts`) — the repo's TTL convention. */
+export declare const LINEAR_CACHE_TTL_MS: number;
+/** What a lookup found, and how much to trust it. */
+export interface CacheHit<T> {
+    value: T;
+    /** Age in ms. Past the TTL the value is still returned, flagged stale. */
+    ageMs: number;
+    stale: boolean;
+}
+/** Look up a project's cached answer. Returns stale entries too — the caller decides. */
+export declare function readCached<T>(projectId: string, nowMs: number): CacheHit<T> | undefined;
+/** Store a freshly fetched answer. */
+export declare function writeCached<T>(projectId: string, value: T, nowMs: number): void;
+/** Drop one project's entry — used when `projects link` re-points a definition. */
+export declare function invalidateCached(projectId: string): void;
+/** True when a prior 429 said the budget is exhausted and has not yet reset. */
+export declare function isRateLimited(nowMs: number): boolean;
+/**
+ * Read a 429's `x-ratelimit-requests-reset` header into an epoch-ms instant.
+ * Linear sends epoch milliseconds; anything absent, non-numeric, or already in
+ * the past is not usable and the caller backs off a TTL instead. Pure, so the
+ * parsing is testable without a live 429.
+ */
+export declare function parseRateLimitReset(header: string | null, nowMs: number): number | undefined;
+/**
+ * Record a 429 so the next runs don't spend a request learning the same thing.
+ * `resetAtMs` comes from {@link parseRateLimitReset}; without it, back off one TTL.
+ */
+export declare function noteRateLimited(resetAtMs: number | undefined, nowMs: number): void;