@phnx-labs/agents-cli 1.22.78 → 1.22.80

package/dist/commands/exec.js

@@ -2218,13 +2218,21 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     process.exit(1);
                 }
                 const { resolveAccountVersion } = await import('../lib/accounting/rotate.js');
-                accountConfigVersion = await resolveAccountVersion(agent, spawnAccount.identityKey) ?? undefined;
+                const { nativeAccountHome } = await import('../lib/account-registry.js');
+                const { readMeta } = await import('../lib/state.js');
+                accountConfigVersion = await resolveAccountVersion(agent, spawnAccount.identityKey, nativeAccountHome(spawnAccount.id, readMeta())) ?? undefined;
                 if (!accountConfigVersion) {
                     console.error(chalk.red(`No installed ${spawnAccount.agent} version is signed in as the identity labeled '${spawnAccount.name}'. Sign in as that identity, or label a different account.`));
                     process.exit(1);
                 }
+                // An account-only run executes the account's own stable installation.
+                // This keeps its model/mode configuration and binary update policy
+                // together. An explicit installation or profile still controls the
+                // executable independently; configVersion continues to select auth.
+                if (!version && !fromProfile)
+                    version = accountConfigVersion;
                 if (!options.quiet)
-                    process.stderr.write(chalk.gray(`[agents] account '${spawnAccount.name}' · ${agent} auth from ${accountConfigVersion}\n`));
+                    process.stderr.write(chalk.gray(`[agents] account '${spawnAccount.name}' · ${agent}\n`));
             }
             else {
                 accountEnv = spawnAccount.env;
@@ -2666,11 +2674,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         // Login preflight (advisory, warn + continue). On a local INTERACTIVE
         // launch, probe whether this agent's account has a credential and print a
         // one-line warning if it looks logged out — so you find out BEFORE the TUI
-        // opens, not after typing a prompt and getting "/login" back. Uses the same
-        // account-global probe as `checkCliSignedIn` / `agents doctor`
-        // (getAccountInfo with no home): file-based, no Keychain ACL prompt, and
-        // correct for HOME-global credential agents (grok/codex) where a per-version
-        // home would false-negative. It can still false-negative for opaque
+        // opens, not after typing a prompt and getting "/login" back. Inspect the
+        // selected account home, not an unrelated global login. This file-based
+        // read makes no Keychain ACL prompt. It can still false-negative for opaque
         // credentials, so this NEVER blocks — it warns and launches anyway. Skipped
         // for --json/--quiet, when a rotation already picked a signed-in account,
         // and via --no-auth-check / AGENTS_NO_AUTH_CHECK=1. (--device/--lease return
@@ -2688,12 +2694,13 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 // `signInLaunch` means the zero-healthy path already reported this exact
                 // account as logged out and named the login command, so re-probing here
                 // only prints a second, near-identical warning.
-                rotated: !!rotationResult || accountPickerRequested || signInLaunch,
+                rotated: !!rotationResult || accountPickerRequested || signInLaunch || spawnAccount?.kind === 'provider',
             });
             if (preflight) {
                 try {
                     const { getAccountInfo } = await import('../lib/agents.js');
-                    const info = await getAccountInfo(agent);
+                    const authVersion = accountConfigVersion ?? version;
+                    const info = await getAccountInfo(agent, authVersion ? getVersionHomePath(agent, authVersion) : undefined);
                     // Claude authenticates interactively from a per-version setup-token on a
                     // keychain-less worker (the shim's .oauth_token fallback), which the
                     // native-credential probe above can't see — so don't warn "logged out" when
@@ -2706,7 +2713,11 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                         authedViaSetupToken = resolveClaudeSetupToken(getVersionHomePath('claude', version)) !== null;
                     }
                     if (!info.signedIn && !authedViaSetupToken) {
-                        process.stderr.write(chalk.yellow(`⚠  ${agent} looks logged out — log in with: ${loginHint(agent)}. Launching anyway...\n`));
+                        const { connectSupported } = await import('../lib/accounts/connect.js');
+                        const hint = connectSupported(agent)
+                            ? `agents accounts connect ${agent}${spawnAccount?.kind === 'native' ? ` ${spawnAccount.name}` : ''}`
+                            : loginHint(agent);
+                        process.stderr.write(chalk.yellow(`${agent} looks logged out — sign in with: ${hint}. Launching anyway...\n`));
                     }
                 }
                 catch {

package/dist/commands/update.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
-import { formatAgentError, resolveAgentName } from '../lib/agents.js';
+import { AGENTS, formatAgentError, resolveAgentName } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
-import { describeInstallation, listInstallations, resolveInstallation, selectUpdateStrategy, supportsPinnedUpdate, updateInstallation, } from '../lib/installations/index.js';
+import { describeInstallation, effectiveUpdatePolicy, listInstallations, planAutoUpdates, resolveInstallation, runAutoUpdatePass, selectUpdateStrategy, supportsPinnedUpdate, updateInstallation, } from '../lib/installations/index.js';
 /**
  * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
  * label, or the release it currently carries — never a release to install; that
@@ -38,11 +38,16 @@ function printOutcome(outcome, json) {
             fromRelease: outcome.fromRelease,
             toRelease: outcome.toRelease,
             unchanged: outcome.unchanged,
+            deferred: outcome.deferred,
             alsoUpdated: outcome.alsoUpdated.map(serialize),
         }, null, 2));
         return;
     }
     const name = `${outcome.installation.agent}@${outcome.installation.label}`;
+    if (outcome.deferred) {
+        console.log(chalk.yellow(`${name}: ${outcome.deferred} Still on release ${outcome.installation.releaseVersion}.`));
+        return;
+    }
     if (outcome.unchanged) {
         console.log(chalk.gray(`${name} is already on release ${outcome.toRelease}.`));
         return;
@@ -78,37 +83,174 @@ function fail(err) {
     console.error(chalk.red(err.message));
     process.exitCode = 1;
 }
+function serializePlanEntry(entry) {
+    const wouldUpdate = entry.eligible && !entry.deferred
+        && !!entry.targetRelease && entry.targetRelease !== entry.currentRelease;
+    return {
+        agent: entry.agent,
+        label: entry.installation.label,
+        currentRelease: entry.currentRelease,
+        targetRelease: entry.targetRelease,
+        policy: entry.policy,
+        eligible: entry.eligible,
+        deferred: entry.deferred,
+        wouldUpdate,
+        reason: entry.reason,
+    };
+}
+/** `--check`'s dry-run output: eligibility/current/target/policy/deferral, machine-readable with `--json`. */
+function printPlan(plan, json) {
+    const rows = plan.map(serializePlanEntry);
+    if (json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(chalk.gray('No managed installations to check.'));
+        return;
+    }
+    console.log(chalk.bold('Automatic-update plan\n'));
+    for (const row of rows) {
+        const name = `${row.agent}@${row.label}`;
+        const status = row.wouldUpdate
+            ? chalk.green(`would update ${row.currentRelease} -> ${row.targetRelease}`)
+            : row.deferred
+                ? chalk.yellow(`deferred — ${row.reason}`)
+                : !row.eligible
+                    ? chalk.gray(`not eligible — ${row.reason}`)
+                    : chalk.gray('already current');
+        console.log(`  ${chalk.cyan(name.padEnd(28))} policy=${row.policy.padEnd(7)} ${status}`);
+    }
+}
+/**
+ * `--to` also decides the installation's update policy going forward: a
+ * concrete release is a manual pin (excluded from the automatic pass until
+ * explicitly unpinned), `latest` (the default) unpins it. Returns `null` when
+ * `--to` was not passed at all, meaning: don't touch the stored policy.
+ */
+function policyForTo(to) {
+    if (to === undefined)
+        return null;
+    return to === 'latest' ? 'latest' : 'pinned';
+}
+async function updateOne(agent, installation, options) {
+    const strategy = selectUpdateStrategy(agent);
+    if (!options.json && !strategy.transactional) {
+        console.log(chalk.yellow(`${agent} installs one vendor-managed binary, so this update cannot be staged or rolled back; `
+            + `a failure leaves whatever its installer wrote.`));
+    }
+    if (!options.json) {
+        console.log(chalk.gray(`Updating ${agent}@${describeInstallation(installation)} via the ${strategy.id} strategy...`));
+    }
+    const outcome = await updateInstallation(installation, {
+        to: options.to,
+        updatePolicy: policyForTo(options.to) ?? undefined,
+        onProgress: options.json ? undefined : (message) => console.log(chalk.gray(`  ${message}`)),
+    });
+    return outcome;
+}
 export function registerUpdateCommand(program) {
     const update = program
         .command('update [target]')
         .description('Move a frozen agent installation to a new release, keeping its name and every reference to it')
-        .option('--to <release>', 'Release to move to: latest (default), oldest, or an exact version')
+        .option('--to <release>', 'Release to move to: latest (default, and unpins), oldest, or an exact version (pins)')
         .option('--json', 'Machine-readable result')
+        .option('--check', 'Dry run: report eligibility/current/target/policy/deferral without changing anything')
+        .option('--auto', 'Run the same automatic-update pass the daemon runs, across every managed harness (ignores <target>)')
         .action(async (target, options) => {
         try {
+            if (options.auto || (options.check && !target)) {
+                if (options.check) {
+                    printPlan(await planAutoUpdates(), !!options.json);
+                    return;
+                }
+                const result = await runAutoUpdatePass({
+                    onProgress: options.json ? undefined : (message) => console.log(chalk.gray(`  ${message}`)),
+                });
+                if (options.json) {
+                    console.log(JSON.stringify({
+                        plan: result.plan.map(serializePlanEntry),
+                        outcomes: result.outcomes.map((o) => ({
+                            agent: o.entry.agent,
+                            label: o.entry.installation.label,
+                            outcome: o.outcome && {
+                                fromRelease: o.outcome.fromRelease,
+                                toRelease: o.outcome.toRelease,
+                                unchanged: o.outcome.unchanged,
+                                deferred: o.outcome.deferred,
+                            },
+                            error: o.error,
+                        })),
+                    }, null, 2));
+                }
+                else if (result.outcomes.length === 0) {
+                    console.log(chalk.gray('Nothing eligible to update this pass.'));
+                }
+                else {
+                    for (const o of result.outcomes) {
+                        const name = `${o.entry.agent}@${o.entry.installation.label}`;
+                        if (o.error)
+                            console.error(chalk.red(`${name}: ${o.error}`));
+                        else if (o.outcome)
+                            printOutcome(o.outcome, false);
+                    }
+                }
+                if (result.outcomes.some((o) => o.error))
+                    process.exitCode = 1;
+                return;
+            }
             if (!target) {
-                throw new Error('Which agent? Use: agents update <agent>[@<installed-version>]');
+                throw new Error('Which agent? Use: agents update <agent>[@<installed-version>], or agents update --auto.');
             }
             const { agent, selector } = parseTarget(target);
+            if (options.check) {
+                const plan = (await planAutoUpdates({ agents: [agent] })).filter((entry) => !selector || entry.installation.label === selector || entry.installation.releaseVersion === selector);
+                if (selector && plan.length === 0) {
+                    throw new Error(`No ${AGENTS[agent].name} installation matches '${selector}'.`);
+                }
+                printPlan(plan, !!options.json);
+                return;
+            }
             if (options.to && options.to !== 'latest' && !supportsPinnedUpdate(agent)) {
                 // Fail loud at the boundary rather than installing the current release
                 // and reporting it as the pin that was asked for.
                 throw new Error(`${agent} is a single self-updating binary with no pinnable releases — drop --to, or pass --to latest.`);
             }
-            const installation = await resolveInstallation(agent, selector);
-            const strategy = selectUpdateStrategy(agent);
-            if (!options.json && !strategy.transactional) {
-                console.log(chalk.yellow(`${agent} installs one vendor-managed binary, so this update cannot be staged or rolled back; `
-                    + `a failure leaves whatever its installer wrote.`));
+            if (selector) {
+                const installation = await resolveInstallation(agent, selector);
+                const outcome = await updateOne(agent, installation, options);
+                printOutcome(outcome, !!options.json);
+                return;
+            }
+            // Bare `<agent>`, no `@label`: act on every installation of that agent
+            // that isn't explicitly pinned — the bulk case. A single installation
+            // keeps the old single-target behavior even if it happens to be pinned,
+            // since naming the agent with only one installed copy is unambiguous
+            // about which one is meant; `--to` still applies to it either way.
+            const installations = listInstallations(agent);
+            if (installations.length === 0) {
+                throw new Error(`No ${AGENTS[agent].name} installations are managed by agents-cli. Install one with: agents add ${agent}@latest`);
+            }
+            const targets = installations.length === 1
+                ? installations
+                : installations.filter((i) => effectiveUpdatePolicy(i) !== 'pinned');
+            if (installations.length > 1 && targets.length === 0) {
+                throw new Error(`Every ${AGENTS[agent].name} installation is pinned to a concrete release. `
+                    + `Select one explicitly: agents update ${agent}@<label> --to latest`);
             }
-            if (!options.json) {
-                console.log(chalk.gray(`Updating ${agent}@${describeInstallation(installation)} via the ${strategy.id} strategy...`));
+            let anyError = false;
+            for (const installation of targets) {
+                try {
+                    const outcome = await updateOne(agent, installation, options);
+                    printOutcome(outcome, !!options.json);
+                }
+                catch (err) {
+                    anyError = true;
+                    fail(err);
+                }
             }
-            const outcome = await updateInstallation(installation, {
-                to: options.to,
-                onProgress: options.json ? undefined : (message) => console.log(chalk.gray(`  ${message}`)),
-            });
-            printOutcome(outcome, !!options.json);
+            if (anyError)
+                process.exitCode = 1;
         }
         catch (err) {
             fail(err);
@@ -136,11 +278,20 @@ export function registerUpdateCommand(program) {
         examples: `agents update list claude
 agents update claude@2.0.65
 agents update claude@2.0.65 --to 2.1.220
-agents update claude@2.0.65 --json`,
+agents update claude@2.0.65 --to latest
+agents update claude
+agents update --check
+agents update claude --check --json
+agents update --auto`,
         notes: 'An installation keeps its name for life; only the release inside it moves. That is why a default, a project pin, '
             + 'a routine version, or a profile that names claude@2.0.65 keeps working after you update it. '
             + 'The selector matches either the installation name or the release it currently carries — when two installations '
             + 'share a release, select one by its installation name. '
-            + 'The new release is fetched and launched before it replaces the working one, so a bad release leaves your agent running.',
+            + 'The new release is fetched and launched before it replaces the working one, so a bad release leaves your agent running. '
+            + 'A bare `<agent>` (no @label) updates every one of its installations that is not pinned; `--to <release>` pins the '
+            + 'installations it touches, `--to latest` unpins them. Pinned and manual/vendor-managed installations are also skipped '
+            + 'by the automatic background pass (agents config set updates.auto / updates.<agent>.auto). `--check` reports what '
+            + '`--auto` would do without changing anything; `--auto` (no target) runs the exact pass the daemon runs, across every '
+            + 'harness.',
     });
 }

package/dist/commands/versions.d.ts

@@ -7,5 +7,16 @@
  * switching, resource sync prompts, and project-level version pinning.
  */
 import type { Command } from 'commander';
+/** Bare installs reuse an account home; explicit labels keep their expert semantics. */
+export declare function planAccountFirstInstall(input: {
+    spec: string;
+    supported: boolean;
+    isolated: boolean;
+    labels: string[];
+    defaultLabel: string | null;
+}): {
+    existingLabel?: string;
+    installationLabel?: string;
+};
 /** Register `agents add`, `agents prune`, `agents remove`, and `agents use`. */
 export declare function registerVersionsCommands(program: Command): void;

package/dist/commands/versions.js

@@ -15,6 +15,15 @@ import { tryAutoPullSystemRepo } from '../lib/git.js';
 import { getAgentsDir, getTrashVersionsDir } from '../lib/state.js';
 import { setHelpSections } from '../lib/help.js';
 import { updateSessionFilePaths } from '../lib/session/db.js';
+import { connectSupported } from '../lib/accounts/connect.js';
+/** Bare installs reuse an account home; explicit labels keep their expert semantics. */
+export function planAccountFirstInstall(input) {
+    if (!input.supported || input.isolated || input.spec.includes('@'))
+        return {};
+    const existingLabel = input.defaultLabel && input.labels.includes(input.defaultLabel)
+        ? input.defaultLabel : input.labels[0];
+    return existingLabel ? { existingLabel } : { installationLabel: 'main' };
+}
 /**
  * After removeVersion soft-deletes a version dir to trash, rewrite session
  * file_path entries in the DB so reads still work from the new trash location.
@@ -317,7 +326,7 @@ export function registerVersionsCommands(program) {
         notes: `
       - The first version you install becomes the default automatically.
       - 'add' does NOT change the default if a default already exists. Use 'agents use' to switch.
-      - Multi-account: each installed version has separate auth, so you can install the same agent twice for two accounts.
+      - Bare Claude/Codex installs reuse your existing home. Connect another account with 'agents accounts connect <agent> [name]'.
       - --isolated installs a self-contained copy: it never sets the default, never creates the bare '<agent>' shim, and never backs up or symlinks your real ~/.<agent>. Run it with 'agents run <agent>@<version>' and remove it with 'agents remove <agent>@<version> --isolated'. Mutually exclusive with --project.
     `,
     });
@@ -376,7 +385,19 @@ export function registerVersionsCommands(program) {
             // Check if already installed (resolve 'latest'/'oldest' against npm first)
             let alreadyInstalled = false;
             let installedAsVersion = version;
-            if (version === 'latest') {
+            const accountInstall = planAccountFirstInstall({
+                spec, supported: connectSupported(agent), isolated: !!isIsolated,
+                labels: listInstalledVersions(agent).filter(label => !isVersionIsolated(agent, label)),
+                defaultLabel: getGlobalDefault(agent),
+            });
+            if (accountInstall.existingLabel) {
+                alreadyInstalled = true;
+                installedAsVersion = accountInstall.existingLabel;
+            }
+            else if (accountInstall.installationLabel) {
+                // A fresh managed home has a stable label, independent of npm's release.
+            }
+            else if (version === 'latest') {
                 const latestCheck = await isLatestInstalled(agent);
                 if (latestCheck.installed && latestCheck.version) {
                     alreadyInstalled = true;
@@ -407,7 +428,12 @@ export function registerVersionsCommands(program) {
                     finalizeIsolatedInstall(agent, installedAsVersion);
                     continue;
                 }
-                console.log(chalk.gray(`${agentLabel(agentConfig.id)}@${installedAsVersion} already installed`));
+                console.log(chalk.gray(accountInstall.existingLabel
+                    ? `${agentLabel(agentConfig.id)} is already installed. Your account home is unchanged.`
+                    : `${agentLabel(agentConfig.id)}@${installedAsVersion} already installed`));
+                if (accountInstall.existingLabel) {
+                    console.log(chalk.gray(`  Accounts: agents view ${agent}. Update now: agents update ${agent}.`));
+                }
                 // Ensure shim exists (in case it was deleted or needs updating)
                 createShim(agent);
             }
@@ -415,7 +441,7 @@ export function registerVersionsCommands(program) {
                 const spinner = ora(`Installing ${agentLabel(agentConfig.id)}@${version}...`).start();
                 const result = await installVersion(agent, version, (msg) => {
                     spinner.text = msg;
-                });
+                }, accountInstall.installationLabel ? { installationLabel: accountInstall.installationLabel } : undefined);
                 if (result.success) {
                     const installedVer = result.installedVersion || version;
                     const installedModel = resolveConfiguredModel(agentConfig.id, installedVer)?.model;

package/dist/commands/view.d.ts

@@ -12,6 +12,7 @@ import type { AccountInfo } from '../lib/agents.js';
 import type { AgentId } from '../lib/types.js';
 import type { FormatUsageSummaryOpts, UsageInfo } from '../lib/accounting/usage.js';
 import { type ConfiguredDeviceRole } from '../lib/device-config.js';
+import { type NativeAccountCatalogRow } from '../lib/account-catalog.js';
 import type { ResourceSection, ViewJsonAgent } from '../lib/view-types.js';
 export type { ResourceItemJson, ResourceSection, SyncState, VersionResourcesJson, ViewJsonAgent, ViewJsonVersion } from '../lib/view-types.js';
 import { type ProfileSummary } from '../lib/profiles.js';
@@ -26,6 +27,8 @@ export declare const accountColumnLabel: typeof accountDisplayLabel;
  * display label when the identity is unnamed.
  */
 export declare function namedAccountColumnLabel(agentId: AgentId, info: AccountInfo | undefined): string;
+/** Human account identity; release labels belong only in installation diagnostics. */
+export declare function nativeAccountViewLabel(row: Pick<NativeAccountCatalogRow, 'name' | 'display'>): string;
 export interface AccountOrderedVersion {
     version: string;
     email: string | null;
@@ -92,6 +95,23 @@ export declare function parseResourceSections(options: {
 export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSections?: Set<ResourceSection>, opts?: {
     forceRefresh?: boolean;
 }): Promise<ViewJsonAgent[]>;
+interface PrunePlanEntry {
+    agentId: AgentId;
+    version: string;
+    email: string;
+    keeper: string;
+    isDefault: boolean;
+    /**
+     * 'duplicate'    — older version sharing an email with a newer install.
+     * 'home-leftover' — home-only dir left over after a previous removeVersion;
+     *                   no binary, but transcripts may still live here.
+     */
+    reason: 'duplicate' | 'home-leftover';
+}
+interface AgentPrunePlan {
+    agentId: AgentId;
+    toPrune: PrunePlanEntry[];
+}
 /**
  * Identity key for duplicate-install detection. Prefers accountKey — which
  * encodes account AND org — over the bare email: two installs can share an
@@ -101,10 +121,55 @@ export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSecti
  * identity key. Null when there is no usable identity.
  */
 export declare function pruneGroupKey(info: Pick<AccountInfo, 'accountKey' | 'email'>): string | null;
+/** One installed home, reduced to the fields duplicate detection needs. */
+export interface PruneCandidate {
+    /** The version-dir label (opaque slot id). */
+    version: string;
+    /** The RUNNING release inside the home (installation.releaseVersion), or the label. */
+    release: string;
+    email: string | null;
+    /** Present only once the home's native identity is captured (claude: account+org). */
+    accountKey: string | null;
+    signedIn: boolean;
+    hasBinary: boolean;
+}
+/** A duplicate home to retire, and the keeper it collapses into. */
+export interface DuplicatePruneEntry {
+    version: string;
+    email: string;
+    keeper: string;
+}
+/**
+ * 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 declare function planDuplicatePrune(candidates: PruneCandidate[]): DuplicatePruneEntry[];
+export declare function executePrunePlan(plan: AgentPrunePlan): Promise<Array<{
+    agent: AgentId;
+    version: string;
+}>>;
 /**
- * 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"
@@ -117,6 +182,7 @@ export declare function pruneDuplicates(filterAgentId: AgentId | undefined, yes:
  */
 export declare function viewAction(agentArg?: string, options?: {
     json?: boolean;
+    versions?: boolean;
     prune?: boolean;
     yes?: boolean;
     dryRun?: boolean;