@phnx-labs/agents-cli 1.22.78 → 1.22.79

package/dist/commands/view.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;
 }
@@ -1603,8 +1695,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 +1766,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 +1794,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 +1832,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 {};

package/dist/lib/account-catalog.js

@@ -1,5 +1,21 @@
-import { ALL_AGENT_IDS, getAccountInfo, supportsAccountInspection } from './agents.js';
-import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
+import { ALL_AGENT_IDS, credentialPresence, getAccountInfo, supportsAccountInspection } from './agents.js';
+import { getGlobalDefault, getVersionHomePath, listInstalledVersions } from './installations/versions.js';
+import { readInstallation } from './installations/store.js';
+import { readMeta } from './state.js';
+import { listNativeAccounts, readAccountRegistry } from './account-registry.js';
+import { isLaunchableSignedIn as isCredentialLaunchable } from './accounting/rotate.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 function isLaunchableSignedIn(agent, versionHome, info) {
+    return isCredentialLaunchable(info.signedIn, credentialPresence(agent, versionHome));
+}
 export function groupNativeAccountRows(rows) {
     const grouped = new Map();
     for (const row of rows) {
@@ -27,12 +43,124 @@ export function groupNativeAccountRows(rows) {
 }
 /** Discover signed-in harness-native identities without copying their auth files. */
 export async function discoverNativeAccounts() {
+    const rows = await collectNativeHomeRows();
+    return groupNativeAccountRows(rows.map(r => ({ agent: r.agent, version: r.label, accountKey: r.accountKey, email: r.email, signedIn: r.signedIn })));
+}
+/** Probe every installed home of every inspectable harness for its native identity. */
+export async function collectNativeHomeRows() {
     const rows = [];
     for (const agent of ALL_AGENT_IDS.filter(supportsAccountInspection)) {
-        for (const version of listInstalledVersions(agent)) {
-            const info = await getAccountInfo(agent, getVersionHomePath(agent, version));
-            rows.push({ agent, version, accountKey: info.accountKey, email: info.email, signedIn: info.signedIn });
+        for (const label of listInstalledVersions(agent)) {
+            const home = getVersionHomePath(agent, label);
+            const info = await getAccountInfo(agent, home);
+            rows.push({
+                agent,
+                label,
+                releaseVersion: readInstallation(agent, label)?.releaseVersion ?? null,
+                accountKey: info.accountKey,
+                email: info.email,
+                // Strict: a live credential in THIS home, not a bare metadata identity.
+                signedIn: isLaunchableSignedIn(agent, home, info),
+            });
+        }
+    }
+    return rows;
+}
+/**
+ * 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 function buildNativeCatalog(rows, meta, globalDefault = getGlobalDefault) {
+    const registered = listNativeAccounts(meta);
+    const defaults = meta.accounts?.defaults ?? {};
+    const groups = new Map();
+    const keyOf = (agent, identity) => `${agent}:${identity}`;
+    // Every installed home that carries a resolvable identity seeds a group.
+    for (const row of rows) {
+        const identity = row.accountKey ?? row.email?.toLowerCase();
+        if (!identity)
+            continue;
+        const key = keyOf(row.agent, identity);
+        const group = groups.get(key) ?? { agent: row.agent, identityKey: identity, email: null, homes: [] };
+        group.email ??= row.email;
+        group.homes.push({ label: row.label, releaseVersion: row.releaseVersion, signedIn: row.signedIn });
+        groups.set(key, group);
+    }
+    // A registered account whose identity has no discovered home still belongs in
+    // the catalog — it just has nothing live to connect through yet. Its
+    // `identityKey` is the same value a home row groups on (a raw accountKey, or
+    // an already-lowercased email), so an exact-key check finds the existing group.
+    for (const account of registered) {
+        const key = keyOf(account.agent, account.identityKey);
+        if (!groups.has(key)) {
+            groups.set(key, { agent: account.agent, identityKey: account.identityKey, email: account.identityLabel ?? null, homes: [] });
+        }
+    }
+    const out = [];
+    for (const group of groups.values()) {
+        const account = registered.find(a => a.agent === group.agent && a.identityKey === group.identityKey);
+        const email = group.email ?? account?.identityLabel ?? null;
+        const homes = [...group.homes].sort((a, b) => a.label.localeCompare(b.label));
+        const signedIn = homes.some(h => h.signedIn);
+        // The configured per-harness account default is AUTHORITATIVE: when present,
+        // only the matching native account is the default — an explicit default that
+        // names a provider (or a stale name) never invents a native default. Only
+        // when NO account default is configured does the global-default installation
+        // home decide (diagnostic fallback).
+        const defaultRef = defaults[group.agent];
+        let isDefault;
+        if (defaultRef !== undefined) {
+            isDefault = !!account && (account.name === defaultRef || account.id === defaultRef);
+        }
+        else {
+            const gd = globalDefault(group.agent);
+            isDefault = !!gd && homes.some(h => h.label === gd);
         }
+        // The home is a PER-HOST fact: this box's recorded connect home when it is
+        // actually installed here, else the local home carrying the identity. A home
+        // label recorded on another box is never assumed to exist locally.
+        const recordedHome = account ? (meta.deviceAccounts?.homes?.[account.id] ?? null) : null;
+        const home = (recordedHome && homes.some(h => h.label === recordedHome))
+            ? recordedHome
+            : (homes.find(h => h.signedIn)?.label ?? homes[0]?.label ?? null);
+        out.push({
+            kind: 'native',
+            agent: group.agent,
+            identityKey: group.identityKey,
+            name: account?.name ?? null,
+            id: account?.id ?? null,
+            email,
+            display: email ?? account?.name ?? group.identityKey,
+            home,
+            installations: homes,
+            isDefault,
+            state: signedIn ? 'connected' : 'reconnect-needed',
+        });
     }
-    return groupNativeAccountRows(rows);
+    // Named accounts first, then default, then a stable display order.
+    return out.sort((a, b) => a.agent.localeCompare(b.agent)
+        || Number(!!b.name) - Number(!!a.name)
+        || Number(b.isDefault) - Number(a.isDefault)
+        || a.display.localeCompare(b.display));
+}
+function toProviderRow(account) {
+    return { kind: 'provider', name: account.name, id: account.id, provider: account.provider, auth: account.auth, baseUrl: account.baseUrl };
+}
+/**
+ * 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 async function loadAccountCatalog() {
+    const meta = readMeta();
+    const native = buildNativeCatalog(await collectNativeHomeRows(), meta);
+    const provider = Object.values(readAccountRegistry().accounts)
+        .map(toProviderRow)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { native, provider };
 }

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

@@ -55,9 +55,52 @@ export declare function listNativeAccounts(meta: Pick<Meta, 'accounts' | 'device
  * able to omit it.
  */
 export declare function findUnifiedAccount(nameOrId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, doc?: AccountRegistryDocument, preferAgent?: AgentId): UnifiedAccount | null;
+/**
+ * Validate a native account NAME (charset + per-harness uniqueness) WITHOUT a
+ * known identity — the pre-flight `agents accounts connect` runs before it
+ * installs a home and drives a login, so a bad/colliding name fails before any
+ * side effect instead of orphaning a freshly-minted home (PHNX-3940).
+ */
+export declare function assertNativeAccountNameAvailable(name: string, agent: AgentId): void;
 export declare function addNativeAccount(name: string, agent: AgentId, identityKey: string, identityLabel: string | undefined, scope: 'version' | 'device'): NativeAccount;
 /** Create or replace the version-independent label for one native identity. */
 export declare function labelNativeAccount(agent: AgentId, identityKey: string, identityLabel: string | undefined, label: string | undefined, scope: 'version' | 'device'): NativeAccount;
+/**
+ * Record THIS box's connect home for an account (PHNX-3940). Device-scoped: the
+ * home a box minted for an account is not assumed to exist on any other box, so
+ * it lives in the device doc keyed by the stable account id, never on the
+ * fleet-synced central identity row. Idempotent. A reconnect reads it back via
+ * {@link nativeAccountHome} to reuse the exact home even when the credential has
+ * expired and local signed-in discovery can no longer find it.
+ */
+export declare function setNativeAccountHome(accountId: string, installationLabel: string): void;
+/** This box's recorded connect home for an account, or null. */
+export declare function nativeAccountHome(accountId: string, meta: Pick<Meta, 'deviceAccounts'>): string | null;
+/**
+ * Every installation label THIS box has recorded as SOME account's connect home
+ * (PHNX-3940). These are identity-bearing and MUST NEVER be re-minted for a new
+ * account — the safe-allocation invariant that stops a new connect from
+ * overwriting another account's login.
+ */
+export declare function ownedConnectHomeLabels(meta: Pick<Meta, 'deviceAccounts'>): Set<string>;
+/** This box's in-flight connect slot for `(agent, name)`, or null. */
+export declare function pendingConnectSlot(agent: AgentId, name: string, meta: Pick<Meta, 'deviceAccounts'>): string | null;
+/** Record an in-flight connect slot for `(agent, name)` (device-scoped). */
+export declare function setPendingConnectSlot(agent: AgentId, name: string, slot: string): void;
+/** Clear the in-flight connect slot for `(agent, name)` once the account lands. */
+export declare function clearPendingConnectSlot(agent: AgentId, name: string): void;
+/**
+ * Set the per-harness default account by NAME only when none is configured
+ * (PHNX-3940). Never overrides an existing choice — a first connect selecting a
+ * default is a convenience, not a takeover. Returns whether it set the default.
+ *
+ * The check-then-write is performed INSIDE the `updateMeta` callback so two
+ * concurrent callers (concurrent Promises or back-to-back calls on an async
+ * boundary) cannot both observe "no default" and then both set themselves. Only
+ * the first write wins; the second callback sees the first's write and returns
+ * the current state unchanged.
+ */
+export declare function setDefaultAccountIfAbsent(agent: AgentId, name: string): boolean;
 export declare function bindAccount(nameOrId: string, target: string, preferAgent?: AgentId): UnifiedAccount;
 export declare function unbindAccount(nameOrId: string, target: string, preferAgent?: AgentId): void;
 /** Every target bound to `accountId`: this box's device-doc bindings merged over