@phnx-labs/agents-cli 1.21.0 → 1.21.2

package/dist/lib/session/discover.js

@@ -1015,6 +1015,7 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, account,
             topic: scan.topic,
             label,
             messageCount: scan.messageCount,
+            toolCallCount: scan.toolCallCount,
             tokenCount: scan.tokenCount,
             outputTokens: scan.outputTokens,
             costUsd: scan.costUsd,
@@ -1044,6 +1045,7 @@ async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, account,
             model: scan.model,
             label,
             messageCount: scan.messageCount,
+            toolCallCount: scan.toolCallCount,
             tokenCount: scan.tokenCount,
             outputTokens: scan.outputTokens,
             costUsd: scan.costUsd,
@@ -2425,6 +2427,7 @@ export function initClaudeParseState() {
         aiTitle: undefined,
         entrypoint: undefined,
         messageCount: 0,
+        toolCallCount: 0,
         tokenCount: 0,
         outputTokens: 0,
         sawTokenCount: false,
@@ -2482,6 +2485,7 @@ export function applyClaudeLine(state, parsed) {
         for (const b of parsed.message.content) {
             if (b?.type !== 'tool_use')
                 continue;
+            state.toolCallCount++;
             if (!state.spawnedTeam && typeof b?.input?.command === 'string') {
                 const team = detectSpawnedTeam(b.input.command);
                 if (team)
@@ -2642,6 +2646,7 @@ export function finalizeClaudeScan(state) {
         topic: resolvedTopic,
         entrypoint: state.entrypoint,
         messageCount: state.messageCount,
+        toolCallCount: state.toolCallCount,
         tokenCount: state.sawTokenCount ? state.tokenCount : undefined,
         outputTokens: state.sawTokenCount ? state.outputTokens : undefined,
         costUsd: state.sawCost ? state.costUsd : undefined,
@@ -2713,6 +2718,7 @@ export function serializeClaudeParserState(state, offset) {
         plan: state.plan,
         lastTsMs: state.lastTsMs,
         messageCount: state.messageCount,
+        toolCallCount: state.toolCallCount,
         tokenCount: state.tokenCount,
         outputTokens: state.outputTokens,
         sawTokenCount: state.sawTokenCount,
@@ -2771,6 +2777,7 @@ export function hydrateClaudeParseState(prior) {
         aiTitle: prior.aiTitle,
         entrypoint: prior.entrypoint,
         messageCount: prior.messageCount,
+        toolCallCount: prior.toolCallCount ?? 0,
         tokenCount: prior.tokenCount,
         outputTokens: prior.outputTokens,
         sawTokenCount: prior.sawTokenCount,
@@ -3734,6 +3741,7 @@ export function readCursorMeta(filePath, currentVersion) {
         topic: firstUserText ? extractSessionTopic(firstUserText) : undefined,
         label: title,
         messageCount: events.filter((event) => event.type === 'message').length,
+        todos: extractTodoProgressFromEvents(events),
     };
     return { meta, content: userTexts.join('\n') };
 }

package/dist/lib/session/types.d.ts

@@ -132,6 +132,7 @@ export interface SessionMeta {
     durationMs?: number;
     /** Underlying LLM model observed in the transcript, when the agent records one. */
     model?: string;
+    toolCallCount?: number;
     version?: string;
     account?: string;
     topic?: string;

package/dist/lib/startup/command-registry.d.ts

@@ -71,6 +71,7 @@ export declare const loadFactory: ModuleLoader;
 export declare const loadUsage: ModuleLoader;
 export declare const loadCost: ModuleLoader;
 export declare const loadPerf: ModuleLoader;
+export declare const loadTrends: ModuleLoader;
 export declare const loadOutput: ModuleLoader;
 export declare const loadBudget: ModuleLoader;
 export declare const loadAlias: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -49,6 +49,7 @@ export const loadFactory = async () => (await import('../../commands/factory.js'
 export const loadUsage = async () => (await import('../../commands/usage.js')).registerUsageCommand;
 export const loadCost = async () => (await import('../../commands/cost.js')).registerCostCommand;
 export const loadPerf = async () => (await import('../../commands/perf.js')).registerPerfCommand;
+export const loadTrends = async () => (await import('../../commands/trends.js')).registerTrendsCommand;
 export const loadOutput = async () => (await import('../../commands/output.js')).registerOutputCommand;
 export const loadBudget = async () => (await import('../../commands/budget.js')).registerBudgetCommand;
 export const loadAlias = async () => (await import('../../commands/alias.js')).registerAliasCommand;
@@ -163,6 +164,7 @@ export const COMMAND_LOADERS = {
     usage: [loadUsage],
     cost: [loadCost],
     perf: [loadPerf],
+    trends: [loadTrends],
     output: [loadOutput],
     budget: [loadBudget],
     alias: [loadAlias],

package/dist/lib/state.d.ts

@@ -117,6 +117,14 @@ export declare function getUserSecretsDir(): string;
  * metadata off the real session flow — not a second write path.
  */
 export declare function getSecretsDbPath(): string;
+/**
+ * Path to the durable resource-usage warehouse (~/.agents/.history/analytics/usage.db).
+ * Value-free frequency/lifecycle events (secrets, agents, browser, …). Read at CALL
+ * time so AGENTS_USAGE_DB can redirect tests. Sync shards may also appear as
+ * usage.<machine-id>.db beside this default file.
+ */
+export declare function getAnalyticsDir(): string;
+export declare function getUsageDbPath(): string;
 export declare function getUserPromptcutsPath(): string;
 /** Canonical home anchor (HOME env override or os.homedir()). */
 export declare function getHomeDir(): string;
@@ -185,9 +193,20 @@ export declare function getActivityDir(): string;
 export declare function getVersionsDir(): string;
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
 export declare function getShimsDir(): string;
-/** Path to generated per-hook caching/timing shims (~/.agents/.cache/shims/hooks/). */
+/**
+ * Path to generated per-hook caching/timing shims (~/.agents/.cache/shims/hooks/).
+ * Read at CALL time — since every hook now resolves through a shim (RUSH-2xxx,
+ * pass-through timing for matcher-only hooks), a test that registers hooks
+ * in-process (no subprocess HOME override) would otherwise write real shim
+ * files into the user's actual ~/.agents/.cache. AGENTS_HOOK_SHIMS_DIR mirrors
+ * the AGENTS_EVENTS_PATH / AGENTS_DEVICES_DIR test-isolation escape hatches;
+ * never set in production code.
+ */
 export declare function getHookShimsDir(): string;
-/** Path to per-hook stdout cache files (~/.agents/.cache/state/hooks/). */
+/**
+ * Path to per-hook stdout cache files (~/.agents/.cache/state/hooks/). Read at
+ * CALL time for the same reason as {@link getHookShimsDir} — see its doc.
+ */
 export declare function getHookCacheDir(): string;
 /** Path to per-agent installed CLI binaries (~/.agents/.cache/bin/). */
 export declare function getBinDir(): string;
@@ -225,11 +244,20 @@ export declare function getDevicesPendingDir(): string;
 export declare function getCloudDir(): string;
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */
 export declare function getTerminalsDir(): string;
-/** Path to runtime logs (~/.agents/.cache/logs/). */
+/**
+ * Path to runtime logs (~/.agents/.cache/logs/). Read at CALL time so
+ * AGENTS_LOGS_DIR can redirect it in tests — same test-isolation escape hatch
+ * as {@link getHookShimsDir}; never set in production code.
+ */
 export declare function getLogsDir(): string;
 /**
  * Path to disposable performance samples (~/.agents/.cache/perf/).
  * Holds `perf.db` + a hook-shim spool. Loss is acceptable — wipe freely.
+ * Read at CALL time: AGENTS_PERF_DIR (the same override perf/db.ts and
+ * perf/spool.ts already honor for their own internal resolution) redirects
+ * this canonical getter too, so a caller that goes through it directly
+ * (hooks/cache.ts's shim generator, the OpenCode timeout sample writer in
+ * hooks.ts) doesn't leak samples into the user's real perf warehouse either.
  */
 export declare function getPerfDir(): string;
 /** Path to the perf SQLite warehouse (~/.agents/.cache/perf/perf.db). */

package/dist/lib/state.js

@@ -96,6 +96,7 @@ const PROJECTS_DIR = path.join(USER_AGENTS_DIR, 'projects');
 // History bucket (durable).
 const SESSIONS_DIR = path.join(HISTORY_DIR, 'sessions');
 const SESSIONS_DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
+const ANALYTICS_DIR = path.join(HISTORY_DIR, 'analytics');
 const VERSIONS_DIR = path.join(HISTORY_DIR, 'versions');
 const RUNS_DIR = path.join(HISTORY_DIR, 'runs');
 // Durable per-monitor state-diff store + fire history (last-seen value/hash,
@@ -377,6 +378,18 @@ export function getUserSecretsDir() { return USER_SECRETS_DIR; }
 export function getSecretsDbPath() {
     return process.env.AGENTS_SECRETS_DB ?? path.join(USER_SECRETS_DIR, 'secrets.db');
 }
+/**
+ * Path to the durable resource-usage warehouse (~/.agents/.history/analytics/usage.db).
+ * Value-free frequency/lifecycle events (secrets, agents, browser, …). Read at CALL
+ * time so AGENTS_USAGE_DB can redirect tests. Sync shards may also appear as
+ * usage.<machine-id>.db beside this default file.
+ */
+export function getAnalyticsDir() {
+    return process.env.AGENTS_ANALYTICS_DIR ?? ANALYTICS_DIR;
+}
+export function getUsageDbPath() {
+    return process.env.AGENTS_USAGE_DB ?? path.join(getAnalyticsDir(), 'usage.db');
+}
 export function getUserPromptcutsPath() { return USER_PROMPTCUTS_FILE; }
 // ─── User operational path getters ────────────────────────────────────────────
 //
@@ -459,10 +472,25 @@ export function getActivityDir() { return ACTIVITY_DIR; }
 export function getVersionsDir() { return VERSIONS_DIR; }
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
 export function getShimsDir() { return SHIMS_DIR; }
-/** Path to generated per-hook caching/timing shims (~/.agents/.cache/shims/hooks/). */
-export function getHookShimsDir() { return HOOK_SHIMS_DIR; }
-/** Path to per-hook stdout cache files (~/.agents/.cache/state/hooks/). */
-export function getHookCacheDir() { return HOOK_CACHE_DIR; }
+/**
+ * Path to generated per-hook caching/timing shims (~/.agents/.cache/shims/hooks/).
+ * Read at CALL time — since every hook now resolves through a shim (RUSH-2xxx,
+ * pass-through timing for matcher-only hooks), a test that registers hooks
+ * in-process (no subprocess HOME override) would otherwise write real shim
+ * files into the user's actual ~/.agents/.cache. AGENTS_HOOK_SHIMS_DIR mirrors
+ * the AGENTS_EVENTS_PATH / AGENTS_DEVICES_DIR test-isolation escape hatches;
+ * never set in production code.
+ */
+export function getHookShimsDir() {
+    return process.env.AGENTS_HOOK_SHIMS_DIR ?? HOOK_SHIMS_DIR;
+}
+/**
+ * Path to per-hook stdout cache files (~/.agents/.cache/state/hooks/). Read at
+ * CALL time for the same reason as {@link getHookShimsDir} — see its doc.
+ */
+export function getHookCacheDir() {
+    return process.env.AGENTS_HOOK_CACHE_DIR ?? HOOK_CACHE_DIR;
+}
 /** Path to per-agent installed CLI binaries (~/.agents/.cache/bin/). */
 export function getBinDir() { return BIN_DIR; }
 /** Path to config backups (~/.agents/.history/backups/). */
@@ -487,7 +515,9 @@ export function getTrashDir() { return TRASH_DIR; }
 /** Path to local session indexer storage (~/.agents/.history/sessions/). */
 export function getSessionsDir() { return SESSIONS_DIR; }
 /** Path to the session index database (~/.agents/.history/sessions/sessions.db). */
-export function getSessionsDbPath() { return SESSIONS_DB_PATH; }
+export function getSessionsDbPath() {
+    return process.env.AGENTS_SESSIONS_DB ?? SESSIONS_DB_PATH;
+}
 /** Path to teams config + registry (~/.agents/teams/). */
 export function getTeamsDir() { return TEAMS_DIR; }
 /** Path to teams execution history (~/.agents/.history/teams/agents/). */
@@ -517,17 +547,30 @@ export function getDevicesPendingDir() { return path.join(RUNTIME_STATE_DIR, 'de
 export function getCloudDir() { return CLOUD_DIR; }
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */
 export function getTerminalsDir() { return TERMINALS_DIR; }
-/** Path to runtime logs (~/.agents/.cache/logs/). */
-export function getLogsDir() { return LOGS_DIR; }
+/**
+ * Path to runtime logs (~/.agents/.cache/logs/). Read at CALL time so
+ * AGENTS_LOGS_DIR can redirect it in tests — same test-isolation escape hatch
+ * as {@link getHookShimsDir}; never set in production code.
+ */
+export function getLogsDir() {
+    return process.env.AGENTS_LOGS_DIR ?? LOGS_DIR;
+}
 /**
  * Path to disposable performance samples (~/.agents/.cache/perf/).
  * Holds `perf.db` + a hook-shim spool. Loss is acceptable — wipe freely.
+ * Read at CALL time: AGENTS_PERF_DIR (the same override perf/db.ts and
+ * perf/spool.ts already honor for their own internal resolution) redirects
+ * this canonical getter too, so a caller that goes through it directly
+ * (hooks/cache.ts's shim generator, the OpenCode timeout sample writer in
+ * hooks.ts) doesn't leak samples into the user's real perf warehouse either.
  */
-export function getPerfDir() { return PERF_DIR; }
+export function getPerfDir() {
+    return process.env.AGENTS_PERF_DIR ?? PERF_DIR;
+}
 /** Path to the perf SQLite warehouse (~/.agents/.cache/perf/perf.db). */
-export function getPerfDbPath() { return path.join(PERF_DIR, 'perf.db'); }
+export function getPerfDbPath() { return path.join(getPerfDir(), 'perf.db'); }
 /** Path to the hook-shim NDJSON spool drained into perf.db on open. */
-export function getPerfSpoolPath() { return path.join(PERF_DIR, 'spool.jsonl'); }
+export function getPerfSpoolPath() { return path.join(getPerfDir(), 'spool.jsonl'); }
 /** Path to per-process runtime state (~/.agents/.cache/state/). */
 export function getRuntimeStateDir() { return RUNTIME_STATE_DIR; }
 /** Path to companion-extension scratch (~/.agents/.cache/companion/). */

package/dist/lib/types.d.ts

@@ -284,6 +284,12 @@ export type HookCache = string | HookCacheConfig;
 export interface ManifestHook {
     script: string;
     events: string[];
+    /**
+     * Seconds before the hook is killed (default 600). In agents.yaml this may be
+     * written as a bare number (seconds) or a duration string (`5s`, `2m`,
+     * `1h30m`); `parseHookManifest` normalizes it to a seconds number here, so
+     * consumers always see a number.
+     */
     timeout?: number;
     matcher?: string;
     /** @deprecated Use the agent capability table; field is ignored. */
@@ -765,10 +771,14 @@ export interface Meta {
     /** Spend guardrails (issue #346). User-global caps; project agents.yaml overrides. */
     budget?: BudgetConfig;
     /**
-     * `agents feed post` fan-out. `broadcast` maps a sink name to the argv template
-     * run for each post, so mirroring to a tracker or a messaging CLI is the
-     * operator's config rather than an integration compiled into this CLI. See
-     * lib/feed-broadcast.ts and docs/06-observability.md.
+     * `agents feed post` fan-out. `broadcast` maps a sink name to either an argv
+     * template (`command:`, run for each post) or an in-process channel delivery
+     * (`channel:`, the same registry `agents send`/`agents notify` use), so
+     * mirroring to a tracker, a messaging CLI, or a channel provider is the
+     * operator's config rather than an integration compiled into this CLI. When
+     * this is unset/empty, an important-level post falls back to `notify.owner`
+     * implicitly (RUSH-2123) — see lib/feed-broadcast.ts and
+     * docs/06-observability.md.
      */
     feed?: {
         broadcast?: FeedBroadcastConfig;

package/dist/lib/usage-refresh.d.ts

@@ -0,0 +1,106 @@
+import { type UsageHeadroom, type UsageSnapshot, type UsageInfo } from './usage.js';
+import type { AgentId } from './types.js';
+/** Floor on the adaptive interval: an account seconds from its cap still isn't
+ * polled faster than this. */
+export declare const REFRESH_MIN_MS: number;
+/** Ceiling on the adaptive interval: an idle account is still re-checked at
+ * least this often so a cache never silently rots. */
+export declare const REFRESH_MAX_MS: number;
+/** Schedule the next refresh at `minutesToLimit / K` — poll well before the cap,
+ * not exactly at it. */
+export declare const REFRESH_BURN_DIVISOR = 4;
+/** At most this many live fetches per account per rolling hour. */
+export declare const HOURLY_CALL_CAP = 6;
+/**
+ * One account's refresh state + published headroom. `sessionUsedPercent` /
+ * `capturedAt` are the prior sample the NEXT tick projects the burn rate from;
+ * `minutesToLimit` / `status` are what the routing hot path reads.
+ */
+export interface HeadroomEntry {
+    status: UsageHeadroom['status'];
+    minutesToLimit: number | null;
+    /** The session window's usedPercent in the last snapshot (the prev sample). */
+    sessionUsedPercent: number | null;
+    /** Epoch ms the last snapshot was captured. */
+    capturedAt: number | null;
+    /** Epoch ms this account is next due for a live refresh. */
+    nextRefreshAt: number;
+    /** Epoch ms of recent live fetches, for the rolling-hour cap. */
+    callTimestamps: number[];
+    /** Epoch ms this entry was written. */
+    computedAt: number;
+}
+export declare function setHeadroomCachePathForTest(cachePath: string | null): string | null;
+/** Read the whole headroom cache (best-effort; missing/corrupt → empty map). */
+export declare function readHeadroomCache(): Record<string, HeadroomEntry>;
+/** Read one account's headroom entry, or null. */
+export declare function readHeadroomEntry(usageKey: string): HeadroomEntry | null;
+/** Merge entries into the cache (best-effort; preserves other accounts' rows). */
+export declare function writeHeadroomEntries(entries: Record<string, HeadroomEntry>): void;
+/**
+ * The adaptive interval until the next refresh, clamped to [MIN, MAX]. A
+ * shorter `minutesToLimit` (closer to the cap) polls sooner; `null` (unknown /
+ * idle / not burning) waits the full ceiling.
+ */
+export declare function computeNextRefreshDelayMs(minutesToLimit: number | null, opts?: {
+    minMs?: number;
+    maxMs?: number;
+    divisor?: number;
+}): number;
+/** Recent call timestamps trimmed to the trailing hour. */
+export declare function pruneCallTimestamps(timestamps: number[], now: number, windowMs?: number): number[];
+/**
+ * Whether an account may be live-refreshed right now: it is due (past its
+ * scheduled `nextRefreshAt`) AND under the rolling-hour call cap. Pure so the
+ * cadence + cap arithmetic is unit-tested without a daemon or a network call.
+ */
+export declare function shouldRefreshAccount(entry: HeadroomEntry | null | undefined, now: number, opts?: {
+    hourlyCap?: number;
+    windowMs?: number;
+}): boolean;
+/**
+ * Build the next headroom entry after a live refresh: project headroom from the
+ * new snapshot against the prior sample, schedule the next refresh from the
+ * projection, and record this call for the hourly cap.
+ */
+export declare function nextHeadroomEntry(prev: HeadroomEntry | null | undefined, snapshot: UsageSnapshot | null, now: number): HeadroomEntry;
+/** An account whose credentials live on THIS host — the only ones we refresh. */
+export interface LocalUsageAccount {
+    usageKey: string;
+    agentId: AgentId;
+    /** Live-fetch this account's usage; the daemon passes the real network fetch. */
+    fetch: () => Promise<UsageInfo>;
+}
+/**
+ * Enumerate the network-usage accounts whose credentials live on THIS host — one
+ * per unique usage key, deduped to the most-recently-active version (the same
+ * canonicalization `getUsageInfoByIdentity` uses). Each carries a closure that
+ * live-fetches its usage. This is the daemon's `listAccounts`; because it only
+ * ever lists local, signed-in accounts, each host is the sole writer for its own
+ * accounts' caches — no cross-host coordination.
+ */
+export declare function buildLocalUsageAccounts(): Promise<LocalUsageAccount[]>;
+/** Injectable side effects, so `runUsageRefresh` is drivable without the daemon. */
+export interface UsageRefreshDeps {
+    now?: number;
+    /** Local-credential accounts to consider (one per unique usage key). */
+    listAccounts: () => Promise<LocalUsageAccount[]>;
+    /** Persist a fresh snapshot to the usage cache (writeClaudeUsageCache). */
+    writeUsageCache: (usageKey: string, snapshot: UsageSnapshot) => void;
+    /** Epoch ms a provider is backed off until, or null when free (usageRateLimitedUntil). */
+    backoffUntil: (agentId: AgentId) => number | null;
+}
+export interface UsageRefreshResult {
+    refreshed: number;
+    skippedNotDue: number;
+    skippedBackoff: number;
+    skippedCap: number;
+    failed: number;
+}
+/**
+ * One refresher tick: for each local account that is due, under its hourly cap,
+ * and not provider-backed-off, live-fetch its usage, update the cache, and
+ * reschedule from the new burn projection. Never throws — a single account's
+ * failed fetch leaves its cache untouched and counts as `failed`.
+ */
+export declare function runUsageRefresh(deps: UsageRefreshDeps): Promise<UsageRefreshResult>;

package/dist/lib/usage-refresh.js

@@ -0,0 +1,238 @@
+/**
+ * Daemon-owned adaptive usage refresher.
+ *
+ * The routing hot path (`agents run` → collectRunCandidates) reads usage
+ * CACHE-ONLY (`getUsageInfoForIdentity` `readOnly`, RUSH-2061) and never blocks
+ * on a provider fetch. Something still has to keep that cache fresh — this
+ * module is that something, running inside the daemon.
+ *
+ * Design (per account, this host is the SOLE writer — the refresher only ever
+ * touches accounts whose credentials live locally, so no cross-host
+ * coordination and no shared-token contention):
+ *
+ *  - **Adaptive cadence from burn rate.** Each refresh stores the session
+ *    window's `usedPercent` + `capturedAt`. The next refresh is scheduled from
+ *    `deriveUsageHeadroom`'s projected `minutesToLimit`: an account racing
+ *    toward its cap is polled more often (down to 90s), an idle one rarely (up
+ *    to 15min). `computeNextRefreshDelayMs` is the pure clamp.
+ *  - **Hard hourly cap.** Regardless of cadence, at most `HOURLY_CALL_CAP` live
+ *    fetches per account per rolling hour, so a fast burn can't turn the 90s
+ *    floor into a hammering loop.
+ *  - **Respects the existing 429 backoff.** A provider under
+ *    `usageRateLimitedUntil` is skipped entirely — the whole point of the
+ *    backoff is to stop poking an endpoint that just said no.
+ *
+ * It also publishes the projected headroom (`minutesToLimit` + status) to a
+ * small cache keyed by usage key, so the routing hot path can deprioritize an
+ * account projected to cap without recomputing a burn rate it has no prior
+ * sample for. `fleet-cache.ts` is the sync reader.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from './state.js';
+import { deriveUsageHeadroom, getUsageInfo, buildCanonicalUsageContext, agentUsesNetworkUsage, USAGE_SOURCE_AGENT_IDS, } from './usage.js';
+import { getAccountInfo } from './agents.js';
+import { listInstalledVersions, getVersionHomePath } from './versions.js';
+/** Floor on the adaptive interval: an account seconds from its cap still isn't
+ * polled faster than this. */
+export const REFRESH_MIN_MS = 90 * 1000;
+/** Ceiling on the adaptive interval: an idle account is still re-checked at
+ * least this often so a cache never silently rots. */
+export const REFRESH_MAX_MS = 15 * 60 * 1000;
+/** Schedule the next refresh at `minutesToLimit / K` — poll well before the cap,
+ * not exactly at it. */
+export const REFRESH_BURN_DIVISOR = 4;
+/** At most this many live fetches per account per rolling hour. */
+export const HOURLY_CALL_CAP = 6;
+const HOUR_MS = 60 * 60 * 1000;
+/** Test seam for the headroom cache path (see usage.ts `setClaudeUsageCachePathForTest`). */
+let headroomCachePathOverride = null;
+export function setHeadroomCachePathForTest(cachePath) {
+    const prev = headroomCachePathOverride;
+    headroomCachePathOverride = cachePath;
+    return prev;
+}
+function headroomCachePath() {
+    return headroomCachePathOverride ?? path.join(getCacheDir(), '.usage-headroom.json');
+}
+/** Read the whole headroom cache (best-effort; missing/corrupt → empty map). */
+export function readHeadroomCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(headroomCachePath(), 'utf-8'));
+        if (parsed && parsed.entries && typeof parsed.entries === 'object')
+            return parsed.entries;
+    }
+    catch {
+        // missing or corrupt — treat as empty
+    }
+    return {};
+}
+/** Read one account's headroom entry, or null. */
+export function readHeadroomEntry(usageKey) {
+    return readHeadroomCache()[usageKey] ?? null;
+}
+/** Merge entries into the cache (best-effort; preserves other accounts' rows). */
+export function writeHeadroomEntries(entries) {
+    try {
+        const dir = getCacheDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const merged = {
+            version: 1,
+            entries: { ...readHeadroomCache(), ...entries },
+        };
+        fs.writeFileSync(headroomCachePath(), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // best-effort; a failed write just means the router sees no projection
+    }
+}
+/**
+ * The adaptive interval until the next refresh, clamped to [MIN, MAX]. A
+ * shorter `minutesToLimit` (closer to the cap) polls sooner; `null` (unknown /
+ * idle / not burning) waits the full ceiling.
+ */
+export function computeNextRefreshDelayMs(minutesToLimit, opts = {}) {
+    const minMs = opts.minMs ?? REFRESH_MIN_MS;
+    const maxMs = opts.maxMs ?? REFRESH_MAX_MS;
+    const divisor = opts.divisor ?? REFRESH_BURN_DIVISOR;
+    if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
+        return maxMs;
+    const targetMs = (minutesToLimit / divisor) * 60_000;
+    return Math.max(minMs, Math.min(maxMs, targetMs));
+}
+/** Recent call timestamps trimmed to the trailing hour. */
+export function pruneCallTimestamps(timestamps, now, windowMs = HOUR_MS) {
+    const floor = now - windowMs;
+    return timestamps.filter((ts) => ts > floor);
+}
+/**
+ * Whether an account may be live-refreshed right now: it is due (past its
+ * scheduled `nextRefreshAt`) AND under the rolling-hour call cap. Pure so the
+ * cadence + cap arithmetic is unit-tested without a daemon or a network call.
+ */
+export function shouldRefreshAccount(entry, now, opts = {}) {
+    const cap = opts.hourlyCap ?? HOURLY_CALL_CAP;
+    const windowMs = opts.windowMs ?? HOUR_MS;
+    const due = !entry || now >= entry.nextRefreshAt;
+    if (!due)
+        return false;
+    const recent = pruneCallTimestamps(entry?.callTimestamps ?? [], now, windowMs);
+    return recent.length < cap;
+}
+/**
+ * Build the next headroom entry after a live refresh: project headroom from the
+ * new snapshot against the prior sample, schedule the next refresh from the
+ * projection, and record this call for the hourly cap.
+ */
+export function nextHeadroomEntry(prev, snapshot, now) {
+    const headroom = deriveUsageHeadroom(snapshot, prev && prev.capturedAt !== null && prev.sessionUsedPercent !== null
+        ? { capturedAt: prev.capturedAt, usedPercent: prev.sessionUsedPercent }
+        : null);
+    const session = snapshot?.windows.find((window) => window.key === 'session') ?? null;
+    const callTimestamps = pruneCallTimestamps([...(prev?.callTimestamps ?? []), now], now);
+    return {
+        status: headroom.status,
+        minutesToLimit: headroom.minutesToLimit,
+        sessionUsedPercent: session?.usedPercent ?? null,
+        capturedAt: snapshot?.capturedAt?.getTime() ?? null,
+        nextRefreshAt: now + computeNextRefreshDelayMs(headroom.minutesToLimit),
+        callTimestamps,
+        computedAt: now,
+    };
+}
+/**
+ * Enumerate the network-usage accounts whose credentials live on THIS host — one
+ * per unique usage key, deduped to the most-recently-active version (the same
+ * canonicalization `getUsageInfoByIdentity` uses). Each carries a closure that
+ * live-fetches its usage. This is the daemon's `listAccounts`; because it only
+ * ever lists local, signed-in accounts, each host is the sole writer for its own
+ * accounts' caches — no cross-host coordination.
+ */
+export async function buildLocalUsageAccounts() {
+    const accounts = [];
+    for (const agentId of USAGE_SOURCE_AGENT_IDS) {
+        if (!agentUsesNetworkUsage(agentId))
+            continue;
+        const versions = listInstalledVersions(agentId);
+        if (versions.length === 0)
+            continue;
+        const inputs = await Promise.all(versions.map(async (version) => {
+            const home = getVersionHomePath(agentId, version);
+            return { agentId, info: await getAccountInfo(agentId, home), home, cliVersion: version };
+        }));
+        const { canonicalByUsageKey, usageFetchInputs } = buildCanonicalUsageContext(inputs);
+        for (const [usageKey, fetchInput] of usageFetchInputs) {
+            const canonical = canonicalByUsageKey.get(usageKey);
+            if (!canonical?.signedIn)
+                continue; // only refresh accounts actually usable here
+            accounts.push({
+                usageKey,
+                agentId,
+                fetch: () => getUsageInfo(agentId, {
+                    home: fetchInput.home,
+                    cliVersion: fetchInput.cliVersion,
+                    organizationId: fetchInput.organizationId,
+                }),
+            });
+        }
+    }
+    return accounts;
+}
+/**
+ * One refresher tick: for each local account that is due, under its hourly cap,
+ * and not provider-backed-off, live-fetch its usage, update the cache, and
+ * reschedule from the new burn projection. Never throws — a single account's
+ * failed fetch leaves its cache untouched and counts as `failed`.
+ */
+export async function runUsageRefresh(deps) {
+    const now = deps.now ?? Date.now();
+    const result = {
+        refreshed: 0,
+        skippedNotDue: 0,
+        skippedBackoff: 0,
+        skippedCap: 0,
+        failed: 0,
+    };
+    const accounts = await deps.listAccounts();
+    const cache = readHeadroomCache();
+    const updates = {};
+    for (const account of accounts) {
+        const entry = cache[account.usageKey] ?? null;
+        // A provider under a 429 penalty is off-limits — poking it re-arms the
+        // penalty (the whole reason usage-backoff exists).
+        if ((deps.backoffUntil(account.agentId) ?? 0) > now) {
+            result.skippedBackoff += 1;
+            continue;
+        }
+        if (!shouldRefreshAccount(entry, now)) {
+            if (entry && now < entry.nextRefreshAt)
+                result.skippedNotDue += 1;
+            else
+                result.skippedCap += 1;
+            continue;
+        }
+        try {
+            const usage = await account.fetch();
+            if (usage.snapshot?.source === 'live') {
+                deps.writeUsageCache(account.usageKey, usage.snapshot);
+                updates[account.usageKey] = nextHeadroomEntry(entry, usage.snapshot, now);
+                result.refreshed += 1;
+            }
+            else {
+                // No live snapshot (expired token / fetch miss): don't rewrite the usage
+                // cache, but still record the call + reschedule so a broken account
+                // isn't retried every tick.
+                updates[account.usageKey] = nextHeadroomEntry(entry, null, now);
+                result.failed += 1;
+            }
+        }
+        catch {
+            updates[account.usageKey] = nextHeadroomEntry(entry, null, now);
+            result.failed += 1;
+        }
+    }
+    if (Object.keys(updates).length > 0)
+        writeHeadroomEntries(updates);
+    return result;
+}