@phnx-labs/agents-cli 1.22.117 → 1.22.119

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

package/dist/lib/accounting/usage.js

@@ -24,7 +24,7 @@ import { resolveClaudeSetupToken } from '../claude-account-token.js';
 import { formatBackoffRemaining, noteUsageRateLimited, usageRateLimitedUntil, } from '../usage-backoff.js';
 import { getCacheDir } from '../state.js';
 import { mapBounded } from '../concurrency.js';
-import { atomicWriteFileSync, ensureLockTarget, withFileLock } from '../fs-atomic.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock, withFileLockAsync } from '../fs-atomic.js';
 import { withRefreshLease } from '../refresh-coordinator.js';
 import { padToWidth } from '../session/width.js';
 const execFileAsync = promisify(execFile);
@@ -723,6 +723,19 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
     }
     return parts.join('  ');
 }
+/**
+ * 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 function liveUsageWindows(snapshot, now = Date.now()) {
+    return snapshot.windows.filter((window) => !(window.resetsAt && window.resetsAt.getTime() <= now));
+}
 /**
  * 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
@@ -742,7 +755,7 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
  * 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 function deriveUsageStatusFromSnapshot(snapshot) {
+export function deriveUsageStatusFromSnapshot(snapshot, now = Date.now()) {
     if (!snapshot)
         return null;
     if (snapshot.unavailable) {
@@ -750,14 +763,17 @@ export function deriveUsageStatusFromSnapshot(snapshot) {
         // clears it. session_limit blocks only until its reset time.
         if (snapshot.unavailable.reason === 'out_of_credits')
             return 'rate_limited';
-        if (snapshot.unavailable.resetsAt && snapshot.unavailable.resetsAt.getTime() > Date.now()) {
+        if (snapshot.unavailable.resetsAt && snapshot.unavailable.resetsAt.getTime() > now) {
             return 'rate_limited';
         }
     }
     if (snapshot.windows.length === 0)
         return null;
-    const blocking = snapshot.windows.filter((window) => window.key !== 'sonnet_week');
-    const windows = blocking.length > 0 ? blocking : snapshot.windows;
+    const live = liveUsageWindows(snapshot, now);
+    if (live.length === 0)
+        return 'available';
+    const blocking = live.filter((window) => window.key !== 'sonnet_week');
+    const windows = blocking.length > 0 ? blocking : live;
     const maxUsed = Math.max(...windows.map((window) => window.usedPercent));
     return maxUsed >= 100 ? 'rate_limited' : 'available';
 }
@@ -1897,7 +1913,9 @@ function parseCapturedAtMs(capturedAt) {
  * 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
@@ -1907,14 +1925,14 @@ function parseCapturedAtMs(capturedAt) {
  * 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()) {
+export async 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, () => {
+        await withFileLockAsync(cachePath, () => {
             const cache = readClaudeUsageCacheFile(cachePath);
             for (const [key, row] of incoming) {
                 const prior = cache[key];

package/dist/lib/accounts/add.d.ts

@@ -128,6 +128,8 @@ export declare function runAdd(agent: AgentId, name: string | undefined, opts: A
  * Drive one `agents accounts login <harness>#<name>`: re-auth into the SAME
  * slot (re-running add's steps 4–8), re-minting the worker credential and
  * re-syncing. On a per-device harness (worker `none`) any box may run it —
- * that IS how such a box logs in.
+ * that IS how such a box logs in. `--per-device` extends that to a dual-path
+ * harness (codex, grok): this box signs the account's subscription seat in for
+ * itself through the device-code flow instead of using a portable key.
  */
 export declare function runLogin(agent: AgentId, name: string, opts: AddOptions, runners?: AddRunners): Promise<AddResult>;

package/dist/lib/accounts/add.js

