@phnx-labs/agents-cli 1.22.56 → 1.22.58

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

@@ -10,15 +10,26 @@
  * floor, so an account racing toward its 5h cap loses priority before it maxes.
  */
 export declare const PROJECTION_HORIZON_MIN = 30;
+/**
+ * The weight an account with NO usage snapshot draws. Absence of a usage signal
+ * is NOT capacity (specifications.md GWT-E5c, SING-1a): a null snapshot means
+ * "unverifiable", not "empty" — on a worker box every account reads null
+ * (setup-token lacks the `user:profile` scope, RUSH-2392), so scoring null as
+ * full capacity made the blind pool's top pick an account that was actually
+ * weekly-exhausted (PHNX-3392). Floored at 1, never 0: an all-unverified pool
+ * must still draw a pick rather than strand the launch.
+ */
+export declare const UNVERIFIED_WEIGHT = 1;
 /**
  * Weight one candidate by remaining routing capacity, deprioritized by how soon
  * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
+ * an account with no live snapshot is NOT full-capacity — absence of a usage
+ * signal is not evidence of headroom, so it draws `UNVERIFIED_WEIGHT` and any
+ * verified-healthy account outranks it (GWT-E5c). `minutesToLimit` (the daemon's
+ * burn-rate projection on the 5h session window) then scales that base: >=
+ * horizon (or unknown) keeps full weight, and closer-to-cap scales toward the
+ * floor of 1 — so a launch avoids an account projected to cap soon, not just a
+ * 100%-maxed one. Pure + exported so the deprioritization is unit-tested
+ * directly (a weighted-random draw is not).
  */
 export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;

package/dist/lib/accounting/capacity.js

@@ -10,19 +10,30 @@
  * floor, so an account racing toward its 5h cap loses priority before it maxes.
  */
 export const PROJECTION_HORIZON_MIN = 30;
