@phnx-labs/agents-cli 1.20.68 → 1.20.69

package/dist/commands/view.js

@@ -4,8 +4,10 @@ import { visibleWidth, termLink } from '../lib/format.js';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, ALL_AGENT_IDS, accountOrgBadge, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { loginHint } from '../lib/signin-badge.js';
+import { machineId } from '../lib/machine-id.js';
+import { authCacheKey, formatCheckedAge, readAuthHealthCache } from '../lib/auth-health.js';
 import { agentReportsUsage, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, } from '../lib/versions.js';
@@ -26,33 +28,8 @@ import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
-// Shown in the email column for agents that are signed in but expose no email
-// address locally (Antigravity stores an opaque OAuth grant with no identity).
-const SIGNED_IN_LABEL = 'signed in';
-/**
- * Text for the account (email) column. Prefers the real email; otherwise, for a
- * signed-in agent whose credential carries no email but does carry an opaque
- * account id (Kimi's user_id), show `id:<user_id>` so distinct accounts read
- * distinctly instead of a generic "signed in". Falls back to "signed in" when we
- * have neither (Antigravity), and empty when signed out.
- *
- * When the account carries a Claude organizationType, the org badge is appended
- * — "email (Turing Labs · Team)" — so two installs signed into the same email
- * under different orgs (personal Max vs a Team seat) read distinctly. The
- * suffix is plain text inside the label so the existing column-width pass
- * measures and pads it for free.
- */
-export function accountColumnLabel(info) {
-    if (!info)
-        return '';
-    if (info.email) {
-        const badge = accountOrgBadge(info);
-        return badge ? `${info.email} (${badge})` : info.email;
-    }
-    if (info.signedIn)
-        return info.accountId ? `id:${info.accountId}` : SIGNED_IN_LABEL;
-    return '';
-}
+/** Shared account identity formatter, re-exported for the view-specific tests. */
+export const accountColumnLabel = accountDisplayLabel;
 /**
  * Group profile summaries by their host harness, optionally filtered to a
  * single agent. Profile YAMLs that fail validation are silently skipped by
@@ -245,6 +222,22 @@ function renderHostClisSection(cwd) {
         console.log(`  ${chalk.red('error')}      ${chalk.gray(err.file)}: ${chalk.gray(err.reason)}`);
     }
 }
+/**
+ * A compact live-auth chip for a version row, read from the fleet auth-health
+ * cache (written by `agents fleet ping` / the daemon). Empty when the install
+ * hasn't been probed — this is the local "signed in" flag's ground-truth
+ * companion: ● live, ○ revoked (re-login), ◐ unverified/limited, plus its age.
+ */
+function liveAuthChip(cache, host, agentId, version) {
+    const h = cache[authCacheKey(host, agentId, version)];
+    if (!h)
+        return '';
+    const glyph = h.verdict === 'live' ? chalk.green('●')
+        : h.verdict === 'revoked' ? chalk.red('○')
+            : h.verdict === 'expired' ? chalk.yellow('○')
+                : chalk.yellow('◐');
+    return `${glyph} ${chalk.gray(formatCheckedAge(h.checkedAt))}`;
+}
 async function showInstalledVersions(filterAgentId, viewOpts) {
     const spinnerText = filterAgentId
         ? `Checking ${agentLabel(filterAgentId)} agents...`
@@ -276,6 +269,9 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     }
     // Shim healing is silent — users don't need to know about internal repairs
     console.log(chalk.bold('Installed Agent CLIs\n'));
+    const selfHost = machineId();
+    // Read the auth-health cache once (not per version row — see the batching note above).
+    const authCache = readAuthHealthCache();
     // Pre-fetch account info for all versions in parallel
     const infoFetches = [];
     const globalInfoFetches = [];
@@ -500,6 +496,9 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 if (runDefaultBits.length > 0) {
                     parts.push(chalk.gray(`run ${runDefaultBits.join(' ')}`));
                 }
