@phnx-labs/agents-cli 1.22.56 → 1.22.58

package/dist/commands/ssh.js

@@ -79,10 +79,14 @@ function deviceSummary(d, isSelf = false, stats, isInteractive = false, roles) {
     const marker = isSelf ? chalk.cyan('▸ ') : '  ';
     const name = isSelf ? chalk.bold.cyan(d.name.padEnd(16)) : chalk.bold(d.name.padEnd(16));
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
-    const interactive = isInteractive ? chalk.yellow('  ★ interactive') : '';
     // `roles` defaults to a single-device roster so a fleet-wide `role` default
     // still reaches this device even when it has no per-device doc of its own.
-    const role = roleTag(d.name, roles ?? listConfiguredDeviceRoles([d.name]));
+    const roleMap = roles ?? listConfiguredDeviceRoles([d.name]);
+    // `personal` already means "the interactive box you sit at", so the star would
+    // just repeat it — show it only when the interactive host is NOT a personal box
+    // (e.g. an unmarked or worker box deliberately pinned as the artifact target).
+    const interactive = isInteractive && roleMap[d.name] !== 'personal' ? chalk.yellow('  ★ interactive') : '';
+    const role = roleTag(d.name, roleMap);
     return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}${role}`;
 }
 /** The fleet-wide role mark, rendered for a device row. Empty when unmarked —
@@ -95,7 +99,9 @@ function roleTag(name, roles) {
         return chalk.green('  worker');
     if (role === 'personal')
         return chalk.yellow('  personal');
-    return chalk.gray('  control');
+    if (role === 'desktop')
+        return chalk.cyan('  desktop');
+    return '';
 }
 const HEADROOM_BADGE = {
     idle: chalk.green('○ idle'),
@@ -257,7 +263,9 @@ export function renderDeviceTable(reg, names, self, statsMap, full = false, inte
             : '';
         const badge = HEADROOM_BADGE[headroom(stats)];
         const here = isSelf ? chalk.cyan('  ← this machine') : '';
-        const interactive = name === interactiveHost ? chalk.yellow('  ★ interactive') : '';
+        // A `personal` role already conveys "your interactive seat"; don't double-
+        // render the star on it. Keep it for a non-personal pinned interactive host.
+        const interactive = name === interactiveHost && deviceRoles[name] !== 'personal' ? chalk.yellow('  ★ interactive') : '';
         lines.push(fitDeviceRow(`${marker}${label}${plat} ${specCell(stats, specWidth)}${load}${mem}${disk}${freeTotal}  ${badge}${relay}${here}${interactive}`, role, desc, width));
     }
     // Fleet capacity summary — total cores, how much RAM is free right now, and
@@ -1449,12 +1457,12 @@ function registerDevicesCommands(program) {
      *
      * A role written here lands in that device's tracked per-device doc
      * (`devices/<name>/agents.yaml` `config.role`) and syncs with repo
-     * push/pull. The vocabulary is deliberately `worker | personal` only.
+     * push/pull. The vocabulary is `worker | personal | desktop`.
      */
     const runDevicesRole = async (name, role, opts) => {
         if (!name) {
             if (role)
-                throw new Error('Name a device: agents devices role <name> <worker|personal>');
+                throw new Error('Name a device: agents devices role <name> <worker|personal|desktop>');
             const reg = await loadDevices();
             // The full registered roster, not just online — a fleet-wide `role`
             // default must reach a registered device even when it has no per-device
@@ -1475,14 +1483,14 @@ function registerDevicesCommands(program) {
             }
             else {
                 for (const [device, r] of marked) {
-                    const tint = r === 'worker' ? chalk.green : r === 'personal' ? chalk.yellow : chalk.gray;
+                    const tint = r === 'worker' ? chalk.green : r === 'personal' ? chalk.yellow : r === 'desktop' ? chalk.cyan : chalk.gray;
                     console.log(`  ${device.padEnd(20)} ${tint(r)}`);
                 }
             }
             console.log();
             console.log(chalk.bold('--device auto picks from: ') + (pool.length > 0 ? pool.join(', ') : chalk.red('nothing — no eligible device')));
             if (mode === 'all')
-                console.log(chalk.gray('auto.pool=all — worker marks are ignored (a personal device is still excluded).'));
+                console.log(chalk.gray('auto.pool=all — worker marks are ignored (personal and desktop devices are still excluded).'));
             return;
         }
         await mustGetDevice(name);
@@ -1669,7 +1677,8 @@ function registerDevicesCommands(program) {
     });
     const roleCmd = devicesCmd
         .command('role [name] [role]')
-        .description('Show or set what a device is for: worker (agents run here) or personal (you sit here — never picked automatically). ' +
+        .description('Show or set what a device is for: worker (agents run here), personal (you sit here), or desktop (a headed ' +
+        'always-on box — the release/credential home). Personal and desktop are never picked automatically. ' +
         'Marking any device worker makes `--device auto` an allowlist over the marked workers.')
         .option('--clear', 'remove the mark, returning the device to unmarked')
         .option('--json', 'output machine-readable JSON')
@@ -1688,6 +1697,7 @@ function registerDevicesCommands(program) {
       agents devices role yosemite-s0 worker       # agents spin up here
       agents devices role yosemite-s1 worker       # …and here; auto now rotates over these two only
       agents devices role zion personal            # your laptop — keep automatic placement off it
+      agents devices role mac-mini desktop         # headed always-on box — also kept out of auto placement
       agents devices role yosemite-s0 --clear      # unmark
       agents devices role --json                   # machine-readable
     `,