+/**
+ * The weight an account with NO usage snapshot draws. Absence of a usage signal
+ * is NOT capacity (specifications.md GWT-E5c, SING-1a): a null snapshot means
+ * "unverifiable", not "empty" — on a worker box every account reads null
+ * (setup-token lacks the `user:profile` scope, RUSH-2392), so scoring null as
+ * full capacity made the blind pool's top pick an account that was actually
+ * weekly-exhausted (PHNX-3392). Floored at 1, never 0: an all-unverified pool
+ * must still draw a pick rather than strand the launch.
+ */
+export const UNVERIFIED_WEIGHT = 1;
 /**
  * Weight one candidate by remaining routing capacity, deprioritized by how soon
  * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
+ * an account with no live snapshot is NOT full-capacity — absence of a usage
+ * signal is not evidence of headroom, so it draws `UNVERIFIED_WEIGHT` and any
+ * verified-healthy account outranks it (GWT-E5c). `minutesToLimit` (the daemon's
+ * burn-rate projection on the 5h session window) then scales that base: >=
+ * horizon (or unknown) keeps full weight, and closer-to-cap scales toward the
+ * floor of 1 — so a launch avoids an account projected to cap soon, not just a
+ * 100%-maxed one. Pure + exported so the deprioritization is unit-tested
+ * directly (a weighted-random draw is not).
  */
 export function capacityWeight(usedPercent, minutesToLimit) {
-    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
+    const base = usedPercent === null ? UNVERIFIED_WEIGHT : Math.max(1, 100 - usedPercent);
     if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
         return base;
     const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));

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,97 @@
+import { type DeviceProfile } from '../devices/registry.js';
+import { type ConfiguredDeviceRole } from '../device-config.js';
+import { type CachedUsageSnapshot, type UsageSnapshot } 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;
+export declare const USAGE_PULL_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;
+    };
+}
+export interface UsagePullResult {
+    pulledFrom: string | null;
+    merged: number;
+    skipped: string | null;
+    error: string | null;
+}
+export interface UsagePullDeps {
+    selfRole?: () => ConfiguredDeviceRole | undefined;
+    listDevices?: () => DeviceProfile[];
+    listRoles?: () => Record<string, ConfiguredDeviceRole>;
+    isPinned?: (name: string) => boolean;
+    exportRows?: () => Record<string, CachedUsageSnapshot>;
+    readRow?: (usageKey: string) => Pick<UsageSnapshot, 'windows'> | null;
+    ingestRows?: (rows: Record<string, CachedUsageSnapshot>) => number;
+    /** Read the versioned payload from the primary. Default: ssh `__usage-export`. */
+    pull?: (device: DeviceProfile) => {
+        ok: boolean;
+        stdout?: string;
+        message?: string;
+    };
+}
+/**
+ * Pull usage from the fleet's primary headed device when this worker's local
+ * cache is empty or contains an expired row. `personal` is the primary role;
+ * a `desktop` is used only when the fleet has no personal device.
+ */
+export declare function pullUsageFromPrimary(deps?: UsagePullDeps): UsagePullResult;
+/**
+ * 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,203 @@
+/**
+ * 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, stripClixml } 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, ingestPeerClaudeUsageRows, readClaudeUsageCache, } 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;
+export const USAGE_PULL_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 };
+}
+/** Production pull: read the primary's cache through its hidden export verb. */
+function defaultUsagePull(device) {
+    const target = sshTargetFor(device);
+    const os = resolveRemoteOsSync(device.name);
+    const remoteCmd = buildRemoteAgentsInvocation(['__usage-export'], undefined, os);
+    const res = sshExec(target, remoteCmd, { timeoutMs: USAGE_PULL_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, stdout: res.stdout };
+}
+/**
+ * Pull usage from the fleet's primary headed device when this worker's local
+ * cache is empty or contains an expired row. `personal` is the primary role;
+ * a `desktop` is used only when the fleet has no personal device.
+ */
+export function pullUsageFromPrimary(deps = {}) {
+    const result = { pulledFrom: null, merged: 0, skipped: null, error: null };
+    if ((deps.selfRole ?? selfConfiguredDeviceRole)() !== 'worker') {
+        result.skipped = 'this device is not a worker';
+        return result;
+    }
+    const localRows = (deps.exportRows ?? exportClaudeUsageCacheRows)();
+    const readRow = deps.readRow ?? readClaudeUsageCache;
+    const localEntries = Object.entries(localRows);
+    if (localEntries.length > 0 && localEntries.every(([key, row]) => {
+        const fresh = readRow(key);
+        return fresh !== null && fresh.windows.length === row.windows.length;
+    })) {
+        result.skipped = 'local usage cache is fresh';
+        return result;
+    }
+    const devices = deps.listDevices?.() ?? Object.values(loadDevicesSync());
+    const roles = deps.listRoles?.() ?? (deps.listDevices
+        ? listConfiguredDeviceRoles(devices.map((device) => device.name))
+        : listConfiguredDeviceRoles());
+    const isPinned = deps.isPinned ?? isHostPinned;
+    const primary = devices
+        .filter((device) => roles[device.name] === 'personal')
+        .concat(devices.filter((device) => roles[device.name] === 'desktop'))
+        .find((device) => device.tailscale?.online !== false && isPinned(device.name));
+    if (!primary) {
+        result.error = 'no reachable, pinned personal or desktop device is configured as the usage primary';
+        return result;
+    }
+    const outcome = (deps.pull ?? defaultUsagePull)(primary);
+    if (!outcome.ok) {
+        result.error = outcome.message ?? 'pull failed';
+        return result;
+    }
+    let payload;
+    try {
+        // A Windows usage primary's `agents.ps1` shim prepends a PowerShell CLIXML
+        // progress banner to stdout, exactly as every other remote-JSON boundary
+        // strips (remote-cmd.ts:325). Without this, a headed Windows box (win-mini
+        // is a live fleet device) makes every pull fail as "malformed JSON", the
+        // worker's cache stays null, and the PHNX-3392 capacity floor silently
+        // becomes the only thing standing between a blind pool and an exhausted pick.
+        payload = JSON.parse(stripClixml(outcome.stdout ?? ''));
+    }
+    catch {
+        result.error = 'primary returned malformed JSON';
+        return result;
+    }
+    if (!payload || payload.v !== 1 || typeof payload.rows !== 'object' || payload.rows === null || Array.isArray(payload.rows)) {
+        result.error = 'primary returned an unrecognized usage-sync payload shape';
+        return result;
+    }
+    result.pulledFrom = primary.name;
+    result.merged = (deps.ingestRows ?? ingestPeerClaudeUsageRows)(payload.rows);
+    return result;
+}
+/**
+ * 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

@@ -284,6 +284,12 @@ const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
 const EMPTY = '\u2591';
 const PARTIAL_BLOCKS = ['', '\u258F', '\u258E', '\u258D', '\u258C', '\u258B', '\u258A', '\u2589'];
+// A window we EXPECTED but have no reading for \u2014 e.g. Claude's 5h "session"
+// window when the account has no usage in the current rolling window, so the
+// usage API returns five_hour.utilization = null and no session bar is written.
+// It must read as neither 0% (EMPTY '\u2591') nor 100% (FULL '\u2588') \u2014 a full block was
+// alarming and looked maxed-out \u2014 so use a dashed row that says "no data".
+const NO_DATA = '\u2504';
 /** Construct the benign no-local-log result without overloading `error`. */
 export function usageNoRecentUsageInfo() {
     return { snapshot: null, error: null, [USAGE_BENIGN_STATE]: 'no-recent-usage' };
@@ -590,7 +596,7 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
             : selected.map((window) => ({ window, shortLabel: window.shortLabel }));
         const windowParts = windowsToRender.map(({ window, shortLabel }, index) => {
             if (!window) {
-                const missing = chalk.red(`${shortLabel}: ${FULL.repeat(COMPACT_BAR_LEN)} unavailable`);
+                const missing = chalk.dim(`${shortLabel}: ${NO_DATA.repeat(COMPACT_BAR_LEN)} unavailable`);
                 return index < windowsToRender.length - 1 ? padToWidth(missing, 20) : missing;
             }
             const bar = renderCompactUsageBar(window.usedPercent);
@@ -1558,7 +1564,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 +1756,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}'` };