@phnx-labs/agents-cli 1.20.71 → 1.20.73

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/version.d.ts

@@ -1,8 +1,48 @@
+/**
+ * Well-known locations of the `agents` launcher for PATH-less GUI/launchd
+ * processes (the menu-bar helper inherits no login PATH). Also the anchor for
+ * recovering the on-disk install layout when the CLI runs as a Bun single-file
+ * binary — see {@link resolveInstalledLayout}.
+ */
+export declare function resolveAgentsBin(): string | null;
+export interface InstallLayout {
+    /** The install's `dist/` directory (holds `index.js` + `lib/`). */
+    distDir: string;
+    /** The compiled CLI entry, `dist/index.js`. */
+    entryPath: string;
+    /** The shipping `package.json`, `dist/../package.json`. */
+    pkgJsonPath: string;
+}
+/**
+ * Pure derivation (no I/O) of an install's on-disk layout from the realpath of
+ * its `agents` launcher. A launcher lives at `<pkg>/dist/bin/agents`, so two
+ * levels up is `<pkg>/dist`. Exported for unit testing so the dirname chain the
+ * Bun-binary fallback depends on stays locked.
+ */
+export declare function installLayoutFromBin(realBin: string): InstallLayout;
+/**
+ * Resolve the on-disk install layout of the running CLI by following the
+ * `agents` launcher symlink.
+ *
+ * When the CLI runs as a Bun single-file executable, `import.meta.url` points
+ * inside the virtual bundle (`/$bunfs/…`), so sibling-relative resolution can't
+ * see the shipped `package.json`, `dist/index.js`, or `MenubarHelper.app` on
+ * disk. The launcher symlink points at the real files; walk up from it. Returns
+ * null when no launcher is found (dev/tsx runs, or a box without the helper) —
+ * callers keep their in-bundle resolution as the primary path and use this only
+ * as the fallback.
+ */
+export declare function resolveInstalledLayout(): InstallLayout | null;
 /**
  * Resolve the CLI version from the shipping package.json. Used by the daemon
  * to answer `IPCAction: 'version'` and by the client to detect daemon drift —
  * a dev-build CLI talking to a launchd-managed registry daemon would silently
  * get stale behavior without this check.
+ *
+ * Primary read is relative to this module; when that fails (the Bun single-file
+ * binary can't read its own bundled package.json), fall back to the on-disk
+ * install found via the launcher symlink so callers like the menu bar don't see
+ * a bogus `unknown`.
  */
 export declare function getCliVersion(): string;
 /**

package/dist/lib/version.js

@@ -1,28 +1,111 @@
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 let cached = null;
+/** Read a `version` string from a package.json, or null if unreadable. */
+function readVersionAt(pkgPath) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return String(pkg.version || '') || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Well-known locations of the `agents` launcher for PATH-less GUI/launchd
+ * processes (the menu-bar helper inherits no login PATH). Also the anchor for
+ * recovering the on-disk install layout when the CLI runs as a Bun single-file
+ * binary — see {@link resolveInstalledLayout}.
+ */
+export function resolveAgentsBin() {
+    const home = os.homedir();
+    const candidates = [
+        path.join(home, '.local', 'bin', 'agents'),
+        '/opt/homebrew/bin/agents',
+        '/usr/local/bin/agents',
+        path.join(home, '.npm-global', 'bin', 'agents'),
+    ];
+    for (const c of candidates) {
+        try {
+            fs.accessSync(c, fs.constants.X_OK);
+            return c;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
+/**
+ * Pure derivation (no I/O) of an install's on-disk layout from the realpath of
+ * its `agents` launcher. A launcher lives at `<pkg>/dist/bin/agents`, so two
+ * levels up is `<pkg>/dist`. Exported for unit testing so the dirname chain the
+ * Bun-binary fallback depends on stays locked.
+ */
+export function installLayoutFromBin(realBin) {
+    const distDir = path.dirname(path.dirname(realBin)); // <pkg>/dist/bin/agents -> <pkg>/dist
+    return {
+        distDir,
+        entryPath: path.join(distDir, 'index.js'),
+        pkgJsonPath: path.join(distDir, '..', 'package.json'),
+    };
+}
+/**
+ * Resolve the on-disk install layout of the running CLI by following the
+ * `agents` launcher symlink.
+ *
+ * When the CLI runs as a Bun single-file executable, `import.meta.url` points
+ * inside the virtual bundle (`/$bunfs/…`), so sibling-relative resolution can't
+ * see the shipped `package.json`, `dist/index.js`, or `MenubarHelper.app` on
+ * disk. The launcher symlink points at the real files; walk up from it. Returns
+ * null when no launcher is found (dev/tsx runs, or a box without the helper) —
+ * callers keep their in-bundle resolution as the primary path and use this only
+ * as the fallback.
+ */
+export function resolveInstalledLayout() {
+    const bin = resolveAgentsBin();
+    if (!bin)
+        return null;
+    try {
+        const layout = installLayoutFromBin(fs.realpathSync(bin));
+        // Validate we landed on a real dist (guards an unexpected launcher layout).
+        if (fs.existsSync(layout.entryPath))
+            return layout;
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}
 /**
  * Resolve the CLI version from the shipping package.json. Used by the daemon
  * to answer `IPCAction: 'version'` and by the client to detect daemon drift —
  * a dev-build CLI talking to a launchd-managed registry daemon would silently
  * get stale behavior without this check.
+ *
+ * Primary read is relative to this module; when that fails (the Bun single-file
+ * binary can't read its own bundled package.json), fall back to the on-disk
+ * install found via the launcher symlink so callers like the menu bar don't see
+ * a bogus `unknown`.
  */
 export function getCliVersion() {
     if (cached)
         return cached;
-    try {
-        const pkgPath = path.join(__dirname, '..', '..', 'package.json');
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        cached = String(pkg.version || 'unknown');
-    }
-    catch {
-        cached = 'unknown';
-    }
+    cached =
+        readVersionAt(path.join(__dirname, '..', '..', 'package.json')) ??
+            readInstalledPackageVersion() ??
+            'unknown';
     return cached;
 }
+/** Version from the on-disk install (Bun-binary fallback). */
+function readInstalledPackageVersion() {
+    const layout = resolveInstalledLayout();
+    return layout ? readVersionAt(layout.pkgJsonPath) : null;
+}
 /**
  * Read the version from package.json on disk every call, bypassing the cache.
  *
@@ -34,12 +117,7 @@ export function getCliVersion() {
  * 'unknown' on any error.
  */
 export function getCliVersionFresh() {
-    try {
-        const pkgPath = path.join(__dirname, '..', '..', 'package.json');
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        return String(pkg.version || 'unknown');
-    }
-    catch {
-        return 'unknown';
-    }
+    return (readVersionAt(path.join(__dirname, '..', '..', 'package.json')) ??
+        readInstalledPackageVersion() ??
+        'unknown');
 }

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.
  */
@@ -399,6 +415,17 @@ export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: s
  *   4. Nothing runnable installed → install `latest`, pin it, return it.
  *   5. Give up → return null (caller surfaces a clear error).
  *
+ * Isolation boundary (both directions — steps 3/4 are the only mutating ones):
+ *   - An ISOLATED target gets step 2 and nothing else. Falling back would let
+ *     `agents run <agent>@<isolated>` silently repoint the user's NORMAL default,
+ *     and installing `latest` would materialize a version they never asked for.
+ *     A failed repair returns null so the caller says so plainly.
+ *   - An isolated version is never a fallback CANDIDATE either, whatever the
+ *     target is: promoting one to the global default is exactly what `agents use`
+ *     refuses and what removeVersion's promotion filter excludes, so it must not
+ *     happen here by the back door (the daemon's launch-health pass calls this
+ *     unattended every ~6h).
+ *
  * Gated to npm-package agents: their native binary ships as an optional per-arch
  * dependency whose tarball can extract partially (interrupted/raced install) —
  * the exact failure this repairs. Agents with a global/native binary (grok,