@phnx-labs/agents-cli 1.20.68 → 1.20.69

package/dist/lib/computer/download.js

@@ -0,0 +1,145 @@
+/**
+ * On-demand download + verification of the macOS `agents computer` helper
+ * ("ComputerHelper.app").
+ *
+ * The helper is a signed + notarized universal `.app` bundle published as a
+ * GitHub release asset per tagged CLI version — the same distribution model as
+ * the Windows helper (see `lib/ssh-tunnel.ts`). A fresh `npm i -g` machine has
+ * no local build, so `agents computer setup` / `agents setup computer` fetch the
+ * asset for the running CLI version, verify its sha256 against the published
+ * `.sha256`, then verify the code signature (Developer ID Team + notarization)
+ * before it is ever copied to /Applications.
+ *
+ * A `.app` is a directory, so the asset is a zip (`ditto -c -k --keepParent`);
+ * we extract it with `ditto -x -k` after the checksum passes.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { getCacheDir } from '../state.js';
+import { getCliVersion } from '../version.js';
+import { parseSha256Asset, sha256File } from '../ssh-tunnel.js';
+import { resolveHelperApp } from '../computer-rpc.js';
+/** GitHub repo whose `v<version>` releases carry the helper asset. */
+export const HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/** The zipped `.app` release asset name. */
+export const MAC_HELPER_ASSET = 'ComputerHelper.app.zip';
+/** The bundle directory name once extracted. */
+export const MAC_HELPER_APP_NAME = 'ComputerHelper.app';
+/** Apple Developer ID Team the helper must be signed by (defense in depth on top
+ * of `spctl` notarization assessment). "Developer ID Application: Muqit Nawaz". */
+export const EXPECTED_TEAM_ID = '2HTP252L87';
+/** Cache dir for the downloaded helper, one subdir per release tag. */
+export function macHelperCacheDir(version) {
+    return path.join(getCacheDir(), 'computer', 'mac-helper', `v${version}`);
+}
+/** Release-asset URLs for the helper zip + its checksum at one `v<version>` tag. */
+export function macHelperAssetUrls(version) {
+    const base = `https://github.com/${HELPER_RELEASE_REPO}/releases/download/v${version}`;
+    return { zip: `${base}/${MAC_HELPER_ASSET}`, sha256: `${base}/${MAC_HELPER_ASSET}.sha256` };
+}
+/**
+ * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
+ * Team, and notarized (Gatekeeper-accepted). Throws with an actionable message
+ * on any failure — a downloaded bundle is never trusted without this.
+ */
+export function verifyMacHelper(appPath) {
+    // 1. Structural + signature integrity.
+    try {
+        execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`code signature invalid for ${appPath}: ${e.message}`);
+    }
+    // 2. Team identity — must be our Developer ID, not some other valid signer.
+    let info = '';
+    try {
+        info = execFileSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { stdio: 'pipe' }).toString();
+    }
+    catch (e) {
+        // codesign -dv writes to stderr; capture whatever it emitted.
+        info = (e.stderr?.toString() ?? '') + (e.stdout?.toString() ?? '');
+        if (!info)
+            throw new Error(`could not read code signature of ${appPath}: ${e.message}`);
+    }
+    const team = info.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1];
+    if (team !== EXPECTED_TEAM_ID) {
+        throw new Error(`helper signed by unexpected Team (${team ?? 'none'}), expected ${EXPECTED_TEAM_ID}. Refusing to install.`);
+    }
+    // 3. Notarization / Gatekeeper — confirms Apple stapled a notarization ticket.
+    try {
+        execFileSync('/usr/sbin/spctl', ['--assess', '--type', 'execute', '--verbose', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`helper is not notarized / rejected by Gatekeeper: ${e.message}. Refusing to install.`);
+    }
+}
+/**
+ * Download the helper release asset for `version`, verify sha256, extract the
+ * `.app`, and verify its signature. Returns the path to the extracted
+ * `ComputerHelper.app`. A missing asset is a hard error naming the exact tag —
+ * never a silent fallback to another release.
+ */
+export async function downloadMacHelperApp(version) {
+    const dir = macHelperCacheDir(version);
+    const cachedApp = path.join(dir, MAC_HELPER_APP_NAME);
+    if (fs.existsSync(cachedApp)) {
+        // Re-verify a cached bundle cheaply; a tampered cache must not be trusted.
+        verifyMacHelper(cachedApp);
+        return cachedApp;
+    }
+    const tag = `v${version}`;
+    const { zip: zipUrl, sha256: shaUrl } = macHelperAssetUrls(version);
+    const missing = (status, url) => new Error(`no ${MAC_HELPER_ASSET} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
+        `The macOS helper ships as a GitHub release asset per tagged CLI version; ` +
+        `from a repo checkout you can build it locally instead: ` +
+        `bash native/computer-mac/scripts/build.sh release`);
+    // Checksum first: it is tiny and 404s fast when the tag has no assets.
+    const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });
+    if (!shaRes.ok)
+        throw missing(shaRes.status, shaUrl);
+    const expected = parseSha256Asset(await shaRes.text());
+    console.error(`Downloading ${MAC_HELPER_ASSET} ${tag} from GitHub releases...`);
+    const zipRes = await fetch(zipUrl, { signal: AbortSignal.timeout(15 * 60_000) });
+    if (!zipRes.ok || !zipRes.body)
+        throw missing(zipRes.status, zipUrl);
+    fs.mkdirSync(dir, { recursive: true });
+    const partial = path.join(dir, `${MAC_HELPER_ASSET}.download`);
+    try {
+        await pipeline(Readable.fromWeb(zipRes.body), fs.createWriteStream(partial));
+        const actual = await sha256File(partial);
+        if (actual !== expected) {
+            throw new Error(`sha256 mismatch for ${zipUrl}: expected ${expected}, got ${actual}`);
+        }
+        // Extract the zip (created with `ditto -c -k --keepParent`, so it contains
+        // ComputerHelper.app/ at top level) into the version cache dir.
+        fs.rmSync(cachedApp, { recursive: true, force: true });
+        execFileSync('/usr/bin/ditto', ['-x', '-k', partial, dir], { stdio: 'pipe' });
+        if (!fs.existsSync(cachedApp)) {
+            throw new Error(`extracted asset did not contain ${MAC_HELPER_APP_NAME}`);
+        }
+        verifyMacHelper(cachedApp);
+    }
+    finally {
+        fs.rmSync(partial, { force: true });
+    }
+    return cachedApp;
+}
+/**
+ * Resolve the helper `.app` to install from: a local build / bundled copy first
+ * (repo checkout), else the checksum + signature-verified release-asset download
+ * for the running CLI version. Throws with the tag it checked when neither
+ * exists. macOS only.
+ */
+export async function ensureMacHelperApp(version = getCliVersion()) {
+    if (os.platform() !== 'darwin') {
+        throw new Error('The macOS computer helper is only available on macOS.');
+    }
+    const local = resolveHelperApp();
+    if (local)
+        return local;
+    return downloadMacHelperApp(version);
+}

package/dist/lib/computer-rpc.js

@@ -163,14 +163,20 @@ export function writeComputerPeers(allowedExecPaths) {
     }
     fs.writeFileSync(resolvePeersPath(), JSON.stringify({ allow: allowedExecPaths }, null, 2), { mode: 0o600 });
 }
-// Resolve the helper executable inside the dist .app bundle. Used by the
-// stdio fallback and by install-helper to find the source bundle.
+// Resolve the helper executable inside the dist .app bundle. Used by the stdio
+// fallback and by install-helper to find the source bundle. Only TRUSTED sources
+// are listed here: a local checkout build and the bundled tarball copy. The
+// download cache is deliberately NOT a candidate — a cached bundle is
+// user-writable and must only ever be read through downloadMacHelperApp(), which
+// re-verifies its signature + Team ID + notarization on every cache hit
+// (lib/computer/download.ts). Listing the cache here would let a same-user
+// process plant a differently-signed .app that install-helper trusts.
 export function resolveHelperExec() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
         // Local build (running from the agents-cli checkout). apps/cli/dist/lib -> repo root (4 up) -> native/computer-mac.
         path.resolve(here, '..', '..', '..', '..', 'native', 'computer-mac', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
-        // Bundled with the npm package (later: CDN download lands here).
+        // Bundled with the npm package.
         path.resolve(here, '..', 'computer-helper', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
     ];
     for (const c of candidates) {

package/dist/lib/devices/connect.d.ts

@@ -43,6 +43,21 @@ export declare function buildSshInvocation(device: DeviceProfile, cmd: string[],
     args: string[];
     env: Record<string, string>;
 };
+/**
+ * Build the askpass shim's `#!/bin/sh` body: a script that re-invokes this CLI
+ * as `agents ssh __askpass`. The relaunch argv comes from {@link getCliLaunch},
+ * never a hand-rolled `[process.execPath, process.argv[1], …]` — on a Bun
+ * standalone binary `process.argv[1]` is the *virtual* embedded entry
+ * `/$bunfs/root/agents`, which the CLI would then receive as a bogus subcommand
+ * (`unknown command '/$bunfs/root/agents'`), print nothing, and hand ssh an
+ * empty password. `getCliLaunch` resolves the physical executable so the shim
+ * works on both the standalone and JS/dev builds. Every argv element is
+ * shell-quoted. Pure (takes the launch as a parameter) so it is unit-testable.
+ */
+export declare function buildAskpassShimBody(launch?: {
+    command: string;
+    args: string[];
+}): string;
 /**
  * Write (idempotently) the askpass shim — a tiny executable that re-invokes
  * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable

package/dist/lib/devices/connect.js

@@ -16,6 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { getCliLaunch } from '../cli-entry.js';
 import { encodePwshBase64 } from '../pwsh.js';
 import { getCacheDir } from '../state.js';
 import { hostKeyCheckingOpts } from './known-hosts.js';
@@ -92,6 +93,21 @@ export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}) {
         args.push(remote);
     return { args, env };
 }
+/**
+ * Build the askpass shim's `#!/bin/sh` body: a script that re-invokes this CLI
+ * as `agents ssh __askpass`. The relaunch argv comes from {@link getCliLaunch},
+ * never a hand-rolled `[process.execPath, process.argv[1], …]` — on a Bun
+ * standalone binary `process.argv[1]` is the *virtual* embedded entry
+ * `/$bunfs/root/agents`, which the CLI would then receive as a bogus subcommand
+ * (`unknown command '/$bunfs/root/agents'`), print nothing, and hand ssh an
+ * empty password. `getCliLaunch` resolves the physical executable so the shim
+ * works on both the standalone and JS/dev builds. Every argv element is
+ * shell-quoted. Pure (takes the launch as a parameter) so it is unit-testable.
+ */
+export function buildAskpassShimBody(launch = getCliLaunch(['ssh', '__askpass'])) {
+    const exec = [launch.command, ...launch.args].map(shellQuote).join(' ');
+    return `#!/bin/sh\n# Generated by agents-cli — bridges ssh SSH_ASKPASS back into the CLI.\nexec ${exec}\n`;
+}
 /**
  * Write (idempotently) the askpass shim — a tiny executable that re-invokes
  * this CLI as `agents ssh __askpass`. ssh execs `SSH_ASKPASS` with no usable
@@ -102,10 +118,6 @@ export function writeAskpassShim() {
     const dir = path.join(getCacheDir(), 'devices');
     fs.mkdirSync(dir, { recursive: true });
     const shimPath = path.join(dir, 'askpass.sh');
-    // process.execPath = the node/bun binary; argv[1] = this CLI's entry script.
-    const node = process.execPath;
-    const entry = process.argv[1] ?? '';
-    const body = `#!/bin/sh\n# Generated by agents-cli — bridges ssh SSH_ASKPASS back into the CLI.\nexec ${shellQuote(node)} ${shellQuote(entry)} ssh __askpass\n`;
-    fs.writeFileSync(shimPath, body, { mode: 0o700 });
+    fs.writeFileSync(shimPath, buildAskpassShimBody(), { mode: 0o700 });
     return shimPath;
 }

package/dist/lib/devices/terminfo.d.ts

@@ -0,0 +1,44 @@
+import { type DeviceProfile } from './registry.js';
+/**
+ * Decide whether an interactive login warrants a terminfo push. Pure so the
+ * gating logic is unit-testable without touching ssh or the filesystem.
+ *
+ * @param interactive true only for a real login (no remote command) on a human tty.
+ */
+export declare function shouldSyncTerminfo(params: {
+    term?: string;
+    shell: DeviceProfile['shell'];
+    interactive: boolean;
+}): boolean;
+/**
+ * Cache key for a device: the remote **user@host**, not just the host. terminfo
+ * is compiled into the *per-user* `~/.terminfo`, so `alice@box` and `bob@box`
+ * are distinct sync targets — keying on host alone would let the first user's
+ * stamp suppress the second user's (never-installed) sync. Mirrors
+ * {@link sshTargetFor}'s user handling; falls back to the device name when the
+ * address is unresolved.
+ */
+export declare function terminfoHostKey(device: Pick<DeviceProfile, 'user' | 'name'>, addr: string | undefined): string;
+/** True when a fresh successful-sync stamp exists for this host+TERM. */
+export declare function terminfoSynced(host: string, term: string, cacheRoot?: string): boolean;
+/** Record a successful sync so repeat logins skip the push. Best-effort. */
+export declare function markTerminfoSynced(host: string, term: string, cacheRoot?: string): void;
+/** Export the local terminfo source for a TERM, or null if it can't be produced. */
+export declare function localTerminfoSource(term: string): string | null;
+/**
+ * Best-effort: ensure `device` has the terminfo entry for the local `$TERM`
+ * before an interactive login. Never throws; returns whether a push succeeded
+ * (false when skipped, already-cached, or failed). `sshArgs`/`sshEnv` are the
+ * SAME host-key + auth options the real login uses, minus the interactive tty —
+ * so a password-auth device resolves through the askpass shim without a second
+ * human prompt.
+ */
+export declare function syncTerminfoToDevice(opts: {
+    device: DeviceProfile;
+    host: string;
+    term: string | undefined;
+    /** ssh argv for a non-interactive `tic -x -` exec against this device. */
+    sshArgs: string[];
+    /** Env overlay for that ssh (askpass wiring for password devices). */
+    sshEnv: Record<string, string>;
+}): boolean;

package/dist/lib/devices/terminfo.js

@@ -0,0 +1,167 @@
+/**
+ * Terminfo propagation for `agents ssh` interactive logins.
+ *
+ * Modern terminals (Ghostty, kitty, Alacritty, WezTerm, foot, rio) advertise a
+ * custom `TERM` (e.g. `xterm-ghostty`) whose terminfo entry ships with the
+ * terminal, not with the remote host's ncurses. SSH into a box that lacks the
+ * entry and the session is subtly broken: wrong backspace, missing colors, a
+ * garbled clear/alt-screen. Ghostty's own shell integration fixes this for the
+ * bare `ssh` command, but `agents ssh` (Tailscale-relayed, spawned directly)
+ * bypasses that wrapper — so we handle it here.
+ *
+ * Strategy: on an interactive POSIX login, if the local `$TERM` is one the
+ * remote is unlikely to have, export it locally (`infocmp -x`) and compile it on
+ * the remote (`tic -x -`, writes to the user's `~/.terminfo`, no sudo). This is
+ * the canonical, terminal-agnostic technique.
+ *
+ * Two invariants keep it safe and cheap:
+ *  - **Fail-safe.** Every failure is swallowed. A push that errors, times out,
+ *    or hits a remote without `tic` leaves the user exactly where they are today
+ *    — it never blocks or delays the actual login beyond the short push timeout.
+ *  - **Cached.** A successful sync stamps a local marker keyed by host+TERM, so
+ *    only the first login to each host pays the one extra round-trip; every
+ *    repeat login is zero-cost.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+/**
+ * Terminfo names that ncurses ships essentially everywhere, so pushing them is
+ * wasted work. Anything NOT in this set (the exotic terminal entries) is a sync
+ * candidate. Kept deliberately conservative: when unsure, we push — `tic` is
+ * idempotent and the result is cached.
+ */
+const UNIVERSAL_TERMS = new Set([
+    'dumb',
+    'ansi',
+    'vt100',
+    'vt102',
+    'vt220',
+    'linux',
+    'cygwin',
+    'xterm',
+    'xterm-color',
+    'xterm-16color',
+    'xterm-256color',
+    'screen',
+    'screen-256color',
+    'tmux',
+    'tmux-256color',
+    'rxvt',
+    'rxvt-unicode',
+    'rxvt-unicode-256color',
+]);
+/** How long a successful sync suppresses re-syncing the same host+TERM. */
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/** Cap on the push so a stalled remote can't delay the login indefinitely. */
+const PUSH_TIMEOUT_MS = 8000;
+/**
+ * Decide whether an interactive login warrants a terminfo push. Pure so the
+ * gating logic is unit-testable without touching ssh or the filesystem.
+ *
+ * @param interactive true only for a real login (no remote command) on a human tty.
+ */
+export function shouldSyncTerminfo(params) {
+    if (!params.interactive)
+        return false;
+    if (params.shell === 'powershell')
+        return false; // Windows console ignores terminfo
+    const term = params.term?.trim();
+    if (!term)
+        return false;
+    if (UNIVERSAL_TERMS.has(term))
+        return false;
+    return true;
+}
+/**
+ * Cache key for a device: the remote **user@host**, not just the host. terminfo
+ * is compiled into the *per-user* `~/.terminfo`, so `alice@box` and `bob@box`
+ * are distinct sync targets — keying on host alone would let the first user's
+ * stamp suppress the second user's (never-installed) sync. Mirrors
+ * {@link sshTargetFor}'s user handling; falls back to the device name when the
+ * address is unresolved.
+ */
+export function terminfoHostKey(device, addr) {
+    const host = addr ?? device.name;
+    return device.user ? `${device.user}@${host}` : host;
+}
+/** Directory holding per-host+TERM sync stamps. `cacheRoot` override is for tests. */
+function stampDir(cacheRoot) {
+    return path.join(cacheRoot ?? getCacheDir(), 'devices', 'terminfo');
+}
+/** Filesystem-safe stamp name for a host+TERM pair. */
+function stampFile(host, term, cacheRoot) {
+    const safe = `${host}__${term}`.replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(stampDir(cacheRoot), safe);
+}
+/** True when a fresh successful-sync stamp exists for this host+TERM. */
+export function terminfoSynced(host, term, cacheRoot) {
+    try {
+        const st = fs.statSync(stampFile(host, term, cacheRoot));
+        return Date.now() - st.mtimeMs < CACHE_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/** Record a successful sync so repeat logins skip the push. Best-effort. */
+export function markTerminfoSynced(host, term, cacheRoot) {
+    try {
+        fs.mkdirSync(stampDir(cacheRoot), { recursive: true });
+        fs.writeFileSync(stampFile(host, term, cacheRoot), `${new Date().toISOString()}\n`);
+    }
+    catch {
+        /* a cache write failure just means we re-sync next time — never fatal */
+    }
+}
+/** Export the local terminfo source for a TERM, or null if it can't be produced. */
+export function localTerminfoSource(term) {
+    try {
+        const res = spawnSync('infocmp', ['-x', term], {
+            encoding: 'utf8',
+            timeout: 4000,
+        });
+        if (res.status === 0 && res.stdout && res.stdout.trim().length > 0) {
+            return res.stdout;
+        }
+    }
+    catch {
+        /* infocmp missing or errored — nothing we can push */
+    }
+    return null;
+}
+/**
+ * Best-effort: ensure `device` has the terminfo entry for the local `$TERM`
+ * before an interactive login. Never throws; returns whether a push succeeded
+ * (false when skipped, already-cached, or failed). `sshArgs`/`sshEnv` are the
+ * SAME host-key + auth options the real login uses, minus the interactive tty —
+ * so a password-auth device resolves through the askpass shim without a second
+ * human prompt.
+ */
+export function syncTerminfoToDevice(opts) {
+    const term = opts.term?.trim();
+    if (!term)
+        return false;
+    if (terminfoSynced(opts.host, term))
+        return false;
+    const source = localTerminfoSource(term);
+    if (!source)
+        return false;
+    try {
+        const res = spawnSync('ssh', opts.sshArgs, {
+            input: source,
+            env: { ...process.env, ...opts.sshEnv },
+            timeout: PUSH_TIMEOUT_MS,
+            stdio: ['pipe', 'ignore', 'ignore'],
+        });
+        if (res.status === 0) {
+            markTerminfoSynced(opts.host, term);
+            return true;
+        }
+    }
+    catch {
+        /* connection failed / timed out — fail-safe, login proceeds unaffected */
+    }
+    return false;
+}

package/dist/lib/rotate.d.ts

@@ -11,6 +11,8 @@ import { type UsageSnapshot } from './usage.js';
 export interface RotateCandidate {
     agent: AgentId;
     version: string;
+    accountKey: string | null;
+    accountLabel: string;
     email: string | null;
     /**
      * Per-org usage/quota key (e.g. `claude:org=<orgUuid>`) — the unit rate
@@ -21,7 +23,9 @@ export interface RotateCandidate {
     usageKey: string | null;
     usageStatus: AccountInfo['usageStatus'];
     usageSnapshot: UsageSnapshot | null;
-    authValid: boolean;
+    usageError: string | null;
+    plan: string | null;
+    signedIn: boolean;
     lastActive: Date | null;
 }
 export interface RotateResult {
@@ -58,7 +62,7 @@ export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: str
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
 /**
  * Whether a specific account can serve a run right now, and — when it can't —
- * why. `signed_out` covers no-email / invalid-auth; `rate_limited` and
+ * why. `signed_out` covers a missing usable credential; `rate_limited` and
  * `out_of_credits` name the throttle. Used to pre-warn on a version-pinned
  * teammate whose account rotation won't route around (a pin IS the target).
  */
@@ -71,7 +75,7 @@ export type AccountReadiness = {
 };
 /**
  * Pure decision reusing the router's own eligibility gate (`hasUsageAvailable`
- * + email/auth, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
+ * + canonical signed-in state, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
  * disagree with what rotation would actually do. The `reason` combines the two
  * signals `hasUsageAvailable` reads: the live snapshot (session-inclusive
  * rate-limit) and the coarse cached `usageStatus` (out-of-credits, which a
@@ -100,17 +104,16 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  * headroom, with no stampede on the lowest-usage one. Stateless — parallel
  * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present), auth valid, and not currently
+ * Eligibility: signed in according to AccountInfo and not currently
  * rate-limited — no blocking window (session OR weekly) at 100%, matching the
  * `agents view` badge; or the local cached status is usable when no live
  * snapshot exists. Note the split: eligibility considers the session window
  * (a session-maxed account can't run now), but the capacity *weight* above is
  * driven by weekly headroom so a brief session spike doesn't distort routing.
  *
- * Dedupe: when multiple versions share an email, collapse to one candidate
- * per email (the least-recently-active version). Prevents two parallel pods
- * from "balancing" to different versions but hitting the same Anthropic
- * account and both 429ing.
+ * Dedupe: when multiple versions share a usage/account identity, collapse to
+ * one candidate (the least-recently-active version). The org-scoped usage key
+ * wins over email so same-email personal and Team accounts remain distinct.
  *
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
@@ -122,6 +125,7 @@ export declare function pickBalancedCandidate(candidates: RotateCandidate[]): Ro
  * usage headroom.
  */
 export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
+export declare function collectRunCandidates(agent: AgentId): Promise<RotateCandidate[]>;
 /**
  * Pick a healthy version for `agent` using weighted random by remaining
  * capacity. See `pickBalancedCandidate` for algorithm details.

package/dist/lib/rotate.js

@@ -6,7 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { getAccountInfo } from './agents.js';
+import { accountDisplayLabel, getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getProjectRunConfigs } from './run-config.js';
@@ -65,14 +65,10 @@ export function setGlobalRunStrategy(agent, strategy) {
     writeMeta(meta);
 }
 function isRotationEligible(candidate) {
-    return !!candidate.email
-        && candidate.authValid
-        && hasUsageAvailable(candidate);
+    return candidate.signedIn && hasUsageAvailable(candidate);
 }
 function isAvailableEligible(candidate) {
-    return !!candidate.email
-        && candidate.authValid
-        && hasUsageAvailable(candidate);
+    return isRotationEligible(candidate);
 }
 function hasUsageAvailable(candidate) {
     const snapshot = candidate.usageSnapshot;
@@ -95,7 +91,7 @@ function hasUsageAvailable(candidate) {
 }
 /**
  * Pure decision reusing the router's own eligibility gate (`hasUsageAvailable`
- * + email/auth, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
+ * + canonical signed-in state, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
  * disagree with what rotation would actually do. The `reason` combines the two
  * signals `hasUsageAvailable` reads: the live snapshot (session-inclusive
  * rate-limit) and the coarse cached `usageStatus` (out-of-credits, which a
@@ -104,7 +100,7 @@ function hasUsageAvailable(candidate) {
  * reported while the account is actually serving requests.
  */
 export function readinessFromCandidate(candidate) {
-    if (!candidate.email || !candidate.authValid) {
+    if (!candidate.signedIn) {
         return { ready: false, reason: 'signed_out', email: candidate.email };
     }
     if (hasUsageAvailable(candidate)) {
@@ -162,7 +158,7 @@ function compareCandidates(a, b) {
  * key; fall back to email only when no usage identity is available.
  */
 function candidateIdentity(c) {
-    return c.usageKey ?? c.email;
+    return c.usageKey ?? c.accountKey ?? c.email ?? `${c.agent}@${c.version}`;
 }
 function dedupeAndSortCandidates(candidates) {
     const byIdentity = new Map();
@@ -189,17 +185,16 @@ function dedupeAndSortCandidates(candidates) {
  * headroom, with no stampede on the lowest-usage one. Stateless — parallel
  * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present), auth valid, and not currently
+ * Eligibility: signed in according to AccountInfo and not currently
  * rate-limited — no blocking window (session OR weekly) at 100%, matching the
  * `agents view` badge; or the local cached status is usable when no live
  * snapshot exists. Note the split: eligibility considers the session window
  * (a session-maxed account can't run now), but the capacity *weight* above is
  * driven by weekly headroom so a brief session spike doesn't distort routing.
  *
- * Dedupe: when multiple versions share an email, collapse to one candidate
- * per email (the least-recently-active version). Prevents two parallel pods
- * from "balancing" to different versions but hitting the same Anthropic
- * account and both 429ing.
+ * Dedupe: when multiple versions share a usage/account identity, collapse to
+ * one candidate (the least-recently-active version). The org-scoped usage key
+ * wins over email so same-email personal and Team accounts remain distinct.
  *
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
@@ -278,12 +273,11 @@ export function pickAvailableCandidate(candidates, preferredVersion) {
         : undefined;
     return { picked: preferred ?? sorted[0], healthy: sorted, excluded };
 }
-async function collectRunCandidates(agent) {
+export async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
     const rows = await Promise.all(versions.map(async (version) => {
         const home = getVersionHomePath(agent, version);
         const info = await getAccountInfo(agent, home);
-        // `info.email` (from .claude.json's oauthAccount) is the auth heuristic.
         // We used to additionally call isClaudeAuthValid(home), which reads
         // "Claude Code-credentials-<hash>" from the system keychain. That item is
         // written by Claude Code itself with its own process in the ACL, so our
@@ -291,15 +285,17 @@ async function collectRunCandidates(agent) {
         // one per installed version, every time `agents run` cold-starts. If
         // claude's stored token has actually expired, the spawned agent detects
         // it at its own startup and re-auths; that's the correct UX.
-        const authValid = info.email != null;
         return {
             agent,
             version,
             home,
             info,
+            accountKey: info.accountKey,
+            accountLabel: accountDisplayLabel(info),
             email: info.email,
             usageStatus: info.usageStatus,
-            authValid,
+            plan: info.plan,
+            signedIn: info.signedIn,
             lastActive: info.lastActive,
         };
     }));
@@ -311,10 +307,13 @@ async function collectRunCandidates(agent) {
     })));
     return rows.map(({ home: _home, info, ...candidate }) => {
         const usageKey = getUsageLookupKey(info);
-        const usageSnapshot = usageKey
-            ? usageByKey.get(usageKey)?.snapshot ?? null
-            : null;
-        return { ...candidate, usageKey, usageSnapshot };
+        const usage = usageKey ? usageByKey.get(usageKey) : undefined;
+        return {
+            ...candidate,
+            usageKey,
+            usageSnapshot: usage?.snapshot ?? null,
+            usageError: usage?.error ?? null,
+        };
     });
 }
 /**