@phnx-labs/agents-cli 1.22.55 → 1.22.57

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`
  *   - `__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`
  *   - `__daemon-run`
  *
  * The tokens are imported from the leaf module sync-commands.ts — the SAME
@@ -75,6 +76,14 @@ 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] === '__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/accounting/usage-ingest.d.ts

@@ -0,0 +1 @@
+export declare function runUsageIngest(): Promise<number>;

package/dist/lib/accounting/usage-ingest.js

@@ -0,0 +1,75 @@
+/**
+ * The `agents __usage-ingest` receiver (PHNX-3392 usage-sync).
+ *
+ * A headed peer's daemon pipes a {@link UsageSyncPayload} JSON envelope to our
+ * stdin; we merge its identity-keyed rows into the local usage cache newest-wins
+ * ({@link ingestPeerClaudeUsageRows}). Hidden internal verb — intercepted in
+ * index.ts before bootstrap, so it never triggers an update check or a detached
+ * sync, and it writes NOTHING to stdout (the caller only reads the exit code).
+ *
+ * Exit codes: 0 = merged (or nothing to merge — an empty payload is not an error),
+ * 2 = malformed input. It fails loud on a bad envelope rather than silently
+ * accepting a wrong shape, but a busy cache lock degrades to best-effort inside
+ * `ingestPeerClaudeUsageRows` like every other cache writer.
+ *
+ * The payload arrives on stdin, EXCEPT on a Windows receiver: the `agents.ps1`
+ * shim does not forward ssh-piped stdin to the node process, so the pusher writes
+ * the payload to a temp file and passes `agents __usage-ingest --from <path>`
+ * (the same workaround the secrets push uses — `buildWindowsStdinImportCommand`).
+ */
+import * as fs from 'fs';
+import { ingestPeerClaudeUsageRows } from './usage.js';
+function readStdin() {
+    return new Promise((resolve) => {
+        let buf = '';
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (chunk) => {
+            buf += chunk;
+        });
+        process.stdin.on('end', () => resolve(buf));
+        process.stdin.on('error', () => resolve(buf));
+    });
+}
+/** `--from <path>` reads the payload from a file instead of stdin (Windows path). */
+function fromFileArg(argv) {
+    const i = argv.indexOf('--from');
+    return i !== -1 && argv[i + 1] ? argv[i + 1] : null;
+}
+export async function runUsageIngest() {
+    const fromPath = fromFileArg(process.argv.slice(3));
+    let source;
+    if (fromPath) {
+        try {
+            source = fs.readFileSync(fromPath, 'utf-8');
+        }
+        catch (err) {
+            process.stderr.write(`[agents] __usage-ingest: cannot read --from ${fromPath}: ${err.message}\n`);
+            return 2;
+        }
+    }
+    else {
+        source = await readStdin();
+    }
+    const raw = source.trim();
+    if (!raw)
+        return 0; // nothing piped — a no-op tick, not a failure.
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        process.stderr.write('[agents] __usage-ingest: malformed JSON payload\n');
+        return 2;
+    }
+    if (!payload ||
+        payload.v !== 1 ||
+        typeof payload.rows !== 'object' ||
+        payload.rows === null ||
+        Array.isArray(payload.rows) // `typeof [] === 'object'` — an array is NOT a rows map
+    ) {
+        process.stderr.write('[agents] __usage-ingest: unrecognized usage-sync payload shape\n');
+        return 2;
+    }
+    ingestPeerClaudeUsageRows(payload.rows);
+    return 0;
+}

package/dist/lib/accounting/usage-sync.d.ts

@@ -0,0 +1,69 @@
+import { type DeviceProfile } from '../devices/registry.js';
+import { type ConfiguredDeviceRole } from '../device-config.js';
+import { type CachedUsageSnapshot } from './usage.js';
+/** How long a single peer push may take before it is abandoned for this tick. */
+export declare const USAGE_PUSH_DEADLINE_MS = 20000;
+/** The stdin envelope the `__usage-ingest` verb reads. `v` guards the shape. */
+export interface UsageSyncPayload {
+    v: 1;
+    rows: Record<string, CachedUsageSnapshot>;
+}
+/** One peer the local publisher is considering, reduced to the plan inputs. */
+export interface UsagePushTarget {
+    name: string;
+    /** The peer's configured role — headed peers are skipped (own reader). */
+    role: ConfiguredDeviceRole | undefined;
+    /** Live-ish reachability from the tailscale snapshot; offline peers are skipped. */
+    online: boolean;
+    /** Managed known-hosts pin — an unpinned host is skipped, never TOFU-accepted. */
+    pinned: boolean;
+}
+export type UsageSyncPlanItem = {
+    action: 'push';
+    device: string;
+} | {
+    action: 'skip';
+    device: string;
+    reason: string;
+};
+/**
+ * Decide, per peer, whether to push the local usage snapshot. Pure.
+ *
+ * - `selfIsPublisher` is false on a `worker`/unmarked box: it has no authoritative
+ *   usage to publish, so every peer is skipped.
+ * - `hasLocalRows` false means the local cache is empty (nothing to teach yet).
+ * - A HEADED peer is skipped — it reads its own usage; pushing risks nothing
+ *   (the merge is newest-wins) but is wasted work, and keeping the fan-out to
+ *   consumers only makes the intent legible.
+ */
+export declare function planUsagePush(selfIsPublisher: boolean, hasLocalRows: boolean, targets: UsagePushTarget[]): UsageSyncPlanItem[];
+export interface UsageSyncResult {
+    pushed: string[];
+    skipped: Array<{
+        device: string;
+        reason: string;
+    }>;
+    errors: Array<{
+        device: string;
+        message: string;
+    }>;
+}
+export interface UsageSyncDeps {
+    selfRole?: () => ConfiguredDeviceRole | undefined;
+    listDevices?: () => DeviceProfile[];
+    /** Configured roles by device name; default reads the fleet config. */
+    listRoles?: () => Record<string, ConfiguredDeviceRole>;
+    localName?: () => string;
+    isPinned?: (name: string) => boolean;
+    exportRows?: () => Record<string, CachedUsageSnapshot>;
+    /** Deliver the serialized payload to one peer. Default: ssh `__usage-ingest`. */
+    push?: (device: DeviceProfile, payload: string) => {
+        ok: boolean;
+        message?: string;
+    };
+}
+/**
+ * Push the local identity-keyed usage snapshot to every reachable, pinned,
+ * non-headed peer. A no-op on a non-headed box or when the local cache is empty.
+ */
+export declare function syncFleetUsageSnapshots(deps?: UsageSyncDeps): UsageSyncResult;

package/dist/lib/accounting/usage-sync.js

@@ -0,0 +1,129 @@
+/**
+ * Fleet sync of the identity-keyed Claude usage snapshot (PHNX-3392 follow-up).
+ *
+ * A rate limit is metered per ACCOUNT, so an account's 5h/weekly usage is the
+ * same number on every box. But only a HEADED device (`personal`/`desktop`) can
+ * read it: the interactive OAuth login it holds carries the `user:profile` scope
+ * `/api/oauth/usage` requires, and its interactive Claude runs feed the native
+ * windows through the status-line writer. A headless `worker` has only the
+ * `user:inference` setup-token, which the usage endpoint 403s (RUSH-2392), so its
+ * local `claude-usage.json` stays blank and `agents view` shows no S:/W: bars.
+ *
+ * This closes that gap the same way {@link ../secrets/reserved-sync.ts} closes
+ * the auth-token gap: each headed daemon PUSHES its identity-keyed usage rows to
+ * the worker peers that cannot read them, which merge NEWEST-WINS
+ * ({@link ingestPeerClaudeUsageRows}). Publish direction is role-driven —
+ * personal/desktop publish, worker/unmarked consume — so it composes with the
+ * device-role taxonomy rather than adding a second notion of "which box is real".
+ *
+ * Double-fire safety: each daemon only writes the DESTINATION's own cache, and
+ * the merge is idempotent + timestamp-guarded, so two headed publishers pushing
+ * the same account to one worker converge on the freshest snapshot regardless of
+ * order. The input a publisher reads is its OWN cache (device-local state), so an
+ * unrestricted per-device fire is correct — no shared queue.
+ *
+ * The planner is pure so tests cover every skip/push branch with no SSH.
+ */
+import { sshExec } from '../ssh-exec.js';
+import { buildRemoteAgentsInvocation, buildWindowsStdinAgentsCommand, remoteShellFor } from '../hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { loadDevicesSync } from '../devices/registry.js';
+import { sshTargetFor } from '../devices/connect.js';
+import { isHostPinned } from '../devices/known-hosts.js';
+import { machineId, normalizeHost } from '../session/sync/config.js';
+import { isHeadedDeviceRole, listConfiguredDeviceRoles, selfConfiguredDeviceRole, } from '../device-config.js';
+import { exportClaudeUsageCacheRows } from './usage.js';
+/** How long a single peer push may take before it is abandoned for this tick. */
+export const USAGE_PUSH_DEADLINE_MS = 20_000;
+/**
+ * Decide, per peer, whether to push the local usage snapshot. Pure.
+ *
+ * - `selfIsPublisher` is false on a `worker`/unmarked box: it has no authoritative
+ *   usage to publish, so every peer is skipped.
+ * - `hasLocalRows` false means the local cache is empty (nothing to teach yet).
+ * - A HEADED peer is skipped — it reads its own usage; pushing risks nothing
+ *   (the merge is newest-wins) but is wasted work, and keeping the fan-out to
+ *   consumers only makes the intent legible.
+ */
+export function planUsagePush(selfIsPublisher, hasLocalRows, targets) {
+    if (!selfIsPublisher) {
+        return targets.map((d) => ({
+            action: 'skip',
+            device: d.name,
+            reason: 'this device is not a usage publisher (mark it personal or desktop)',
+        }));
+    }
+    if (!hasLocalRows) {
+        return targets.map((d) => ({ action: 'skip', device: d.name, reason: 'no local usage snapshot to publish' }));
+    }
+    return targets.map((d) => {
+        if (isHeadedDeviceRole(d.role))
+            return { action: 'skip', device: d.name, reason: 'headed peer reads its own usage' };
+        if (!d.online)
+            return { action: 'skip', device: d.name, reason: 'offline' };
+        if (!d.pinned) {
+            return { action: 'skip', device: d.name, reason: `host key not pinned; run \`agents ssh ${d.name}\` once` };
+        }
+        return { action: 'push', device: d.name };
+    });
+}
+/** Production push: pipe the payload to the peer's `agents __usage-ingest` over ssh. */
+function defaultUsagePush(device, payload) {
+    const target = sshTargetFor(device);
+    const os = resolveRemoteOsSync(device.name);
+    // A Windows peer's `agents.ps1` shim does not forward ssh-piped stdin, so hand
+    // the payload through a temp file (`--from`) instead of stdin — same workaround
+    // the secrets push uses. A POSIX peer reads stdin directly.
+    const remoteCmd = remoteShellFor(os) === 'powershell'
+        ? buildWindowsStdinAgentsCommand(['__usage-ingest'])
+        : buildRemoteAgentsInvocation(['__usage-ingest'], undefined, os);
+    const res = sshExec(target, remoteCmd, { input: payload, timeoutMs: USAGE_PUSH_DEADLINE_MS });
+    if (res.timedOut)
+        return { ok: false, message: 'timed out' };
+    if (res.code !== 0)
+        return { ok: false, message: res.stderr.trim() || `remote exit ${res.code}` };
+    return { ok: true };
+}
+/**
+ * Push the local identity-keyed usage snapshot to every reachable, pinned,
+ * non-headed peer. A no-op on a non-headed box or when the local cache is empty.
+ */
+export function syncFleetUsageSnapshots(deps = {}) {
+    const result = { pushed: [], skipped: [], errors: [] };
+    const selfRole = (deps.selfRole ?? selfConfiguredDeviceRole)();
+    const devices = deps.listDevices?.() ?? Object.values(loadDevicesSync());
+    const self = deps.localName?.() ?? machineId();
+    const selfNorm = normalizeHost(self);
+    const roles = deps.listRoles?.() ?? (deps.listDevices ? listConfiguredDeviceRoles(devices.map((d) => d.name)) : listConfiguredDeviceRoles());
+    const isPinned = deps.isPinned ?? isHostPinned;
+    const byName = new Map(devices.map((d) => [d.name, d]));
+    const targets = devices
+        .filter((d) => normalizeHost(d.name) !== selfNorm)
+        .map((d) => ({
+        name: d.name,
+        role: roles[d.name],
+        online: d.tailscale?.online !== false,
+        pinned: isPinned(d.name),
+    }));
+    const rows = (deps.exportRows ?? exportClaudeUsageCacheRows)();
+    const plan = planUsagePush(isHeadedDeviceRole(selfRole), Object.keys(rows).length > 0, targets);
+    const payload = JSON.stringify({ v: 1, rows });
+    const push = deps.push ?? defaultUsagePush;
+    for (const item of plan) {
+        if (item.action === 'skip') {
+            result.skipped.push({ device: item.device, reason: item.reason });
+            continue;
+        }
+        const device = byName.get(item.device);
+        if (!device) {
+            result.errors.push({ device: item.device, message: 'device left the registry mid-sync' });
+            continue;
+        }
+        const outcome = push(device, payload);
+        if (outcome.ok)
+            result.pushed.push(item.device);
+        else
+            result.errors.push({ device: item.device, message: outcome.message ?? 'push failed' });
+    }
+    return result;
+}