@@ -1699,12 +1709,12 @@ function registerDevicesCommands(program) {
 
       Effect on '--device auto' (agents run, teams, agents ssh auto, and the AGI
       EXT launch commands, which all resolve placement through the CLI):
-        no device marked  -> every online device, as before
-        any worker marked -> ONLY the marked workers
-        personal          -> never picked, under either state
+        no device marked   -> every online device, as before
+        any worker marked  -> ONLY the marked workers
+        personal / desktop -> never picked, under either state
 
-      Turn the allowlist off with 'agents config set auto.pool all'; a personal
-      box stays excluded, since that is what the mark is for.
+      Turn the allowlist off with 'agents config set auto.pool all'; personal and
+      desktop boxes stay excluded, since that is what the mark is for.
     `,
     });
     const describeCmd = devicesCmd

package/dist/commands/status.js

@@ -78,7 +78,7 @@ export function registerStatusCommand(syncCmd) {
         // A non-git / partial ~/.agents is its own drift state, not a per-agent
         // "N missing" — surface it distinctly so the real problem isn't buried (PHNX-3301).
         if (status.user.notGitRepo) {
-            console.log(`  ${'~/.agents (user repo)'.padEnd(28)} ${chalk.yellow('not a git repo — will adopt on next `agents repo sync user`')}`);
+            console.log(`  ${'~/.agents (user repo)'.padEnd(28)} ${chalk.yellow('not a git repo — will adopt on next `agents sync` (or `agents repo sync user`)')}`);
         }
         if (status.agents.length === 0) {
             console.log(chalk.gray('  (no installed agent versions)'));

package/dist/commands/sync.js

@@ -45,6 +45,7 @@ import { runLaunchSync } from '../lib/project-launch.js';
 import { formatKeptProjectResources } from '../lib/project-resources.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { runUmbrellaSync } from '../lib/sync-umbrella.js';
+import { verifyVersionConverged, formatResidualDrift } from '../lib/sync-status.js';
 import { addHostOption } from '../lib/hosts/option.js';
 import { syncRepoGit, adoptUserRepoIfNeeded, recordUserRepoRemote, resolveUserRepoRemoteUrl } from '../lib/git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
@@ -53,6 +54,46 @@ import { registerStatusCommand } from './status.js';
 function emitJson(payload) {
     console.log(JSON.stringify(payload));
 }
+/**
+ * Post-reconcile verification (PHNX-3186): after a sync writes into a set of
+ * version homes, re-read each home and confirm it now matches its resolved
+ * sources. The `agents sync` success line MUST NOT read "reconciled" while the
+ * drift it was asked to fix stays put. Any residual drifted/missing resource
+ * sets a non-zero exit code and — outside `--json` — names the exact unfixed
+ * drift so the operator sees what did not converge instead of a false ✓. Orphans
+ * are excluded (sync never removes them). Returns the residual for `--json`.
+ */
+function verifyReconciled(pairs, cwd) {
+    const residual = [];
+    const seen = new Set();
+    for (const { agent, version } of pairs) {
+        const key = `${agent}@${version}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const r = verifyVersionConverged(agent, version, cwd);
+        if (r)
+            residual.push(r);
+    }
+    // Residual drift is reported loudly via `ok:false` + the printed ⚠ block, but
+    // does NOT change the exit code — matching the declined-write precedent
+    // (RUSH-2700). The fleet fan-out (`agents sync --device all`) THROWS on a
+    // non-zero peer exit (`hosts/passthrough.ts`), discarding that box's JSON, so a
+    // non-zero exit here would hide the very `residualDrift` payload it emitted.
+    // Callers that must treat an incomplete sync as failure read `ok`/`residualDrift`
+    // from `--json`, exactly as they already do for declines.
+    return residual;
+}
+/** Print the residual-drift block naming exactly what did not converge. */
+function printResidual(residual, errLog) {
+    if (residual.length === 0)
+        return;
+    const lines = formatResidualDrift(residual);
+    errLog(chalk.yellow(`⚠ sync did not fully reconcile — ${lines.length} resource(s) still drift after writing:`));
+    for (const line of lines)
+        errLog(chalk.yellow(`  ${line}`));
+    errLog(chalk.gray('  Re-run the sync; a gap that survives a re-run is a real unreconcilable drift — report it.'));
+}
 /**
  * Translate per-kind CLI flags into a `ResourceSelection` for `buildSelection`.
  * Returns `undefined` when no kind flag was given (caller should use full sync).
@@ -429,6 +470,7 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
         await runInteractiveReconcile(opts, outLog, errLog);
         return;
     }
+    const cwd = opts.cwd || process.cwd();
     const flags = {
         repos: opts.repos,
         secrets: opts.secrets,
@@ -459,10 +501,18 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
         // --cloud (fetch-only, no local reconcile).
         if (!opts.cloud)
             evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog);
+        // Post-reconcile verification (PHNX-3186): re-read every version the reconcile
+        // wrote into and confirm it now matches source. Without this the umbrella
+        // printed `✓ sync: reconciled` unconditionally, the exact false-success the
+        // ticket reports. Residual drift downgrades the line and sets a non-zero exit.
+        const residual = result.reconciled
+            ? verifyReconciled(result.reconciledVersions.map((r) => ({ agent: r.agent, version: r.version })), cwd)
+            : [];
         if (json) {
             emitJson({
-                // A refused resource is not a clean sync (RUSH-2700).
-                ok: result.declined.length === 0,
+                // A refused resource OR residual drift is not a clean sync (RUSH-2700 +
+                // PHNX-3186).
+                ok: result.declined.length === 0 && residual.length === 0,
                 mode: 'umbrella',
                 plan: result.plan,
                 repos: result.repos,
@@ -470,6 +520,7 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
                 devices: result.devices,
                 reconciled: result.reconciled,
                 declined: result.declined,
+                residualDrift: residual,
             });
             return;
         }
@@ -482,12 +533,18 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
             if (result.secrets) {
                 parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
             }
+            // Only claim "reconciled" when the reconcile actually converged. Residual
+            // drift is already printed loudly by verifyReconciled above; reflect it in
+            // the one-line summary rather than a bare ✓.
             if (result.reconciled)
-                parts.push('reconciled');
-            outLog(chalk.green(`✓ sync: ${parts.join(' · ') || 'nothing to do'}`));
+                parts.push(residual.length === 0 ? 'reconciled' : 'reconcile INCOMPLETE');
+            const symbol = residual.length === 0 ? chalk.green('✓') : chalk.yellow('⚠');
+            const line = `${symbol} sync: ${parts.join(' · ') || 'nothing to do'}`;
+            outLog(residual.length === 0 ? chalk.green(line) : chalk.yellow(line));
             const errs = [...(result.repos?.errors ?? []), ...(result.secrets?.errors ?? [])];
             for (const e of errs)
                 errLog(chalk.yellow(`  ! ${e}`));
+            printResidual(residual, errLog);
         }
     }
     catch (err) {
@@ -700,13 +757,23 @@ async function runSync(agentSpec, repoArg, opts) {
             if (!quiet && !json)
                 printSyncDetail(result, agentId, v, cwd);
         }
+        // Verify each version actually converged; a repo-scoped sync only touched
+        // that repo's kinds, so skip verification there (the other layers legitimately
+        // still differ and are not this run's responsibility).
+        const residual = repoScope
+            ? []
+            : verifyReconciled(versions.map(({ version: v }) => ({ agent: agentId, version: v })), cwd);
+        if (!quiet && !json)
+            printResidual(residual, errLog);
         if (json) {
             emitJson({
-                // Any version that refused a write makes the whole run not-ok (RUSH-2700).
-                ok: versions.every(({ result }) => result.declined.length === 0),
+                // Any version that refused a write, or any residual drift after the
+                // reconcile, makes the whole run not-ok (RUSH-2700 + PHNX-3186).
+                ok: versions.every(({ result }) => result.declined.length === 0) && residual.length === 0,
                 mode: 'agent-all',
                 agent: agentId,
                 repo: repoScope,
+                residualDrift: residual,
                 ...healedPointers,
                 versions: versions.map(({ version: v, result }) => ({
                     version: v,
@@ -901,6 +968,11 @@ async function runSync(agentSpec, repoArg, opts) {
         return;
     }
     const result = syncResourcesToVersion(agentId, version, selection, { projectDir, cwd, force, allowExecSurfaces: !!opts.allowExecSurfaces });
+    // Post-reconcile verification (PHNX-3186). Only for a FULL reconcile
+    // (`!selection`): an interactive subset-selection deliberately touched only the
+    // picked kinds, so the rest legitimately still differs and is not this run's
+    // failure. This is the exact path `agents sync <agent>[@version]` takes.
+    const residual = selection ? [] : verifyReconciled([{ agent: agentId, version }], cwd);
     // Compile project-scope rules into the workspace itself so each agent's
     // native loader picks up cwd/<INSTRUCTIONS_FILE>. projectDir is the
     // .agents/ directory; the workspace root is its parent.
@@ -910,8 +982,11 @@ async function runSync(agentSpec, repoArg, opts) {
         projectCompile = compileRulesForProject(projectRoot);
     }
     if (json) {
+        const base = agentSyncJson(agentId, version, result);
         emitJson({
-            ...agentSyncJson(agentId, version, result),
+            ...base,
+            ok: base.ok === true && residual.length === 0,
+            residualDrift: residual,
             ...healedPointers,
             projectCompile: projectCompile
                 ? {
@@ -928,6 +1003,7 @@ async function runSync(agentSpec, repoArg, opts) {
         return;
     // ---------- 6. Detailed output ----------
     printSyncDetail(result, agentId, version, cwd);
+    printResidual(residual, errLog);
     if (projectCompile?.compiled) {
         const linkInfo = projectCompile.symlinks.length > 0
             ? ` (+ ${projectCompile.symlinks.join(', ')})`

package/dist/commands/traces.js

@@ -109,6 +109,13 @@ async function handleSync(opts) {
         parts.push(chalk.dim('nothing new'));
     }
     console.log(parts.join(chalk.dim('  ·  ')));
+    // The per-session data can upload cleanly while the aggregated console shard
+    // fails to refresh (e.g. the sessions DB is locked by a running app). That used
+    // to be silent, so the console sat stale with no signal here (PHNX-3401).
+    if (result.indexError) {
+        console.log(chalk.yellow('  ⚠ console index not refreshed') +
+            chalk.dim(` (${result.indexError}) — dashboard may be stale; it will retry next sync`));
+    }
 }
 async function handleStatus() {
     const ledger = readSyncLedger();

package/dist/commands/trash.d.ts

@@ -9,13 +9,13 @@
 import type { Command } from 'commander';
 /**
  * Restore a soft-deleted version back into ~/.agents/.history/versions/.
- * Shared by `agents trash restore` and the top-level `agents restore` alias.
+ * Backs the top-level `agents restore` command.
  * Exits the process with a non-zero code on any failure.
  */
 export declare function restoreVersion(target: string): void;
 /**
  * Register the top-level `agents restore` command — a shorthand for
- * `agents trash restore` so users can undo a `remove`/`prune` directly.
+ * `agents restore` so users can undo a `remove`/`prune` directly.
  */
 export declare function registerRestoreCommand(program: Command): void;
 export declare function registerTrashCommands(program: Command): void;

