@phnx-labs/agents-cli 1.22.117 → 1.22.118

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

@@ -1,29 +1,59 @@
 /**
- * Fleet distribution of identity-keyed Claude usage through the user repo.
+ * Fleet distribution of identity-keyed Claude usage over SSH (PHNX-4116).
  *
- * A headed device can read authoritative usage; a worker's setup-token cannot.
- * Headed daemons therefore publish one snapshot into their conflict-free
- * `~/.agents/devices/<device>/daemon-state.json`. The daemon's bounded Git
- * transport delivers those files automatically; workers merge newest-wins.
- * There is deliberately no device-to-device SSH in this module or its tick.
+ * A headed device can read authoritative usage; a worker's setup-token cannot
+ * (credential-management.md invariant 5: a worker never polls
+ * `/api/oauth/usage`). So the headed daemon's `usage-sync` tick dials every
+ * dialable peer in parallel with `agents __usage-ingest --reply`, sending this
+ * box's own daemon-state envelope on stdin; the peer merges the usage rows into
+ * its cache newest-wins and prints its own envelope back, which the headed box
+ * stores in `~/.agents/devices/<peer>/daemon-state.json` stamped `receivedAt`.
+ * Workers never initiate. A peer that times out is skipped this tick and never
+ * blocks another. Only usage rows, verdicts, and session digests move here —
+ * never a credential (invariant 7: roles never cross).
+ *
+ * This replaced a git exchange over the fleet-synced user repo: every daemon
+ * committed its own file each tick, so the shared store reached 1.1 GiB /
+ * 18,358 commits with 100% of the last 2,000 being `chore(devices): publish
+ * <device> daemon state`, and a worker's clone fell 10k commits behind with
+ * `git fetch timed out` on every tick — a valid setup-token could not be
+ * scheduled because a repo was bloated. Git now carries human-authored
+ * resources only; `devices/<device>/daemon-state.json` is untracked.
  */
 import { type ConfiguredDeviceRole } from '../device-config.js';
+import { type FleetSharedDeviceState } from '../fleet-shared-state.js';
+import type { DeviceProfile } from '../devices/registry.js';
+import type { SshExecResult } from '../ssh-exec.js';
 import { type CachedUsageSnapshot } from './usage.js';
-/** Cadence of the usage-sync git tick — the trust window for a `sync` snapshot. */
+/** Cadence of the usage-sync tick — the trust window for a `sync` snapshot. */
 export declare const USAGE_SYNC_INTERVAL_MS: number;
 /** Re-publish an unchanged windowed row at least this often so workers' 15-min trust does not lapse. */
 export declare const USAGE_PUBLISH_HEARTBEAT_MS: number;
+/** Per-peer SSH budget for one exchange; a peer past it is skipped this tick. */
+export declare const USAGE_EXCHANGE_PEER_TIMEOUT_MS = 20000;
+/** Marks the start of the JSON reply on the peer's stdout, so login-shell noise before it is ignored. */
+export declare const FLEET_STATE_REPLY_MARKER = "@@AGENTS_FLEET_STATE@@";
 /**
  * Keep the previously published `capturedAt` when meters have not moved and
  * the last publish is still inside the heartbeat. Stops statusline re-renders
- * from dirtying the shared store (and taking the git lock) every few seconds.
+ * from rewriting the own-state file every few seconds.
  */
 export declare function mergeUsageRowsForPublish(previous: Record<string, CachedUsageSnapshot> | undefined, next: Record<string, CachedUsageSnapshot>, nowMs?: number): Record<string, CachedUsageSnapshot>;
-/** Legacy hidden ingest/export envelope kept for older fleet CLI compatibility. */
+/** Legacy `__usage-ingest` envelope (v1): bare rows from an older headed peer. */
 export interface UsageSyncPayload {
     v: 1;
     rows: Record<string, CachedUsageSnapshot>;
 }
