@phnx-labs/agents-cli 1.21.1 → 1.21.3

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

@@ -17,12 +17,32 @@ export interface SkillUse {
     count: number;
 }
 /**
- * Skills invoked during the session, from `Skill` tool calls. Claude and Kimi
- * both name the tool `Skill` and carry the skill id in `args.skill` (plugin
- * skills surface here too — a plugin-provided skill is invoked through the
- * same tool). Sorted by count desc, then name.
+ * True for a tool_use event that is that harness's skill-invocation call (see
+ * {@link SKILL_TOOL_NAME_BY_AGENT}). Exported so an INCREMENTAL parser
+ * (discover.ts's ClaudeParseState/foldDerivedToolState) can select matching
+ * events into a small held array as it streams, then run {@link extractSkills}
+ * over just that subset at finalize — without re-parsing the whole transcript.
+ */
+export declare function isSkillInvocation(e: SessionEvent): boolean;
+/**
+ * Skills invoked during the session, from that harness's skill-invocation
+ * tool calls (see {@link SKILL_TOOL_NAME_BY_AGENT}). Carries the skill id in
+ * `args.skill` (or `args.name`). Sorted by count desc, then name.
  */
 export declare function extractSkills(events: SessionEvent[]): SkillUse[];
+export interface SlashCommandUse {
+    /** WITH the leading slash, e.g. `/recap`, `/code:commit` — matches SessionEvent.slashCommand's shape. */
+    name: string;
+    count: number;
+}
+/**
+ * Slash commands invoked during the session — either the user typing one
+ * (Claude's `<command-name>` wrapper) or the model invoking one via the
+ * `SlashCommand` tool (`SessionEvent.slashCommand`, populated by
+ * `parseClaudeContent` for both sources — see session/prompt.ts). Sorted by
+ * count desc, then name.
+ */
+export declare function extractSlashCommands(events: SessionEvent[]): SlashCommandUse[];
 export interface HookUse {
     /** Hook name as configured, e.g. `SessionStart:startup`. */
     name: string;

package/dist/lib/session/highlights.js

@@ -15,17 +15,44 @@ import os from 'node:os';
 import path from 'node:path';
 import { isNoisePath } from './digest.js';
 /**
- * Skills invoked during the session, from `Skill` tool calls. Claude and Kimi
- * both name the tool `Skill` and carry the skill id in `args.skill` (plugin
- * skills surface here too — a plugin-provided skill is invoked through the
- * same tool). Sorted by count desc, then name.
+ * The tool name a harness uses to invoke a skill, keyed by `SessionAgentId` —
+ * a registry, not a single hardcoded string, so a harness whose transcript
+ * names the tool differently is one table row away from support instead of a
+ * near-identical `if` arm (see CLAUDE.md's registry-over-if-chain convention).
+ *
+ * Verified entries only: Claude and Kimi both empirically name the tool
+ * `Skill` (a plugin-provided skill rides the same tool). No other harness has
+ * a confirmed skill-invocation tool name in this codebase's fixtures — an
+ * absent entry means "we don't know yet", not "this harness has no skills";
+ * extractSkills yields `[]` for it rather than guessing a name and silently
+ * mismatching (or worse, matching a coincidental tool with the same name).
+ */
+const SKILL_TOOL_NAME_BY_AGENT = {
+    claude: 'Skill',
+    kimi: 'Skill',
+};
+/**
+ * True for a tool_use event that is that harness's skill-invocation call (see
+ * {@link SKILL_TOOL_NAME_BY_AGENT}). Exported so an INCREMENTAL parser
+ * (discover.ts's ClaudeParseState/foldDerivedToolState) can select matching
+ * events into a small held array as it streams, then run {@link extractSkills}
+ * over just that subset at finalize — without re-parsing the whole transcript.
+ */
+export function isSkillInvocation(e) {
+    if (e.type !== 'tool_use' || e._local)
+        return false;
+    const skillTool = SKILL_TOOL_NAME_BY_AGENT[e.agent];
+    return !!skillTool && e.tool === skillTool;
+}
+/**
+ * Skills invoked during the session, from that harness's skill-invocation
+ * tool calls (see {@link SKILL_TOOL_NAME_BY_AGENT}). Carries the skill id in
+ * `args.skill` (or `args.name`). Sorted by count desc, then name.
  */
 export function extractSkills(events) {
     const counts = new Map();
     for (const e of events) {
-        if (e.type !== 'tool_use' || e._local)
-            continue;
-        if (e.tool !== 'Skill')
+        if (!isSkillInvocation(e))
             continue;
         const name = e.args?.skill ?? e.args?.name;
         if (typeof name !== 'string' || !name.trim())
@@ -37,6 +64,24 @@ export function extractSkills(events) {
         .map(([name, count]) => ({ name, count }))
         .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
 }
+/**
+ * Slash commands invoked during the session — either the user typing one
+ * (Claude's `<command-name>` wrapper) or the model invoking one via the
+ * `SlashCommand` tool (`SessionEvent.slashCommand`, populated by
+ * `parseClaudeContent` for both sources — see session/prompt.ts). Sorted by
+ * count desc, then name.
+ */
+export function extractSlashCommands(events) {
+    const counts = new Map();
+    for (const e of events) {
+        if (!e.slashCommand)
+            continue;
+        counts.set(e.slashCommand, (counts.get(e.slashCommand) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([name, count]) => ({ name, count }))
+        .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
 /**
  * Hooks that fired during the session, folded from `hook` events (parsed from
  * Claude's `hook_success`/`hook_error`/… attachment records; other harnesses

package/dist/lib/session/parse.js

@@ -9,7 +9,7 @@ import * as fs from 'fs';
 import { truncate } from '../format.js';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { isSyntheticUserMessage } from './prompt.js';
+import { isSyntheticUserMessage, extractSlashCommandName, extractSlashCommandFromToolInput } from './prompt.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
  * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
@@ -379,6 +379,14 @@ export function parseClaudeContent(content) {
                     };
                     if (isLocal)
                         event._local = true;
+                    // SlashCommand: the MODEL invoking a slash command programmatically
+                    // (distinct from the <command-name> wrapper below, which is the
+                    // USER typing one) — see prompt.ts's extractSlashCommandFromToolInput.
+                    if (toolName === 'SlashCommand') {
+                        const slashCommand = extractSlashCommandFromToolInput(toolInput);
+                        if (slashCommand)
+                            event.slashCommand = slashCommand;
+                    }
                     events.push(event);
                 }
             }
@@ -403,13 +411,21 @@ export function parseClaudeContent(content) {
                 // Simple user text
                 const text = contentBlocks.trim();
                 if (text) {
-                    events.push({
+                    const event = {
                         type: 'message',
                         agent: 'claude',
                         timestamp,
                         role: 'user',
                         content: text,
-                    });
+                    };
+                    // The USER typing a slash command — Claude injects a <command-name>
+                    // wrapper as the message content (see prompt.ts's
+                    // extractSlashCommandName; distinct from the SlashCommand tool-use
+                    // above, which is the model invoking one programmatically).
+                    const slashCommand = extractSlashCommandName(text);
+                    if (slashCommand)
+                        event.slashCommand = slashCommand;
+                    events.push(event);
                 }
             }
             else if (Array.isArray(contentBlocks)) {

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

@@ -12,6 +12,25 @@
  * own scaffolding at parse time simply never reach here.
  */
 export declare function isSyntheticUserMessage(raw: string | undefined): boolean;
+/**
+ * Extract the invoked slash-command name from a raw `role=user` message, or
+ * undefined when the message carries no `<command-name>` wrapper. Used by
+ * `parseClaudeContent` to populate `SessionEvent.slashCommand`.
+ *
+ * Normalizes a leading `/` onto the result: current Claude Code wraps the
+ * name WITH the slash already (`/recap`), but the wrapper predates that and
+ * older transcripts carry the bare name (`recap`) — normalizing here means
+ * every consumer sees one consistent `/name` shape regardless of vintage.
+ */
+export declare function extractSlashCommandName(raw: string | undefined): string | undefined;
+/**
+ * Extract the invoked slash-command name from the `SlashCommand` tool's input
+ * — the MODEL invoking a command programmatically, not the user typing it.
+ * The tool's `command` field carries the full invocation text (name plus any
+ * args, e.g. `/code:commit fix the bug`); only the leading command token is
+ * the name, matching {@link extractSlashCommandName}'s shape.
+ */
+export declare function extractSlashCommandFromToolInput(toolInput: Record<string, any> | undefined): string | undefined;
 export declare const HEADLESS_PLAN_MODE_PREFIX = "You are running in HEADLESS PLAN MODE.";
 /** Strip framework noise from a raw session prompt, returning only meaningful user text. */
 export declare function cleanSessionPrompt(raw: string): string;

package/dist/lib/session/prompt.js

@@ -63,6 +63,49 @@ export function isSyntheticUserMessage(raw) {
         return false;
     return SYNTHETIC_USER_MESSAGE_PATTERNS.some(pattern => pattern.test(raw));
 }
+/**
+ * The `<command-name>` wrapper Claude injects into a `role=user` message when
+ * a typed slash command is invoked, e.g.:
+ *   <command-message>recap</command-message>
+ *   <command-name>/recap</command-name>
+ * Captures the name INCLUDING its leading slash (`/recap`), matching how the
+ * `SlashCommand` tool's own `command` input is formatted (see
+ * `extractSlashCommandFromToolInput`) so both sources land on the same shape.
+ */
+const COMMAND_NAME_WRAPPER_RE = /<command-name>\s*([^<]*?)\s*<\/command-name>/i;
+/**
+ * Extract the invoked slash-command name from a raw `role=user` message, or
+ * undefined when the message carries no `<command-name>` wrapper. Used by
+ * `parseClaudeContent` to populate `SessionEvent.slashCommand`.
+ *
+ * Normalizes a leading `/` onto the result: current Claude Code wraps the
+ * name WITH the slash already (`/recap`), but the wrapper predates that and
+ * older transcripts carry the bare name (`recap`) — normalizing here means
+ * every consumer sees one consistent `/name` shape regardless of vintage.
+ */
+export function extractSlashCommandName(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.match(COMMAND_NAME_WRAPPER_RE);
+    const name = m?.[1]?.trim();
+    if (!name)
+        return undefined;
+    return name.startsWith('/') ? name : `/${name}`;
+}
+/**
+ * Extract the invoked slash-command name from the `SlashCommand` tool's input
+ * — the MODEL invoking a command programmatically, not the user typing it.
+ * The tool's `command` field carries the full invocation text (name plus any
+ * args, e.g. `/code:commit fix the bug`); only the leading command token is
+ * the name, matching {@link extractSlashCommandName}'s shape.
+ */
+export function extractSlashCommandFromToolInput(toolInput) {
+    const command = toolInput?.command;
+    if (typeof command !== 'string')
+        return undefined;
+    const name = command.trim().split(/\s+/)[0];
+    return name || undefined;
+}
 // Prefix prepended to every Claude-in-plan-mode team spawn prompt.
 // Ends at a blank line before the real user task.
 export const HEADLESS_PLAN_MODE_PREFIX = 'You are running in HEADLESS PLAN MODE.';

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

@@ -52,6 +52,15 @@ export interface SessionEvent {
     hookName?: string;
     /** Lifecycle event the hook fired on (SessionStart, PreToolUse, …). */
     hookEvent?: string;
+    /**
+     * Slash-command invocation name (e.g. `/recap`, `/code:commit`), captured
+     * two ways in a Claude transcript: a `role=user` message whose content is
+     * the `<command-name>` wrapper Claude injects for a typed slash command
+     * (`parseClaudeContent`, see `prompt.ts`'s `extractSlashCommandName`), or a
+     * `tool_use` event for the `SlashCommand` tool (a command the MODEL invoked
+     * programmatically, not the user). Undefined for every other event.
+     */
+    slashCommand?: string;
 }
 /** A displayable file attachment discovered in a session transcript. */
 export interface SessionAttachment {
@@ -132,6 +141,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;
@@ -185,6 +195,39 @@ export interface SessionMeta {
     todos?: TodoProgress;
     /** Most-recent unique directories changed or used as a shell working directory. */
     recentDirectoriesTouched?: string[];
+    /**
+     * Skills invoked during the session (structurally identical to
+     * session/highlights.ts's SkillUse — declared inline here rather than
+     * imported, to avoid a circular import: highlights.ts imports SessionEvent
+     * from this file). Populated by discover.ts's incremental Claude
+     * accumulator (ClaudeParseState.skillEvents, run through extractSkills at
+     * finalize) so session/db.ts's upsertSessionsBatch can write
+     * session_resource_usage rows WITHOUT re-parsing the whole transcript —
+     * the same reason meta.todos/recentDirectoriesTouched are pre-computed by
+     * the caller for claude/codex instead of left to db.ts's re-parse path.
+     */
+    skillsUsed?: Array<{
+        name: string;
+        count: number;
+    }>;
+    /** Sibling of {@link skillsUsed} for slash-command invocations (SessionEvent.slashCommand). */
+    slashCommandsUsed?: Array<{
+        name: string;
+        count: number;
+    }>;
+    /**
+     * Whether this session emitted at least one `browser.navigate` /
+     * `browser.screenshot` event, computed at scan time from a sessionId-scoped
+     * read of the events log (events.ts `query({ sessionId })`) rather than a
+     * transcript re-scan — see `detectToolUsage` in session/db.ts. `undefined`
+     * means a legacy row this scanner hasn't computed the field for yet (never
+     * collapsed to `false`, so a consumer — e.g. sessions-picker.ts's
+     * `classifySessionTool` — knows to fall back to a transcript-derived guess
+     * instead of trusting a false negative).
+     */
+    usedBrowser?: boolean;
+    /** Sibling of {@link usedBrowser} for `computer.action` events. */
+    usedComputer?: boolean;
     /** Linear project containing ticketId, resolved lazily and cached in SQLite. */
     linearProject?: string;
     /** Browser URL for linearProject. */

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

@@ -605,6 +605,20 @@ export interface DiscoveredPlugin {
      * (e.g. workflow-scoped) — those default to the user marketplace on sync.
      */
     marketplace?: string;
+    /**
+     * Absolute path to the DotAgents repo root containing this plugin — the
+     * grandparent of `root` (`<repo>/plugins/<name>` → `<repo>`), true for every
+     * marketplace kind (user/system/extra/project). DotAgents repos are
+     * git-tracked (plugins.ts), so this pairs with {@link snapshotSha}.
+     */
+    repoRoot: string;
+    /**
+     * Short HEAD sha of `repoRoot`'s git checkout, lazily resolved (a getter,
+     * not computed at discovery time) and memoized per repoRoot
+     * (`git.ts` `resolveSnapshotSha`) — see `ResolvedResource.snapshotSha` for
+     * the identical rationale. `undefined` when `repoRoot` isn't a git repo.
+     */
+    readonly snapshotSha: string | undefined;
 }
 /**
  * Identifies one DotAgents repo that contributes a plugin marketplace. Each
@@ -771,10 +785,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>;