package/dist/commands/trash.js

@@ -112,7 +112,7 @@ function humanSize(bytes) {
 }
 /**
  * Restore a soft-deleted version back into ~/.agents/.history/versions/.
- * Shared by `agents trash restore` and the top-level `agents restore` alias.
+ * Backs the top-level `agents restore` command.
  * Exits the process with a non-zero code on any failure.
  */
 export function restoreVersion(target) {
@@ -157,7 +157,7 @@ export function restoreVersion(target) {
 }
 /**
  * Register the top-level `agents restore` command — a shorthand for
- * `agents trash restore` so users can undo a `remove`/`prune` directly.
+ * `agents restore` so users can undo a `remove`/`prune` directly.
  */
 export function registerRestoreCommand(program) {
     program
@@ -196,8 +196,4 @@ export function registerTrashCommands(program) {
         console.log();
         console.log(chalk.gray('Restore with: agents restore <agent>@<version>'));
     });
-    trash
-        .command('restore <target>')
-        .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents/.history/versions/')
-        .action((target) => restoreVersion(target));
 }

package/dist/commands/versions.d.ts

@@ -2,10 +2,10 @@
  * Version management commands for installing, switching, and removing agent CLIs.
  *
  * Implements `agents add`, `agents prune`, `agents remove` (alias),
