@phnx-labs/agents-cli 1.22.79 → 1.22.80

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.22.80
+
+- **`agents prune cleanup` collapses duplicate account homes to one per account — and keeps the RIGHT one (PHNX-3940).** After the automatic-update pass moves every home to the latest release in place, an account can be left with two homes: the original identity-captured login and a freshly re-logged-in home that only carries an email ("usage unavailable"). Consolidation now groups those together and keeps the home that best represents the account — captured identity first, then a signed-in credential, then the newest running release — instead of the blind highest dir-name semver, which was the just-created duplicate and whose selection trashed the working login. When the retired duplicate held the global default, the default is repointed onto the keeper first, so the duplicate actually collapses instead of being skipped. Retirement stays a reversible soft-delete (`agents restore`). Source: `cli/src/commands/view.ts` (`planDuplicatePrune`).
+
 ## 1.22.79
 
 - **Managed harnesses follow the latest release without replacing account homes (PHNX-3940).** Automatic updates are on by default and configurable with `updates.auto` and per-harness `updates.<harness>.auto`. Updates preserve existing home paths and identities, defer active installations, and stage and verify the executable before committing it. A concrete `--to` release pins an installation; `--to latest` resumes automatic updates. `agents update --check` previews without changing local state. Source: `cli/src/lib/installations/update.ts`, `cli/src/lib/daemon/harness-update-service.ts`, `cli/src/commands/update.ts`.

package/dist/commands/view.d.ts

@@ -95,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
@@ -104,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"

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';
@@ -1455,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
@@ -1517,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) {
@@ -1537,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)}:`;
@@ -1562,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"
@@ -1577,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;
@@ -1588,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.79",
+  "version": "1.22.80",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",