@phnx-labs/agents-cli 1.22.78 → 1.22.80

package/dist/commands/view.js

@@ -11,7 +11,7 @@ import { authCacheKey, readAuthHealthCache } from '../lib/auth-health.js';
 import { agentReportsUsage, classifyUsageErrorKind, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageBenignState, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, usageErrorForDisplay, } from '../lib/accounting/usage.js';
 import { isHeadedDeviceRole, selfConfiguredDeviceRole } from '../lib/device-config.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/installations/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/installations/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/installations/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { renderMergedResources } from '../lib/merged-resources.js';
@@ -21,6 +21,11 @@ import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins/plugins.js';
 import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts, readMeta } from '../lib/state.js';
 import { listNativeAccounts } from '../lib/account-registry.js';
+import { buildNativeCatalog } from '../lib/account-catalog.js';
+import { connectSupported } from '../lib/accounts/connect.js';
+import { readInstallation } from '../lib/installations/store.js';
+import { isAutoUpdateEnabledForAgent } from '../lib/installations/update-policy.js';
+import { selectUpdateStrategy } from '../lib/installations/strategies.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
@@ -68,6 +73,10 @@ export function namedAccountColumnLabel(agentId, info) {
     const saved = listNativeAccounts(readMeta()).find(item => item.agent === agentId && item.identityKey === identityKey);
     return saved ? `${saved.name} · ${display || saved.identityLabel || identityKey}` : display;
 }