- * `agents use`, and the deprecated `agents list`. Handles npm-based installation,
+ * and `agents use`. Handles npm-based installation,
  * shim creation, config symlink
  * switching, resource sync prompts, and project-level version pinning.
  */
 import type { Command } from 'commander';
-/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+/** Register `agents add`, `agents prune`, `agents remove`, and `agents use`. */
 export declare function registerVersionsCommands(program: Command): void;

package/dist/commands/versions.js

@@ -1,4 +1,3 @@
-import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -6,7 +5,6 @@ import * as path from 'path';
 import { select, confirm, checkbox } from '@inquirer/prompts';
 import { AGENTS, MANAGED_AGENT_IDS, accountOrgBadge, getAccountEmail, getAccountInfo, agentLabel, warnAgentDeprecated, isAgentHardDeprecated, hardDeprecationError, isSelfUpdatingAgent, } from '../lib/agents.js';
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, } from '../lib/accounting/usage.js';
-import { viewAction } from './view.js';
 import { resolveConfiguredModel, formatAgentIdentity } from '../lib/models.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
 import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, isOldestInstalled, getGlobalDefault, setGlobalDefault, markVersionIsolated, setIsolatedDefault, isVersionIsolated, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/installations/versions.js';
@@ -288,7 +286,7 @@ function configureVersionPruneCommand(cmd, commandName) {
     });
     cmd.action((specs, options) => versionPruneAction(specs, options, commandName));
 }
