@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/usage.js

@@ -1,3 +1,11 @@
+/**
+ * Usage and rate-limit tracking for Claude and Codex agents.
+ *
+ * Fetches live usage data from the Anthropic OAuth API (Claude) or parses
+ * rate-limit events from Codex session logs. Results are normalized into a
+ * common UsageSnapshot shape, cached to disk, and rendered as terminal
+ * progress bars for the `agents view` and `agents status` commands.
+ */
 import { execFile } from 'child_process';
 import { createHash } from 'crypto';
 import * as fs from 'fs';
@@ -6,8 +14,8 @@ import * as path from 'path';
 import * as readline from 'readline';
 import { promisify } from 'util';
 import chalk from 'chalk';
+import { walkForFiles } from './fs-walk.js';
 import { getAgentsDir } from './state.js';
-import { walkForFiles } from './session/discover.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -22,12 +30,13 @@ const CLAUDE_SCOPES = [
     'user:file_upload',
 ];
 const CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
-const CLAUDE_USAGE_CACHE_PATH = path.join(getAgentsDir(), 'cache', 'claude-usage.json');
+const getClaudeUsageCachePath = () => path.join(getAgentsDir(), 'cache', 'claude-usage.json');
 const CACHED_CLAUDE_USAGE_SOURCE_LABEL = 'last seen live account data';
 const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
 const EMPTY = '\u2591';