+/** Human account identity; release labels belong only in installation diagnostics. */
+export function nativeAccountViewLabel(row) {
+    return row.name && row.name !== row.display ? `${row.name} · ${row.display}` : row.display;
+}
 /**
  * Human `agents view` row order: selected default first, then email-bearing
  * accounts alphabetically, then installs whose account has no email. Version
@@ -368,7 +377,7 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     const cliStates = Object.fromEntries(await Promise.all(agentsToShow
         .filter((agentId) => !hasNonIsolatedVersion(agentId))
         .map(async (agentId) => [agentId, await getUnmanagedCliState(agentId)])));
-    const showPaths = !!filterAgentId;
+    const showPaths = !!filterAgentId && viewOpts?.versions === true;
     // A filtered native view is about that native harness's installed versions.
     // Custom forks are standalone agent types and only belong in the overview.
     const harnesses = filterAgentId ? [] : getHarnesses();
@@ -452,7 +461,7 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         allowInteractiveLogin: usageAllowInteractiveLogin(),
     });
     spinner.stop();
-    console.log(chalk.bold('Installed Agent CLIs\n'));
+    console.log(chalk.bold(viewOpts?.versions ? 'Installed Agent CLIs\n' : 'Agents and accounts\n'));
     const mergeCanonical = (info) => {
         const key = getUsageLookupKey(info);
         if (!key)
@@ -504,12 +513,13 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         if (live)
             liveVersionByAgent.set(agentId, live);
     }));
-    const displayVersion = (agentId, dirVersion) => liveVersionByAgent.get(agentId) ?? dirVersion;
+    const displayVersion = (agentId, dirVersion) => liveVersionByAgent.get(agentId) ?? readInstallation(agentId, dirVersion)?.releaseVersion ?? dirVersion;
     // Uncolored row label, shared by the width pass and the render so padding lines
     // up. An isolated copy is never the global default (installing one deliberately
     // records no default), so the two tags can't collide.
     const versionRowLabel = (agentId, version, globalDefault) => {
-        const shown = displayVersion(agentId, version);
+        const release = displayVersion(agentId, version);
+        const shown = release === version ? version : `${version} → ${release}`;
         if (version === globalDefault)
             return `${shown} (default)`;
         if (isVersionIsolated(agentId, version)) {
@@ -522,7 +532,69 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         return shown;
     };
     // Show version-managed agents
-    if (versionManaged.length > 0) {
+    if (versionManaged.length > 0 && !viewOpts?.versions) {
+        const catalog = buildNativeCatalog(infoResults.map(({ agentId, version, home, info }) => ({
+            agent: agentId,
+            label: version,
+            releaseVersion: displayVersion(agentId, version),
+            accountKey: info.accountKey,
+            email: info.email,
+            signedIn: isLaunchableSignedIn(info.signedIn, credentialPresence(agentId, home)),
+        })), readMeta(), (agent) => getGlobalDefault(agent) ?? getIsolatedDefault(agent));
+        for (const agentId of versionManaged) {
+            const accounts = catalog.filter((row) => row.agent === agentId);
+            let updateLabel = 'manual updates';
+            try {
+                if (selectUpdateStrategy(agentId).transactional) {
+                    updateLabel = `automatic updates ${isAutoUpdateEnabledForAgent(agentId) ? 'on' : 'off'}`;
+                }
+            }
+            catch { /* unsupported updater: keep the truthful manual label */ }
+            console.log(`  ${chalk.bold(agentLabel(agentId))}${chalk.gray(` · ${updateLabel}`)}`);
+            const width = Math.max(0, ...accounts.map((row) => stringWidth(nativeAccountViewLabel(row))));
+            for (const row of accounts) {
+                const source = row.installations.find((home) => home.label === row.home && home.signedIn)
+                    ?? row.installations.find((home) => home.signedIn)
+                    ?? row.installations[0];
+                const rawInfo = source ? infoMap.get(`${agentId}:${source.label}`) : undefined;
+                const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
+                const usageKey = getUsageLookupKey(info);
+                const usageInfo = usageKey ? usageByKey.get(usageKey) : undefined;
+                const usage = formatUsageSummary(info?.plan ?? null, usageInfo?.snapshot ?? null, 3, viewUsageSummaryOptions(agentId, row.state === 'connected', usageInfo, usageWindowCap));
+                const connected = row.state === 'connected';
+                const model = source ? resolveConfiguredModel(agentId, source.label)?.model : null;
+                const pinned = row.installations.some((home) => readInstallation(agentId, home.label)?.updatePolicy === 'pinned');
+                const parts = [
+                    `    ${row.isDefault ? chalk.green('*') : ' '} ${chalk.cyan(padToWidth(nativeAccountViewLabel(row), width))}`,
+                    connected ? chalk.green('connected') : chalk.yellow('not connected here'),
+                    model ? chalk.yellow(model) : '',
+                    usage,
+                    formatUsageStatusBadge(info?.usageStatus),
+                    pinned ? chalk.gray('release pinned · --versions') : '',
+                ];
+                console.log(joinViewColumns(parts));
+            }
+            if (accounts.length === 0) {
+                const localIdentity = infoResults.some((row) => row.agentId === agentId && row.info.signedIn);
+                const hint = connectSupported(agentId) ? `agents accounts connect ${agentId}` : loginHint(agentId);
+                console.log(chalk.gray(localIdentity
+                    ? '    Native login detected · account identity unavailable'
+                    : `    No native login detected · ${hint}`));
+            }
+            const isolatedCount = listInstalledVersions(agentId).filter((label) => isVersionIsolated(agentId, label)).length;
+            if (isolatedCount > 0)
+                console.log(chalk.gray(`    ${isolatedCount} isolated installation${isolatedCount === 1 ? '' : 's'} · inspect with --versions`));
+            const projectVersion = getProjectVersionFromCwd(agentId);
+            if (projectVersion)
+                console.log(chalk.gray('    Project installation override configured · inspect with --versions'));
+            console.log();
+        }
+        if (filterAgentId) {
+            const connect = connectSupported(filterAgentId) ? `Connect: agents accounts connect ${filterAgentId} [name] · ` : '';
+            console.log(chalk.gray(`  ${connect}Details: agents view ${filterAgentId} --versions\n`));
+        }
+    }
+    if (versionManaged.length > 0 && viewOpts?.versions) {
         // Calculate column widths across all agents for alignment
         let maxVerLabel = 0;
         let maxEmail = 0;
@@ -596,7 +668,8 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                 const isDefault = version === globalDefault;
                 const isolated = !isDefault && isVersionIsolated(agentId, version);
                 const isolatedTag = getIsolatedDefault(agentId) === version ? ' (isolated default)' : ' (isolated)';
-                const shown = displayVersion(agentId, version);
+                const release = displayVersion(agentId, version);
+                const shown = release === version ? version : `${version} → ${release}`;
                 const base = versionRowLabel(agentId, version, globalDefault);
                 const tagPad = ' '.repeat(maxVerLabel - base.length);
                 const label = isDefault
@@ -1253,6 +1326,15 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
         }
     }
     const infoResults = await Promise.all(infoFetches);
