@phnx-labs/agents-cli 1.20.33 → 1.20.34

package/dist/lib/sync-status.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Unified sync-status engine — the SINGLE source of truth for "is this resource
+ * synced to this agent version?" consumed by `agents doctor`, `agents view`, the
+ * menu-bar app, and any Agency surface.
+ *
+ * Why this exists: before this module there were four different notions of
+ * "synced" living in four files:
+ *   - doctor:  isStale() vs .sync-manifest.json  — catches SOURCE drift only.
+ *   - view:    git working-tree state of ~/.agents/ — a resource can show green
+ *              while its installed copy is stale/deleted/corrupted (false positive).
+ *   - lists:   file-exists-in-home — never reports content drift at all.
+ *   - menubar: read doctor --json (so it inherited doctor's source-only blind spot).
+ *
+ * The reliable signal is diffVersionResources() (src/lib/doctor-diff.ts): it reads
+ * the ACTUAL version home and compares it to the resolved sources, so it catches
+ * every drift class — source-side changes AND home-side rot (deleted / corrupted /
+ * hand-edited installed copies) AND orphans. This module wraps it once, maps its
+ * per-resource DiffStatus onto one stable enum, folds in `.system` repo freshness,
+ * and lets every surface render the same warnings instead of re-deriving them.
+ */
+import { AgentId } from './types.js';
+import { type DoctorKind } from './doctor-diff.js';
+/**
+ * One stable status per resource, unified across every surface.
+ *  - `synced`  — installed copy matches the resolved source (DiffStatus 'ok').
+ *  - `drifted` — installed copy exists but differs from source (DiffStatus 'diff').
+ *  - `missing` — source exists, nothing installed in the version home ('missing').
+ *  - `orphan`  — installed in the home with no source ('extra'); prune's job, not sync's.
+ */
+export type ResourceSyncStatus = 'synced' | 'drifted' | 'missing' | 'orphan';
+export interface ResourceStatusRow {
+    agent: AgentId;
+    version: string;
+    kind: DoctorKind;
+    name: string;
+    status: ResourceSyncStatus;
+    /** Human-readable specifics for a drifted row (e.g. plugin version delta). */
+    detail?: string;
+}
+export interface AgentVersionStatus {
+    agent: AgentId;
+    version: string;
+    isDefault: boolean;
+    /** False = no .sync-manifest.json: this version was never synced (cold). */
+    everSynced: boolean;
+    counts: {
+        synced: number;
+        drifted: number;
+        missing: number;
+        orphan: number;
+    };
+    /** drifted + missing > 0 — a real reconcile is owed. Orphans do NOT set this
+     * (heal never deletes; orphan removal is `agents prune cleanup`). */
+    needsSync: boolean;
+    resources: ResourceStatusRow[];
+}
+export interface SystemRepoStatus {
+    dir: string;
+    /** Commits the local `.system` checkout is behind its tracking branch, as of
+     * the last background fetch (no network is performed here). 0 = up to date. */
+    behind: number;
+    ahead: number;
+    branch: string | null;
+    /** True when the dir isn't a git repo or has no upstream — behind is unknown. */
+    unknown: boolean;
+}
+export interface UnifiedSyncStatus {
+    system: SystemRepoStatus;
+    agents: AgentVersionStatus[];
+    totals: {
+        drifted: number;
+        missing: number;
+        orphan: number;
+        /** Versions with a manifest that are behind on content. */
+        versionsNeedingSync: number;
+        /** Versions that were never synced at all. */
+        versionsNeverSynced: number;
+        /** Distinct agent ids that own at least one version needing sync. */
+        agentsNeedingSync: number;
+    };
+}
+export interface SyncStatusOptions {
+    cwd?: string;
+    /** Restrict to specific agent ids; undefined = every supported agent. */
+    agents?: AgentId[];
+    /** Restrict to specific resource kinds; undefined = all. */
+    kinds?: DoctorKind[];
+}
+/**
+ * Read `.system` repo freshness WITHOUT touching the network. `git status`
+ * reports ahead/behind against the remote-tracking ref, which the detached
+ * auto-pull worker keeps warm via periodic `git fetch`. This is the same number
+ * the menu-bar surfaces; we read it once, here, so every surface agrees.
+ */
+export declare function getSystemRepoStatus(): Promise<SystemRepoStatus>;
+/**
+ * Compute unified sync status across the fleet. Resolves against non-project
+ * layers only (`excludeProject: true`) — the GLOBAL version home is never
+ * reconciled against per-cwd `<cwd>/.agents/` resources, so counting them as
+ * "missing" there would be a false gap (matches doctor's overview semantics).
+ */
+export declare function computeSyncStatus(options?: SyncStatusOptions): Promise<UnifiedSyncStatus>;

package/dist/lib/sync-status.js

@@ -0,0 +1,135 @@
+/**
+ * Unified sync-status engine — the SINGLE source of truth for "is this resource
+ * synced to this agent version?" consumed by `agents doctor`, `agents view`, the
+ * menu-bar app, and any Agency surface.
+ *
+ * Why this exists: before this module there were four different notions of
+ * "synced" living in four files:
+ *   - doctor:  isStale() vs .sync-manifest.json  — catches SOURCE drift only.
+ *   - view:    git working-tree state of ~/.agents/ — a resource can show green
+ *              while its installed copy is stale/deleted/corrupted (false positive).
+ *   - lists:   file-exists-in-home — never reports content drift at all.
+ *   - menubar: read doctor --json (so it inherited doctor's source-only blind spot).
+ *
+ * The reliable signal is diffVersionResources() (src/lib/doctor-diff.ts): it reads
+ * the ACTUAL version home and compares it to the resolved sources, so it catches
+ * every drift class — source-side changes AND home-side rot (deleted / corrupted /
+ * hand-edited installed copies) AND orphans. This module wraps it once, maps its
+ * per-resource DiffStatus onto one stable enum, folds in `.system` repo freshness,
+ * and lets every surface render the same warnings instead of re-deriving them.
+ */
+import simpleGit from 'simple-git';
+import { ALL_AGENT_IDS } from './agents.js';
+import { diffVersionResources, } from './doctor-diff.js';
+import { listInstalledVersions, getGlobalDefault } from './versions.js';
+import { loadManifest } from './staleness/index.js';
+import { getSystemAgentsDir } from './state.js';
+import { isGitRepo } from './git.js';
+const STATUS_MAP = {
+    ok: 'synced',
+    diff: 'drifted',
+    missing: 'missing',
+    extra: 'orphan',
+};
+function rowsFromReport(agent, version, report) {
+    const out = [];
+    for (const list of Object.values(report.kinds)) {
+        for (const r of list) {
+            out.push({
+                agent,
+                version,
+                kind: r.kind,
+                name: r.name,
+                status: STATUS_MAP[r.status],
+                ...(r.detail ? { detail: r.detail } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Read `.system` repo freshness WITHOUT touching the network. `git status`
+ * reports ahead/behind against the remote-tracking ref, which the detached
+ * auto-pull worker keeps warm via periodic `git fetch`. This is the same number
+ * the menu-bar surfaces; we read it once, here, so every surface agrees.
+ */
+export async function getSystemRepoStatus() {
+    const dir = getSystemAgentsDir();
+    const base = { dir, behind: 0, ahead: 0, branch: null, unknown: true };
+    if (!isGitRepo(dir))
+        return base;
+    try {
+        const status = await simpleGit(dir).status();
+        return {
+            dir,
+            behind: status.behind ?? 0,
+            ahead: status.ahead ?? 0,
+            branch: status.tracking ?? status.current ?? null,
+            // Without a tracking branch there's no upstream to compare against.
+            unknown: !status.tracking,
+        };
+    }
+    catch {
+        return base;
+    }
+}
+/**
+ * Compute unified sync status across the fleet. Resolves against non-project
+ * layers only (`excludeProject: true`) — the GLOBAL version home is never
+ * reconciled against per-cwd `<cwd>/.agents/` resources, so counting them as
+ * "missing" there would be a false gap (matches doctor's overview semantics).
+ */
+export async function computeSyncStatus(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const agentIds = options.agents ?? ALL_AGENT_IDS;
+    const agents = [];
+    for (const agent of agentIds) {
+        const def = getGlobalDefault(agent);
+        for (const version of listInstalledVersions(agent)) {
+            const report = diffVersionResources(agent, version, {
+                cwd,
+                excludeProject: true,
+                ...(options.kinds ? { kinds: options.kinds } : {}),
+            });
+            const resources = rowsFromReport(agent, version, report);
+            const counts = { synced: 0, drifted: 0, missing: 0, orphan: 0 };
+            for (const r of resources)
+                counts[r.status]++;
+            agents.push({
+                agent,
+                version,
+                isDefault: version === def,
+                everSynced: loadManifest(agent, version) !== null,
+                counts,
+                needsSync: counts.drifted + counts.missing > 0,
+                resources,
+            });
+        }
+    }
+    const system = await getSystemRepoStatus();
+    const agentsNeedingSync = new Set();
+    let drifted = 0, missing = 0, orphan = 0, versionsNeedingSync = 0, versionsNeverSynced = 0;
+    for (const v of agents) {
+        drifted += v.counts.drifted;
+        missing += v.counts.missing;
+        orphan += v.counts.orphan;
+        if (!v.everSynced)
+            versionsNeverSynced++;
+        if (v.needsSync) {
+            versionsNeedingSync++;
+            agentsNeedingSync.add(v.agent);
+        }
+    }
+    return {
+        system,
+        agents,
+        totals: {
+            drifted,
+            missing,
+            orphan,
+            versionsNeedingSync,
+            versionsNeverSynced,
+            agentsNeedingSync: agentsNeedingSync.size,
+        },
+    };
+}

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

@@ -68,6 +68,30 @@ export declare function checkAllClis(): Record<string, {
     path: string | null;
     error: string | null;
 }>;
+/**
+ * Advisory sign-in probe for a teammate's agent. Reads the account-global login
+ * (no `home` → active config) via `getAccountInfo`. Deliberately best-effort:
+ * sign-in detection is UNRELIABLE for opaque-credential agents (Kimi/Antigravity
+ * store an OAuth/JWT with no email claim) and for keychain-probed agents, so a
+ * `false` here is often a false negative. Callers must WARN and continue — never
+ * block a team on this result. Never throws (returns false on any error).
+ */
+export declare function checkCliSignedIn(agentType: AgentType): Promise<boolean>;
+/** Advisory sign-in status for a `teams doctor` row. */
+export interface SignInAdvisory {
+    /** true / false from the probe, or null when the agent isn't installed. */
+    signedIn: boolean | null;
+    /** Whether the agent is currently a running teammate. */
+    running: boolean;
+}
+/**
+ * Resolve the advisory sign-in status shown by `teams doctor`. An agent that is
+ * currently RUNNING in a team is live proof it works, so it overrides a
+ * (frequently false-negative) sign-in probe — doctor must never report a
+ * working agent as logged out. Not installed → `signedIn: null` (nothing to
+ * probe). Never flips the authoritative installed/ready column.
+ */
+export declare function resolveSignInAdvisory(installed: boolean, running: boolean, probeSignedIn: boolean): SignInAdvisory;
 /** Resolve and cache the base directory where teammate process data is stored. */
 export declare function getAgentsDir(): Promise<string>;
 /**

package/dist/lib/teams/agents.js

@@ -19,7 +19,7 @@ import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
 import { getAgentsDir as getSystemAgentsDir, getShimsDir } from '../state.js';
-import { AGENTS } from '../agents.js';
+import { AGENTS, getAccountInfo } 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
@@ -353,6 +353,35 @@ export function checkAllClis() {
     }
     return results;
 }
+/**
+ * Advisory sign-in probe for a teammate's agent. Reads the account-global login
+ * (no `home` → active config) via `getAccountInfo`. Deliberately best-effort:
+ * sign-in detection is UNRELIABLE for opaque-credential agents (Kimi/Antigravity
+ * store an OAuth/JWT with no email claim) and for keychain-probed agents, so a
+ * `false` here is often a false negative. Callers must WARN and continue — never
+ * block a team on this result. Never throws (returns false on any error).
+ */
+export async function checkCliSignedIn(agentType) {
+    try {
+        const info = await getAccountInfo(agentType);
+        return info.signedIn;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the advisory sign-in status shown by `teams doctor`. An agent that is
+ * currently RUNNING in a team is live proof it works, so it overrides a
+ * (frequently false-negative) sign-in probe — doctor must never report a
+ * working agent as logged out. Not installed → `signedIn: null` (nothing to
+ * probe). Never flips the authoritative installed/ready column.
+ */
+export function resolveSignInAdvisory(installed, running, probeSignedIn) {
+    if (!installed)
+        return { signedIn: null, running: false };
+    return { signedIn: running ? true : probeSignedIn, running };
+}
 let AGENTS_DIR = null;
 /** Resolve and cache the base directory where teammate process data is stored. */
 export async function getAgentsDir() {

package/dist/lib/types.d.ts

@@ -7,7 +7,7 @@
  */
 import type { CloudProviderId } from './cloud/types.js';
 /** Unique identifier for a supported AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi' | 'droid';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /** Per-agent run strategy config. */
@@ -99,6 +99,25 @@ export interface AgentConfig {
      * cloud and falls back to the configured default.
      */
     cloudProvider?: CloudProviderId;
+    /**
+     * Set when the upstream vendor has retired this agent's CLI. Presence marks
+     * the agent deprecated (it is never blocked from use); `warnAgentDeprecated`
+     * surfaces this in yellow whenever a user installs the agent or adds it to a
+     * team. Point `replacement` at the successor agent so the warning can suggest
+     * a migration path.
+     */
+    deprecated?: {
+        /** Vendor that retired it, e.g. "Google". */
+        by: string;
+        /** Human date it stopped working / was retired, e.g. "June 18, 2026". */
+        date: string;
+        /** One-line explanation shown under the warning header. */
+        reason: string;
+        /** Successor agent id to suggest instead (e.g. 'antigravity'). */
+        replacement?: AgentId;
+        /** Announcement URL for the deprecation. */
+        url?: string;
+    };
     capabilities: {
         hooks: Capability;
         mcp: Capability;

package/dist/lib/usage.d.ts

@@ -17,6 +17,7 @@ export interface UsageSnapshot {
     sourceLabel: string;
     capturedAt: Date | null;
     windows: UsageWindow[];
+    plan?: string | null;
 }
 /** Usage data plus any error encountered while fetching. */
 export interface UsageInfo {
@@ -122,6 +123,35 @@ export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot |
 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[];
+/** Raw quota bucket from the Kimi /usages response (numbers arrive as strings). */
+interface KimiUsageQuota {
+    limit?: string | number | null;
+    used?: string | number | null;
+    remaining?: string | number | null;
+    resetTime?: string | null;
+}
+/** Response shape from the Kimi Code /usages endpoint (subset we render). */
+export interface KimiUsagesResponse {
+    user?: {
+        userId?: string | null;
+        membership?: {
+            level?: string | null;
+        } | null;
+    } | null;
+    usage?: KimiUsageQuota | null;
+    limits?: Array<{
+        window?: {
+            duration?: number | null;
+            timeUnit?: string | null;
+        } | null;
+        detail?: KimiUsageQuota | null;
+    } | null> | null;
+    subType?: string | null;
+}
+/** Normalize the Kimi /usages payload into the common UsageWindow shape. */
+export declare function normalizeKimiWindows(data: KimiUsagesResponse): UsageWindow[];
+/** Derive a display plan label from Kimi's membership tier or subscription type. */
+export declare function formatKimiPlan(data: KimiUsagesResponse): string | null;
 /** Load Claude OAuth credentials from the system keychain/keyring. */
 export declare function loadClaudeOauth(home?: string): Promise<ClaudeOauthCredentials | null>;
 /**

package/dist/lib/usage.js

@@ -33,6 +33,7 @@ const CLAUDE_SCOPES = [
 const CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
 const getClaudeUsageCachePath = () => path.join(getCacheDir(), 'claude-usage.json');
 const CACHED_CLAUDE_USAGE_SOURCE_LABEL = 'last seen live account data';
+const KIMI_USAGES_URL = 'https://api.kimi.com/coding/v1/usages';
 const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
@@ -44,6 +45,8 @@ export async function getUsageInfo(agentId, options) {
             return getClaudeUsageInfo(options);
         case 'codex':
             return getCodexUsageInfo(options);
+        case 'kimi':
+            return getKimiUsageInfo(options);
         default:
             return { snapshot: null, error: null };
     }
@@ -114,8 +117,14 @@ const inFlightRefreshes = new Map();
  */
 export async function getUsageInfoForIdentity(input) {
     const usageKey = getUsageLookupKey(input.info);
-    // Non-Claude or no identity: legacy path, blocking fetch.
-    if (input.agentId !== 'claude' || !usageKey) {
+    // Agents whose usage comes from a live network call (Claude, Kimi) go through
+    // the stale-while-revalidate cache below so `agents run`/`agents view` stay off
+    // the network on the hot path. Everything else (Codex reads local session
+    // logs) takes the legacy blocking path. The on-disk cache is shared and keyed
+    // by usageKey, which is namespaced per agent (`claude:org=…`, `kimi:user=…`),
+    // so one cache file holds every account without collision.
+    const usesNetworkUsage = input.agentId === 'claude' || input.agentId === 'kimi';
+    if (!usesNetworkUsage || !usageKey) {
         return getUsageInfo(input.agentId, {
             home: input.home,
             cliVersion: input.cliVersion,
@@ -356,6 +365,152 @@ async function getClaudeUsageInfo(options) {
         return { snapshot: null, error: 'Usage data unavailable right now.' };
     }
 }
+/**
+ * Resolve Kimi's OAuth credential file. Sign-in is account-global but each
+ * installed version has an isolated home; the file physically lives only in the
+ * home the user logged in under. Check the per-version home first, then the
+ * active location under the real HOME — mirrors resolveAccountCredentialPath in
+ * agents.ts so every version reflects the true account state.
+ */
+function resolveKimiCredentialPath(home) {
+    const rel = ['.kimi-code', 'credentials', 'kimi-code.json'];
+    const perVersion = path.join(home || os.homedir(), ...rel);
+    try {
+        if (fs.existsSync(perVersion))
+            return perVersion;
+    }
+    catch { /* unreadable */ }
+    const active = path.join(process.env.AGENTS_REAL_HOME || os.homedir(), ...rel);
+    if (active !== perVersion) {
+        try {
+            if (fs.existsSync(active))
+                return active;
+        }
+        catch { /* unreadable */ }
+    }
+    return null;
+}
+/**
+ * Fetch Kimi usage via the Kimi Code /usages API. Kimi's JWT has no email
+ * claim, so the account row can't show an address — but /usages returns quota
+ * windows and the membership tier, which is what we render.
+ *
+ * Deliberately NO token refresh: `agents view` is a read/inspect command and
+ * must not rotate the user's Kimi OAuth credential (rewriting the file,
+ * invalidating the old refresh token, racing a concurrently-running kimi CLI).
+ * The kimi CLI refreshes on its own launch; if the stored token is expired we
+ * skip the live fetch and let the SWR cache serve the last-seen snapshot.
+ */
+async function getKimiUsageInfo(options) {
+    try {
+        const credPath = resolveKimiCredentialPath(options?.home);
+        if (!credPath)
+            return { snapshot: null, error: null };
+        const cred = JSON.parse(fs.readFileSync(credPath, 'utf-8'));
+        const accessToken = cred?.access_token;
+        if (typeof accessToken !== 'string' || !accessToken) {
+            return { snapshot: null, error: null };
+        }
+        const expiresAt = typeof cred?.expires_at === 'number' ? cred.expires_at : null;
+        if (expiresAt !== null && Date.now() / 1000 >= expiresAt) {
+            return { snapshot: null, error: null };
+        }
+        const response = await fetch(KIMI_USAGES_URL, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: 'application/json',
+            },
+            signal: AbortSignal.timeout(5000),
+        });
+        // 401/403/404 => expired token or no Kimi For Coding subscription; render
+        // nothing rather than a misleading empty bar.
+        if (!response.ok) {
+            return { snapshot: null, error: null };
+        }
+        const data = await response.json();
+        const windows = normalizeKimiWindows(data);
+        if (windows.length === 0) {
+            return { snapshot: null, error: null };
+        }
+        return {
+            snapshot: {
+                source: 'live',
+                sourceLabel: 'live account data',
+                capturedAt: new Date(),
+                windows,
+                plan: formatKimiPlan(data),
+            },
+            error: null,
+        };
+    }
+    catch {
+        return { snapshot: null, error: null };
+    }
+}
+/** Normalize the Kimi /usages payload into the common UsageWindow shape. */
+export function normalizeKimiWindows(data) {
+    const windows = [];
+    // Per-window rate limit (e.g. a 300-minute bucket) -> "session".
+    const shortLimit = Array.isArray(data.limits)
+        ? data.limits.find((entry) => entry?.detail)
+        : null;
+    const session = normalizeKimiWindow(shortLimit?.detail, 'session', 'Current session', 'S', kimiWindowMinutes(shortLimit?.window));
+    if (session)
+        windows.push(session);
+    // Rolling account quota -> "week".
+    const period = normalizeKimiWindow(data.usage, 'week', 'Current period', 'W', null);
+    if (period)
+        windows.push(period);
+    return windows;
+}
+/** Normalize a single Kimi quota bucket (used/limit strings) into a UsageWindow. */
+function normalizeKimiWindow(quota, key, label, shortLabel, windowMinutes) {
+    const limit = kimiNumber(quota?.limit);
+    const used = kimiNumber(quota?.used);
+    if (limit === null || used === null || limit <= 0)
+        return null;
+    const usedPercent = normalizePercent((used / limit) * 100);
+    if (usedPercent === null)
+        return null;
+    return {
+        key,
+        label,
+        shortLabel,
+        usedPercent,
+        resetsAt: parseDateValue(quota?.resetTime),
+        windowMinutes: windowMinutes ?? inferWindowMinutes(key),
+    };
+}
+/** Parse a numeric field that Kimi serializes as a string (e.g. "100"). */
+function kimiNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))) {
+        return Number(value);
+    }
+    return null;
+}
+/** Convert a Kimi limit window (duration + timeUnit enum) to minutes. */
+function kimiWindowMinutes(window) {
+    const duration = typeof window?.duration === 'number' ? window.duration : null;
+    if (duration === null || duration <= 0)
+        return null;
+    switch (window?.timeUnit) {
+        case 'TIME_UNIT_HOUR': return duration * 60;
+        case 'TIME_UNIT_SECOND': return duration / 60;
+        default: return duration; // TIME_UNIT_MINUTE or unknown -> minutes
+    }
+}
+/** Derive a display plan label from Kimi's membership tier or subscription type. */
+export function formatKimiPlan(data) {
+    const level = data.user?.membership?.level;
+    const raw = (typeof level === 'string' && level) || (typeof data.subType === 'string' && data.subType) || '';
+    const tail = raw.split('_').pop() || ''; // LEVEL_INTERMEDIATE -> INTERMEDIATE
+    if (!tail)
+        return null;
+    return tail.charAt(0).toUpperCase() + tail.slice(1).toLowerCase();
+}
 /** Collect Codex JSONL session files sorted newest-first. */
 function collectCodexSessionFiles(home) {
     const base = home || os.homedir();
@@ -590,6 +745,7 @@ function writeClaudeUsageCacheFile(cache, cachePath) {
 function serializeClaudeUsageSnapshot(snapshot) {
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
+        plan: snapshot.plan ?? null,
         windows: snapshot.windows.map((window) => ({
             key: window.key,
             label: window.label,
@@ -626,6 +782,7 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         sourceLabel: CACHED_CLAUDE_USAGE_SOURCE_LABEL,
         capturedAt,
         windows,
+        plan: snapshot.plan ?? null,
     };
 }
 /** Check whether a cached usage window is still relevant (not expired or reset). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.33",
+  "version": "1.20.34",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",