+/**
+ * The exchange envelope (v2), identical in both directions: a device's own
+ * daemon-state envelope. `errors` carries the replying peer's non-fatal
+ * publisher failures so the headed box can log them against that peer.
+ */
+export interface FleetStateExchangePayload {
+    v: 2;
+    state: FleetSharedDeviceState;
+    errors?: string[];
+}
 interface PublishUsageSnapshotOptions {
     userAgentsDir?: string;
     cachePath?: string;
@@ -37,39 +67,112 @@ interface PublishUsageSnapshotResult {
     error: string | null;
     path: string | null;
 }
-/** Publish this headed device's stable usage snapshot into its owned store file. */
+/** Publish this headed device's stable usage snapshot into its own state file. */
 export declare function publishUsageSnapshotToSharedStore(options?: PublishUsageSnapshotOptions): Promise<PublishUsageSnapshotResult>;
+export interface PublishOwnFleetStateResult {
+    usage: PublishUsageSnapshotResult;
+    mirror: {
+        changed: boolean;
+        count: number;
+        error: string | null;
+    };
+    auth: {
+        status: string;
+        error: string | null;
+    };
+    /** Every publisher failure, as `<field>: <message>` — logged by the caller, never fatal. */
+    errors: string[];
+}
 /**
- * Publish a changed snapshot immediately and exchange the shared repo so
- * workers see it without waiting for the 15-minute tick. No-ops when the
- * serialized store is unchanged (statusline re-renders with the same windows).
+ * Refresh every field this device owns in its own state file: the usage
+ * snapshot (headed only), the session digests, and the reserved-auth readiness
+ * verdict. Run before the envelope is sent (the headed tick) or printed back
+ * (`__usage-ingest --reply`) so a peer always receives current fields. Each
+ * publisher is independent: one failing is reported in `errors` and the others
+ * still land. All three writers are the async, non-blocking variants
+ * (`updateFleetSharedDeviceStateAsync` underneath).
  */
-export declare function pushUsageSnapshotNow(options?: PublishUsageSnapshotOptions & {
-    lockPath?: string;
-    timeoutMs?: number;
-}): Promise<{
-    published: PublishUsageSnapshotResult;
-    transport?: import('../fleet-shared-repo-sync.js').FleetSharedRepoSyncResult;
-}>;
-interface ConsumeUsageSnapshotsOptions {
+export declare function publishOwnFleetState(options?: PublishUsageSnapshotOptions): Promise<PublishOwnFleetStateResult>;
+interface BuildPayloadOptions {
+    device?: string;
     userAgentsDir?: string;
     cachePath?: string;
     role?: ConfiguredDeviceRole;
+    /**
+     * Send only the usage rows (read live from the cache, headed only) — the
+     * placement probe's shape: the dispatcher hands the chosen worker current
+     * numbers without the sessions/auth fields the tick carries.
+     */
+    usageOnly?: boolean;
+    errors?: string[];
+}
+/** This device's exchange envelope, from its own state file (or usage-only from the cache). */
+export declare function buildFleetStatePayload(options?: BuildPayloadOptions): FleetStateExchangePayload;
+/** Serialize the reply as the peer prints it: marker line, then one JSON line. */
+export declare function formatFleetStateReply(payload: FleetStateExchangePayload): string;
+/**
+ * Parse what a peer sent — a v2 exchange envelope, or the legacy v1 bare-rows
+ * envelope from an older headed peer. Throws a clear message on anything else;
+ * the caller decides whether that is exit code 2 (the receiver) or a per-peer
+ * error (the headed tick).
+ */
+export declare function parseFleetStateExchangeInput(raw: string): FleetStateExchangePayload | UsageSyncPayload;
+/** Extract the reply envelope from a peer's stdout (text before the marker is login-shell noise). */
+export declare function parseFleetStateReply(stdout: string): FleetStateExchangePayload;
+interface ApplyPeerStateOptions {
+    userAgentsDir?: string;
+    cachePath?: string;
     device?: string;
-    roles?: Record<string, ConfiguredDeviceRole>;
+    receivedAt?: number;
 }
-interface ConsumeUsageSnapshotsResult {
-    sources: string[];
+export interface ApplyPeerStateResult {
+    path: string;
+    /** Usage rows merged into the local cache (newest-wins per identity). */
     merged: number;
+    receivedAt: number;
+}
+/**
+ * Take a peer's envelope in: store it as that peer's file (stamped `receivedAt`)
+ * and merge its usage rows into this box's cache newest-wins. The same step runs
+ * on both ends — the worker on the pushed envelope, the headed box on the reply.
+ * Both writes take their file lock asynchronously: this runs on the daemon tick
+ * once per peer, and a `sleepSync` lock there freezes every other service.
+ */
+export declare function applyPeerFleetState(state: FleetSharedDeviceState, options?: ApplyPeerStateOptions): Promise<ApplyPeerStateResult>;
+/** The remote command one exchange runs on a peer, in the peer's shell dialect. */
+export declare function buildFleetStateExchangeCommand(os?: string): Promise<string>;
+/** The SSH boundary: run `remoteCmd` on `peer` with `input` on stdin. Injected by tests. */
+export type FleetStateDial = (peer: DeviceProfile, remoteCmd: string, input: string) => Promise<SshExecResult>;
+interface ExchangeOptions {
+    peers?: DeviceProfile[];
+    dial?: FleetStateDial;
+    payload?: FleetStateExchangePayload;
+    device?: string;
+    userAgentsDir?: string;
+    cachePath?: string;
+    timeoutMs?: number;
+}
+export interface PeerExchangeOutcome {
+    device: string;
+    delivered: boolean;
+    /** Set when the peer's reply was stored — PR 5's per-peer freshness input. */
+    receivedAt: number | null;
+    merged: number;
+    /** Why this peer got nothing this tick (timeout, old CLI, mismatched name, …). */
+    error: string | null;
+    /** The peer's own publisher failures, verbatim from its reply. */
+    peerErrors: string[];
+}
+export interface ExchangeResult {
     skipped: string | null;
-    errors: Array<{
-        device: string;
-        message: string;
-    }>;
+    outcomes: PeerExchangeOutcome[];
 }
 /**
- * Read headed publishers from the local user-repo checkout and merge one
- * newest-wins batch into the worker cache. No network or subprocess is touched.
+ * The headed publisher's fan-out: dial every peer in parallel, each under its
+ * own timeout, and apply each reply as it arrives. Never throws for a peer — a
+ * timeout, an old CLI with no `--reply`, or a reply naming the wrong device is
+ * that peer's `error` and the others are unaffected. A non-headed device skips:
+ * workers never initiate (they only answer), so a worker's tick is a no-op here.
  */
-export declare function consumeUsageSnapshotsFromSharedStore(options?: ConsumeUsageSnapshotsOptions): ConsumeUsageSnapshotsResult;
+export declare function exchangeFleetStateWithPeers(options?: ExchangeOptions): Promise<ExchangeResult>;
 export {};

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

@@ -1,21 +1,38 @@
 /**
- * Fleet distribution of identity-keyed Claude usage through the user repo.
+ * Fleet distribution of identity-keyed Claude usage over SSH (PHNX-4116).
  *
- * A headed device can read authoritative usage; a worker's setup-token cannot.
- * Headed daemons therefore publish one snapshot into their conflict-free
- * `~/.agents/devices/<device>/daemon-state.json`. The daemon's bounded Git
- * transport delivers those files automatically; workers merge newest-wins.
- * There is deliberately no device-to-device SSH in this module or its tick.
+ * A headed device can read authoritative usage; a worker's setup-token cannot
+ * (credential-management.md invariant 5: a worker never polls
+ * `/api/oauth/usage`). So the headed daemon's `usage-sync` tick dials every
+ * dialable peer in parallel with `agents __usage-ingest --reply`, sending this
+ * box's own daemon-state envelope on stdin; the peer merges the usage rows into
+ * its cache newest-wins and prints its own envelope back, which the headed box
+ * stores in `~/.agents/devices/<peer>/daemon-state.json` stamped `receivedAt`.
+ * Workers never initiate. A peer that times out is skipped this tick and never
+ * blocks another. Only usage rows, verdicts, and session digests move here —
+ * never a credential (invariant 7: roles never cross).
+ *
+ * This replaced a git exchange over the fleet-synced user repo: every daemon
+ * committed its own file each tick, so the shared store reached 1.1 GiB /
+ * 18,358 commits with 100% of the last 2,000 being `chore(devices): publish
+ * <device> daemon state`, and a worker's clone fell 10k commits behind with
+ * `git fetch timed out` on every tick — a valid setup-token could not be
+ * scheduled because a repo was bloated. Git now carries human-authored
+ * resources only; `devices/<device>/daemon-state.json` is untracked.
  */
-import { isHeadedDeviceRole, listConfiguredDeviceRoles, selfConfiguredDeviceRole } from '../device-config.js';
-import { readFleetSharedDeviceStates, updateFleetSharedDeviceStateAsync, } from '../fleet-shared-state.js';
+import { isHeadedDeviceRole, selfConfiguredDeviceRole } from '../device-config.js';
+import { FLEET_SHARED_STATE_VERSION, parseFleetSharedDeviceStateEnvelope, readFleetSharedDeviceStates, readOwnFleetSharedDeviceState, storePeerFleetSharedDeviceState, updateFleetSharedDeviceStateAsync, } from '../fleet-shared-state.js';
 import { getUserAgentsDir } from '../state.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
 import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, } from './usage.js';
-/** Cadence of the usage-sync git tick — the trust window for a `sync` snapshot. */
+/** Cadence of the usage-sync tick — the trust window for a `sync` snapshot. */
 export const USAGE_SYNC_INTERVAL_MS = 15 * 60_000;
 /** Re-publish an unchanged windowed row at least this often so workers' 15-min trust does not lapse. */
 export const USAGE_PUBLISH_HEARTBEAT_MS = 10 * 60_000;
+/** Per-peer SSH budget for one exchange; a peer past it is skipped this tick. */
+export const USAGE_EXCHANGE_PEER_TIMEOUT_MS = 20_000;
+/** Marks the start of the JSON reply on the peer's stdout, so login-shell noise before it is ignored. */
+export const FLEET_STATE_REPLY_MARKER = '@@AGENTS_FLEET_STATE@@';
 function usageMeterSignature(row) {
     return JSON.stringify({
         windows: row.windows,
@@ -28,7 +45,7 @@ function usageMeterSignature(row) {
 /**
  * Keep the previously published `capturedAt` when meters have not moved and
  * the last publish is still inside the heartbeat. Stops statusline re-renders
- * from dirtying the shared store (and taking the git lock) every few seconds.
+ * from rewriting the own-state file every few seconds.
  */
 export function mergeUsageRowsForPublish(previous, next, nowMs = Date.now()) {
     if (!previous)
@@ -47,7 +64,7 @@ export function mergeUsageRowsForPublish(previous, next, nowMs = Date.now()) {
     }
     return out;
 }
-/** Publish this headed device's stable usage snapshot into its owned store file. */
+/** Publish this headed device's stable usage snapshot into its own state file. */
 export async function publishUsageSnapshotToSharedStore(options = {}) {
     const result = {
         published: false,
@@ -84,68 +101,212 @@ export async function publishUsageSnapshotToSharedStore(options = {}) {
     return result;
 }
 /**
- * Publish a changed snapshot immediately and exchange the shared repo so
- * workers see it without waiting for the 15-minute tick. No-ops when the
- * serialized store is unchanged (statusline re-renders with the same windows).
+ * Refresh every field this device owns in its own state file: the usage
+ * snapshot (headed only), the session digests, and the reserved-auth readiness
+ * verdict. Run before the envelope is sent (the headed tick) or printed back
+ * (`__usage-ingest --reply`) so a peer always receives current fields. Each
+ * publisher is independent: one failing is reported in `errors` and the others
+ * still land. All three writers are the async, non-blocking variants
+ * (`updateFleetSharedDeviceStateAsync` underneath).
  */
-export async function pushUsageSnapshotNow(options = {}) {
-    const published = await publishUsageSnapshotToSharedStore(options);
-    if (!published.changed)
-        return { published };
-    const { syncFleetSharedStateRepo } = await import('../fleet-shared-repo-sync.js');
-    const transport = await syncFleetSharedStateRepo({
-        userAgentsDir: options.userAgentsDir,
-        device: options.device,
-        timeoutMs: options.timeoutMs,
-        lockPath: options.lockPath,
-    });
-    return { published, transport };
+export async function publishOwnFleetState(options = {}) {
+    const errors = [];
+    const usage = await publishUsageSnapshotToSharedStore(options);
+    if (usage.error)
+        errors.push(`usage: ${usage.error}`);
+    let mirror = { changed: false, count: 0, error: null };
+    try {
+        const { publishSessionMirrorToSharedStore } = await import('../session/mirror.js');
+        const published = await publishSessionMirrorToSharedStore({ userAgentsDir: options.userAgentsDir, device: options.device });
+        mirror = { changed: published.changed, count: published.count, error: published.error };
+    }
+    catch (err) {
+        mirror = { changed: false, count: 0, error: err.message };
+    }
+    if (mirror.error)
+        errors.push(`sessions: ${mirror.error}`);
+    let auth = { status: 'unknown', error: null };
+    try {
+        const { publishReservedAuthVerdict } = await import('../secrets-policy.js');
+        const verdict = await publishReservedAuthVerdict({ userAgentsDir: options.userAgentsDir, localName: options.device });
+        auth = { status: verdict.status, error: verdict.error };
+    }
+    catch (err) {
+        auth = { status: 'unknown', error: err.message };
+    }
+    if (auth.error)
+        errors.push(`auth: ${auth.error}`);
+    return { usage, mirror, auth, errors };
+}
+/** This device's exchange envelope, from its own state file (or usage-only from the cache). */
+export function buildFleetStatePayload(options = {}) {
+    const device = options.device ?? machineId();
+    if (options.usageOnly) {
+        const state = { version: FLEET_SHARED_STATE_VERSION, device };
+        if (isHeadedDeviceRole(options.role ?? selfConfiguredDeviceRole())) {
+            const rows = exportClaudeUsageCacheRows(options.cachePath);
+            if (Object.keys(rows).length > 0)
+                state.usage = { rows };
+        }
+        return { v: 2, state };
+    }
+    const state = readOwnFleetSharedDeviceState(device, options.userAgentsDir);
+    return { v: 2, state, ...(options.errors?.length ? { errors: options.errors } : {}) };
 }
-function capturedAtMs(row) {
-    if (!row.capturedAt)
-        return null;
-    const ms = Date.parse(row.capturedAt);
-    return Number.isFinite(ms) ? ms : null;
+/** Serialize the reply as the peer prints it: marker line, then one JSON line. */
+export function formatFleetStateReply(payload) {
+    return `${FLEET_STATE_REPLY_MARKER}\n${JSON.stringify(payload)}\n`;
 }
 /**
- * Read headed publishers from the local user-repo checkout and merge one
- * newest-wins batch into the worker cache. No network or subprocess is touched.
+ * Parse what a peer sent — a v2 exchange envelope, or the legacy v1 bare-rows
+ * envelope from an older headed peer. Throws a clear message on anything else;
+ * the caller decides whether that is exit code 2 (the receiver) or a per-peer
+ * error (the headed tick).
  */
-export function consumeUsageSnapshotsFromSharedStore(options = {}) {
-    const result = { sources: [], merged: 0, skipped: null, errors: [] };
-    if ((options.role ?? selfConfiguredDeviceRole()) !== 'worker') {
-        result.skipped = 'this device is not a worker';
-        return result;
+export function parseFleetStateExchangeInput(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
     }
-    const read = readFleetSharedDeviceStates(options.userAgentsDir ?? getUserAgentsDir());
-    result.errors.push(...read.errors);
-    const self = normalizeHost(options.device ?? machineId());
-    const roles = options.roles ?? listConfiguredDeviceRoles(read.states.map((state) => state.device));
-    const rows = {};
-    for (const state of read.states) {
-        if (normalizeHost(state.device) === self || !isHeadedDeviceRole(roles[state.device]) || !state.usage)
+    catch {
+        throw new Error('malformed JSON payload');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('unrecognized usage-sync payload shape');
+    }
+    const record = parsed;
+    if (record.v === 2) {
+        const state = parseFleetSharedDeviceStateEnvelope(record.state);
+        const errors = Array.isArray(record.errors) ? record.errors.filter((e) => typeof e === 'string') : undefined;
+        return { v: 2, state, ...(errors?.length ? { errors } : {}) };
+    }
+    if (record.v === 1) {
+        const rows = record.rows;
+        // `typeof [] === 'object'` — an array is NOT a rows map.
+        if (typeof rows !== 'object' || rows === null || Array.isArray(rows)) {
+            throw new Error('unrecognized usage-sync payload shape');
+        }
+        return { v: 1, rows: rows };
+    }
+    throw new Error('unrecognized usage-sync payload shape');
+}
+/** Extract the reply envelope from a peer's stdout (text before the marker is login-shell noise). */
+export function parseFleetStateReply(stdout) {
+    const idx = stdout.lastIndexOf(FLEET_STATE_REPLY_MARKER);
+    if (idx === -1) {
+        throw new Error(stdout.trim()
+            ? 'no reply envelope on stdout (peer agents-cli predates `__usage-ingest --reply`?)'
+            : 'empty reply (peer agents-cli predates `__usage-ingest --reply`?)');
+    }
+    const body = stdout.slice(idx + FLEET_STATE_REPLY_MARKER.length).trim();
+    const payload = parseFleetStateExchangeInput(body);
+    if (payload.v !== 2)
+        throw new Error('reply is not a v2 exchange envelope');
+    return payload;
+}
+/**
+ * Rows as the receiver stores them: provenance `sync` (so the trust window is
+ * `USAGE_SYNC_TRUST_MS`, not the local-capture bar) and the poller pinned to the
+ * device that actually read the endpoint, defaulting to the sender.
+ */
+function stampSyncRows(rows, sender) {
+    const out = {};
+    for (const [identity, incoming] of Object.entries(rows)) {
+        if (!incoming || !Array.isArray(incoming.windows) || incoming.windows.length === 0)
             continue;
-        result.sources.push(state.device);
-        for (const [identity, incoming] of Object.entries(state.usage.rows)) {
-            if (!incoming || !Array.isArray(incoming.windows) || incoming.windows.length === 0)
-                continue;
-            const stamped = {
-                ...incoming,
-                freshnessSource: 'sync',
-                pollerDevice: incoming.pollerDevice ?? state.device,
-            };
-            const current = rows[identity];
-            if (!current) {
-                rows[identity] = stamped;
-                continue;
+        out[identity] = { ...incoming, freshnessSource: 'sync', pollerDevice: incoming.pollerDevice ?? sender };
+    }
+    return out;
+}
+/**
+ * Take a peer's envelope in: store it as that peer's file (stamped `receivedAt`)
+ * and merge its usage rows into this box's cache newest-wins. The same step runs
+ * on both ends — the worker on the pushed envelope, the headed box on the reply.
+ * Both writes take their file lock asynchronously: this runs on the daemon tick
+ * once per peer, and a `sleepSync` lock there freezes every other service.
+ */
+export async function applyPeerFleetState(state, options = {}) {
+    const self = normalizeHost(options.device ?? machineId());
+    if (normalizeHost(state.device) === self) {
+        throw new Error(`peer envelope names this device (${state.device}); refusing to overwrite the own state file`);
+    }
+    const receivedAt = options.receivedAt ?? Date.now();
+    const write = await storePeerFleetSharedDeviceState(state, options.userAgentsDir ?? getUserAgentsDir(), receivedAt);
+    const merged = state.usage
+        ? await ingestPeerClaudeUsageRows(stampSyncRows(state.usage.rows, state.device), options.cachePath)
+        : 0;
+    return { path: write.path, merged, receivedAt };
+}
+/** The remote command one exchange runs on a peer, in the peer's shell dialect. */
+export async function buildFleetStateExchangeCommand(os) {
+    const { buildRemoteAgentsInvocation, buildWindowsStdinAgentsCommand, remoteShellFor } = await import('../hosts/remote-cmd.js');
+    // The Windows `agents.ps1` shim does not forward ssh-piped stdin, so the
+    // payload goes through a temp file and `--from <path>` there.
+    return remoteShellFor(os) === 'powershell'
+        ? buildWindowsStdinAgentsCommand(['__usage-ingest', '--reply'])
+        : buildRemoteAgentsInvocation(['__usage-ingest', '--reply'], undefined, os);
+}
+async function sshDial(timeoutMs) {
+    const { sshExecAsync } = await import('../ssh-exec.js');
+    const { sshTargetFor, deviceIdentityArgs } = await import('../devices/connect.js');
+    return (peer, remoteCmd, input) => sshExecAsync(sshTargetFor(peer), remoteCmd, {
+        input,
+        timeoutMs,
+        extraSshArgs: deviceIdentityArgs(peer),
+    });
+}
+async function defaultPeers(self) {
+    const { isDialableDevice, loadDevicesSync } = await import('../devices/registry.js');
+    return Object.values(loadDevicesSync())
+        .filter((d) => normalizeHost(d.name) !== self && isDialableDevice(d))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * The headed publisher's fan-out: dial every peer in parallel, each under its
+ * own timeout, and apply each reply as it arrives. Never throws for a peer — a
+ * timeout, an old CLI with no `--reply`, or a reply naming the wrong device is
+ * that peer's `error` and the others are unaffected. A non-headed device skips:
+ * workers never initiate (they only answer), so a worker's tick is a no-op here.
+ */
+export async function exchangeFleetStateWithPeers(options = {}) {
+    const device = options.device ?? machineId();
+    const self = normalizeHost(device);
+    const peers = options.peers ?? await defaultPeers(self);
+    if (peers.length === 0)
+        return { skipped: 'no dialable peer in the device registry', outcomes: [] };
+    const timeoutMs = options.timeoutMs ?? USAGE_EXCHANGE_PEER_TIMEOUT_MS;
+    const dial = options.dial ?? await sshDial(timeoutMs);
+    const payload = options.payload ?? buildFleetStatePayload({ device, userAgentsDir: options.userAgentsDir });
+    const input = JSON.stringify(payload);
+    const outcomes = await Promise.all(peers.map(async (peer) => {
+        const outcome = { device: peer.name, delivered: false, receivedAt: null, merged: 0, error: null, peerErrors: [] };
+        try {
+            const remoteCmd = await buildFleetStateExchangeCommand(peer.shell === 'powershell' ? 'windows' : undefined);
+            const res = await dial(peer, remoteCmd, input);
+            if (res.timedOut)
+                throw new Error(`timed out after ${Math.round(timeoutMs / 1000)}s`);
+            if (res.code !== 0) {
+                const detail = res.stderr.trim().split('\n').pop() ?? '';
+                throw new Error(`exited ${res.code ?? 'without a status'}${detail ? `: ${detail}` : ''}`);
+            }
+            const reply = parseFleetStateReply(res.stdout);
+            if (normalizeHost(reply.state.device) !== normalizeHost(peer.name)) {
+                throw new Error(`reply names device '${reply.state.device}', expected '${peer.name}'`);
             }
-            const incomingMs = capturedAtMs(stamped);
-            const currentMs = capturedAtMs(current);
-            if (incomingMs !== null && (currentMs === null || incomingMs > currentMs))
-                rows[identity] = stamped;
+            const applied = await applyPeerFleetState(reply.state, {
+                device,
+                userAgentsDir: options.userAgentsDir,
+                cachePath: options.cachePath,
+            });
+            outcome.delivered = true;
+            outcome.receivedAt = applied.receivedAt;
+            outcome.merged = applied.merged;
+            outcome.peerErrors = reply.errors ?? [];
         }
-    }
-    result.sources.sort();
-    result.merged = ingestPeerClaudeUsageRows(rows, options.cachePath);
-    return result;
+        catch (err) {
+            outcome.error = err.message;
+        }
+        return outcome;
+    }));
+    return { skipped: null, outcomes };
 }

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

@@ -494,6 +494,17 @@ export interface FormatUsageSummaryOpts {
 export declare function viewUsageSummaryOptions(agentId: AgentId, signedIn: boolean, usageInfo: UsageInfo | undefined, maxWindows: number | undefined, version?: string): FormatUsageSummaryOpts;
 /** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number, opts?: FormatUsageSummaryOpts): string;
+/**
+ * The snapshot's windows that are still LIVE — reset time not yet passed. A
+ * window past its `resetsAt` has rolled over: its `usedPercent` is a reading of
+ * the PREVIOUS period, not a live throttle (PHNX-4116). Both the throttle
+ * verdict ({@link deriveUsageStatusFromSnapshot}) and the displayed
+ * `usedPercent` (`devices/harness-inventory.ts`) MUST select from this SAME set,
+ * or a maxed-then-reset account reads `available` yet shows a stale 99% next to
+ * its "ready" verdict (#3705). Callers still narrow further (dropping
+ * `sonnet_week`, the model sub-limit); this is only the reset-rollover cut.
+ */
+export declare function liveUsageWindows(snapshot: UsageSnapshot, now?: number): UsageWindow[];
 /**
  * Derive an account's real throttle state from its live usage windows — the
  * single signal both the `agents view` badge and run-rotation eligibility share
@@ -513,7 +524,7 @@ export declare function formatUsageSummary(plan: string | null, snapshot: UsageS
  * The model-specific `sonnet_week` sub-limit is excluded: hitting it throttles
  * one model, not the account, so it shouldn't flip the whole row to throttled.
  */
-export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot | null | undefined): 'available' | 'rate_limited' | null;
+export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot | null | undefined, now?: number): 'available' | 'rate_limited' | null;
 /** A prior sample of one window's utilization, for burn-rate projection. */
 interface UsagePriorSample {
     /** Epoch ms the prior snapshot was captured. */
@@ -768,7 +779,9 @@ export declare function exportClaudeUsageCacheRows(cachePath?: string): Record<s
  * 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.
+ * Locked + atomic like every other cache writer, but through the ASYNC lock: it
+ * runs on the daemon's usage-sync tick once per peer reply (PHNX-4116), where
+ * the sync lock's `sleepSync` would freeze every other service under contention.
  *
  * 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
@@ -778,7 +791,7 @@ export declare function exportClaudeUsageCacheRows(cachePath?: string): Record<s
  * 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;
+export declare function ingestPeerClaudeUsageRows(rows: Record<string, CachedUsageSnapshot>, cachePath?: string): Promise<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