@@ -73,6 +73,12 @@ export function workerApiKeyEnv(agent) {
 function hasPortableWorkerKind(agent) {
     return harnessWorkerKinds(agent).some((k) => k === 'setup-token' || k.startsWith('api-key:'));
 }
+function hasPerDeviceWorkerKind(agent) {
+    return harnessWorkerKinds(agent).some((k) => k.startsWith('per-device'));
+}
+function perDeviceRefusal(agent) {
+    return `--per-device is only valid for a harness with a per-device worker path; ${agent} is provisioned from ${workerProvisioningHint(agent)}.`;
+}
 /** Whether `accounts add` can drive this harness (nameable, version-scoped, a real login command). */
 export function addSupported(agent) {
     const cap = nativeAccountCapability(agent);
@@ -232,9 +238,8 @@ async function mintWorkerCredential(agent, account, home, opts, runners, warning
         return { outcome: 'skipped', provisioning: 'per-device' };
     }
     if (opts.perDevice) {
-        if (!kinds.some((k) => k.startsWith('per-device'))) {
-            throw new Error(`--per-device is only valid for a harness with a per-device worker path (codex); ${agent} is provisioned from ${workerProvisioningHint(agent)}.`);
-        }
+        if (!hasPerDeviceWorkerKind(agent))
+            throw new Error(perDeviceRefusal(agent));
         return { outcome: 'per-device', provisioning: 'per-device' };
     }
     const { seedReservedStoreKey, seedReservedAuthToken, workerCredentialStoreKey, } = await import('../auth-mint.js');
@@ -260,7 +265,7 @@ async function mintWorkerCredential(agent, account, home, opts, runners, warning
         let value = opts.apiKey?.trim();
         if (!value) {
             if (!runners.promptApiKey) {
-                throw new Error(`${agent}'s worker credential is an ${env} API key. Pass --api-key <key> (or --no-worker-token to skip, --per-device for a codex ChatGPT-plan account).`);
+                throw new Error(`${agent}'s worker credential is an ${env} API key. Pass --api-key <key> (or --no-worker-token to skip, or --per-device for a subscription seat when the harness has one).`);
             }
             const entered = await runners.promptApiKey(agent, env);
             if (entered === null) {
@@ -290,8 +295,8 @@ export async function runAdd(agent, name, opts, runners) {
     // before the lock, slot, install, or browser — no side effects on a worker.
     assertAddAllowedOnThisDevice(agent, name);
     const kinds = harnessWorkerKinds(agent);
-    if (opts.perDevice && !kinds.some((k) => k.startsWith('per-device'))) {
-        throw new Error(`--per-device is only valid for a harness with a per-device worker path (codex); ${agent} is provisioned from ${workerProvisioningHint(agent)}.`);
+    if (opts.perDevice && !hasPerDeviceWorkerKind(agent)) {
+        throw new Error(perDeviceRefusal(agent));
     }
     // The ambient-token refusal is checked up front (not at the mint step) so the
     // user doesn't complete a browser login only to be refused at the end.
@@ -410,13 +415,18 @@ async function _runAddLocked(agent, name, opts, lock, runners) {
  * Drive one `agents accounts login <harness>#<name>`: re-auth into the SAME
  * slot (re-running add's steps 4–8), re-minting the worker credential and
  * re-syncing. On a per-device harness (worker `none`) any box may run it —
- * that IS how such a box logs in.
+ * that IS how such a box logs in. `--per-device` extends that to a dual-path
+ * harness (codex, grok): this box signs the account's subscription seat in for
+ * itself through the device-code flow instead of using a portable key.
  */
 export async function runLogin(agent, name, opts, runners) {
     // A harness with a portable worker credential authenticates workers from that
     // credential, so the interactive re-login stays headed-only. A per-device
-    // harness (kimi) is logged in per box BY DESIGN — any role may run this.
-    if (hasPortableWorkerKind(agent))
+    // harness (kimi), or a per-device login of a dual-path harness, is logged in
+    // per box BY DESIGN — any role may run it.
+    if (opts.perDevice && !hasPerDeviceWorkerKind(agent))
+        throw new Error(perDeviceRefusal(agent));
+    if (hasPortableWorkerKind(agent) && !opts.perDevice)
         assertAddAllowedOnThisDevice(agent, name);
     if (!opts.noWorkerToken && harnessWorkerKinds(agent).includes('setup-token')) {
         const refusal = ambientTokenRefusal(agent, opts.env ?? process.env);
@@ -437,6 +447,7 @@ export async function runLogin(agent, name, opts, runners) {
 async function _runLoginLocked(agent, name, opts, lock, runners) {
     const run = runners ?? await defaultAddRunners();
     lock.assertHeld();
+    const perDevice = !!opts.perDevice || !hasPortableWorkerKind(agent);
     const meta = readMeta();
     const account = findAddAccount(agent, name, meta);
     if (!account) {
@@ -452,7 +463,7 @@ async function _runLoginLocked(agent, name, opts, lock, runners) {
         const slot = ensureSlot(agent, account.id);
         recordSlot(account.id, {
             ...slot,
-            authMode: hasPortableWorkerKind(agent) ? 'native' : 'per-device',
+            authMode: perDevice ? 'per-device' : 'native',
         });
     }
     // Pre-launch guard: refuse to launch a login into a slot signed in as a
@@ -481,8 +492,8 @@ async function _runLoginLocked(agent, name, opts, lock, runners) {
     const warnings = [];
     let outcome = 'per-device';
     let ref;
-    let provisioning = account.provisioning ?? (hasPortableWorkerKind(agent) ? 'portable' : 'per-device');
-    if (hasPortableWorkerKind(agent)) {
+    let provisioning = perDevice ? 'per-device' : (account.provisioning ?? 'portable');
+    if (!perDevice) {
         if (opts.apiKey && workerApiKeyEnv(agent)) {
             // Explicit rotation of the stored API key.
             const minted = await mintWorkerCredential(agent, account, home, opts, run, warnings);
@@ -520,7 +531,7 @@ async function _runLoginLocked(agent, name, opts, lock, runners) {
     recordSlot(account.id, {
         accountId: account.id,
         slotDir: home,
-        authMode: hasPortableWorkerKind(agent) ? 'native' : 'per-device',
+        authMode: perDevice ? 'per-device' : 'native',
         verdict: 'live',
         checkedAt: new Date().toISOString(),
     });

package/dist/lib/accounts/slots.d.ts

@@ -2,6 +2,14 @@ import type { AgentId, DeviceAccountSlot, Meta } from '../types.js';
 export type { DeviceAccountSlot };
 export declare function slotDir(harness: AgentId, accountId: string): string;
 export declare function readSlots(meta: Pick<Meta, 'deviceAccounts'>): Record<string, DeviceAccountSlot>;
+/**
+ * Remove slot records from THIS box's device doc (`deviceAccounts.slots`).
+ * Symmetric with {@link recordSlot}. The slot DIRECTORY is not touched — a
+ * caller that also wants the on-disk home gone removes it separately; a stale
+ * worker slot keeps its dir because `.claude/projects` holds transcripts
+ * (PHNX-4116). A no-op for an empty list or an id with no record.
+ */
+export declare function dropSlots(accountIds: readonly string[]): void;
 export declare function recordSlot(accountId: string, slot: DeviceAccountSlot): void;
 export interface SlotProjection {
     accountId: string;

package/dist/lib/accounts/slots.js

@@ -35,6 +35,23 @@ export function slotDir(harness, accountId) {
 export function readSlots(meta) {
     return { ...(meta.deviceAccounts?.slots ?? {}) };
 }
+/**
+ * Remove slot records from THIS box's device doc (`deviceAccounts.slots`).
+ * Symmetric with {@link recordSlot}. The slot DIRECTORY is not touched — a
+ * caller that also wants the on-disk home gone removes it separately; a stale
+ * worker slot keeps its dir because `.claude/projects` holds transcripts
+ * (PHNX-4116). A no-op for an empty list or an id with no record.
+ */
+export function dropSlots(accountIds) {
+    if (accountIds.length === 0)
+        return;
+    updateMeta((current) => {
+        const slots = { ...current.deviceAccounts?.slots };
+        for (const id of accountIds)
+            delete slots[id];
+        return { ...current, deviceAccounts: { ...current.deviceAccounts, slots } };
+    });
+}
 export function recordSlot(accountId, slot) {
     if (slot.accountId !== accountId) {
         throw new Error(`recordSlot accountId mismatch: key '${accountId}' vs slot.accountId '${slot.accountId}'.`);

package/dist/lib/add-dir.js

@@ -32,7 +32,6 @@ export const ADD_DIR_STRATEGY = {
     grok: 'grok-sandbox',
     // No multi-root CLI surface today (single --dir / project path).
     opencode: 'none',
-    gemini: 'none',
     openclaw: 'none',
     copilot: 'none',
     amp: 'none',

package/dist/lib/agent-cli-commands.js

@@ -11,7 +11,6 @@
 export const AGENT_CLI_COMMANDS = [
     'claude',
     'codex',
-    'gemini',
     'cursor-agent',
     'opencode',
     'openclaw',