package/dist/lib/accounting/usage.d.ts

@@ -228,8 +228,8 @@ interface UsageOptions {
      * When true, a read that finds no file-based setup-token MAY fall through to
      * Claude Code's interactive OAuth login (the only credential carrying
      * `user:profile`, which `/api/oauth/usage` requires). OFF by default and set
-     * ONLY by a foreground human `agents view` on a `personal` device (see
-     * USAGE-READ-2). Every background caller — daemon usage warm, auth-health
+     * ONLY by a foreground human `agents view` on a headed device (personal or
+     * desktop; see USAGE-READ-2). Every background caller — daemon usage warm, auth-health
      * probe, watchdog — leaves it unset, preserving the RUSH-1822 guarantee that
      * an unattended loop never transmits the interactive login to Anthropic.
      */
@@ -252,6 +252,26 @@ interface ClaudeOauthCredentials {
     rateLimitTier?: string | null;
     organizationUuid?: string | null;
 }
+/** Serialized usage window for the on-disk cache. */
+interface CachedUsageWindow {
+    key: UsageWindowKey;
+    label: string;
+    shortLabel: string;
+    usedPercent: number;
+    resetsAt: string | null;
+    windowMinutes: number | null;
+}
+/** Serialized usage snapshot for the on-disk cache. */
+export interface CachedUsageSnapshot {
+    capturedAt: string | null;
+    windows: CachedUsageWindow[];
+    plan?: string | null;
+    refreshHint?: string | null;
+    unavailable?: {
+        reason: 'session_limit' | 'out_of_credits';
+        resetsAt?: string;
+    };
+}
 /** The single registry of agent usage sources and their transport. */
 declare const USAGE_SOURCES: {
     readonly claude: {
@@ -666,6 +686,32 @@ export declare function pruneExpiredClaudeUsageCacheEntry(usageKey: string, cach
 export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
 /** Atomically merge partial native Claude windows into the current fresh row. */
 export declare function mergeClaudeUsageCacheWindows(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
+/**
+ * Export the local usage cache rows worth publishing to fleet peers (PHNX-3392
+ * usage-sync). Returns the raw serialized rows keyed by usage identity, filtered
+ * to those carrying at least one window — an empty row has nothing to teach a
+ * worker. The transport is the on-disk cache form, so there is no Date round-trip.
+ */
+export declare function exportClaudeUsageCacheRows(cachePath?: string): Record<string, CachedUsageSnapshot>;
+/**
+ * Merge usage rows received from a fleet peer into the local cache, NEWEST-WINS
+ * per identity by `capturedAt` (PHNX-3392 usage-sync). A worker has no local
+ * usage writer, so an incoming row is almost always the freshest it will get; the
+ * timestamp guard exists so a stale push from one headed peer can never overwrite
+ * a fresher row another peer (or, on a headed receiver, the local status-line)
+ * already wrote. An incoming row with no `capturedAt` cannot prove it is newer, so
+ * it never displaces an existing timestamped row. Returns the count updated.
+ * Locked + atomic like every other cache writer.
+ *
+ * Deliberately NOT role-gated on the receiver. "Consume only on worker/unmarked"
+ * is a SENDER-side optimization (don't waste a push on a headed peer that reads
+ * its own usage), not a safety invariant — the actual safety property is this
+ * newest-wins guard. Receiving on a headed box is harmless (its fresher local
+ * status-line row survives) or helpful (an account it is signed into but never
+ * runs now shows a usage bar), so gating here on the receiver's own — laggier —
+ * view of its role would only reject legitimate data.
+ */
+export declare function ingestPeerClaudeUsageRows(rows: Record<string, CachedUsageSnapshot>, cachePath?: string): number;
 /**
  * Persist a Claude tokens/credits exhaustion (`out of usage credits` / `monthly
  * spend limit`) from a real run. Unlike a rate/session limit this does NOT reset

package/dist/lib/accounting/usage.js

@@ -1558,7 +1558,7 @@ export async function loadClaudeOauth(home, opts) {
         // setup-token via the mint-auth path to restore usage/probe for the account.
         //
         // The single sanctioned exception (USAGE-READ-1/2): a foreground human
-        // `agents view` on a `personal` device sets allowInteractiveLogin, and only
+        // `agents view` on a headed device (personal or desktop) sets allowInteractiveLogin, and only
         // then do we fall through to the interactive-login read below — the one
         // credential carrying `user:profile`, which the usage endpoint requires. This
         // is a human running one command, not an unattended loop, so it is not the
@@ -1750,6 +1750,77 @@ export function mergeClaudeUsageCacheWindows(usageKey, snapshot, cachePath = get
         /* best-effort cache write — lock busy or disk full */
     }
 }
+/**
+ * Export the local usage cache rows worth publishing to fleet peers (PHNX-3392
+ * usage-sync). Returns the raw serialized rows keyed by usage identity, filtered
+ * to those carrying at least one window — an empty row has nothing to teach a
+ * worker. The transport is the on-disk cache form, so there is no Date round-trip.
+ */
+export function exportClaudeUsageCacheRows(cachePath = getClaudeUsageCachePath()) {
+    const cache = readClaudeUsageCacheFile(cachePath);
+    const out = {};
+    for (const [key, row] of Object.entries(cache)) {
+        if (row && Array.isArray(row.windows) && row.windows.length > 0)
+            out[key] = row;
+    }
+    return out;
+}
+function parseCapturedAtMs(capturedAt) {
+    if (!capturedAt)
+        return null;
+    const ms = Date.parse(capturedAt);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Merge usage rows received from a fleet peer into the local cache, NEWEST-WINS
+ * per identity by `capturedAt` (PHNX-3392 usage-sync). A worker has no local
+ * usage writer, so an incoming row is almost always the freshest it will get; the
+ * timestamp guard exists so a stale push from one headed peer can never overwrite
+ * a fresher row another peer (or, on a headed receiver, the local status-line)
+ * already wrote. An incoming row with no `capturedAt` cannot prove it is newer, so
+ * it never displaces an existing timestamped row. Returns the count updated.
+ * Locked + atomic like every other cache writer.
+ *
+ * Deliberately NOT role-gated on the receiver. "Consume only on worker/unmarked"
+ * is a SENDER-side optimization (don't waste a push on a headed peer that reads
+ * its own usage), not a safety invariant — the actual safety property is this
+ * newest-wins guard. Receiving on a headed box is harmless (its fresher local
+ * status-line row survives) or helpful (an account it is signed into but never
+ * runs now shows a usage bar), so gating here on the receiver's own — laggier —
+ * view of its role would only reject legitimate data.
+ */
+export function ingestPeerClaudeUsageRows(rows, cachePath = getClaudeUsageCachePath()) {
+    const incoming = Object.entries(rows).filter(([, row]) => row && Array.isArray(row.windows) && row.windows.length > 0);
+    if (incoming.length === 0)
+        return 0;
+    let merged = 0;
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            for (const [key, row] of incoming) {
+                const prior = cache[key];
+                if (prior) {
+                    const priorMs = parseCapturedAtMs(prior.capturedAt);
+                    const incomingMs = parseCapturedAtMs(row.capturedAt);
+                    // Keep local unless the incoming row PROVES it is strictly newer.
+                    if (incomingMs === null)
+                        continue;
+                    if (priorMs !== null && priorMs >= incomingMs)
+                        continue;
+                }
+                cache[key] = row;
+                merged += 1;
+            }
+            if (merged > 0)
+                writeClaudeUsageCacheFile(cache, cachePath);
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
+    return merged;
+}
 /** Read the entire usage cache file from disk. */
 function readClaudeUsageCacheFile(cachePath) {
     if (!fs.existsSync(cachePath)) {

package/dist/lib/agent-spec/agents.js

@@ -3093,7 +3093,7 @@ export function parseAgentVersionSpec(raw) {
     const [rawAgent, rawVersion] = parts;
     const agent = resolveAgentName(rawAgent);
     if (!agent) {
-        return { error: `Unknown agent, profile, or workflow: ${rawAgent}. See \`agents list\` for the installed harnesses.` };
+        return { error: `Unknown agent, profile, or workflow: ${rawAgent}. See \`agents view\` for the installed harnesses.` };
     }
     if (rawVersion !== undefined && (rawVersion === '' || !VERSION_RE.test(rawVersion))) {
         return { error: `Invalid version '${rawVersion}' in '${raw}'` };

package/dist/lib/analytics/mix-commands.d.ts

@@ -4,11 +4,13 @@
  * These used to live as the top-level `agents trends` tree. That name was a
  * peer of `agents insights` with overlapping "analytics" meaning, so agents and
  * humans kept picking the wrong verb. The cheap counter path (sessions index +
- * usage.db) still exists — it is now `agents insights mix` and the recipe
- * subcommands below. Latency stays on `agents perf`; quota on `agents view`.
+ * usage.db) still exists — it is now `agents insights mix`. Latency stays on
+ * `agents insights perf`; quota on `agents view`.
  *
- * Former top-level `agents trends` is gone. The nested spelling
- * `agents insights trends` is an alias of `agents insights mix`.
+ * One surface, not five: the board is `agents insights mix`, one section is
+ * `agents insights mix <recipe>`, and `--list` names the recipe ids. The former
+ * per-recipe shortcut commands (`harness-mix`, `model-mix`, …), the `recipes`
+ * lister, and the `trends` alias were removed — `mix` already did all three.
  */
 import type { Command } from 'commander';
 export declare function parseMixDays(raw: string | undefined): number;
@@ -23,9 +25,8 @@ export declare function renderMixDashboard(days: number, asJson: boolean, banner
  *
  * Layout:
  *   <parent> mix                 multi-recipe board
- *   <parent> trends              alias of mix (former top-level `agents trends`)
- *   <parent> recipes             list recipe ids
+ *   <parent> mix <recipe>        one baked recipe (harness-mix, model-mix, …)
+ *   <parent> mix --list          list recipe ids
  *   <parent> query               raw usage.db rows
- *   <parent> harness-mix|…       one baked recipe
  */
 export declare function registerMixCommands(parent: Command): void;