+    const globalReleases = new Map();
+    await Promise.all(agentsToShow.filter(isGlobalBinaryAgent).map(async (agent) => {
+        if (!infoResults.some((row) => row.agentId === agent))
+            return;
+        const release = await getLiveVersion(agent);
+        if (release)
+            globalReleases.set(agent, release);
+    }));
+    const actualRelease = (agent, label) => globalReleases.get(agent) ?? readInstallation(agent, label)?.releaseVersion ?? label;
     const { canonicalByUsageKey, usageByKey } = await getUsageInfoByIdentity(infoResults.map(({ agentId, home, version, info }) => ({
         agentId,
         home,
@@ -1290,6 +1372,7 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
         const authHealth = authCache[authCacheKey(host, agentId, version)];
         const entry = {
             version,
+            releaseVersion: actualRelease(agentId, version),
             isDefault: version === globalDefault,
             isolated: isVersionIsolated(agentId, version),
             isIsolatedDefault: getIsolatedDefault(agentId) === version,
@@ -1348,7 +1431,16 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
                 return a.isDefault ? -1 : 1;
             return compareVersions(b.version, a.version);
         });
-        out.push({ agent: agentId, versions, harnesses: harnesses.filter((h) => h.agent === agentId) });
+        const accounts = buildNativeCatalog(infoResults.filter((row) => row.agentId === agentId).map(({ version, home, info }) => ({
+            agent: agentId,
+            label: version,
+            releaseVersion: actualRelease(agentId, version),
+            accountKey: info.accountKey,
+            email: info.email,
+            signedIn: isLaunchableSignedIn(info.signedIn, credentialPresence(agentId, home)),
+        })), readMeta(), (agent) => getGlobalDefault(agent) ?? getIsolatedDefault(agent))
+            .filter((row) => row.agent === agentId);
+        out.push({ agent: agentId, versions, accounts, harnesses: harnesses.filter((h) => h.agent === agentId) });
     }
     return out;
 }
@@ -1363,50 +1455,116 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
 export function pruneGroupKey(info) {
     return info.accountKey ?? info.email?.toLowerCase() ?? null;
 }
+/**
+ * PURE duplicate-home detection: given every installed home for one agent, decide
+ * which are redundant duplicates of the SAME logical account and which single home
+ * to keep per account. Extracted from buildAgentPrunePlan so the keeper/merge rules
+ * are unit-tested without touching disk.
+ *
+ * Two rules, both conservative:
+ *  - GROUPING. A home with a captured `accountKey` groups by it (account+org, so a
+ *    personal Max and a Team seat on the same email stay separate). A home with NO
+ *    accountKey folds into a same-email account ONLY when a sibling home for that
+ *    email IS identified — that email-only home is an incompletely-captured re-login
+ *    of the known account, not a distinct seat (PHNX-3887). Otherwise it groups by
+ *    its bare email and only ever collapses against another equally-bare home.
+ *  - KEEPER. Within a group the keeper is the home that best represents the account:
+ *    captured identity first, then a signed-in credential, then the newest RUNNING
+ *    release, then the highest dir label as a stable tiebreak. This is deliberately
+ *    NOT "highest dir-name semver" — in the wild that is the freshly re-logged-in
+ *    duplicate that never captured its identity or usage, and keeping it while
+ *    trashing the identified home is the exact bug this replaces.
+ */
+export function planDuplicatePrune(candidates) {
+    // Only installs with a working binary compete for "the live install for this account".
+    const installed = candidates.filter((c) => c.hasBinary && c.email);
+    // email -> every DISTINCT captured accountKey seen for it. An email-only home
+    // folds into an identified account only when that email maps to EXACTLY ONE
+    // account; when two distinct orgs share the email (the Personal+Team case) the
+    // fold is ambiguous, so the identity-less home is left ungrouped rather than
+    // guessed into one — guessing could retire the actually-working re-login of the
+    // OTHER org (the exact bug this function exists to prevent, one level up).
+    const emailToAccountKeys = new Map();
+    for (const c of installed) {
+        if (!c.accountKey)
+            continue;
+        const email = c.email.toLowerCase();
+        (emailToAccountKeys.get(email) ?? emailToAccountKeys.set(email, new Set()).get(email)).add(c.accountKey);
+    }
+    const groupKeyFor = (c) => {
+        if (c.accountKey)
+            return c.accountKey;
+        const email = c.email?.toLowerCase();
+        const keys = email ? emailToAccountKeys.get(email) : undefined;
+        if (keys && keys.size === 1)
+            return [...keys][0];
+        // ≥2 identified orgs on this email: never merge the ambiguous home. A unique
+        // key makes it its own singleton group (length 1 → never pruned).
+        if (keys && keys.size >= 2)
+            return `ambiguous:${c.email.toLowerCase()}:${c.version}`;
+        // No identified sibling at all: group equally-bare homes by email as before.
+        return pruneGroupKey(c);
+    };
+    const byAccount = new Map();
+    for (const c of installed) {
+        const key = groupKeyFor(c);
+        if (!key)
+            continue;
+        (byAccount.get(key) ?? byAccount.set(key, []).get(key)).push(c);
+    }
+    const rank = (c) => [c.accountKey ? 1 : 0, c.signedIn ? 1 : 0];
+    const better = (a, b) => {
+        const [aa, ab] = rank(a);
+        const [ba, bb] = rank(b);
+        if (aa !== ba)
+            return ba - aa;
+        if (ab !== bb)
+            return bb - ab;
+        if (a.release !== b.release)
+            return compareVersions(b.release, a.release);
+        return compareVersions(b.version, a.version);
+    };
+    const out = [];
+    for (const group of byAccount.values()) {
+        if (group.length < 2)
+            continue;
+        const sorted = [...group].sort(better);
+        const keeper = sorted[0].version;
+        for (const dup of sorted.slice(1)) {
+            out.push({ version: dup.version, email: dup.email, keeper });
+        }
+    }
+    return out;
+}
 async function buildAgentPrunePlan(agentId) {
     const dirInfos = listInstalledVersionDirs(agentId);
     const entries = await Promise.all(dirInfos.map(async ({ version, hasBinary }) => {
         const home = getVersionHomePath(agentId, version);
         const info = await getAccountInfo(agentId, home);
-        return { version, info, hasBinary };
+        const release = readInstallation(agentId, version)?.releaseVersion ?? version;
+        return { version, info, hasBinary, release };
     }));
     const globalDefault = getGlobalDefault(agentId);
     const toPrune = [];
-    const skippedDefaults = [];
-    // Duplicate-account detection runs only over installs that actually have a
-    // working binary — those are the things that compete for "the live install
-    // for this account."
-    const installed = entries.filter((e) => e.hasBinary);
-    const byAccount = new Map();
-    for (const e of installed) {
-        if (!e.info.email)
-            continue;
-        const key = pruneGroupKey(e.info);
-        if (!key)
-            continue;
-        const list = byAccount.get(key) ?? [];
-        list.push(e);
-        byAccount.set(key, list);
-    }
-    for (const [, group] of byAccount) {
-        if (group.length < 2)
-            continue;
-        const sorted = [...group].sort((a, b) => compareVersions(b.version, a.version));
-        const keeper = sorted[0].version;
-        for (const older of sorted.slice(1)) {
-            const plan = {
-                agentId,
-                version: older.version,
-                email: older.info.email,
-                keeper,
-                isDefault: older.version === globalDefault,
-                reason: 'duplicate',
-            };
-            if (plan.isDefault)
-                skippedDefaults.push(plan);
-            else
-                toPrune.push(plan);
-        }
+    for (const d of planDuplicatePrune(entries.map((e) => ({
+        version: e.version,
+        release: e.release,
+        email: e.info.email,
+        accountKey: e.info.accountKey,
+        signedIn: e.info.signedIn,
+        hasBinary: e.hasBinary,
+    })))) {
+        toPrune.push({
+            agentId,
+            version: d.version,
+            email: d.email,
+            keeper: d.keeper,
+            // The default may itself be a to-be-retired duplicate (a freshly created
+            // home often becomes the global default). We do NOT skip it: executePrune
+            // repoints the default onto the keeper first, then retires the duplicate.
+            isDefault: d.version === globalDefault,
+            reason: 'duplicate',
+        });
     }
     // Home-only leftovers: dirs without a binary. These are residue from a
     // prior removeVersion before the soft-delete migration, plus any hand-edited
@@ -1425,10 +1583,20 @@ async function buildAgentPrunePlan(agentId) {
             reason: 'home-leftover',
         });
     }
-    return { agentId, toPrune, skippedDefaults };
+    return { agentId, toPrune };
 }
