@phnx-labs/agents-cli 1.20.0 → 1.20.4

package/dist/lib/teams/agents.js

@@ -19,6 +19,7 @@ import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
 import { getAgentsDir as getSystemAgentsDir } from '../state.js';
 import { AGENTS } from '../agents.js';
+import { sanitizeProcessEnv } from '../secrets/bundles.js';
 let lastMemoryWarnAt = 0;
 // On macOS, os.freemem() returns only the truly-free pool and ignores the
 // large inactive+purgeable cache the kernel will reclaim under pressure, so
@@ -183,12 +184,17 @@ When you're done, provide a brief summary of:
 const CLAUDE_PLAN_MODE_PREFIX = `You are running in HEADLESS PLAN MODE. This mode works like normal plan mode with one exception: you cannot write to ~/.claude/plans/ directory. Instead of writing a plan file, output your complete plan/response as your final message.
 
 `;
-const VALID_MODES = ['plan', 'edit', 'full', 'auto'];
+// Canonical modes plus the historical `full` alias (rewritten to `skip` by
+// normalizeModeValue). Keep `full` listed so user-typed CLI flags and stored
+// metadata that pre-date the rename continue to parse.
+export const VALID_MODES = ['plan', 'edit', 'auto', 'skip', 'full'];
 function normalizeModeValue(modeValue) {
     if (!modeValue)
         return null;
     const normalized = modeValue.trim().toLowerCase();
-    if (VALID_MODES.includes(normalized)) {
+    if (normalized === 'full')
+        return 'skip';
+    if (['plan', 'edit', 'auto', 'skip'].includes(normalized)) {
         return normalized;
     }
     return null;
@@ -201,7 +207,7 @@ function defaultModeFromEnv() {
             return parsed;
         }
         if (rawValue) {
-            console.warn(`Invalid ${envVar}='${rawValue}'. Use 'plan' or 'edit'. Falling back to plan mode.`);
+            console.warn(`Invalid ${envVar}='${rawValue}'. Use plan, edit, auto, or skip. Falling back to plan mode.`);
         }
     }
     return 'plan';
@@ -253,12 +259,12 @@ function extractTimestamp(raw) {
 export function resolveMode(requestedMode, defaultMode = 'plan') {
     const normalizedDefault = normalizeModeValue(defaultMode);
     if (!normalizedDefault) {
-        throw new Error(`Invalid default mode '${defaultMode}'. Use 'plan' or 'edit'.`);
+        throw new Error(`Invalid default mode '${defaultMode}'. Use plan, edit, auto, or skip.`);
     }
     if (requestedMode !== null && requestedMode !== undefined) {
         const normalizedMode = normalizeModeValue(requestedMode);
         if (!normalizedMode) {
-            throw new Error(`Invalid mode '${requestedMode}'. Valid modes: 'plan' (read-only) or 'edit' (can write).`);
+            throw new Error(`Invalid mode '${requestedMode}'. Valid modes: plan (read-only), edit (can write), auto (smart classifier), skip (bypass all permissions). 'full' is accepted as alias for skip.`);
         }
         return normalizedMode;
     }
@@ -363,6 +369,11 @@ export class AgentProcess {
     // Pinned model for this teammate. When null, the agent's CLI picks its
     // own default (no --model forwarded).
     model = null;
+    // Profile target name when the teammate was added via `agents teams add
+    // <team> <profile>`. The launcher targets the profile name so env/keychain
+    // injection happens; agentType stays the underlying harness so event
+    // parsers and CLI availability checks keep working.
+    profileName = null;
     // Extra env vars passed through to the child process (from --env KEY=VALUE).
     envOverrides = null;
     // Factory task-type label. Drives planner fan-out. Null for plain teammates — no behavioral change.
@@ -378,13 +389,14 @@ export class AgentProcess {
     eventsCache = [];
     lastReadPos = 0;
     baseDir = null;
-    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null, cloudSessionId = null, cloudProvider = null, prUrl = null, version = null, remoteSessionId = null, name = null, after = [], effort = null, model = null, envOverrides = null, taskType = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
+    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null, cloudSessionId = null, cloudProvider = null, prUrl = null, version = null, remoteSessionId = null, name = null, after = [], effort = null, model = null, envOverrides = null, taskType = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
         this.agentId = agentId;
         this.remoteSessionId = remoteSessionId;
         this.name = name;
         this.after = after;
         this.effort = effort;
         this.model = model;
+        this.profileName = profileName;
         this.envOverrides = envOverrides;
         this.taskType = taskType;
         this.cloudRepo = cloudRepo;
@@ -409,7 +421,9 @@ export class AgentProcess {
         this.version = version;
     }
     get isEditMode() {
-        return this.mode === 'edit' || this.mode === 'full';
+        // Any mode that can mutate the workspace counts as "edit mode" for the
+        // purposes of guarding read-only flows (plan-mode teammates).
+        return this.mode === 'edit' || this.mode === 'auto' || this.mode === 'skip';
     }
     async getAgentDir() {
         const base = this.baseDir || await getAgentsDir();
@@ -466,6 +480,7 @@ export class AgentProcess {
             after: this.after,
             effort: this.effort,
             model: this.model,
+            profile_name: this.profileName,
             env_overrides: this.envOverrides,
             task_type: this.taskType,
             cloud_repo: this.cloudRepo,
@@ -596,6 +611,7 @@ export class AgentProcess {
             after: this.after,
             effort: this.effort,
             model: this.model,
+            profile_name: this.profileName,
             env_overrides: this.envOverrides,
             task_type: this.taskType,
             cloud_repo: this.cloudRepo,
@@ -619,12 +635,16 @@ export class AgentProcess {
         try {
             const metaContent = await fs.readFile(metaPath, 'utf-8');
             const meta = JSON.parse(metaContent);
-            // Legacy teammates may have mode='ralph' or 'cloud' from before modes
-            // were narrowed. Coerce to the closest current mode so they still load.
+            // Legacy teammates may have mode='ralph', 'cloud', or 'full' from before
+            // modes were narrowed/renamed. Coerce to the closest current mode so they
+            // still load.
             const modeMap = {
+                plan: 'plan',
                 edit: 'edit',
-                full: 'full',
-                ralph: 'full', // ralph used the same "no-permission" flags as full
+                auto: 'auto',
+                skip: 'skip',
+                full: 'skip', // historical alias — `full` is the old name for `skip`
+                ralph: 'skip', // ralph used the same "no-permission" flags as full
                 cloud: 'edit', // cloud teammates had edit-level write access
             };
             const resolvedMode = modeMap[meta.mode] || 'plan';
@@ -637,7 +657,7 @@ export class AgentProcess {
                 : AgentStatus.RUNNING;
             const agent = new AgentProcess(meta.agent_id, meta.task_name || 'default', meta.agent_type, meta.prompt, meta.cwd || null, resolvedMode, meta.pid || null, resolvedStatus, new Date(meta.started_at), meta.completed_at ? new Date(meta.completed_at) : null, baseDir, meta.parent_session_id || null, meta.workspace_dir || null, meta.cloud_session_id || null, meta.cloud_provider || null, meta.pr_url || null, meta.version || null, meta.remote_session_id || null, meta.name || null, Array.isArray(meta.after) ? meta.after : [], meta.effort || null, meta.model || null, meta.env_overrides || null, meta.task_type && VALID_TASK_TYPES.includes(meta.task_type)
                 ? meta.task_type
-                : null, meta.cloud_repo || null, meta.cloud_branch || null, meta.worktree_name || null, meta.worktree_path || null);
+                : null, meta.cloud_repo || null, meta.cloud_branch || null, meta.worktree_name || null, meta.worktree_path || null, meta.profile_name || null);
             agent.startTime = typeof meta.start_time === 'string' ? meta.start_time : null;
             return agent;
         }
@@ -759,7 +779,7 @@ export class AgentManager {
         this.cleanupAgeDays = cleanupAgeDays;
         const resolvedDefaultMode = defaultMode ? normalizeModeValue(defaultMode) : defaultModeFromEnv();
         if (!resolvedDefaultMode) {
-            throw new Error(`Invalid default_mode '${defaultMode}'. Use 'plan' or 'edit'.`);
+            throw new Error(`Invalid default_mode '${defaultMode}'. Use plan, edit, auto, or skip.`);
         }
         this.defaultMode = resolvedDefaultMode;
         this.initPromise = this.doInitialize();
@@ -875,7 +895,7 @@ export class AgentManager {
         }
         debug(`Loaded ${loadedCount} agents from disk`);
     }
-    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
+    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
         await this.initialize();
         const resolvedMode = resolveMode(mode, this.defaultMode);
         // Enforce: teammate names are unique within a team.
@@ -922,6 +942,9 @@ export class AgentManager {
         // dispatched via the cloud provider and passed us the provider + session.
         const isCloudBacked = Boolean(cloudProvider);
         if (!isCloudBacked) {
+            // Profile-backed teammates still spawn through `agents run`, which
+            // resolves the profile to its host harness — so the CLI we need to be
+            // present is the underlying agentType, not the profile name.
             const [available, pathOrError] = checkCliAvailable(agentType);
             if (!available) {
                 throw new Error(pathOrError || 'CLI tool not available');
@@ -934,7 +957,7 @@ export class AgentManager {
         const initialStatus = isStaged || !isCloudBacked
             ? AgentStatus.PENDING
             : AgentStatus.RUNNING;
-        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, initialStatus, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, cloudSessionId, cloudProvider, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null, taskType, cloudRepo, cloudBranch, worktreeName, worktreePath);
+        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, initialStatus, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, cloudSessionId, cloudProvider, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null, taskType, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName);
         const agentDir = await agent.getAgentDir();
         try {
             await fs.mkdir(agentDir, { recursive: true });
@@ -971,7 +994,7 @@ export class AgentManager {
         // forwarded). Effort is a separate knob wired into buildReasoningFlags
         // inside buildCommand.
         const resolvedModel = agent.model ?? null;
-        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version);
+        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName);
         debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]: ${cmd.slice(0, 3).join(' ')}...`);
         try {
             const stdoutPath = await agent.getStdoutPath();
@@ -982,8 +1005,8 @@ export class AgentManager {
                 cwd: agent.cwd || undefined,
                 detached: true,
                 env: agent.envOverrides
-                    ? { ...process.env, ...agent.envOverrides }
-                    : process.env,
+                    ? { ...sanitizeProcessEnv(process.env), ...agent.envOverrides }
+                    : sanitizeProcessEnv(process.env),
             });
             childProcess.unref();
             stdoutFile.close().catch(() => { });
@@ -1055,15 +1078,18 @@ export class AgentManager {
      * exec path (src/lib/exec.ts). The team runner just supplies prompt + mode
      * and reads stream-json events off stdout.
      */
-    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null) {
+    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null) {
         // Compose the prompt: a plan-mode prefix for Claude (clarifying headless
         // plan-mode restrictions) and a universal summary suffix. These are
         // team-specific prompt scaffolding — `agents run` does not apply them.
         let fullPrompt = prompt + PROMPT_SUFFIX;
-        if (agentType === 'claude' && mode !== 'edit') {
+        if (agentType === 'claude' && mode === 'plan') {
             fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
         }
-        const target = version ? `${agentType}@${version}` : agentType;
+        // Profile target takes precedence — `agents run <profile>` resolves the
+        // host harness, version pin, and env injection in one place. Plain
+        // version pins only apply when no profile is selected.
+        const target = profileName ?? (version ? `${agentType}@${version}` : agentType);
         const agentsCli = process.argv[1];
         const cmd = [
             process.execPath,

package/dist/lib/teams/api.d.ts

@@ -13,6 +13,7 @@ export interface SpawnResult {
     status: string;
     started_at: string;
     version?: string | null;
+    profile_name?: string | null;
     remote_session_id?: string | null;
     name?: string | null;
     after?: string[];
@@ -88,7 +89,7 @@ export interface TasksResult {
     tasks: TaskInfo[];
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null): Promise<SpawnResult>;
+export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null): Promise<SpawnResult>;
 /** Retrieve the current status of all teammates in a task, with optional timestamp-based delta filtering. */
 export declare function handleStatus(manager: AgentManager, taskName: string | null | undefined, filter?: string, since?: string, // Optional ISO timestamp - return only events after this time
 parentSessionId?: string | null): Promise<TaskStatusResult>;

package/dist/lib/teams/api.js

@@ -56,12 +56,12 @@ function recentToolCalls(events, max = 10) {
     }));
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
+export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
     const defaultMode = manager.getDefaultMode();
     const resolvedMode = resolveMode(mode, defaultMode);
     const resolvedEffort = effort ?? 'medium';
-    debug(`[spawn] Spawning ${agentType} agent for task "${taskName}" [${resolvedMode}] effort=${resolvedEffort}...`);
-    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath);
+    debug(`[spawn] Spawning ${agentType} agent for task "${taskName}" [${resolvedMode}] effort=${resolvedEffort}${profileName ? ` profile=${profileName}` : ''}...`);
+    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName);
     debug(`[spawn] Spawned ${agentType} agent ${agent.agentId} for task "${taskName}"`);
     return {
         task_name: taskName,
@@ -70,6 +70,7 @@ export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mod
         status: agent.status,
         started_at: agent.startedAt.toISOString(),
         version: agent.version,
+        profile_name: agent.profileName,
         remote_session_id: agent.remoteSessionId,
         name: agent.name,
         after: agent.after,

package/dist/lib/types.d.ts

@@ -40,6 +40,12 @@ export interface AgentConfig {
         skills: Capability;
         commands: Capability;
         plugins: Capability;
+        /**
+         * Permission modes this agent natively supports. Modes outside this set
+         * are gated by buildExecCommand: `auto` silently degrades to `edit`,
+         * `skip` errors with a clear message naming the supported modes.
+         */
+        modes: Mode[];
         /**
          * Whether the agent natively resolves `@path/to/file` imports inside its
          * rules file at session start. If false, agents-cli must pre-compile the
@@ -60,6 +66,19 @@ export type Capability = boolean | {
 };
 /** Names of every gateable capability on AgentConfig. */
 export type CapabilityName = 'hooks' | 'mcp' | 'allowlist' | 'skills' | 'commands' | 'plugins';
+/**
+ * Permission modes controlling agent autonomy.
+ *   plan  read-only investigation; no writes, no shell side-effects
+ *   edit  may edit files; prompts for shell/risky operations
+ *   auto  smart classifier auto-approves safe operations, prompts for risky ones
+ *   skip  bypasses every permission prompt (dangerously-skip-permissions)
+ *
+ * `full` is accepted as a permanent silent alias for `skip` via normalizeMode().
+ * Per-agent support is declared on AgentConfig.capabilities.modes.
+ */
+export type Mode = 'plan' | 'edit' | 'auto' | 'skip';
+/** Every canonical mode in declaration order. Useful for iteration / validation. */
+export declare const ALL_MODES: readonly Mode[];
 /** Reason a capability check failed. */
 export type CapabilityFailReason = 'unsupported' | 'too_old' | 'too_new';
 /** Result of `supports(agent, cap, version?)`. */
@@ -100,6 +119,36 @@ export interface HookMatches {
     cwd_includes?: string | string[];
     project_has?: string;
 }
+/**
+ * Cache scoping. Determines which cache file a hook invocation reads/writes:
+ *  - `global`      one file per hook, shared across cwds/sessions. Right for
+ *                  SessionStart hooks pulling org-wide context (Linear sprint).
+ *  - `per-cwd`     keyed on the working directory the hook fires from.
+ *  - `per-session` keyed on the agent's session_id (read from stdin JSON).
+ *  - `per-project` keyed on the nearest git repo root above cwd.
+ */
+export type HookCacheKey = 'global' | 'per-cwd' | 'per-session' | 'per-project';
+/** Prefetch strategy when the cache is stale. */
+export type HookCachePrefetch = 'none' | 'background';
+/**
+ * Full hook cache config. Authors usually use the shorthand string form
+ * (`HookCache`) below. Shorthand examples in hooks.yaml:
+ *
+ *   cache: 5m          # → { ttl: 300, key: 'global', prefetch: 'none' }
+ *   cache: 5m-bg       # → { ttl: 300, key: 'global', prefetch: 'background' }
+ *   cache:             # full form
+ *     ttl: 1h
+ *     key: per-cwd
+ *     prefetch: background
+ */
+export interface HookCacheConfig {
+    /** TTL in seconds or duration string ("30s", "5m", "1h"). */
+    ttl: number | string;
+    key?: HookCacheKey;
+    prefetch?: HookCachePrefetch;
+}
+/** Cache shorthand: duration string, optionally suffixed `-bg` for background prefetch. */
+export type HookCache = string | HookCacheConfig;
 /** Hook entry as declared in a package manifest (agents.yaml). */
 export interface ManifestHook {
     script: string;
@@ -114,6 +163,13 @@ export interface ManifestHook {
     override?: boolean;
     /** Optional pre-filter predicates evaluated before invoking the script. */
     matches?: HookMatches;
+    /**
+     * Opt-in caching. When set, the registrar generates a per-hook shim
+     * under the hook shims dir that handles cache lookup, stale-while-revalidate,
+     * and per-invocation timing/logging, then registers that shim with the agent
+     * instead of the raw script. The underlying script is unchanged.
+     */
+    cache?: HookCache;
 }
 /** Lightweight hook descriptor used in resource listings. */
 export interface HookResourceEntry {
@@ -469,7 +525,7 @@ export interface BrowserProfileConfig {
     };
     /** Directory holding source-side JSONL logs (e.g. ~/.rush/logs). */
     logDir?: string;
-    /** Optional SSH host where logDir lives, e.g. "user@mac-mini". */
+    /** Optional SSH host where logDir lives, e.g. "user@remote-host". */
     logHost?: string;
 }
 /** Options controlling which agents and resources are synced during `agents pull` / `agents use`. */

package/dist/lib/types.js

@@ -5,6 +5,8 @@
  * configuration schemas, resource tracking, registry types, and permission
  * formats for each supported agent.
  */
+/** Every canonical mode in declaration order. Useful for iteration / validation. */
+export const ALL_MODES = ['plan', 'edit', 'auto', 'skip'];
 /** Canonical system repo cloned into ~/.agents-system/. */
 export const DEFAULT_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */

package/dist/lib/usage.d.ts

@@ -71,12 +71,37 @@ export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[]): Pr
     usageByKey: Map<string, UsageInfo>;
 }>;
 /**
- * Fetch usage for a single identity, with a 2-minute cache fast path.
- * Falls back to cached data when the live fetch fails.
+ * Fetch usage for a single identity using stale-while-revalidate.
+ *
+ * - Cache fresh (< 2 min): return cached snapshot, NO network.
+ * - Cache stale but < 24h: return cached snapshot instantly, fire background refresh.
+ * - Cache too stale or absent: block on live fetch, fall back to cache on error.
+ *
+ * This keeps `agents run` startup off the network on the hot path. The first
+ * invocation after a cold install or 24h gap still blocks once to seed the
+ * cache; every run after that returns instantly while the cache silently
+ * refreshes in the background.
  */
 export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Promise<UsageInfo>;
 /** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
+/**
+ * Compact colored badge for the account's overall usage status. Renders only
+ * when the account is throttled — `available` and `null` return ''.
+ *
+ * - `out_of_credits` → red "out of credits" (terminal account, all buckets dry)
+ * - `rate_limited`   → yellow "rate-limited" (transient throttling)
+ *
+ * The badge sits between the usage bars and `lastActive` in `agents view`, so
+ * a glance at the row tells the user whether the version can do useful work.
+ * The same signal is exposed as `usageStatus` in `agents view --json` for
+ * programmatic consumers (e.g. the swarmify panel's "resume in healthy agent").
+ *
+ * The switch is exhaustive on purpose — adding a new `AccountInfo.usageStatus`
+ * value without updating the cases here is a build error at `_exhaustive`,
+ * which is exactly the bug class this PR is fixing.
+ */
+export declare function formatUsageStatusBadge(usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null | undefined): string;
 /** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
 /** Load Claude OAuth credentials from the system keychain/keyring. */

package/dist/lib/usage.js

@@ -96,42 +96,95 @@ export async function getUsageInfoByIdentity(inputs) {
         usageByKey: new Map(usageResults.map(({ key, usage }) => [key, usage])),
     };
 }
-const USAGE_CACHE_FRESH_MS = 2 * 60 * 1000; // 2 minutes
+const USAGE_CACHE_FRESH_MS = 2 * 60 * 1000; // 2 minutes — fresh window: don't refresh.
+const USAGE_CACHE_SWR_MS = 24 * 60 * 60 * 1000; // 24 hours — beyond this, block on live fetch.
+/** In-process dedup: don't fire concurrent background refreshes for the same identity. */
+const inFlightRefreshes = new Map();
 /**
- * Fetch usage for a single identity, with a 2-minute cache fast path.
- * Falls back to cached data when the live fetch fails.
+ * Fetch usage for a single identity using stale-while-revalidate.
+ *
+ * - Cache fresh (< 2 min): return cached snapshot, NO network.
+ * - Cache stale but < 24h: return cached snapshot instantly, fire background refresh.
+ * - Cache too stale or absent: block on live fetch, fall back to cache on error.
+ *
+ * This keeps `agents run` startup off the network on the hot path. The first
+ * invocation after a cold install or 24h gap still blocks once to seed the
+ * cache; every run after that returns instantly while the cache silently
+ * refreshes in the background.
  */
 export async function getUsageInfoForIdentity(input) {
     const usageKey = getUsageLookupKey(input.info);
-    // Fast path: serve from cache if fresh. Skips the network call entirely.
-    if (input.agentId === 'claude' && usageKey) {
-        const cached = readClaudeUsageCache(usageKey);
-        if (cached?.capturedAt) {
-            const ageMs = Date.now() - cached.capturedAt.getTime();
-            if (ageMs < USAGE_CACHE_FRESH_MS) {
-                return { snapshot: cached, error: null };
-            }
-        }
+    // Non-Claude or no identity: legacy path, blocking fetch.
+    if (input.agentId !== 'claude' || !usageKey) {
+        return getUsageInfo(input.agentId, {
+            home: input.home,
+            cliVersion: input.cliVersion,
+            organizationId: input.info.organizationId,
+        });
     }
-    // Cache miss or stale -- make the network call.
+    const cached = readClaudeUsageCache(usageKey);
+    const ageMs = cached?.capturedAt ? Date.now() - cached.capturedAt.getTime() : Infinity;
+    // Fresh: cache is recent enough, skip network entirely.
+    if (cached && ageMs < USAGE_CACHE_FRESH_MS) {
+        return { snapshot: cached, error: null };
+    }
+    // Stale-while-revalidate: cache exists and isn't ancient, return it now and
+    // refresh in the background so the next invocation has fresh data.
+    if (cached && ageMs < USAGE_CACHE_SWR_MS) {
+        triggerBackgroundUsageRefresh(input, usageKey);
+        return { snapshot: cached, error: null };
+    }
+    // Cold cache or > 24h old: block on live fetch.
     const usage = await getUsageInfo(input.agentId, {
         home: input.home,
         cliVersion: input.cliVersion,
         organizationId: input.info.organizationId,
     });
-    if (input.agentId !== 'claude' || !usageKey) {
-        return usage;
-    }
     if (usage.snapshot?.source === 'live') {
         writeClaudeUsageCache(usageKey, usage.snapshot);
         return usage;
     }
-    const cached = readClaudeUsageCache(usageKey);
+    // Live fetch failed — last-resort fallback to whatever cache we had.
     if (cached) {
         return { snapshot: cached, error: usage.error };
     }
     return usage;
 }
+/**
+ * Kick off a background refresh of the usage cache. Errors are swallowed —
+ * a failed background refresh leaves the existing cache in place for the
+ * next invocation. The work is deferred to a future event-loop tick via
+ * `setImmediate` because some of the call chain (loadClaudeOauth →
+ * getKeychainToken → execFileSync) does synchronous I/O even though the
+ * functions are declared `async`. Without the defer, that sync I/O blocks
+ * the SWR caller and defeats the whole point of returning the cache instantly.
+ */
+function triggerBackgroundUsageRefresh(input, usageKey) {
+    if (inFlightRefreshes.has(usageKey))
+        return;
+    const promise = new Promise((resolve) => {
+        setImmediate(async () => {
+            try {
+                const usage = await getUsageInfo(input.agentId, {
+                    home: input.home,
+                    cliVersion: input.cliVersion,
+                    organizationId: input.info.organizationId,
+                });
+                if (usage.snapshot?.source === 'live') {
+                    writeClaudeUsageCache(usageKey, usage.snapshot);
+                }
+            }
+            catch {
+                /* background refresh failed — leave existing cache in place */
+            }
+            finally {
+                inFlightRefreshes.delete(usageKey);
+                resolve();
+            }
+        });
+    });
+    inFlightRefreshes.set(usageKey, promise);
+}
 /** Format a one-line usage summary with compact bars for inline display. */
 export function formatUsageSummary(plan, snapshot, planWidth = 3) {
     const parts = [];
@@ -148,6 +201,36 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
     }
     return parts.join('  ');
 }
+/**
+ * Compact colored badge for the account's overall usage status. Renders only
+ * when the account is throttled — `available` and `null` return ''.
+ *
+ * - `out_of_credits` → red "out of credits" (terminal account, all buckets dry)
+ * - `rate_limited`   → yellow "rate-limited" (transient throttling)
+ *
+ * The badge sits between the usage bars and `lastActive` in `agents view`, so
+ * a glance at the row tells the user whether the version can do useful work.
+ * The same signal is exposed as `usageStatus` in `agents view --json` for
+ * programmatic consumers (e.g. the swarmify panel's "resume in healthy agent").
+ *
+ * The switch is exhaustive on purpose — adding a new `AccountInfo.usageStatus`
+ * value without updating the cases here is a build error at `_exhaustive`,
+ * which is exactly the bug class this PR is fixing.
+ */
+export function formatUsageStatusBadge(usageStatus) {
+    if (usageStatus === null || usageStatus === undefined)
+        return '';
+    switch (usageStatus) {
+        case 'available': return '';
+        case 'out_of_credits': return chalk.red('out of credits');
+        case 'rate_limited': return chalk.yellow('rate-limited');
+        default: {
+            const _exhaustive = usageStatus;
+            void _exhaustive;
+            return '';
+        }
+    }
+}
 /** Format a multi-line usage section for detailed agent views. */
 export function formatUsageSection(usage) {
     if (!usage.snapshot && !usage.error) {

package/dist/lib/versions.d.ts

@@ -48,12 +48,35 @@ export declare function getAvailableResources(cwd?: string): AvailableResources;
 export declare function getActuallySyncedResources(agent: AgentId, version: string, options?: {
     cwd?: string;
 }): AvailableResources;
+/** Resource names that only exist in the project's `.agents/` layer, grouped by kind. */
+export interface ProjectOnlyResources {
+    commands: Set<string>;
+    skills: Set<string>;
+    hooks: Set<string>;
+    subagents: Set<string>;
+    plugins: Set<string>;
+    workflows: Set<string>;
+}
+/**
+ * Names that exist ONLY in the project's `.agents/` layer (no matching entry in
+ * user/system/extra layers). Sync intentionally skips project-layer commands,
+ * skills, hooks, subagents, plugins, and workflows for security — see the
+ * defense comments above each sync branch in syncResourcesToVersion. Without
+ * this filter, those names would forever appear in the "New resources" diff
+ * because they live in `available` but never reach `actuallySynced`.
+ */
+export declare function getProjectOnlyResources(cwd?: string): ProjectOnlyResources;
 /**
  * Compare available resources with what's ACTUALLY synced to version home.
  * Returns only NEW resources that haven't been synced yet.
  * Source of truth: the actual files/config, NOT agents.yaml tracking.
+ *
+ * `projectOnly` (recommended): the result of `getProjectOnlyResources(cwd)`.
+ * Names listed there are filtered out for kinds that sync intentionally
+ * excludes the project layer — otherwise they would re-appear as "new"
+ * on every run and "Yes, sync all new" would silently do nothing for them.
  */
-export declare function getNewResources(available: AvailableResources, actuallySynced: AvailableResources): AvailableResources;
+export declare function getNewResources(available: AvailableResources, actuallySynced: AvailableResources, projectOnly?: ProjectOnlyResources): AvailableResources;
 /**
  * Check if there are any new resources to sync.
  * When version is provided, uses version-specific capability checks.
@@ -285,6 +308,17 @@ export interface InstalledAgentTargetResult {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }
+/**
+ * Thrown when the user references an agent@version that is not installed.
+ * Carries the parsed (agentId, version) so callers can react — e.g. prompt
+ * to install it on demand — without having to parse the error message.
+ */
+export declare class VersionNotInstalledError extends Error {
+    readonly agentId: AgentId;
+    readonly version: string;
+    readonly installedVersions: readonly string[];
+    constructor(agentId: AgentId, version: string, installedVersions: readonly string[]);
+}
 /**
  * Resolve a comma-separated --agents list into concrete version selections.
  * Bare agents target the default version, or the newest installed version when no default exists.