+/** Fetch usage info for a given agent, dispatching to the agent-specific implementation. */
 export async function getUsageInfo(agentId, options) {
     switch (agentId) {
         case 'claude':
@@ -38,9 +47,14 @@ export async function getUsageInfo(agentId, options) {
             return { snapshot: null, error: null };
     }
 }
+/** Derive a stable lookup key from account info for usage deduplication. */
 export function getUsageLookupKey(info) {
     return info?.usageKey || info?.accountKey || null;
 }
+/**
+ * Deduplicate identity inputs into canonical (most-recently-active) accounts
+ * and build the corresponding fetch inputs for each unique usage key.
+ */
 export function buildCanonicalUsageContext(inputs) {
     const canonicalByUsageKey = new Map();
     const usageFetchInputs = new Map();
@@ -64,6 +78,7 @@ export function buildCanonicalUsageContext(inputs) {
     }
     return { canonicalByUsageKey, usageFetchInputs };
 }
+/** Fetch usage info for all unique accounts in parallel, keyed by usage key. */
 export async function getUsageInfoByIdentity(inputs) {
     const { canonicalByUsageKey, usageFetchInputs } = buildCanonicalUsageContext(inputs);
     const usageResults = await Promise.all([...usageFetchInputs.entries()].map(async ([key, input]) => ({
@@ -81,6 +96,10 @@ export async function getUsageInfoByIdentity(inputs) {
     };
 }
 const USAGE_CACHE_FRESH_MS = 2 * 60 * 1000; // 2 minutes
+/**
+ * Fetch usage for a single identity, with a 2-minute cache fast path.
+ * Falls back to cached data when the live fetch fails.
+ */
 export async function getUsageInfoForIdentity(input) {
     const usageKey = getUsageLookupKey(input.info);
     // Fast path: serve from cache if fresh. Skips the network call entirely.
@@ -93,7 +112,7 @@ export async function getUsageInfoForIdentity(input) {
             }
         }
     }
-    // Cache miss or stale — make the network call.
+    // Cache miss or stale -- make the network call.
     const usage = await getUsageInfo(input.agentId, {
         home: input.home,
         cliVersion: input.cliVersion,
@@ -112,6 +131,7 @@ export async function getUsageInfoForIdentity(input) {
     }
     return usage;
 }
+/** Format a one-line usage summary with compact bars for inline display. */
 export function formatUsageSummary(plan, snapshot, planWidth = 3) {
     const parts = [];
     if (plan) {
@@ -127,6 +147,7 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
     }
     return parts.join('  ');
 }
+/** Format a multi-line usage section for detailed agent views. */
 export function formatUsageSection(usage) {
     if (!usage.snapshot && !usage.error) {
         return [];
@@ -151,6 +172,7 @@ export function formatUsageSection(usage) {
     lines.push(`    ${chalk.dim(`Source: ${usage.snapshot.sourceLabel}`)}`);
     return lines;
 }
+/** Fetch Codex usage by scanning the most recent session files for rate-limit events. */
 async function getCodexUsageInfo(options) {
     try {
         const files = collectCodexSessionFiles(options?.home);
@@ -177,6 +199,7 @@ async function getCodexUsageInfo(options) {
         return { snapshot: null, error: null };
     }
 }
+/** Fetch Claude usage via the Anthropic OAuth usage API. */
 async function getClaudeUsageInfo(options) {
     try {
         const oauth = await loadClaudeOauth(options?.home);
@@ -224,6 +247,7 @@ async function getClaudeUsageInfo(options) {
         return { snapshot: null, error: 'Usage data unavailable right now.' };
     }
 }
+/** Collect Codex JSONL session files sorted newest-first. */
 function collectCodexSessionFiles(home) {
     const base = home || os.homedir();
     const dir = path.join(base, '.codex', 'sessions');
@@ -244,6 +268,7 @@ function collectCodexSessionFiles(home) {
     files.sort((a, b) => b.mtime - a.mtime);
     return files.map((file) => file.path);
 }
+/** Stream a Codex JSONL file and return the last rate_limits payload found. */
 async function readLatestCodexRateLimits(filePath) {
     return new Promise((resolve) => {
         let latest = null;
@@ -270,6 +295,7 @@ async function readLatestCodexRateLimits(filePath) {
         rl.on('error', () => resolve(latest));
     });
 }
+/** Normalize Codex rate-limit windows into the common UsageWindow shape. */
 function normalizeCodexWindows(rateLimits) {
     const windows = [];
     const primary = normalizeCodexWindow(rateLimits.primary, 'session', 'Current session', 'S');
@@ -280,6 +306,7 @@ function normalizeCodexWindows(rateLimits) {
         windows.push(secondary);
     return windows;
 }
+/** Normalize a single Codex rate-limit window. */
 function normalizeCodexWindow(window, key, label, shortLabel) {
     const usedPercent = normalizePercent(window?.used_percent);
     if (usedPercent === null)
@@ -293,6 +320,7 @@ function normalizeCodexWindow(window, key, label, shortLabel) {
         windowMinutes: normalizeWindowMinutes(window?.window_minutes),
     };
 }
+/** Normalize Claude API usage windows into the common UsageWindow shape. */
 function normalizeClaudeWindows(data) {
     const windows = [
         normalizeClaudeWindow(data.five_hour, 'session', 'Current session', 'S'),
@@ -301,6 +329,7 @@ function normalizeClaudeWindows(data) {
     ];
     return windows.filter((window) => window !== null);
 }
+/** Normalize a single Claude API usage window. */
 function normalizeClaudeWindow(window, key, label, shortLabel) {
     const usedPercent = normalizePercent(window?.utilization);
     if (usedPercent === null)
@@ -314,7 +343,8 @@ function normalizeClaudeWindow(window, key, label, shortLabel) {
         windowMinutes: inferWindowMinutes(key),
     };
 }
-async function loadClaudeOauth(home) {
+/** Load Claude OAuth credentials from the macOS Keychain. */
+export async function loadClaudeOauth(home) {
     if (process.platform !== 'darwin') {
         return null;
     }
@@ -330,6 +360,8 @@ async function loadClaudeOauth(home) {
             '-w',
         ]);
         const payload = JSON.parse(stdout.trim());
+        if (typeof payload?.claudeAiOauth?.accessToken !== 'string')
+            return null;
         if (!payload.claudeAiOauth) {
             return null;
         }
@@ -342,6 +374,10 @@ async function loadClaudeOauth(home) {
         return null;
     }
 }
+/**
+ * Derive the Keychain service name for a Claude home directory.
+ * Managed (non-default) homes get a hash suffix for isolation.
+ */
 export function getClaudeKeychainService(home) {
     if (!home) {
         return CLAUDE_KEYCHAIN_SERVICE;
@@ -350,12 +386,17 @@ export function getClaudeKeychainService(home) {
     const hash = createHash('sha256').update(configDir).digest('hex').slice(0, 8);
     return `${CLAUDE_KEYCHAIN_SERVICE}-${hash}`;
 }
+/**
+ * Check whether a requested org ID matches the live OAuth org ID.
+ * Returns true when either is absent (no filtering) or when they match.
+ */
 export function isClaudeUsageOrgMatch(requestedOrgId, liveOrgId) {
     const requested = normalizeString(requestedOrgId);
     const live = normalizeString(liveOrgId);
     return !requested || !live || requested === live;
 }
-export function readClaudeUsageCache(usageKey, cachePath = CLAUDE_USAGE_CACHE_PATH, now = new Date()) {
+/** Read a cached usage snapshot for a given usage key. Returns null if absent or stale. */
+export function readClaudeUsageCache(usageKey, cachePath = getClaudeUsageCachePath(), now = new Date()) {
     const cache = readClaudeUsageCacheFile(cachePath);
     const cached = cache[usageKey];
     if (!cached) {
@@ -368,11 +409,13 @@ export function readClaudeUsageCache(usageKey, cachePath = CLAUDE_USAGE_CACHE_PA
     }
     return snapshot;
 }
-export function writeClaudeUsageCache(usageKey, snapshot, cachePath = CLAUDE_USAGE_CACHE_PATH) {
+/** Write a usage snapshot to the on-disk cache. */
+export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeUsageCachePath()) {
     const cache = readClaudeUsageCacheFile(cachePath);
     cache[usageKey] = serializeClaudeUsageSnapshot(snapshot);
     writeClaudeUsageCacheFile(cache, cachePath);
 }
+/** Read the entire usage cache file from disk. */
 function readClaudeUsageCacheFile(cachePath) {
     if (!fs.existsSync(cachePath)) {
         return {};
@@ -385,6 +428,7 @@ function readClaudeUsageCacheFile(cachePath) {
         return {};
     }
 }
+/** Write the entire usage cache to disk. Best-effort; failures are silent. */
 function writeClaudeUsageCacheFile(cache, cachePath) {
     try {
         fs.mkdirSync(path.dirname(cachePath), { recursive: true });
@@ -394,6 +438,7 @@ function writeClaudeUsageCacheFile(cache, cachePath) {
         /* best-effort cache write */
     }
 }
+/** Convert a live UsageSnapshot to its JSON-serializable cached form. */
 function serializeClaudeUsageSnapshot(snapshot) {
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
@@ -407,18 +452,24 @@ function serializeClaudeUsageSnapshot(snapshot) {
         })),
     };
 }
+/** Deserialize a cached snapshot, zeroing out windows whose reset time has passed. */
 function deserializeClaudeUsageSnapshot(snapshot, now) {
     const capturedAt = parseDateValue(snapshot.capturedAt);
     const windows = snapshot.windows
-        .map((window) => ({
-        key: window.key,
-        label: window.label,
-        shortLabel: window.shortLabel,
-        usedPercent: window.usedPercent,
-        resetsAt: parseDateValue(window.resetsAt),
-        windowMinutes: window.windowMinutes,
-    }))
-        .filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
+        .map((window) => {
+        const w = {
+            key: window.key,
+            label: window.label,
+            shortLabel: window.shortLabel,
+            usedPercent: window.usedPercent,
+            resetsAt: parseDateValue(window.resetsAt),
+            windowMinutes: window.windowMinutes,
+        };
+        if (!isCachedUsageWindowFresh(w, capturedAt, now)) {
+            w.usedPercent = 0;
+        }
+        return w;
+    });
     if (windows.length === 0) {
         return null;
     }
@@ -429,6 +480,7 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         windows,
     };
 }
+/** Check whether a cached usage window is still relevant (not expired or reset). */
 function isCachedUsageWindowFresh(window, capturedAt, now) {
     if (window.resetsAt && window.resetsAt.getTime() <= now.getTime()) {
         return false;
@@ -441,6 +493,7 @@ function isCachedUsageWindowFresh(window, capturedAt, now) {
     }
     return true;
 }
+/** Obtain a valid access token, refreshing if expired. */
 async function getClaudeAccessToken(oauth) {
     const accessToken = oauth.accessToken?.trim();
     if (!accessToken) {
@@ -456,6 +509,7 @@ async function getClaudeAccessToken(oauth) {
     const refreshed = await refreshClaudeToken(oauth);
     return refreshed?.accessToken?.trim() || null;
 }
+/** Refresh an expired Claude OAuth access token using the refresh token. */
 async function refreshClaudeToken(oauth) {
     const response = await fetch(CLAUDE_TOKEN_URL, {
         method: 'POST',
@@ -484,27 +538,44 @@ async function refreshClaudeToken(oauth) {
         scopes: data.scope ? data.scope.split(/\s+/).filter(Boolean) : (oauth.scopes || CLAUDE_SCOPES),
     };
 }
+/**
+ * Check whether the Claude OAuth credentials for a given home are usable.
+ * Attempts a token refresh if the access token is expired.
+ * Returns true only when a valid access token can be obtained.
+ */
+export async function isClaudeAuthValid(home) {
+    const oauth = await loadClaudeOauth(home);
+    if (!oauth)
+        return false;
+    const token = await getClaudeAccessToken(oauth);
+    return token !== null;
+}
+/** Build a User-Agent string for Claude API requests. */
 function getClaudeUserAgent(cliVersion) {
     return cliVersion ? `claude-code/${cliVersion}` : 'claude-code';
 }
+/** Map an HTTP status code to a user-facing error message. */
 function formatClaudeUsageError(status) {
     if (status === 429) {
         return 'Usage data unavailable right now.';
     }
     return 'Could not load usage data right now.';
 }
+/** Clamp a numeric value to 0..100, returning null for non-finite values. */
 function normalizePercent(value) {
     if (typeof value !== 'number' || !Number.isFinite(value)) {
         return null;
     }
     return Math.max(0, Math.min(100, value));
 }
+/** Validate and return a positive window duration, or null. */
 function normalizeWindowMinutes(value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
         return null;
     }
     return value;
 }
+/** Infer the window duration in minutes from a well-known window key. */
 function inferWindowMinutes(key) {
     switch (key) {
         case 'session':
@@ -514,6 +585,7 @@ function inferWindowMinutes(key) {
             return 10080;
     }
 }
+/** Parse a date value from a number (epoch seconds or ms) or ISO string. */
 function parseDateValue(value) {
     if (value === null || value === undefined || value === '') {
         return null;
@@ -531,27 +603,33 @@ function parseDateValue(value) {
     }
     return null;
 }
+/** Trim and return a string, or null if empty/non-string. */
 function normalizeString(value) {
     if (typeof value !== 'string')
         return null;
     const trimmed = value.trim();
     return trimmed || null;
 }
+/** Render a full-width usage bar for detailed views. */
 function renderUsageBar(usedPercent) {
     return renderBar(usedPercent, USAGE_BAR_LEN);
 }
+/** Render a compact usage bar for inline summaries. */
 function renderCompactUsageBar(usedPercent) {
     return renderBar(usedPercent, COMPACT_BAR_LEN, usedPercent > 0 ? 1 : 0);
 }
+/** Render a colored block-character progress bar. */
 function renderBar(usedPercent, length, minimumVisible = 0) {
     const rounded = Math.round((usedPercent / 100) * length);
     const filled = Math.max(minimumVisible, Math.max(0, Math.min(length, rounded)));
     const color = getUsageColor(usedPercent);
     return color(FULL.repeat(filled)) + chalk.dim(EMPTY.repeat(length - filled));
 }
+/** Apply the appropriate color to a text string based on usage percentage. */
 function colorUsage(text, usedPercent) {
     return getUsageColor(usedPercent)(text);
 }
+/** Return a chalk color function based on the usage percentage threshold. */
 function getUsageColor(usedPercent) {
     if (usedPercent >= 100)
         return chalk.red;
@@ -559,10 +637,12 @@ function getUsageColor(usedPercent) {
         return chalk.yellow;
     return chalk.cyan;
 }
+/** Format a percentage value with at most one decimal place. */
 function formatPercent(value) {
     const rounded = Math.round(value * 10) / 10;
     return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
 }
+/** Format a reset timestamp as a human-readable relative or absolute time. */
 function formatResetAt(date) {
     const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
     const now = new Date();
@@ -587,6 +667,7 @@ function formatResetAt(date) {
     }
     return `${date.toLocaleString('en-US', options)} (${timezone})`;
 }
+/** Safe wrapper around fs.realpathSync that returns null on error. */
 function safeRealpathSync(filePath) {
     try {
         return fs.realpathSync(filePath);
@@ -595,6 +676,7 @@ function safeRealpathSync(filePath) {
         return null;
     }
 }
+/** Safe wrapper around fs.statSync that returns null on error. */
 function safeStatSync(filePath) {
     try {
         return fs.statSync(filePath);
@@ -603,4 +685,3 @@ function safeStatSync(filePath) {
         return null;
     }
 }
-//# sourceMappingURL=usage.js.map

package/dist/lib/version-duplicates.d.ts

@@ -0,0 +1,21 @@
+import { type AccountInfo } from './agents.js';
+import type { AgentId } from './types.js';
+export interface VersionAccountEntry {
+    version: string;
+    info: AccountInfo;
+}
+export interface NewerDuplicateVersion {
+    version: string;
+    email: string | null;
+    plan: string | null;
+}
+/**
+ * Return installed versions newer than selectedVersion that share the same
+ * account identity. This is intentionally pure so command output can share one
+ * duplicate rule with tests.
+ */
+export declare function findNewerDuplicateVersions(entries: VersionAccountEntry[], selectedVersion: string): NewerDuplicateVersion[];
+/** Collect account info for an agent and find newer duplicates of selectedVersion. */
+export declare function getNewerDuplicateVersions(agentId: AgentId, selectedVersion: string): Promise<NewerDuplicateVersion[]>;
+/** Format the non-interactive guidance shown by view/run when duplicates exist. */
+export declare function formatNewerDuplicateNotice(agentId: AgentId, selectedVersion: string, duplicates: NewerDuplicateVersion[], selectedLabel?: string): string;

package/dist/lib/version-duplicates.js

@@ -0,0 +1,90 @@
+import chalk from 'chalk';
+import { getAccountInfo, agentLabel } from './agents.js';
+import { compareVersions, getVersionHomePath, listInstalledVersions, } from './versions.js';
+import { getUsageInfoByIdentity, getUsageLookupKey, } from './usage.js';
+function duplicateIdentity(info) {
+    if (!info)
+        return null;
+    const usageKey = getUsageLookupKey(info);
+    if (usageKey)
+        return usageKey;
+    return info.email ? `email:${info.email.toLowerCase()}` : null;
+}
+/**
+ * Return installed versions newer than selectedVersion that share the same
+ * account identity. This is intentionally pure so command output can share one
+ * duplicate rule with tests.
+ */
+export function findNewerDuplicateVersions(entries, selectedVersion) {
+    const selected = entries.find((entry) => entry.version === selectedVersion);
+    const selectedIdentity = duplicateIdentity(selected?.info);
+    if (!selectedIdentity)
+        return [];
+    return entries
+        .filter((entry) => entry.version !== selectedVersion &&
+        compareVersions(entry.version, selectedVersion) > 0 &&
+        duplicateIdentity(entry.info) === selectedIdentity)
+        .sort((a, b) => compareVersions(b.version, a.version))
+        .map((entry) => ({
+        version: entry.version,
+        email: entry.info.email,
+        plan: entry.info.plan,
+    }));
+}
+/** Collect account info for an agent and find newer duplicates of selectedVersion. */
+export async function getNewerDuplicateVersions(agentId, selectedVersion) {
+    const rows = await Promise.all(listInstalledVersions(agentId).map(async (version) => {
+        const home = getVersionHomePath(agentId, version);
+        const info = await getAccountInfo(agentId, home);
+        return { version, home, info };
+    }));
+    const { canonicalByUsageKey } = await getUsageInfoByIdentity(rows.map(({ version, home, info }) => ({
+        agentId,
+        home,
+        cliVersion: version,
+        info,
+    })));
+    const entries = rows.map(({ version, info }) => {
+        const key = getUsageLookupKey(info);
+        const canon = key ? canonicalByUsageKey.get(key) : undefined;
+        return {
+            version,
+            info: canon
+                ? {
+                    ...info,
+                    plan: canon.plan,
+                    usageStatus: canon.usageStatus,
+                    overageCredits: canon.overageCredits,
+                }
+                : info,
+        };
+    });
+    return findNewerDuplicateVersions(entries, selectedVersion);
+}
+/** Format the non-interactive guidance shown by view/run when duplicates exist. */
+export function formatNewerDuplicateNotice(agentId, selectedVersion, duplicates, selectedLabel = '') {
+    if (duplicates.length === 0)
+        return '';
+    const versionLabel = selectedLabel
+        ? `${selectedLabel} ${agentLabel(agentId)}@${selectedVersion}`
+        : `${agentLabel(agentId)}@${selectedVersion}`;
+    const plural = duplicates.length === 1 ? 'duplicate' : 'duplicates';
+    const maxVersion = Math.max(...duplicates.map((duplicate) => duplicate.version.length));
+    const maxEmail = Math.max(0, ...duplicates.map((duplicate) => duplicate.email?.length ?? 0));
+    const lines = [
+        `Found ${duplicates.length} newer ${plural} for ${versionLabel}:`,
+    ];
+    for (const duplicate of duplicates) {
+        const parts = [`  ${duplicate.version.padEnd(maxVersion)}`];
+        if (maxEmail > 0) {
+            parts.push(duplicate.email ? chalk.cyan(duplicate.email.padEnd(maxEmail)) : ''.padEnd(maxEmail));
+        }
+        if (duplicate.plan) {
+            parts.push(duplicate.plan);
+        }
+        lines.push(parts.join('  '));
+    }
+    lines.push('');
+    lines.push(`Run: agents use ${agentId}@${duplicates[0].version}`);
+    return lines.join('\n');
+}

package/dist/lib/versions.d.ts

@@ -18,6 +18,11 @@ export interface ResourceSelection {
 }
 /**
  * Available resources in ~/.agents/ for syncing.
+ *
+ * `promptcuts` is a boolean, not a list — there is at most one
+ * ~/.agents/promptcuts.yaml file. It is NOT version-scoped: the
+ * expand-promptcuts hook reads it directly, so no per-version copy
+ * is made and no sync step is needed.
  */
 export interface AvailableResources {
     commands: string[];
@@ -28,6 +33,7 @@ export interface AvailableResources {
     permissions: string[];
     subagents: string[];
     plugins: string[];
+    promptcuts: boolean;
 }
 /**
  * Get all available resources from ~/.agents/.
@@ -60,6 +66,7 @@ export declare function promptNewResourceSelection(agent: AgentId, newResources:
  * Returns the selection, or null if user cancels.
  */
 export declare function promptResourceSelection(agent: AgentId): Promise<ResourceSelection | null>;
+/** Parsed agent@version specification from CLI input. */
 export interface AgentSpec {
     agent: AgentId;
     version: string;
@@ -121,11 +128,14 @@ export declare function installVersion(agent: AgentId, version: string, onProgre
     error?: string;
 }>;
 /**
- * Remove a specific version of an agent.
+ * Remove a specific version of an agent. Preserves `home/` under the version
+ * directory so conversation history survives reinstalls.
  */
 export declare function removeVersion(agent: AgentId, version: string): boolean;
 /**
- * Remove all versions of an agent.
+ * Remove all versions of an agent. Preserves each version's `home/` directory
+ * so conversation history is never deleted; the per-version folders (now
+ * containing only `home/`) remain under the agent dir.
  */
 export declare function removeAllVersions(agent: AgentId): number;
 /**
@@ -134,7 +144,28 @@ export declare function removeAllVersions(agent: AgentId): number;
  */
 export declare function resolveVersion(agent: AgentId, projectPath?: string): string | null;
 /**
- * Get version specified in project manifest.
+ * Normalize a user-supplied @version token across CLI subcommands.
+ *
+ *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
+ *   "latest"                    -> highest installed version (process.exit if none installed)
+ *   "x.y.z" (installed)         -> "x.y.z"
+ *   "x.y.z" (not installed)     -> process.exit with installed-list hint
+ *
+ * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
+ * vocabulary consistent. Subcommands with different semantics for `latest`
+ * (install/remove/use, where `latest` means npm-latest) keep their existing
+ * parsing.
+ */
+export declare function resolveVersionAlias(agent: AgentId, raw: string | undefined | null): string | undefined;
+/**
+ * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
+ * team history). Same `default`/`latest` semantics, but explicit versions
+ * pass through unchanged so historical records of uninstalled versions remain
+ * queryable.
+ */
+export declare function resolveVersionAliasLoose(agent: AgentId, raw: string | undefined | null): string | undefined;
+/**
+ * Get version specified in a project-root agents.yaml (not the user ~/.agents-system/agents.yaml).
  */
 export declare function getProjectVersion(agent: AgentId, startPath: string): string | null;
 /**
@@ -145,6 +176,7 @@ export declare function compareVersions(a: string, b: string): number;
  * Get actual version from an installed 'latest' directory.
  */
 export declare function getInstalledVersion(agent: AgentId, version: string): Promise<string | null>;
+/** Outcome of syncing resources to a version home, keyed by resource type. */
 export interface SyncResult {
     commands: boolean;
     skills: boolean;
@@ -155,6 +187,7 @@ export interface SyncResult {
     subagents: string[];
     plugins: string[];
 }
+/** Diff between central ~/.agents/ resources and what is synced to a version home. */
 export interface ResourceDiff {
     commands: {
         added: string[];
@@ -193,6 +226,7 @@ export declare function getResourceDiff(agent: AgentId, version: string): Resour
 export declare function syncResourcesToVersion(agent: AgentId, version: string, selection?: ResourceSelection, options?: {
     projectDir?: string;
     cwd?: string;
+    force?: boolean;
 }): SyncResult;
 /**
  * Get the effective HOME directory for an agent.
@@ -200,10 +234,12 @@ export declare function syncResourcesToVersion(agent: AgentId, version: string,
  * Otherwise returns the real HOME.
  */
 export declare function getEffectiveHome(agentId: AgentId): string;
+/** Result of resolving agent/version targets from CLI input or interactive selection. */
 export interface VersionSelectionResult {
     selectedAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }
+/** Extended target result that distinguishes managed versions from direct (unmanaged) agent homes. */
 export interface InstalledAgentTargetResult {
     selectedAgents: AgentId[];
     directAgents: AgentId[];
@@ -239,4 +275,3 @@ export declare function resolveConfiguredAgentTargets(agents: readonly AgentId[]
 export declare function promptAgentVersionSelection(availableAgents: AgentId[], options?: {
     skipPrompts?: boolean;
 }): Promise<VersionSelectionResult>;
-//# sourceMappingURL=versions.d.ts.map