@phnx-labs/agents-cli 1.20.70 → 1.20.72

package/dist/lib/uninstall.js

@@ -0,0 +1,347 @@
+/**
+ * Complete teardown of agents-cli — the reverse of `agents setup`.
+ *
+ * The hard part is undoing "adoption": normal installs move the user's real
+ * `~/.<agent>` aside and replace it with a symlink into agents-cli's version
+ * homes (see `switchConfigSymlink` / `importAgent`). A clean uninstall must put
+ * those real directories back, release any adopted launchers, strip the shim
+ * directory from the user's PATH, and only then dispose of `~/.agents`.
+ *
+ * Safety invariant: a `~/.<agent>` that agents-cli never adopted is a REAL user
+ * directory and is never touched. Ownership is decided structurally by
+ * `getConfigSymlinkVersion` (non-null only for a symlink into our versions dir),
+ * exactly as `removeVersion` does it — no marker files, no guessing.
+ *
+ * This module is split into a read-only {@link planUninstall} and a mutating
+ * {@link executeUninstall} so `--dry-run` and the real run share one code path.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { AGENTS, ALL_AGENT_IDS } from './agents.js';
+import { getAgentConfigPath, getConfigSymlinkVersion, stripShimPathLines, releaseAdoptedLauncher, } from './shims.js';
+import { getUserAgentsDir, getBackupsDir, getHistoryDir, getShimsDir, getLegacySystemAgentsDir, } from './state.js';
+/** Home dir honoring the AGENTS_REAL_HOME test/override, mirroring shims.ts. */
+function realHome() {
+    return process.env.AGENTS_REAL_HOME || os.homedir();
+}
+/** Newest timestamped backup dir under `<backups>/<agent>/`, or null. */
+function newestBackupDir(agent) {
+    const dir = path.join(getBackupsDir(), agent);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir).filter((n) => /^\d+$/.test(n));
+    }
+    catch {
+        return null;
+    }
+    if (entries.length === 0)
+        return null;
+    entries.sort((a, b) => Number(a) - Number(b));
+    return path.join(dir, entries[entries.length - 1]);
+}
+/** Absolute target of a symlink, or null if `p` is not a readable symlink. */
+function symlinkTarget(p) {
+    try {
+        const raw = fs.readlinkSync(p);
+        return path.resolve(path.dirname(p), raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove a symlink/junction at `p` without following into its target. On POSIX
+ * this is a plain `unlinkSync`; on Windows the same call correctly deletes a
+ * junction or directory-symlink reparse point while leaving the target intact —
+ * verified on a real Windows host, where `fs.rmSync(p, { force: true })` instead
+ * throws `EFAULT` on a reparse point. `rmSync` is deliberately NOT used here.
+ */
+function removeLink(p) {
+    fs.unlinkSync(p);
+}
+/**
+ * Move `source` onto `dest` across possibly-different volumes. `renameSync` is
+ * atomic but throws EXDEV when `~/.agents` lives on a different filesystem than
+ * `$HOME`; fall back to copy-then-remove so the restore still completes. The
+ * source (a backup inside `~/.agents`) is removed only after the copy succeeds,
+ * so a mid-copy failure never destroys the sole surviving copy.
+ */
+function moveDirCrossDevice(source, dest) {
+    try {
+        fs.renameSync(source, dest);
+    }
+    catch (err) {
+        if (err.code !== 'EXDEV')
+            throw err;
+        fs.cpSync(source, dest, { recursive: true });
+        fs.rmSync(source, { recursive: true, force: true });
+    }
+}
+/**
+ * Copy `source` to `dest`, dropping any symlink whose target resolves back into
+ * `~/.agents`. Adoption syncs managed resources (skills/commands) into the
+ * version home as symlinks into `~/.agents`; copying them verbatim would leave
+ * the restored config full of links that dangle the moment `~/.agents` is
+ * disposed. Stripping them yields a clean, self-contained restore.
+ */
+function copyDirStrippingAgentsSymlinks(source, dest, agentsDir) {
+    const inside = agentsDir + path.sep;
+    fs.cpSync(source, dest, {
+        recursive: true,
+        filter: (src) => {
+            try {
+                const st = fs.lstatSync(src);
+                if (st.isSymbolicLink()) {
+                    const tgt = path.resolve(path.dirname(src), fs.readlinkSync(src));
+                    if (tgt === agentsDir || tgt.startsWith(inside))
+                        return false;
+                }
+            }
+            catch {
+                /* unreadable entry — let cpSync surface it on the real copy */
+            }
+            return true;
+        },
+    });
+}
+/** Classify one agent's config dir without mutating anything. */
+function planConfig(agent) {
+    const realPath = getAgentConfigPath(agent);
+    let stat;
+    try {
+        stat = fs.lstatSync(realPath);
+    }
+    catch {
+        return { agent, realPath, kind: 'absent' };
+    }
+    // A real directory means agents-cli never adopted it — leave it alone.
+    if (!stat.isSymbolicLink())
+        return { agent, realPath, kind: 'leave-real' };
+    // A symlink we don't own (target not under our versions dir) — leave it alone.
+    if (getConfigSymlinkVersion(agent) === null)
+        return { agent, realPath, kind: 'leave-foreign' };
+    // Owned symlink: prefer the timestamped backup (switchConfigSymlink moved the
+    // real dir there); otherwise the symlink target itself holds the user's data
+    // (importAgent renamed the real dir INTO the version home).
+    const backup = newestBackupDir(agent);
+    if (backup)
+        return { agent, realPath, kind: 'restore-backup', source: backup };
+    const target = symlinkTarget(realPath);
+    if (target && fs.existsSync(target)) {
+        return { agent, realPath, kind: 'restore-version-home', source: target };
+    }
+    return { agent, realPath, kind: 'remove-dangling' };
+}
+/** Owned home-file symlinks (e.g. `~/.claude.json`) to copy back as real files. */
+function planHomeFiles() {
+    const home = realHome();
+    const userDir = getUserAgentsDir();
+    const out = [];
+    for (const agent of ALL_AGENT_IDS) {
+        const homeFiles = AGENTS[agent].homeFiles;
+        if (!homeFiles)
+            continue;
+        for (const fileName of homeFiles) {
+            const realPath = path.join(home, fileName);
+            let stat;
+            try {
+                stat = fs.lstatSync(realPath);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isSymbolicLink())
+                continue;
+            const target = symlinkTarget(realPath);
+            // Only ours (points into ~/.agents) and only if the target still exists.
+            if (target && target.startsWith(userDir + path.sep) && fs.existsSync(target)) {
+                out.push({ realPath, source: target });
+            }
+        }
+    }
+    return out;
+}
+/** cliCommand basenames that have an adopted-launcher record to release. */
+function planLaunchers() {
+    const dir = path.join(getHistoryDir(), 'adopted-launchers');
+    try {
+        return fs.readdirSync(dir).filter((n) => !n.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Candidate shell rc files that currently contain a shim PATH entry. */
+function planRcFiles() {
+    const home = realHome();
+    const shimsDir = getShimsDir();
+    const candidates = ['.zshrc', '.bashrc', '.bash_profile', '.profile', path.join('.config', 'fish', 'config.fish')];
+    const out = [];
+    for (const rel of candidates) {
+        const rc = path.join(home, rel);
+        let content;
+        try {
+            content = fs.readFileSync(rc, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        if (stripShimPathLines(content, shimsDir) !== content)
+            out.push(rc);
+    }
+    return out;
+}
+/**
+ * Build a read-only plan of everything a complete uninstall would change.
+ * Performs no mutations; safe to run for `--dry-run` and to print for confirm.
+ */
+export function planUninstall() {
+    const agentsDir = getUserAgentsDir();
+    const legacy = getLegacySystemAgentsDir();
+    let legacySymlink = null;
+    try {
+        // Only claim it if it's actually a link (symlink on POSIX, junction on Windows —
+        // both report isSymbolicLink()); a real directory here is left alone so removeLink
+        // (unlinkSync) is always the correct primitive for what we captured.
+        if (fs.lstatSync(legacy).isSymbolicLink())
+            legacySymlink = legacy;
+    }
+    catch {
+        legacySymlink = null;
+    }
+    return {
+        isInstalled: fs.existsSync(agentsDir),
+        agentsDir,
+        legacySymlink,
+        configs: ALL_AGENT_IDS.map(planConfig),
+        homeFiles: planHomeFiles(),
+        launchers: planLaunchers(),
+        rcFiles: planRcFiles(),
+    };
+}
+/**
+ * Execute a plan built by {@link planUninstall}. Restores adopted config dirs
+ * and home files, releases adopted launchers, strips shim PATH lines, then
+ * disposes of `~/.agents` — moved aside to `~/.agents.removed-<ts>` (recoverable)
+ * by default, or hard-deleted when `purge` is set. Config restore always runs
+ * before disposal because the backups live inside `~/.agents`.
+ */
+export function executeUninstall(plan, opts) {
+    const result = {
+        restoredConfigs: [],
+        removedDanglingConfigs: [],
+        restoredHomeFiles: [],
+        releasedLaunchers: [],
+        cleanedRcFiles: [],
+        agentsDir: { path: plan.agentsDir, disposition: 'absent' },
+        legacySymlinkRemoved: false,
+        purgeDowngraded: false,
+        errors: [],
+    };
+    // 1. Restore adopted config directories (reads backups inside ~/.agents).
+    for (const c of plan.configs) {
+        try {
+            if (c.kind === 'restore-backup') {
+                // The adopted link carries no data (the real dir is the backup); drop it,
+                // then move the backup out of ~/.agents onto the real path — EXDEV-safe so a
+                // cross-volume ~/.agents can't strand the backup mid-restore. unlinkSync (not
+                // rmSync) is deliberate: it removes a POSIX symlink AND a Windows junction/
+                // dir-symlink without following into the target, whereas rmSync throws EFAULT
+                // on a Windows reparse point.
+                removeLink(c.realPath);
+                moveDirCrossDevice(c.source, c.realPath);
+                result.restoredConfigs.push({ agent: c.agent, realPath: c.realPath });
+            }
+            else if (c.kind === 'restore-version-home') {
+                // importAgent renamed the real dir INTO the version home; copy it back
+                // (step 6 disposes the original) while stripping resource symlinks that
+                // would dangle once ~/.agents is gone.
+                removeLink(c.realPath);
+                copyDirStrippingAgentsSymlinks(c.source, c.realPath, plan.agentsDir);
+                result.restoredConfigs.push({ agent: c.agent, realPath: c.realPath });
+            }
+            else if (c.kind === 'remove-dangling') {
+                removeLink(c.realPath);
+                result.removedDanglingConfigs.push({ agent: c.agent, realPath: c.realPath });
+            }
+            // leave-real / leave-foreign / absent: intentionally untouched.
+        }
+        catch (err) {
+            result.errors.push(`config ${c.agent} (${c.realPath}): ${err.message}`);
+        }
+    }
+    // 2. Restore owned home-file symlinks as real files (e.g. ~/.claude.json).
+    for (const hf of plan.homeFiles) {
+        try {
+            removeLink(hf.realPath);
+            fs.cpSync(hf.source, hf.realPath, { recursive: true });
+            result.restoredHomeFiles.push(hf.realPath);
+        }
+        catch (err) {
+            result.errors.push(`home file ${hf.realPath}: ${err.message}`);
+        }
+    }
+    // 3. Release adopted launchers (reads records inside ~/.agents).
+    const byCli = new Map(ALL_AGENT_IDS.map((a) => [AGENTS[a].cliCommand, a]));
+    for (const cli of plan.launchers) {
+        const agent = byCli.get(cli);
+        if (!agent)
+            continue;
+        try {
+            releaseAdoptedLauncher(agent);
+            result.releasedLaunchers.push(cli);
+        }
+        catch (err) {
+            result.errors.push(`launcher ${cli}: ${err.message}`);
+        }
+    }
+    // 4. Strip the shim directory from the user's PATH across all rc files.
+    const shimsDir = getShimsDir();
+    for (const rc of plan.rcFiles) {
+        try {
+            const content = fs.readFileSync(rc, 'utf-8');
+            fs.writeFileSync(rc, stripShimPathLines(content, shimsDir));
+            result.cleanedRcFiles.push(rc);
+        }
+        catch (err) {
+            result.errors.push(`rc file ${rc}: ${err.message}`);
+        }
+    }
+    // 5. Remove the legacy back-compat symlink, if present. `~/.agents-system` is a
+    // link (junction on Windows — createLink uses 'junction' for a dir source), so it
+    // goes through removeLink for the same reason as the config links: rmSync throws
+    // EFAULT on a Windows reparse point.
+    if (plan.legacySymlink) {
+        try {
+            removeLink(plan.legacySymlink);
+            result.legacySymlinkRemoved = true;
+        }
+        catch (err) {
+            result.errors.push(`legacy ${plan.legacySymlink}: ${err.message}`);
+        }
+    }
+    // 6. Dispose of ~/.agents LAST (its backups fed step 1). If any restore above
+    // failed, downgrade a --purge to a recoverable move-aside: a swallowed restore
+    // error must never let the hard-delete take the user's only copy with it.
+    if (fs.existsSync(plan.agentsDir)) {
+        const purge = !!opts.purge && result.errors.length === 0;
+        if (opts.purge && !purge)
+            result.purgeDowngraded = true;
+        try {
+            if (purge) {
+                fs.rmSync(plan.agentsDir, { recursive: true, force: true });
+                result.agentsDir = { path: plan.agentsDir, disposition: 'purged' };
+            }
+            else {
+                const movedTo = `${plan.agentsDir}.removed-${opts.timestamp}`;
+                fs.renameSync(plan.agentsDir, movedTo);
+                result.agentsDir = { path: plan.agentsDir, disposition: 'moved', movedTo };
+            }
+        }
+        catch (err) {
+            result.errors.push(`dispose ${plan.agentsDir}: ${err.message}`);
+        }
+    }
+    return result;
+}

package/dist/lib/usage.d.ts

@@ -1,5 +1,17 @@
 import { type AccountInfo } from './agents.js';
 import type { AgentId } from './types.js';
+/**
+ * True when a Claude OAuth access token is within the refresh leeway of expiry
+ * (or already expired) — i.e. it "would need a refresh" before the next use.
+ *
+ * Single source of truth for the expiry gate, shared by the two callers that
+ * must agree on it but act differently: the run/usage hot path
+ * (`getClaudeAccessToken`) refreshes when this is true; the health probe
+ * (`probeClaudeStatus`) must NOT refresh and instead reports the non-fatal
+ * `expired` state (RUSH-1822). A missing `expiresAt` is treated as "still
+ * fresh" (never force a refresh on a token with no known expiry).
+ */
+export declare function claudeAccessTokenNeedsRefresh(expiresAt: number | null | undefined, nowMs?: number): boolean;
 /** Discriminator for usage window types. */
 export type UsageWindowKey = 'session' | 'week' | 'sonnet_week' | 'month';
 /** A single rate-limit window with utilization percentage and reset time. */
@@ -201,7 +213,7 @@ export interface ProviderProbe {
     /** Network/parse error message when status is null but a token was present. */
     error?: string;
 }
-/** Probe Claude's OAuth token against the usage endpoint. Refreshes an expired access token (safe for Claude). */
+/** Probe Claude's OAuth token against the usage endpoint. Never refreshes — reports `expired` for a near-expiry token; see the comment below (RUSH-1822). */
 export declare function probeClaudeStatus(home?: string, cliVersion?: string | null): Promise<ProviderProbe>;
 /** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
 export declare function probeKimiStatus(home?: string): Promise<ProviderProbe>;

package/dist/lib/usage.js

@@ -25,6 +25,22 @@ const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
 const CLAUDE_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
 const CLAUDE_OAUTH_BETA_HEADER = 'oauth-2025-04-20';
 const CLAUDE_REFRESH_LEEWAY_MS = 5 * 60 * 1000;
+/**
+ * True when a Claude OAuth access token is within the refresh leeway of expiry
+ * (or already expired) — i.e. it "would need a refresh" before the next use.
+ *
+ * Single source of truth for the expiry gate, shared by the two callers that
+ * must agree on it but act differently: the run/usage hot path
+ * (`getClaudeAccessToken`) refreshes when this is true; the health probe
+ * (`probeClaudeStatus`) must NOT refresh and instead reports the non-fatal
+ * `expired` state (RUSH-1822). A missing `expiresAt` is treated as "still
+ * fresh" (never force a refresh on a token with no known expiry).
+ */
+export function claudeAccessTokenNeedsRefresh(expiresAt, nowMs = Date.now()) {
+    if (expiresAt == null)
+        return false;
+    return nowMs + CLAUDE_REFRESH_LEEWAY_MS >= expiresAt;
+}
 const CLAUDE_SCOPES = [
     'user:profile',
     'user:inference',
@@ -609,26 +625,29 @@ async function getDroidUsageInfo(options) {
         return { snapshot: null, error: null };
     }
 }
-/** Probe Claude's OAuth token against the usage endpoint. Refreshes an expired access token (safe for Claude). */
+/** Probe Claude's OAuth token against the usage endpoint. Never refreshes — reports `expired` for a near-expiry token; see the comment below (RUSH-1822). */
 export async function probeClaudeStatus(home, cliVersion) {
     const oauth = await loadClaudeOauth(home);
-    if (!oauth?.accessToken)
+    const accessToken = oauth?.accessToken?.trim();
+    if (!accessToken)
         return { status: null, token: 'missing' };
-    let access = null;
-    try {
-        access = await getClaudeAccessToken(oauth, home);
-    }
-    catch {
-        access = null;
+    // Never refresh from a health probe. Claude's refresh token is single-use and
+    // rotates on every refresh; with one account signed into several machines the
+    // daemon's every-3-min fleet-cache warm (probeLocalFleetAuth -> here) would
+    // stampede that one rotating token and silently invalidate every other
+    // holder, dropping the fleet to "run /login" (RUSH-1822). Mirror the sibling
+    // Kimi/Droid probes, which never refresh: if the stored token is within the
+    // refresh leeway of expiry, report the non-fatal `expired` state ("would need
+    // a refresh") instead of rotating it, and leave the single legitimate refresh
+    // to the run/usage hot path (getClaudeAccessToken).
+    if (claudeAccessTokenNeedsRefresh(oauth?.expiresAt ?? null)) {
+        return { status: null, token: 'expired' };
     }
-    // Fall back to the stored (possibly stale) token so the server returns the
-    // real verdict — a 401 here IS the revoked/expired signal we want to surface.
-    const bearer = access || oauth.accessToken.trim();
     try {
         const response = await fetch(CLAUDE_USAGE_URL, {
             method: 'GET',
             headers: {
-                Authorization: `Bearer ${bearer}`,
+                Authorization: `Bearer ${accessToken}`,
                 'Content-Type': 'application/json',
                 'anthropic-beta': CLAUDE_OAUTH_BETA_HEADER,
                 'User-Agent': getClaudeUserAgent(cliVersion),
@@ -1058,8 +1077,7 @@ async function getClaudeAccessToken(oauth, home) {
     if (!accessToken) {
         return null;
     }
-    const expiresAt = oauth.expiresAt ?? null;
-    if (expiresAt === null || Date.now() + CLAUDE_REFRESH_LEEWAY_MS < expiresAt) {
+    if (!claudeAccessTokenNeedsRefresh(oauth.expiresAt ?? null)) {
         return accessToken;
     }
     if (!oauth.refreshToken) {

package/dist/lib/versions.d.ts

@@ -216,6 +216,22 @@ export declare function getGlobalDefault(agent: AgentId): string | null;
  * Set the global default version for an agent.
  */
 export declare function setGlobalDefault(agent: AgentId, version: string | undefined): void;
+/**
+ * Mark an installed version as an isolated install (`agents add --isolated`).
+ *
+ * Isolated versions are fully self-contained: they never become the global
+ * default and never own the user's real `~/.<agent>` config directory. This
+ * flag is what keeps every "adopting" code path away from them.
+ */
+export declare function markVersionIsolated(agent: AgentId, version: string): void;
+/**
+ * Whether a version was installed as an isolated install (`agents add --isolated`).
+ *
+ * Used to exclude such versions from global-default promotion and from any
+ * flow that would touch the user's real `~/.<agent>` directory, and to gate the
+ * `--isolated` safety check on `agents remove`.
+ */
+export declare function isVersionIsolated(agent: AgentId, version: string): boolean;
 /**
  * Install a specific version of an agent.
  */

package/dist/lib/versions.js

@@ -1148,6 +1148,37 @@ export function setGlobalDefault(agent, version) {
     }
     writeMeta(meta);
 }
+/**
+ * Path to the sentinel file that marks a version as an isolated install.
+ *
+ * It lives at the version-dir root (a sibling of `home/`), so it is carried
+ * along when `softDeleteVersionDir` moves the whole directory to trash and is
+ * restored intact by `agents trash restore`. Its mere presence is the marker;
+ * the contents are an informational timestamp only.
+ */
+function getIsolatedMarkerPath(agent, version) {
+    return path.join(getVersionDir(agent, version), '.isolated');
+}
+/**
+ * Mark an installed version as an isolated install (`agents add --isolated`).
+ *
+ * Isolated versions are fully self-contained: they never become the global
+ * default and never own the user's real `~/.<agent>` config directory. This
+ * flag is what keeps every "adopting" code path away from them.
+ */
+export function markVersionIsolated(agent, version) {
+    fs.writeFileSync(getIsolatedMarkerPath(agent, version), `${new Date().toISOString()}\n`, { mode: 0o600 });
+}
+/**
+ * Whether a version was installed as an isolated install (`agents add --isolated`).
+ *
+ * Used to exclude such versions from global-default promotion and from any
+ * flow that would touch the user's real `~/.<agent>` directory, and to gate the
+ * `--isolated` safety check on `agents remove`.
+ */
+export function isVersionIsolated(agent, version) {
+    return fs.existsSync(getIsolatedMarkerPath(agent, version));
+}
 /**
  * Grok's official installer writes into ~/.grok/downloads, which (because we
  * symlink ~/.grok to the active version home) resolves to the PREVIOUS default
@@ -1676,14 +1707,20 @@ export function removeVersion(agent, version) {
     // broke every launcher after removing the pinned default.
     if (getGlobalDefault(agent) === version) {
         const remaining = listInstalledVersions(agent);
-        if (remaining.length > 0) {
-            const newestRemaining = remaining[remaining.length - 1];
+        // Never auto-promote an isolated install to the global default: it was
+        // installed to stay separate from the user's setup, and promoting it would
+        // silently make `<agent>` resolve to it (and let a later `use` adopt its
+        // home into `~/.<agent>`). Prefer the newest NON-isolated survivor; if every
+        // survivor is isolated, clear the default rather than adopt one.
+        const promotable = remaining.filter((v) => !isVersionIsolated(agent, v));
+        if (promotable.length > 0) {
+            const newestRemaining = promotable[promotable.length - 1];
             setGlobalDefault(agent, newestRemaining);
             console.log(chalk.yellow(`Default ${agent} was ${version} (removed); reassigned to ${newestRemaining}. Change it with: agents use ${agent}@<version>`));
         }
         else {
             setGlobalDefault(agent, undefined);
-            console.log(chalk.yellow(`Removed the last installed ${agent} version and cleared its default. Reinstall with: agents add ${agent}, then set one with: agents use ${agent}@<version>`));
+            console.log(chalk.yellow(`Removed the last non-isolated ${agent} version and cleared its default. Reinstall with: agents add ${agent}, then set one with: agents use ${agent}@<version>`));
         }
     }
     // Clean up dangling config symlink if it pointed to the removed version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.70",
+  "version": "1.20.72",
   "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",