+                const authChip = liveAuthChip(authCache, selfHost, agentId, version);
+                if (authChip)
+                    parts.push(authChip);
                 console.log(parts.join('  '));
                 if (showPaths) {
                     const versionDir = getVersionDir(agentId, version);

package/dist/index.js

@@ -50,7 +50,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadMonitors, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadShare, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadMonitors, loadRun, loadFork, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadShare, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -690,6 +690,7 @@ async function registerAllEagerCommands() {
     await reg(loadRoutines);
     await reg(loadMonitors);
     await reg(loadRun);
+    await reg(loadFork);
     await reg(loadDefaults);
     await reg(loadModels);
     await reg(loadPrune);

package/dist/lib/agents.d.ts

@@ -148,6 +148,16 @@ export declare function formatClaudeOrgLabel(orgType: string | null | undefined)
  * organizationType (signed out, non-Claude agents, configs predating the field).
  */
 export declare function accountOrgBadge(info?: Pick<AccountInfo, 'organizationType' | 'organizationName'> | null): string | null;
+/** Agents whose local credential formats expose enough state for account selection. */
+export declare const ACCOUNT_INSPECTION_AGENT_IDS: readonly ["claude", "codex", "gemini", "grok", "antigravity", "kimi", "droid", "opencode"];
+/** Whether agents-cli can determine this agent's per-version sign-in state. */
+export declare function supportsAccountInspection(agentId: AgentId): boolean;
+/**
+ * Human-readable account identity shared by every account-aware surface.
+ * Prefer email, append a multi-seat Claude organization name when present,
+ * then fall back to a non-secret account id or a generic signed-in label.
+ */
+export declare function accountDisplayLabel(info?: Pick<AccountInfo, 'email' | 'accountId' | 'signedIn' | 'organizationType' | 'organizationName'> | null): string;
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
 /** Decrypted contents of Droid's auth.v2.file (subset we consume). */

package/dist/lib/agents.js

@@ -992,6 +992,38 @@ export function accountOrgBadge(info) {
         return info.organizationName;
     return null;
 }
+/** Agents whose local credential formats expose enough state for account selection. */
+export const ACCOUNT_INSPECTION_AGENT_IDS = [
+    'claude',
+    'codex',
+    'gemini',
+    'grok',
+    'antigravity',
+    'kimi',
+    'droid',
+    'opencode',
+];
+const ACCOUNT_INSPECTION_AGENTS = new Set(ACCOUNT_INSPECTION_AGENT_IDS);
+/** Whether agents-cli can determine this agent's per-version sign-in state. */
+export function supportsAccountInspection(agentId) {
+    return ACCOUNT_INSPECTION_AGENTS.has(agentId);
+}
+/**
+ * Human-readable account identity shared by every account-aware surface.
+ * Prefer email, append a multi-seat Claude organization name when present,
+ * then fall back to a non-secret account id or a generic signed-in label.
+ */
+export function accountDisplayLabel(info) {
+    if (!info)
+        return '';
+    if (info.email) {
+        const badge = accountOrgBadge(info);
+        return badge ? `${info.email} (${badge})` : info.email;
+    }
+    if (info.signedIn)
+        return info.accountId ? `id:${info.accountId}` : 'signed in';
+    return '';
+}
 /** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {
     const info = await getAccountInfo(agentId, home);

package/dist/lib/auth-health.d.ts

@@ -0,0 +1,103 @@
+import { type AccountInfo } from './agents.js';
+import type { AgentId } from './types.js';
+import { type ProviderProbe } from './usage.js';
+/**
+ * - `live`        — completed an authenticated request (200).
+ * - `revoked`     — the server rejected the token (401/403).
+ * - `expired`     — locally-detected expiry; not network-verified (no refresh on the read path).
+ * - `rate_limited`— token works but is throttled right now (429).
+ * - `unverified`  — credential present, not locally expired, but this agent has no in-repo probe endpoint (codex/grok).
+ * - `unconfigured`— no usable credential on disk.
+ * - `error`       — network/other failure; verdict indeterminate (keep the last known one).
+ */
+export type AuthVerdict = 'live' | 'revoked' | 'expired' | 'rate_limited' | 'unverified' | 'unconfigured' | 'error';
+export interface AuthHealth {
+    verdict: AuthVerdict;
+    /** epoch ms of the probe. */
+    checkedAt: number;
+    /** optional short human detail (e.g. "HTTP 401", a network error). */
+    detail?: string;
+    /** account label for display (email / id), when known. Never part of the key. */
+    account?: string;
+}
+/** Agents with a live network probe wired up today. The rest are best-effort. */
+export declare const LIVE_PROBE_AGENTS: ReadonlySet<AgentId>;
+/** Map an HTTP status from a live probe to a verdict. */
+export declare function classifyHttpStatus(status: number): AuthVerdict;
+/** Turn a raw provider probe (from usage.ts) into a verdict. */
+export declare function verdictFromProbe(probe: ProviderProbe): AuthVerdict;
+/** A short human detail line for a probe result (rendered under --verbose). */
+export declare function probeDetail(probe: ProviderProbe): string | undefined;
+/** Uncolored glyph for a verdict (color is applied by the caller). */
+export declare function verdictGlyph(verdict: AuthVerdict): string;
+/** One-word label for matrices/verbose output. */
+export declare function verdictLabel(verdict: AuthVerdict): string;
+/** Roll a set of verdicts (one host×agent's installs) into counts for a matrix cell. */
+export interface VerdictSummary {
+    live: number;
+    /** revoked — the server rejected the token (401/403). Genuinely needs re-login. */
+    bad: number;
+    /**
+     * expired / rate_limited / unverified / error — degraded or unknown, but NOT
+     * "re-login now". `expired` is soft for kimi/droid (their CLIs refresh the
+     * token on next launch; we don't refresh on the read path), so it must not be
+     * lumped with revoked or we'd cry wolf on a self-healing token.
+     */
+    warn: number;
+    total: number;
+}
+export declare function summarizeVerdicts(verdicts: AuthVerdict[]): VerdictSummary;
+/** Verdicts that mean "this token was rejected by the server — re-login required". */
+export declare function isDeadVerdict(verdict: AuthVerdict): boolean;
+/** Human "3m ago" style age for a checkedAt timestamp. */
+export declare function formatCheckedAge(checkedAt: number, now?: number): string;
+/**
+ * Human account label for display (email, else id). NOT used in the cache key —
+ * two installs on one host can hold the same account with independently valid
+ * tokens, so the key is keyed by version (below), not account.
+ */
+export declare function authAccountLabel(info: Pick<AccountInfo, 'email' | 'accountId' | 'userId'> | null | undefined): string | undefined;
+/** Cache key: one entry per install — (host, agent, version). Unique per token. */
+export declare function authCacheKey(host: string, agent: AgentId | string, version: string): string;
+/** Read the whole cache (best-effort; a corrupt/missing file yields an empty map). */
+export declare function readAuthHealthCache(): Record<string, AuthHealth>;
+/** Read one entry, or null. */
+export declare function readAuthHealth(host: string, agent: AgentId | string, version: string): AuthHealth | null;
+/**
+ * Merge entries into the cache. An incoming `error` verdict (a network blip,
+ * not a server rejection) is indeterminate, so it must NOT clobber a prior
+ * known verdict — otherwise one 8s timeout flips a `live` chip to `error`,
+ * exactly the "cry wolf" the verdict model avoids for `expired`. This is the
+ * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
+ * one"). Pure, so it's unit-tested directly. */
+export declare function mergeAuthHealthEntries(current: Record<string, AuthHealth>, incoming: Record<string, AuthHealth>): Record<string, AuthHealth>;
+/** Merge one or more entries into the cache (best-effort write). */
+export declare function writeAuthHealthEntries(entries: Record<string, AuthHealth>): void;
+/**
+ * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
+ * hits the provider; for everyone else it reports a best-effort local verdict
+ * (`unverified` when a credential is present, `unconfigured` otherwise) — never
+ * masquerading as `live`.
+ */
+export declare function probeAuthHealth(agent: AgentId, home: string | undefined, opts?: {
+    cliVersion?: string | null;
+    info?: AccountInfo | null;
+}): Promise<AuthHealth>;
+/** One probed install on a host. */
+export interface AuthProbeRow {
+    agent: AgentId;
+    version: string;
+    account?: string;
+    health: AuthHealth;
+}
+/**
+ * Enumerate every installed (agent, version) on THIS host, probe each in
+ * parallel, and return the rows (installs with no credential at all are
+ * dropped). Shared by `agents fleet ping --local` and the daemon refresh.
+ */
+export declare function probeLocalFleetAuth(opts?: {
+    cliVersion?: string | null;
+    agents?: readonly AgentId[];
+}): Promise<AuthProbeRow[]>;
+/** Persist a host's probed rows into the cache (keyed by host+agent+version). */
+export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[]): void;

package/dist/lib/auth-health.js

@@ -0,0 +1,232 @@
+/**
+ * Live auth-health: does an agent account's stored credential actually complete
+ * an authenticated request right now?
+ *
+ * The rest of the CLI reports "signed in" from a local heuristic — a credential
+ * file is present and its email decodes — which cannot distinguish a good token
+ * from a revoked-but-unexpired one. This module completes a real request per
+ * (agent, account) and records the verdict in a small cache that `agents view`,
+ * `agents fleet status`, and the run rotation all read. The daemon and
+ * `agents fleet ping` are the writers; everyone else reads.
+ *
+ * The network probes themselves live in lib/usage.ts (where the per-provider
+ * token loaders + endpoints already are); this module classifies their result,
+ * covers the best-effort (non-networked) providers, and owns the cache.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ALL_AGENT_IDS, getAccountInfo } from './agents.js';
+import { getCacheDir } from './state.js';
+import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, } from './usage.js';
+import { getVersionHomePath, listInstalledVersions } from './versions.js';
+/** Agents with a live network probe wired up today. The rest are best-effort. */
+export const LIVE_PROBE_AGENTS = new Set(['claude', 'kimi', 'droid']);
+// ---------------------------------------------------------------------------
+// Pure classifiers / render (unit-tested; no network, no fs)
+// ---------------------------------------------------------------------------
+/** Map an HTTP status from a live probe to a verdict. */
+export function classifyHttpStatus(status) {
+    if (status >= 200 && status < 300)
+        return 'live';
+    if (status === 401 || status === 403)
+        return 'revoked';
+    if (status === 429)
+        return 'rate_limited';
+    return 'error';
+}
+/** Turn a raw provider probe (from usage.ts) into a verdict. */
+export function verdictFromProbe(probe) {
+    if (probe.token === 'missing')
+        return 'unconfigured';
+    if (probe.token === 'expired')
+        return 'expired';
+    if (probe.status == null)
+        return 'error';
+    return classifyHttpStatus(probe.status);
+}
+/** A short human detail line for a probe result (rendered under --verbose). */
+export function probeDetail(probe) {
+    if (probe.status != null && (probe.status < 200 || probe.status >= 300))
+        return `HTTP ${probe.status}`;
+    if (probe.error)
+        return probe.error;
+    return undefined;
+}
+const VERDICT_GLYPHS = {
+    live: '●', // ●
+    revoked: '○', // ○
+    expired: '○', // ○
+    rate_limited: '◐', // ◐
+    unverified: '◐', // ◐
+    unconfigured: '·', // ·
+    error: '·', // ·
+};
+/** Uncolored glyph for a verdict (color is applied by the caller). */
+export function verdictGlyph(verdict) {
+    return VERDICT_GLYPHS[verdict] ?? '·';
+}
+/** One-word label for matrices/verbose output. */
+export function verdictLabel(verdict) {
+    switch (verdict) {
+        case 'live': return 'live';
+        case 'revoked': return 'revoked';
+        case 'expired': return 'expired';
+        case 'rate_limited': return 'limited';
+        case 'unverified': return 'unverified';
+        case 'unconfigured': return '—';
+        case 'error': return '?';
+    }
+}
+export function summarizeVerdicts(verdicts) {
+    let live = 0;
+    let bad = 0;
+    let warn = 0;
+    for (const v of verdicts) {
+        if (v === 'live')
+            live++;
+        else if (v === 'revoked')
+            bad++;
+        else
+            warn++;
+    }
+    return { live, bad, warn, total: verdicts.length };
+}
+/** Verdicts that mean "this token was rejected by the server — re-login required". */
+export function isDeadVerdict(verdict) {
+    return verdict === 'revoked';
+}
+/** Human "3m ago" style age for a checkedAt timestamp. */
+export function formatCheckedAge(checkedAt, now = Date.now()) {
+    const secs = Math.max(0, Math.round((now - checkedAt) / 1000));
+    if (secs < 60)
+        return `${secs}s ago`;
+    const mins = Math.round(secs / 60);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+// ---------------------------------------------------------------------------
+// Cache identity + IO (single source of truth read by view/fleet/rotation)
+// ---------------------------------------------------------------------------
+/**
+ * Human account label for display (email, else id). NOT used in the cache key —
+ * two installs on one host can hold the same account with independently valid
+ * tokens, so the key is keyed by version (below), not account.
+ */
+export function authAccountLabel(info) {
+    return info?.email || info?.accountId || info?.userId || undefined;
+}
+/** Cache key: one entry per install — (host, agent, version). Unique per token. */
+export function authCacheKey(host, agent, version) {
+    return `${host}:${agent}:${version}`;
+}
+function cacheFilePath() {
+    return path.join(getCacheDir(), '.auth-health.json');
+}
+/** Read the whole cache (best-effort; a corrupt/missing file yields an empty map). */
+export function readAuthHealthCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cacheFilePath(), 'utf-8'));
+        if (parsed && parsed.entries && typeof parsed.entries === 'object')
+            return parsed.entries;
+    }
+    catch {
+        // missing or corrupt — treat as empty
+    }
+    return {};
+}
+/** Read one entry, or null. */
+export function readAuthHealth(host, agent, version) {
+    return readAuthHealthCache()[authCacheKey(host, agent, version)] ?? null;
+}
+/**
+ * Merge entries into the cache. An incoming `error` verdict (a network blip,
+ * not a server rejection) is indeterminate, so it must NOT clobber a prior
+ * known verdict — otherwise one 8s timeout flips a `live` chip to `error`,
+ * exactly the "cry wolf" the verdict model avoids for `expired`. This is the
+ * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
+ * one"). Pure, so it's unit-tested directly. */
+export function mergeAuthHealthEntries(current, incoming) {
+    const merged = { ...current };
+    for (const [key, health] of Object.entries(incoming)) {
+        if (health.verdict === 'error' && merged[key])
+            continue; // keep last known
+        merged[key] = health;
+    }
+    return merged;
+}
+/** Merge one or more entries into the cache (best-effort write). */
+export function writeAuthHealthEntries(entries) {
+    try {
+        const dir = getCacheDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const merged = {
+            version: 1,
+            entries: mergeAuthHealthEntries(readAuthHealthCache(), entries),
+        };
+        fs.writeFileSync(cacheFilePath(), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // best-effort; a failed write just means the next reader falls back to heuristics
+    }
+}
+// ---------------------------------------------------------------------------
+// The probe (writer side)
+// ---------------------------------------------------------------------------
+/**
+ * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
+ * hits the provider; for everyone else it reports a best-effort local verdict
+ * (`unverified` when a credential is present, `unconfigured` otherwise) — never
+ * masquerading as `live`.
+ */
+export async function probeAuthHealth(agent, home, opts) {
+    const checkedAt = Date.now();
+    if (LIVE_PROBE_AGENTS.has(agent)) {
+        let probe;
+        if (agent === 'claude')
+            probe = await probeClaudeStatus(home, opts?.cliVersion);
+        else if (agent === 'kimi')
+            probe = await probeKimiStatus(home);
+        else
+            probe = await probeDroidStatus(home);
+        return { verdict: verdictFromProbe(probe), checkedAt, detail: probeDetail(probe) };
+    }
+    const info = opts?.info !== undefined ? opts.info : await getAccountInfo(agent, home).catch(() => null);
+    return { verdict: info?.signedIn ? 'unverified' : 'unconfigured', checkedAt };
+}
+/**
+ * Enumerate every installed (agent, version) on THIS host, probe each in
+ * parallel, and return the rows (installs with no credential at all are
+ * dropped). Shared by `agents fleet ping --local` and the daemon refresh.
+ */
+export async function probeLocalFleetAuth(opts) {
+    const agentIds = opts?.agents ?? ALL_AGENT_IDS;
+    const tasks = [];
+    for (const agent of agentIds) {
+        for (const version of listInstalledVersions(agent)) {
+            const home = getVersionHomePath(agent, version);
+            tasks.push((async () => {
+                const info = await getAccountInfo(agent, home).catch(() => null);
+                const health = await probeAuthHealth(agent, home, { cliVersion: opts?.cliVersion, info });
+                health.account = authAccountLabel(info);
+                if (health.verdict === 'unconfigured')
+                    return null;
+                return { agent, version, account: health.account, health };
+            })());
+        }
+    }
+    const settled = await Promise.all(tasks);
+    return settled.filter((r) => r !== null);
+}
+/** Persist a host's probed rows into the cache (keyed by host+agent+version). */
+export function writeFleetAuthRows(host, rows) {
+    const entries = {};
+    for (const row of rows) {
+        entries[authCacheKey(host, row.agent, row.version)] = row.health;
+    }
+    writeAuthHealthEntries(entries);
+}

package/dist/lib/browser/chrome.d.ts

@@ -24,6 +24,15 @@ export declare function findFirstInstalledBrowser(platform?: string): {
     browserType: BrowserType;
     binary: string;
 } | null;
+/**
+ * List every installed Chromium-family browser on this machine, in the platform
+ * priority order. Used by `agents setup browser` to offer a pick when more than
+ * one is present. Returns [] if none are installed.
+ */
+export declare function listInstalledBrowsers(platform?: string): {
+    browserType: BrowserType;
+    binary: string;
+}[];
 export interface LaunchResult {
     pid: number;
     port: number;

package/dist/lib/browser/chrome.js

@@ -203,6 +203,28 @@ export function findFirstInstalledBrowser(platform = os.platform()) {
     }
     return null;
 }
+/**
+ * List every installed Chromium-family browser on this machine, in the platform
+ * priority order. Used by `agents setup browser` to offer a pick when more than
+ * one is present. Returns [] if none are installed.
+ */
+export function listInstalledBrowsers(platform = os.platform()) {
+    const priority = DEFAULT_BROWSER_PRIORITY[platform];
+    const platformPaths = BROWSER_PATHS[platform];
+    if (!priority || !platformPaths)
+        return [];
+    const found = [];
+    for (const browserType of priority) {
+        const candidates = platformPaths[browserType] || [];
+        for (const p of candidates) {
+            if (fs.existsSync(p)) {
+                found.push({ browserType, binary: resolveBrowserBinary(p) });
+                break; // one install path per browser type is enough
+            }
+        }
+    }
+    return found;
+}
 export async function launchBrowser(profileName, browserType, port, options = {}, secrets, customBinary, 
 // `electron: true` distinguishes Notion / VS Code-style apps from
 // regular Chrome — purely informational, stored in meta.json so the

package/dist/lib/computer/download.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+/** GitHub repo whose `v<version>` releases carry the helper asset. */
+export declare const HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/** The zipped `.app` release asset name. */
+export declare const MAC_HELPER_ASSET = "ComputerHelper.app.zip";
+/** The bundle directory name once extracted. */
+export declare 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 declare const EXPECTED_TEAM_ID = "2HTP252L87";
+/** Cache dir for the downloaded helper, one subdir per release tag. */
+export declare function macHelperCacheDir(version: string): string;
+/** Release-asset URLs for the helper zip + its checksum at one `v<version>` tag. */
+export declare function macHelperAssetUrls(version: string): {
+    zip: string;
+    sha256: string;
+};
+/**
+ * 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 declare function verifyMacHelper(appPath: string): void;
+/**
+ * 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 declare function downloadMacHelperApp(version: string): Promise<string>;
+/**
+ * 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 declare function ensureMacHelperApp(version?: string): Promise<string>;