-/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+/** Register `agents add`, `agents prune`, `agents remove`, and `agents use`. */
 export function registerVersionsCommands(program) {
     const addCmd = program
         .command('add <specs...>')
@@ -943,11 +941,4 @@ export function registerVersionsCommands(program) {
             throw err;
         }
     });
-    // Deprecated: use `agents view` instead
-    addHostOption(program.command('list [agent]'))
-        .description('List installed agent CLI versions')
-        .action(async (agentArg) => {
-        console.log(chalk.red('Deprecated: "agents list" is now "agents view"\n'));
-        await viewAction(agentArg);
-    });
 }

package/dist/commands/view.d.ts

@@ -72,8 +72,8 @@ export declare function renderHarnessBlocks(harnesses: ProfileSummary[], install
 /**
  * The USAGE-READ-2 decision, isolated from its runtime inputs so it can be
  * tested directly: a usage read may fall through to the interactive OAuth login
- * ONLY for a foreground human render on a `personal` device. Both conditions are
- * required — role alone is not sufficient.
+ * ONLY for a foreground human render on a headed device (`personal` or
+ * `desktop`). Both conditions are required — role alone is not sufficient.
  */
 export declare function allowInteractiveUsageLogin(role: ConfiguredDeviceRole | undefined, isTTY: boolean): boolean;
 /** Build the set of resource sections to include in `--json` from the

package/dist/commands/view.js

@@ -9,7 +9,7 @@ import { ambientClaudeToken, loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 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 { selfConfiguredDeviceRole } from '../lib/device-config.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 { ensureVersionedAliasCurrent, removeShim, } from '../lib/installations/shims.js';
@@ -320,17 +320,18 @@ function renderHostClisSection(cwd) {
 /**
  * The USAGE-READ-2 decision, isolated from its runtime inputs so it can be
  * tested directly: a usage read may fall through to the interactive OAuth login
- * ONLY for a foreground human render on a `personal` device. Both conditions are
- * required — role alone is not sufficient.
+ * ONLY for a foreground human render on a headed device (`personal` or
+ * `desktop`). Both conditions are required — role alone is not sufficient.
  */
 export function allowInteractiveUsageLogin(role, isTTY) {
-    return role === 'personal' && isTTY === true;
+    return isHeadedDeviceRole(role) && isTTY === true;
 }
 /**
  * Whether this `agents view` invocation may fall through to the interactive
  * OAuth login for a usage read (USAGE-READ-2). True only for a foreground human
- * render on a `personal` device: the interactive login is the sole credential
- * carrying the `user:profile` scope the usage endpoint needs, and a human
+ * render on a headed device (`personal` or `desktop`): the interactive login is
+ * the sole credential carrying the `user:profile` scope the usage endpoint needs,
+ * and a human
  * running one command is not the unattended-loop revocation risk RUSH-1822
  * fixed. The `--json` path never reaches these render functions (it returns
  * early via `collectAgentsJson`), and a non-TTY (piped/scripted) run is excluded

package/dist/index.d.ts

@@ -15,6 +15,7 @@
  *   - `__secrets-get` / `__secrets-ping` / `__secrets-lock` (SYNC_* tokens)
  *   - `__shim`
  *   - `__claude-statusline`
+ *   - `__usage-ingest` / `__usage-export`
  *   - `__daemon-run`
  *
  * The tokens are imported from the leaf module sync-commands.ts — the SAME

package/dist/index.js

@@ -15,6 +15,7 @@
  *   - `__secrets-get` / `__secrets-ping` / `__secrets-lock` (SYNC_* tokens)
  *   - `__shim`
  *   - `__claude-statusline`
+ *   - `__usage-ingest` / `__usage-export`
  *   - `__daemon-run`
  *
  * The tokens are imported from the leaf module sync-commands.ts — the SAME
@@ -75,6 +76,19 @@ if (process.argv[2] === '__claude-statusline') {
     const { runClaudeStatusLine } = await import('./lib/claude-statusline.js');
     process.exit(await runClaudeStatusLine());
 }
+// Fleet usage-sync receiver: a headed peer pipes its identity-keyed usage rows to
+// stdin, we merge them newest-wins into this box's cache (PHNX-3392). Above the
+// bootstrap line for the same reason as __claude-statusline — no update check, no
+// detached sync fork, and nothing writes to stdout to corrupt the caller's view.
+if (process.argv[2] === '__usage-ingest') {
+    const { runUsageIngest } = await import('./lib/accounting/usage-ingest.js');
+    process.exit(await runUsageIngest());
+}
+if (process.argv[2] === '__usage-export') {
+    const { exportClaudeUsageCacheRows } = await import('./lib/accounting/usage.js');
+    process.stdout.write(JSON.stringify({ v: 1, rows: exportClaudeUsageCacheRows() }));
+    process.exit(0);
+}
 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-registry.d.ts

@@ -63,11 +63,15 @@ export declare function unbindAccount(nameOrId: string, target: string): void;
 /** Every target bound to `accountId`: this box's device-doc bindings merged over
  * the fleet-shared central bindings (PHNX-3315). */
 export declare function accountBindings(accountId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): string[];
+export interface AccountSelection {
+    id: string;
+    source: 'explicit' | 'binding' | 'default';
+}
 /** Explicit selection wins over a configured per-harness default. */
 export declare function resolveAccountSelection(explicit: string | undefined, agent: AgentId, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, opts?: {
     useDefault?: boolean;
     target?: string;
-}): string | undefined;
+}): AccountSelection | undefined;
 export interface AddAccountOptions {
     baseUrl?: string;
 }