-async function executePrunePlan(plan) {
+export async function executePrunePlan(plan) {
     const moved = [];
+    // Repoint the global default onto the keeper BEFORE retiring a duplicate that
+    // currently holds it, so consolidation collapses the duplicate instead of
+    // leaving it pinned as the default (and so removeVersion's own fallback never
+    // has to guess a replacement).
+    for (const p of plan.toPrune) {
+        if (p.reason === 'duplicate' && p.isDefault && p.keeper && p.keeper !== p.version) {
+            setGlobalDefault(p.agentId, p.keeper);
+            console.log(chalk.gray(`Default ${agentLabel(p.agentId)} moved ${p.version} → ${p.keeper} (keeper) before pruning the duplicate.`));
+        }
+    }
     for (const p of plan.toPrune) {
         const ok = removeVersion(p.agentId, p.version);
         if (ok) {
@@ -1445,14 +1613,6 @@ async function executePrunePlan(plan) {
     return moved;
 }
 function printPrunePlan(plan, isFirst) {
-    if (plan.skippedDefaults.length > 0) {
-        console.log(chalk.yellow(`Skipping default versions for ${agentLabel(plan.agentId)} (switch default first):`));
-        for (const s of plan.skippedDefaults) {
-            console.log(`  ${agentLabel(s.agentId)}@${s.version}  ${chalk.cyan(s.email)}  ` +
-                chalk.gray(`— duplicate of ${s.agentId}@${s.keeper}. Run: agents use ${s.agentId}@${s.keeper}`));
-        }
-        console.log();
-    }
     if (plan.toPrune.length === 0)
         return;
     const heading = isFirst ? `Will move to trash for ${agentLabel(plan.agentId)}:` : `Also found candidates for ${agentLabel(plan.agentId)}:`;
@@ -1470,9 +1630,11 @@ function printPrunePlan(plan, isFirst) {
     console.log();
 }
 /**
- * Prune older installed versions that share an email with a newer installed
- * version. Keeps the highest semver per email, skips the global default (with
- * a warning so the user can switch first).
+ * Consolidate to one home per logical account: retire the redundant duplicate
+ * homes an account accumulated, keeping the single home that best represents it
+ * (see {@link planDuplicatePrune} for the keeper/merge rules). When the retired
+ * duplicate holds the global default, the default is first repointed onto the
+ * keeper, so consolidation collapses it instead of leaving it pinned.
  *
  * When filterAgentId is set, prunes that agent first, then cascades: after
  * each agent, offers the next agent with duplicates. User answering "no"
@@ -1485,7 +1647,7 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
     const spinner = ora({ text: 'Scanning installed versions...', isSilent: !process.stdout.isTTY }).start();
     const plans = await Promise.all(ordered.map((a) => buildAgentPrunePlan(a)));
     spinner.stop();
-    const actionable = plans.filter((p) => p.toPrune.length > 0 || p.skippedDefaults.length > 0);
+    const actionable = plans.filter((p) => p.toPrune.length > 0);
     if (actionable.length === 0) {
         console.log(chalk.gray('Nothing to prune — no duplicate-account installs and no home-only leftovers.'));
         return;
@@ -1496,11 +1658,6 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
     let processedAny = false;
     for (const plan of actionable) {
         printPrunePlan(plan, isFirst);
-        if (plan.toPrune.length === 0) {
-            // Only skippedDefaults for this agent; move on.
-            isFirst = false;
-            continue;
-        }
         if (dryRun) {
             processedAny = true;
             isFirst = false;
@@ -1603,8 +1760,7 @@ export async function viewAction(agentArg, options) {
             console.log(JSON.stringify(data, null, 2));
             return;
         }
-        // No argument: show all installed versions
-        await showInstalledVersions(undefined, { forceRefresh });
+        await showInstalledVersions(undefined, { forceRefresh, versions: options?.versions });
         return;
     }
     // Parse agent@version syntax
@@ -1675,15 +1831,15 @@ export async function viewAction(agentArg, options) {
         await showAgentResources(agentId, 'default', filter);
     }
     else {
-        // Just agent name: show versions for that agent
-        await showInstalledVersions(agentId, { forceRefresh });
+        await showInstalledVersions(agentId, { forceRefresh, versions: options?.versions });
     }
 }
 /** Register the `agents view` command. */
 export function registerViewCommand(program) {
     addHostOption(program.command('view [agent]'))
-        .description('Show what agent CLIs are installed and which versions you have. Inspect resources when you pass agent@version.')
-        .option('--json', 'Emit machine-readable JSON (version list, usage, signed-in status).')
+        .description('Show your agents, connected accounts, and usage. Use --versions for installation diagnostics.')
+        .option('--versions', 'Show every installation, actual release, account, model, and home path.')
+        .option('--json', 'Emit machine-readable JSON (accounts plus backward-compatible installation list).')
         .option('--resources [sections]', 'In --json mode, include each version\'s resources: "all" (default) or a comma list (skills,plugins,mcp,commands,workflows,memory,hooks). Implies --json.')
         .option('--detailed', 'Include all resources in --json output (alias for --resources all). Implies --json.')
         .option('-r, --refresh', 'Force a live usage refresh, bypassing the cache (slower). Repopulates the S:/W: limit bars for every account whose token is reachable.')
@@ -1703,12 +1859,15 @@ export function registerViewCommand(program) {
         .option('--merged', 'Show the merged, first-wins resource surface across all layers (project, user, extras, system) in one table with the winning layer per row.')
         .addHelpText('after', `
 Examples:
-  # Show all installed agents with versions, accounts, and usage
+  # Show installed agents with connected accounts and usage
   agents view
 
-  # Show versions for one agent
+  # Show accounts for one agent
   agents view claude
 
+  # Inspect installation labels, current releases, models, and paths
+  agents view claude --versions
+
   # Describe one custom harness (host, model, provider, auth, path)
   agents view deepseek-flash
 
@@ -1738,16 +1897,17 @@ Examples:
   agents view --merged
 
 When to use:
-  - Checking which agents are installed and what their default versions are
-  - Seeing which account each version is logged into (useful for multi-account setups)
+  - Checking which agents and accounts are connected on this device
+  - Seeing the selected default account and each account's usage
   - Inspecting commands, skills, hooks, and MCP servers synced to a version
   - Verifying a version is installed before running it
   - Cleaning up stale versions left behind after upgrading (--prune)
 
 Output:
-  - Without arguments: table of all agents with versions, emails, usage stats,
+  - Without arguments: table of all agents with accounts, connection state, usage,
     then one block per custom harness (see 'agents harness')
-  - With agent name: versions for that agent, showing which is the default
+  - With agent name: one row per native identity, showing the default account
+  - With --versions: every retained installation, actual release, model, and home
   - With a custom harness name: that harness's host, model, provider, and auth
   - With agent@version: detailed breakdown of resources synced to that version
   - With --json: structured JSON with version, isDefault, signedIn, authVerdict,

package/dist/index.js

@@ -24,8 +24,21 @@
  * agent.js would pull the whole secrets graph into every invocation.
  */
 import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './lib/secrets/sync-commands.js';
-// Force exit on Ctrl+C when no interactive prompt is handling it.
-process.on('SIGINT', () => process.exit(130));
+// Force exit on Ctrl+C when no interactive prompt is handling it — UNLESS a
+// guarded harness auto-update pass is mutating this process transactionally
+// (PHNX-3940). A hard exit mid-swap can leave an installation whose directory
+// and metadata disagree, so defer ONLY while that guard is held; the pass sees
+// the same SIGINT cooperatively (lib/installations/update-cancellation.ts) and
+// stops at its next safe boundary. The depth is read through the shared
+// `Symbol.for` registry key so this slim entry shell needs no static import of
+// that module (agent.test.ts pins the single allowed import). Every other SIGINT
+// still force-exits 130, and no other listener is touched.
+process.on('SIGINT', () => {
+    const depth = globalThis[Symbol.for('agents.guardedAutoUpdateDepth')] ?? 0;
+    if (depth > 0)
+        return;
+    process.exit(130);
+});
 // Ignore SIGPIPE — prevents exit code 13 crashes in piped environments
 // (e.g. `agents sessions | head`, or when stdout is captured by another process).
 process.on('SIGPIPE', () => { });
@@ -58,6 +71,15 @@ if (process.argv[2] === SYNC_GET_CMD ||
             : await runAgentLockSync(name);
     process.exit(code);
 }
+// Launch-lease delegate: every generated native shim/alias calls
+// `agents __launch-lease <agent> <label> <pid>` right before its final `exec`
+// (PHNX-3940) — on the hot launch path of every managed agent, so it must skip
+// the same update-check/bootstrap machinery `__shim` skips below. See
+// `lib/installations/launch-gate.ts` for what this call actually does.
+if (process.argv[2] === '__launch-lease') {
+    const { runLaunchLeaseCli } = await import('./lib/installations/launch-gate.js');
+    process.exit(await runLaunchLeaseCli(process.argv.slice(3)));
+}
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before bootstrap
 // parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
@@ -98,6 +120,17 @@ if (process.argv[2] === '__usage-export') {
     process.stdout.write(JSON.stringify({ v: 1, rows: exportClaudeUsageCacheRows() }));
     process.exit(0);
 }
+// Harness auto-update child (PHNX-3940): the daemon's harness-update tick spawns
+// `agents __harness-update-run` over a Node IPC channel and cancels it
+// cooperatively by MESSAGE, never a kill (see
+// lib/daemon/harness-update-service.ts + lib/installations/update-cancellation.ts).
+// Above bootstrap for the same reason as __daemon-run: this internal periodic
+// child must not itself fire a self-update check or fork a detached sync, and its
+// stdout carries a clean JSON summary the daemon logs.
+if (process.argv[2] === '__harness-update-run') {
+    const { runHarnessUpdateChild } = await import('./lib/installations/update-runtime.js');
+    process.exit(await runHarnessUpdateChild());
+}
 if (process.argv[2] === '__daemon-run') {
     const { runDaemon, log: daemonLog } = await import('./lib/daemon/daemon.js');
     // RUSH-2418: the daemon is the one always-on process here, and it ran with no

package/dist/lib/account-catalog.d.ts

@@ -1,4 +1,15 @@
-import type { AgentId } from './types.js';
+import { type AccountInfo } from './agents.js';
+import type { AgentId, Meta } from './types.js';
+/**
+ * Strict "is this home actually connected?" — a live CREDENTIAL in that exact
+ * version home, not just a metadata identity claim (PHNX-3940). A `.claude.json`
+ * carrying an `oauthAccount` block with no `.credentials.json`/`.oauth_token`
+ * beside it is stale/expired, and must read as `reconnect-needed`, never
+ * `connected`. Where agents-cli does not know the credential location
+ * (`knownLocation` false), it falls back to the metadata `signedIn` since there
+ * is nothing stricter to check.
+ */
+export declare function isLaunchableSignedIn(agent: AgentId, versionHome: string, info: Pick<AccountInfo, 'signedIn'>): boolean;
 export interface NativeAccountCatalogEntry {
     kind: 'native';
     id: string;
@@ -16,3 +27,88 @@ export declare function groupNativeAccountRows(rows: Array<{
 }>): NativeAccountCatalogEntry[];
 /** Discover signed-in harness-native identities without copying their auth files. */
 export declare function discoverNativeAccounts(): Promise<NativeAccountCatalogEntry[]>;
+/** One installed home carrying an identity — the secondary "release/home" facts. */
+export interface AccountHome {
+    /** The installation label (version-dir basename). */
+    label: string;
+    /** The vendor release the home currently carries, when the record is present. */
+    releaseVersion: string | null;
+    /** Whether this exact home currently has a live signed-in credential. */
+    signedIn: boolean;
+}
+/**
+ * A live credential state, derived from the homes rather than the registry:
+ * - `connected` — at least one home for this identity is signed in.
+ * - `reconnect-needed` — the account is registered (or was created by connect)
+ *   but no home currently holds a live credential; the label alone is not a
+ *   connection. `agents accounts connect <name>` re-authenticates it.
+ */
+export type AccountConnectionState = 'connected' | 'reconnect-needed';
+/** Account-first row for a native (harness-owned OAuth) identity. */
+export interface NativeAccountCatalogRow {
+    kind: 'native';
+    agent: AgentId;
+    identityKey: string;
+    /** Registered account name/label, or null for an unnamed discovered login. */
+    name: string | null;
+    /** Registered stable account id, or null when unnamed. */
+    id: string | null;
+    email: string | null;
+    display: string;
+    /**
+     * The LOCAL installation home for this identity on THIS box: the recorded
+     * connect home when installed here, else the local home carrying the login.
+     * Null when no local home exists (the identity may be connected on another
+     * box). Per-host by construction — never a label another box minted.
+     */
+    home: string | null;
+    /** Every installed home carrying this identity (secondary diagnostics). */
+    installations: AccountHome[];
+    /** Whether the harness's configured default account points at this identity. */
+    isDefault: boolean;
+    state: AccountConnectionState;
+}
+/** Account-first row for a durable provider (API-key / token) account bundle. */
+export interface ProviderAccountCatalogRow {
+    kind: 'provider';
+    name: string;
+    id: string;
+    provider: string;
+    auth: string;
+    baseUrl?: string;
+}
+export type AccountCatalogRow = NativeAccountCatalogRow | ProviderAccountCatalogRow;
+export interface AccountCatalog {
+    native: NativeAccountCatalogRow[];
+    provider: ProviderAccountCatalogRow[];
+}
+/** One installed home probed for its native identity — the raw input to the fold. */
+export interface NativeHomeRow {
+    agent: AgentId;
+    label: string;
+    releaseVersion: string | null;
+    accountKey: string | null;
+    email: string | null;
+    signedIn: boolean;
+}
+/** Probe every installed home of every inspectable harness for its native identity. */
+export declare function collectNativeHomeRows(): Promise<NativeHomeRow[]>;
+/** The subset of Meta the pure builder reads — the registered native accounts + defaults. */
+type CatalogMeta = Pick<Meta, 'accounts' | 'deviceAccounts'>;
+/**
+ * Fold installed homes + the registry into account-first native rows (pure).
+ *
+ * Every home carrying an identity contributes an `AccountHome`; the identity is
+ * the group key. A registered account (name/id/connect home) is merged onto its
+ * identity, and — crucially — a registered account whose identity has NO live
+ * home still appears, as `reconnect-needed`, so a stale/expired login is never
+ * silently dropped from the list nor shown as connected.
+ */
+export declare function buildNativeCatalog(rows: NativeHomeRow[], meta: CatalogMeta, globalDefault?: (agent: AgentId) => string | null): NativeAccountCatalogRow[];
+/**
+ * Wire the real collectors to the pure builder. This is the canonical
+ * account-first read model `view.ts` renders: native identities (account +
+ * connection first, release/home secondary) plus the durable provider bundles.
+ */
+export declare function loadAccountCatalog(): Promise<AccountCatalog>;
+export {};