package/dist/lib/account-registry.js

@@ -20,6 +20,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import * as yaml from 'yaml';
+import chalk from 'chalk';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { getUserAgentsDir, readMeta, updateMeta } from './state.js';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken } from './secrets/index.js';
@@ -307,18 +308,19 @@ export function accountBindings(accountId, meta) {
 /** Explicit selection wins over a configured per-harness default. */
 export function resolveAccountSelection(explicit, agent, meta, opts = {}) {
     if (explicit)
-        return explicit;
+        return { id: explicit, source: 'explicit' };
     // This box's device-doc bindings win over the fleet-shared central bindings
     // (PHNX-3315), so a per-box account attachment resolves without touching the
     // shared file. Defaults are genuinely fleet-shared and stay central.
     const bindings = { ...meta.accounts?.bindings, ...meta.deviceAccounts?.bindings };
     const bound = opts.target ? bindings[opts.target] : undefined;
     if (bound)
-        return bound;
+        return { id: bound, source: 'binding' };
     const deviceScoped = bindings[agent];
     if (deviceScoped)
-        return deviceScoped;
-    return opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
+        return { id: deviceScoped, source: 'binding' };
+    const defaulted = opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
+    return defaulted ? { id: defaulted, source: 'default' } : undefined;
 }
 function profileConsumers(name, base) {
     const dir = path.join(base, 'profiles');
@@ -371,19 +373,30 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     const rows = nativeRowsForNameOrId(meta, oldName);
     if (rows.length) {
         assertUniqueUnifiedName(newName, meta, doc, new Set(rows.map(account => account.id)));
-        // Sweep every row for the identity (PHNX-3206) in its owning store (PHNX-3315).
+        // Sweep every row for the identity (PHNX-3206) in its owning store (PHNX-3315)
+        // and any per-harness default that points to the old name or row ids.
         const rowScope = rows[0].scope;
+        const idsToRename = new Set([oldName, ...rows.map(row => row.id)]);
         updateMeta(current => {
+            const defaults = { ...current.accounts?.defaults };
+            for (const [agent, value] of Object.entries(defaults)) {
+                if (idsToRename.has(value))
+                    defaults[agent] = newName;
+            }
+            const next = { ...current, accounts: { ...current.accounts, defaults } };
             if (rowScope === 'device') {
                 const native = { ...current.deviceAccounts?.native };
                 for (const row of rows)
                     native[row.id] = { ...native[row.id], name: newName };
-                return { ...current, deviceAccounts: { ...current.deviceAccounts, native } };
+                next.deviceAccounts = { ...current.deviceAccounts, native };
             }
-            const native = { ...current.accounts?.native };
-            for (const row of rows)
-                native[row.id] = { ...native[row.id], name: newName };
-            return { ...current, accounts: { ...current.accounts, native } };
+            else {
+                const native = { ...current.accounts?.native };
+                for (const row of rows)
+                    native[row.id] = { ...native[row.id], name: newName };
+                next.accounts = { ...next.accounts, native };
+            }
+            return next;
         });
         return;
     }
@@ -391,6 +404,15 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     if (!account)
         throw new Error(`Unknown account '${oldName}'.`);
     assertUniqueUnifiedName(newName, meta, doc);
+    const idsToRename = new Set([account.name, account.id]);
+    updateMeta(current => {
+        const defaults = { ...current.accounts?.defaults };
+        for (const [agent, value] of Object.entries(defaults)) {
+            if (idsToRename.has(value))
+                defaults[agent] = newName;
+        }
+        return { ...current, accounts: { ...current.accounts, defaults } };
+    });
     renameBundle(account.name, newName); // moves metadata + secret, preserves ACCOUNT_ID
     renameProfileConsumers(account.name, newName, base);
 }
@@ -422,7 +444,7 @@ export function removeAccount(name, base = getUserAgentsDir()) {
     if (!account)
         throw new Error(`Unknown account '${name}'.`);
     const bindings = accountBindings(account.id, meta);
-    const defaults = Object.entries(meta.accounts?.defaults ?? {}).filter(([, id]) => id === account.id).map(([agent]) => agent);
+    const defaults = Object.entries(meta.accounts?.defaults ?? {}).filter(([, value]) => value === account.id || value === account.name).map(([agent]) => agent);
     if (bindings.length || defaults.length) {
         const refs = [...bindings.map(target => `binding ${target}`), ...defaults.map(agent => `default ${agent}`)];
         throw new Error(`Account '${account.name}' is still referenced by: ${refs.join(', ')}. Detach or clear those references before removing it.`);
@@ -505,9 +527,20 @@ export function resolveSpawnAccount(explicit, agent, version, meta, opts = {}) {
     const selection = resolveAccountSelection(explicit, agent, meta, { useDefault: opts.useDefault, target });
     if (!selection)
         return null;
-    const unified = findUnifiedAccount(selection, meta);
-    if (!unified)
-        throw new Error(`Unknown account '${selection}'.`);
+    const unified = findUnifiedAccount(selection.id, meta);
+    if (!unified) {
+        // A stale per-harness default is a preference, not a hard requirement: the
+        // machine stays runnable by falling back to balanced rotation. Bindings and
+        // explicit --account are intentional, so they still fail loud.
+        if (selection.source === 'default') {
+            process.stderr.write(chalk.yellow(`[agents] default account '${selection.id}' for ${agent} no longer exists on this machine; falling back to balanced selection. Clear the stale default with: agents accounts clear-default ${agent}\n`));
+            return null;
+        }
+        const remedy = selection.source === 'binding'
+            ? `Detach the stale binding with: agents accounts detach ${selection.id} ${target}`
+            : `Add an account named '${selection.id}' or remove the --account override.`;
+        throw new Error(`Unknown account '${selection.id}' for ${agent} harness. ${remedy}`);
+    }
     if (unified.kind === 'native') {
         if (unified.agent !== agent) {
             throw new Error(`Account '${unified.name}' is a ${unified.agent} login and cannot authenticate the ${agent} harness.`);