@phnx-labs/agents-cli 1.22.109 → 1.22.111

package/dist/commands/sessions.js

@@ -37,6 +37,7 @@ import { inferSessionState } from '../lib/session/state.js';
 import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
 import { findSessionsById, querySessions, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
 import { liveSessionMetas, fleetExecutionMachineById, reconcileLiveMetaMachine } from '../lib/session/live-metadata.js';
+import { sessionHeadline } from '../lib/session/title.js';
 import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
@@ -351,6 +352,7 @@ export function buildSessionDescription(s) {
         return cleanPreview(parts.filter(Boolean).join(' · '));
     }
     // Terminal, headless, or sub-agent: todos + live preview, then label, then topic.
+    // ladder-exempt: the compact --active preview BASE (a live snippet), not the row's headline title.
     const base = s.preview || s.label || s.topic || '';
     return cleanPreview([todo, base].filter(Boolean).join(' · '));
 }
@@ -759,22 +761,39 @@ export function renderActiveRowLines(s, indent, termW) {
     // Line 2: label/topic + checklist (the identity, no longer buried) then the
     // jump locator. Skipped entirely when there is nothing to say. desc may carry a
     // clickable project link, so it also goes through fitCell.
+    const contIndent = indent + ' '.repeat(ROW_ID_W);
     const desc = formatActiveRowDescription(s);
     const loc = locatorBadge(s);
-    if (!desc && !loc)
-        return lines;
-    const contIndent = indent + ' '.repeat(ROW_ID_W);
-    const room2 = Math.max(0, termW - stringWidth(contIndent) - 2);
-    const locCell = fitCell(loc, room2);
-    const locW = stringWidth(locCell);
-    const descRoom = Math.max(0, room2 - (locW ? locW + 2 : 0));
-    const descCell = chalk.white(fitCell(desc || '-', descRoom));
-    let line2 = contIndent + chalk.dim('└ ') + descCell;
-    if (locCell)
-        line2 += '  ' + locCell;
-    if (stringWidth(line2) > termW)
-        line2 = truncateToWidth(line2, termW);
-    lines.push(line2);
+    if (desc || loc) {
+        const room2 = Math.max(0, termW - stringWidth(contIndent) - 2);
+        const locCell = fitCell(loc, room2);
+        const locW = stringWidth(locCell);
+        const descRoom = Math.max(0, room2 - (locW ? locW + 2 : 0));
+        const descCell = chalk.white(fitCell(desc || '-', descRoom));
+        let line2 = contIndent + chalk.dim('└ ') + descCell;
+        if (locCell)
+            line2 += '  ' + locCell;
+        if (stringWidth(line2) > termW)
+            line2 = truncateToWidth(line2, termW);
+        lines.push(line2);
+    }
+    // Secondary line (PHNX-3797 owner feedback): surface the most important recent
+    // agent message when it is a pending QUESTION or a NEEDS-YOU block — the urgency
+    // a rolling activity preview buries. Plain `activity` is already the preview on
+    // line 2, so it earns no extra line here; the full ranked message still rides
+    // the JSON/mirror feed for AGI EXT via `s.importantMessage`.
+    const important = s.importantMessage;
+    if (important && (important.kind === 'question' || important.kind === 'needs_you')) {
+        const glyph = important.kind === 'question' ? '? ' : '! ';
+        const room3 = Math.max(0, termW - stringWidth(contIndent) - 2 - glyph.length);
+        const msgCell = fitCell(cleanPreview(important.text), room3);
+        if (msgCell) {
+            let line3 = contIndent + chalk.dim(glyph + msgCell);
+            if (stringWidth(line3) > termW)
+                line3 = truncateToWidth(line3, termW);
+            lines.push(line3);
+        }
+    }
     return lines;
 }
 /** Render a single agent-session row inside an already-printed group header. */
@@ -2200,7 +2219,7 @@ export function printToolSearch(envelope) {
             ? truncate(sanitizeForTerminal(session.machine).replace(/\s+/g, ' '), 80)
             : '';
         const machine = machineName ? ` @ ${machineName}` : '';
-        const rawHeading = session.label || session.topic || session.project || session.shortId;
+        const rawHeading = sessionHeadline(session) || session.project || session.shortId;
         const heading = truncate(sanitizeForTerminal(rawHeading).replace(/\s+/g, ' '), Math.max(30, terminalWidth() - 20));
         console.log(`${chalk.cyan(session.shortId)}${chalk.gray(machine)}  ${heading}`);
         for (const call of session.calls) {
@@ -3374,7 +3393,7 @@ function printTeamsView(pool, liveIndex, hiddenUnmanaged = 0) {
     // degradation the --active teams rows use (active.ts resolveOrchestratorLabels).
     const labelById = new Map();
     for (const s of pool) {
-        const label = s.label || s.topic;
+        const label = sessionHeadline(s);
         if (label)
             labelById.set(s.id, cleanPreview(label));
     }
@@ -3504,7 +3523,7 @@ function renderArchivedSession(session, mode, options = {}) {
     const shown = sessionDisplayAgent(session);
     const agentColor = colorAgent(shown);
     const absTime = formatAbsoluteTime(session.timestamp);
-    const title = session.label || session.topic;
+    const title = sessionHeadline(session);
     console.log('');
     if (title)
         console.log(chalk.bold.white(title));
@@ -3562,9 +3581,10 @@ async function renderSession(session, mode, filters, options = {}) {
         const modelStr = stats.models.length > 0 ? chalk.yellow(`  ${stats.models.join(', ')}`) : '';
         const branchStr = session.gitBranch ? chalk.gray(` (${session.gitBranch})`) : '';
         const absTime = formatAbsoluteTime(session.timestamp);
-        // Auto-inferred title headline (user /rename > Claude ai-title > first-prompt
-        // topic) — the fastest way to recognize which task this session is.
-        const title = session.label || session.topic;
+        // Auto-inferred title headline (user /rename > Claude ai-title >
+        // daemon-generated title > first-prompt topic) — the fastest way to
+        // recognize which task this session is.
+        const title = sessionHeadline(session);
         if (title) {
             const badges = signalBadges(metaSignals(session));
             console.log(chalk.bold.white(title) + (badges ? '  ' + badges : ''));
@@ -4456,7 +4476,7 @@ async function renderArtifactsGlobal(query, listAll, name, scope) {
             spinner.stop();
             console.error(chalk.red(`Multiple sessions match "${query}":`));
             for (const m of queryMatches.slice(0, 10)) {
-                console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${m.label ?? m.topic ?? ''}`));
+                console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${sessionHeadline(m) ?? ''}`));
             }
             console.error(chalk.gray(ambiguityHint(byId, completeId)));
             process.exit(1);
@@ -4613,7 +4633,7 @@ async function renderOneSession(query, mode, scope) {
                 spinner.stop();
                 console.error(chalk.red(`Multiple sessions match "${query}":`));
                 for (const match of queryMatches.slice(0, 10)) {
-                    console.error(chalk.cyan(`  ${match.shortId}  ${match.id}  ${match.label ?? match.topic ?? ''}`));
+                    console.error(chalk.cyan(`  ${match.shortId}  ${match.id}  ${sessionHeadline(match) ?? ''}`));
                 }
                 console.error(chalk.gray(ambiguityHint(byId, completeId)));
                 process.exit(1);
@@ -5067,7 +5087,7 @@ export async function resolveSessionMetadata(selector, scope, deps = { gatherRem
         for (const candidate of outcome.candidates) {
             const session = candidate.hits[0].session;
             const machines = candidate.hits.map(hit => hit.machine).join(', ');
-            console.error(chalk.cyan(`  ${session.shortId}  ${session.id}`) + chalk.gray(`  ${machines}  ${session.label ?? session.topic ?? ''}`));
+            console.error(chalk.cyan(`  ${session.shortId}  ${session.id}`) + chalk.gray(`  ${machines}  ${sessionHeadline(session) ?? ''}`));
         }
         console.error(chalk.gray(looksLikeSessionId(selector) ? 'Pass a longer ID to narrow it down.' : 'Narrow the keywords to one session.'));
         process.exit(1);
@@ -5107,7 +5127,7 @@ export async function resolveSessionAcrossFleet(query, mode, hosts, deps = { gat
         console.error(chalk.red(`Multiple sessions match "${query}" across the fleet:`));
         for (const candidate of candidates) {
             const s = candidate.hits[0].session;
-            const label = s.label ?? s.topic ?? '';
+            const label = sessionHeadline(s) ?? '';
             const machines = candidate.hits.map(hit => hit.machine).join(', ');
             console.error(chalk.cyan(`  ${s.shortId}  ${s.id}`) + chalk.gray(`  ${machines}  ${s.agent}${s.version ? ` ${s.version}` : ''}  ${label}`));
         }

package/dist/commands/utils.d.ts

@@ -45,6 +45,15 @@ export interface Surface {
  * to a single `const s = resolveSurface(cmd)` without changing its flag surface.
  */
 export declare function resolveSurface(cmd: Command): Surface;
+/**
+ * Coerce a `--device` value that may arrive as a scalar or an array to a single
+ * host string. A subcommand whose own `--device` collides in name with an
+ * ancestor's variadic `-D, --device <target...>` (e.g. `sessions inject`,
+ * `sessions resume` under the parent `sessions` command) can receive an array
+ * even when the command only ever targets one device — fail loud on more than
+ * one rather than guessing the first (PHNX-3688, PHNX-3940).
+ */
+export declare function normalizeSingleDeviceOption(value: string | string[] | undefined, commandLabel: string): string | undefined;
 /**
  * Exit with a clean message when a picker would be required in a non-interactive shell.
  */

package/dist/commands/utils.js

@@ -59,6 +59,24 @@ export function resolveSurface(cmd) {
         interactive: tty && !json,
     };
 }
+/**
+ * Coerce a `--device` value that may arrive as a scalar or an array to a single
+ * host string. A subcommand whose own `--device` collides in name with an
+ * ancestor's variadic `-D, --device <target...>` (e.g. `sessions inject`,
+ * `sessions resume` under the parent `sessions` command) can receive an array
+ * even when the command only ever targets one device — fail loud on more than
+ * one rather than guessing the first (PHNX-3688, PHNX-3940).
+ */
+export function normalizeSingleDeviceOption(value, commandLabel) {
+    const list = value == null ? [] : Array.isArray(value) ? value : [value];
+    const hosts = list.map((v) => String(v).trim()).filter((v) => v.length > 0);
+    if (hosts.length === 0)
+        return undefined;
+    if (hosts.length > 1) {
+        throw new Error(`${commandLabel} targets a single device, but --device named ${hosts.length}: ${hosts.join(', ')}.`);
+    }
+    return hosts[0];
+}
 /**
  * Exit with a clean message when a picker would be required in a non-interactive shell.
  */

package/dist/commands/watchdog.js

@@ -27,6 +27,7 @@ import { isWatchdogRotateEnabled, listRotateStates, setWatchdogRotateEnabled } f
 import { loadWatchdogSessions, runWatchdogPass } from '../lib/watchdog/service.js';
 import { readWatchdogEvents, WATCHDOG_LOG_PATH } from '../lib/watchdog/log.js';
 import { selectWatchdogHistory } from '../lib/watchdog/history.js';
+import { sessionHeadline } from '../lib/session/title.js';
 /** Default state dir the runner and these subcommands share. */
 function stateDir() {
     return path.join(getRuntimeStateDir(), 'watchdog');
@@ -99,7 +100,9 @@ export function formatWatchdogTickLines(result, willInject, verbose = false) {
                     : o.decision === 'nudge' ? 'WOULD-NUDGE'
                         : 'skip';
         const id = o.sessionId?.slice(0, 8) ?? 'no-session-id';
-        const title = o.label || o.name || o.topic;
+        // `name` is the `agents run --name` launch handle — a user-given name, so it
+        // ranks with the label; everything below it is the shared headline ladder.
+        const title = o.label || o.name || sessionHeadline(o);
         lines.push(`  ${tag.padEnd(11)} ${id}${title ? ` · ${title}` : ''}`);
         const metadata = [
             o.kind,

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

@@ -178,6 +178,14 @@ export declare function isVersionLaunchableHere(agent: AgentId, version: string)
  * launched into it while the account was actually at its weekly cap.
  */
 export declare const USAGE_DECISION_MAX_AGE_MS: number;
+/**
+ * How old a *synced* snapshot (arrived from the account's poller through the
+ * fleet store) may be and still settle a routing decision. Matches the
+ * usage-sync tick so a worker that only ever sees 15-minute-old rows does not
+ * drop to the account picker. Local captures (`poll` / `statusline`) keep
+ * {@link USAGE_DECISION_MAX_AGE_MS}.
+ */
+export declare const USAGE_SYNC_TRUST_MS: number;
 /**
  * How old a usage snapshot may be before routing REFUSES to run at all
  * (NO_VERIFIED_USAGE), as opposed to merely declining to *weight* by its number.
@@ -212,6 +220,7 @@ export declare const USAGE_STALE_REFUSAL_MAX_AGE_MS: number;
  * running it refreshes that log. That self-reinforcing pin is exactly what the
  * narrowing rule below exists to prevent.
  */
+export declare function usageVerifiedMaxAgeMs(snapshot: UsageSnapshot | null | undefined): number;
 export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
 /**
  * Whether this candidate carries a GENUINELY-STALE usage number: a snapshot with

package/dist/lib/accounting/rotate.js

@@ -140,6 +140,14 @@ export async function isVersionLaunchableHere(agent, version) {
  * launched into it while the account was actually at its weekly cap.
  */
 export const USAGE_DECISION_MAX_AGE_MS = 5 * 60 * 1000;
+/**
+ * How old a *synced* snapshot (arrived from the account's poller through the
+ * fleet store) may be and still settle a routing decision. Matches the
+ * usage-sync tick so a worker that only ever sees 15-minute-old rows does not
+ * drop to the account picker. Local captures (`poll` / `statusline`) keep
+ * {@link USAGE_DECISION_MAX_AGE_MS}.
+ */
+export const USAGE_SYNC_TRUST_MS = 15 * 60 * 1000;
 /**
  * How old a usage snapshot may be before routing REFUSES to run at all
  * (NO_VERIFIED_USAGE), as opposed to merely declining to *weight* by its number.
@@ -174,12 +182,18 @@ export const USAGE_STALE_REFUSAL_MAX_AGE_MS = 40 * 60 * 1000;
  * running it refreshes that log. That self-reinforcing pin is exactly what the
  * narrowing rule below exists to prevent.
  */
+export function usageVerifiedMaxAgeMs(snapshot) {
+    // D8: a row that arrived via sync from the account's own poller is trusted
+    // for the sync cadence. A locally captured row (poll / statusline / unset)
+    // keeps the 5-minute bar — the poller is on this box and can refresh it.
+    return snapshot?.freshness?.source === 'sync' ? USAGE_SYNC_TRUST_MS : USAGE_DECISION_MAX_AGE_MS;
+}
 export function isUsageVerified(candidate, nowMs = Date.now()) {
     const snapshot = candidate.usageSnapshot;
     const capturedAt = snapshot?.capturedAt;
     if (!capturedAt || !snapshot?.windows.length)
         return false;
-    return nowMs - capturedAt.getTime() <= USAGE_DECISION_MAX_AGE_MS;
+    return nowMs - capturedAt.getTime() <= usageVerifiedMaxAgeMs(snapshot);
 }
 /**
  * Whether this candidate carries a GENUINELY-STALE usage number: a snapshot with
@@ -996,6 +1010,8 @@ function describeRotationCandidate(c, nowMs) {
         tier,
         source: snap?.source ?? null,
         sourceLabel: snap?.sourceLabel ?? null,
+        captureSource: snap?.freshness?.source ?? null,
+        pollerDevice: snap?.freshness?.poller ?? null,
         capturedAt: snap?.capturedAt ? snap.capturedAt.toISOString() : null,
         ageMs: capturedAtMs === null ? null : nowMs - capturedAtMs,
         windows: (snap?.windows ?? []).map((w) => ({ key: w.key, usedPercent: Math.round(w.usedPercent) })),

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

@@ -9,6 +9,16 @@
  */
 import { type ConfiguredDeviceRole } from '../device-config.js';
 import { type CachedUsageSnapshot } from './usage.js';
+/** Cadence of the usage-sync git 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;
+/**
+ * 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.
+ */
+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. */
 export interface UsageSyncPayload {
     v: 1;
@@ -29,6 +39,18 @@ export interface PublishUsageSnapshotResult {
 }
 /** Publish this headed device's stable usage snapshot into its owned store file. */
 export declare function publishUsageSnapshotToSharedStore(options?: PublishUsageSnapshotOptions): Promise<PublishUsageSnapshotResult>;
+/**
+ * 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).
+ */
+export declare function pushUsageSnapshotNow(options?: PublishUsageSnapshotOptions & {
+    lockPath?: string;
+    timeoutMs?: number;
+}): Promise<{
+    published: PublishUsageSnapshotResult;
+    transport?: import('../fleet-shared-repo-sync.js').FleetSharedRepoSyncResult;
+}>;
 export interface ConsumeUsageSnapshotsOptions {
     userAgentsDir?: string;
     cachePath?: string;

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

@@ -12,6 +12,41 @@ import { readFleetSharedDeviceStates, updateFleetSharedDeviceStateAsync, } from
 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. */
+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;
+function usageMeterSignature(row) {
+    return JSON.stringify({
+        windows: row.windows,
+        plan: row.plan ?? null,
+        unavailable: row.unavailable ?? null,
+        freshnessSource: row.freshnessSource ?? null,
+        pollerDevice: row.pollerDevice ?? null,
+    });
+}
+/**
+ * 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.
+ */
+export function mergeUsageRowsForPublish(previous, next, nowMs = Date.now()) {
+    if (!previous)
+        return next;
+    const out = {};
+    for (const [key, row] of Object.entries(next)) {
+        const prior = previous[key];
+        if (prior && usageMeterSignature(prior) === usageMeterSignature(row)) {
+            const priorMs = prior.capturedAt ? Date.parse(prior.capturedAt) : NaN;
+            if (Number.isFinite(priorMs) && nowMs - priorMs < USAGE_PUBLISH_HEARTBEAT_MS) {
+                out[key] = { ...row, capturedAt: prior.capturedAt };
+                continue;
+            }
+        }
+        out[key] = row;
+    }
+    return out;
+}
 /** Publish this headed device's stable usage snapshot into its owned store file. */
 export async function publishUsageSnapshotToSharedStore(options = {}) {
     const result = {
@@ -26,13 +61,19 @@ export async function publishUsageSnapshotToSharedStore(options = {}) {
         result.skipped = 'this device is not a usage publisher (mark it personal or desktop)';
         return result;
     }
-    const rows = exportClaudeUsageCacheRows(options.cachePath);
-    if (Object.keys(rows).length === 0) {
+    const rawRows = exportClaudeUsageCacheRows(options.cachePath);
+    if (Object.keys(rawRows).length === 0) {
         result.skipped = 'no local usage snapshot to publish';
         return result;
     }
     try {
-        const write = await updateFleetSharedDeviceStateAsync(options.device ?? machineId(), { usage: { rows } }, options.userAgentsDir ?? getUserAgentsDir());
+        const device = options.device ?? machineId();
+        const userAgentsDir = options.userAgentsDir ?? getUserAgentsDir();
+        const prior = readFleetSharedDeviceStates(userAgentsDir).states
+            .find((state) => normalizeHost(state.device) === normalizeHost(device))
+            ?.usage?.rows;
+        const rows = mergeUsageRowsForPublish(prior, rawRows);
+        const write = await updateFleetSharedDeviceStateAsync(device, { usage: { rows } }, userAgentsDir);
         result.published = true;
         result.changed = write.changed;
         result.path = write.path;
@@ -42,6 +83,24 @@ 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).
+ */
+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 };
+}
 function capturedAtMs(row) {
     if (!row.capturedAt)
         return null;
@@ -70,15 +129,20 @@ export function consumeUsageSnapshotsFromSharedStore(options = {}) {
         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] = incoming;
+                rows[identity] = stamped;
                 continue;
             }
-            const incomingMs = capturedAtMs(incoming);
+            const incomingMs = capturedAtMs(stamped);
             const currentMs = capturedAtMs(current);
             if (incomingMs !== null && (currentMs === null || incomingMs > currentMs))
-                rows[identity] = incoming;
+                rows[identity] = stamped;
         }
     }
     result.sources.sort();

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

@@ -157,6 +157,12 @@ export declare function claudeAccessTokenNeedsRefresh(expiresAt: number | null |
 export declare function setClaudeUsageCachePathForTest(cachePath: string | null): string | null;
 /** Discriminator for usage window types. */
 export type UsageWindowKey = 'session' | 'week' | 'sonnet_week' | 'month';
+/**
+ * How this box obtained a usage row (delta-spec D8). Distinct from
+ * {@link UsageSnapshot.source} (`live` | `last_seen`), which is how the
+ * number was collected from the harness/API.
+ */
+export type UsageCaptureSource = 'poll' | 'statusline' | 'sync';
 /** A single rate-limit window with utilization percentage and reset time. */
 export interface UsageWindow {
     key: UsageWindowKey;
@@ -203,6 +209,16 @@ export interface UsageSnapshot {
         reason: 'session_limit' | 'out_of_credits';
         resetsAt?: Date;
     };
+    /**
+     * D8 freshness provenance. A `sync` row arrived from the account's poller
+     * through the fleet store and is trusted for the sync cadence; `poll` and
+     * `statusline` are local captures and keep the 5-minute decision bar.
+     */
+    freshness?: {
+        source: UsageCaptureSource;
+        /** Device that polled or ingested the authoritative reading. */
+        poller?: string;
+    };
 }
 /** Usage data plus any error encountered while fetching. */
 export interface UsageInfo {
@@ -257,6 +273,13 @@ interface UsageOptions {
      * an unattended loop never transmits the interactive login to Anthropic.
      */
     allowInteractiveLogin?: boolean;
+    /**
+     * Headed usage poller: skip the setup-token and the ACL keychain, and read
+     * only `<home>/.claude/.credentials.json` (the native rotating blob). A
+     * setup-token 403s on `/api/oauth/usage`; the keychain pops Touch ID. The
+     * file blob is the Linux headed native login, and a no-op when absent.
+     */
+    nativeFileLogin?: boolean;
 }
 /** Canonical input for a single usage fetch operation. */
 export interface UsageFetchInput {
@@ -317,6 +340,10 @@ export interface CachedUsageSnapshot {
      * usage bucket.
      */
     modelRefusals?: Record<string, CachedModelRefusal>;
+    /** D8: `poll` | `statusline` | `sync`. Survives export → ingest. */
+    freshnessSource?: UsageCaptureSource;
+    /** D8: device that polled or ingested the authoritative reading. */
+    pollerDevice?: string;
 }
 /** The single registry of agent usage sources and their transport. */
 declare const USAGE_SOURCES: {
@@ -406,6 +433,8 @@ export interface UsageLookupOptions {
      * `loadClaudeOauth`. Unset for every other lookup.
      */
     allowInteractiveLogin?: boolean;
+    /** Headed poller: native `.credentials.json` only, never the setup-token. */
+    nativeFileLogin?: boolean;
 }
 export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[], opts?: UsageLookupOptions): Promise<{
     canonicalByUsageKey: Map<string, AccountInfo>;
@@ -712,10 +741,13 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * `.credentials.json` only. Used by the daemon usage refresher so a background
  * tick can never pop Touch ID.
  */
+/** True when `<home>/.claude/.credentials.json` is a native rotating OAuth blob. */
+export declare function claudeHomeHasNativeOauthFile(home?: string): boolean;
 export declare function loadClaudeOauth(home?: string, opts?: {
     accessTokenCache?: boolean;
     fileOnly?: boolean;
     allowInteractiveLogin?: boolean;
+    nativeFileLogin?: boolean;
 }): Promise<ClaudeOauthCredentials | null>;
 /**
  * Save Claude OAuth credentials to the system keychain/keyring.

package/dist/lib/accounting/usage.js

@@ -431,6 +431,7 @@ export async function getUsageInfoForIdentity(input, opts) {
             organizationId: input.info.organizationId,
             fileOnly: opts?.fileOnly,
             allowInteractiveLogin: opts?.allowInteractiveLogin,
+            nativeFileLogin: opts?.nativeFileLogin,
             signal: opts?.signal,
         });
     }
@@ -469,6 +470,7 @@ export async function getUsageInfoForIdentity(input, opts) {
     // Explicit refresh: block on the shared device collector.
     return fetchLiveUsageDeduped(input, usageKey, cached, opts?.fileOnly === true, {
         allowInteractiveLogin: opts?.allowInteractiveLogin === true,
+        nativeFileLogin: opts?.nativeFileLogin === true,
         signal: opts?.signal,
     });
 }
@@ -501,6 +503,7 @@ async function fetchLiveUsageDeduped(input, usageKey, cached, fileOnly, opts) {
                 usageScope: usageKey,
                 fileOnly,
                 allowInteractiveLogin: opts?.allowInteractiveLogin === true,
+                nativeFileLogin: opts?.nativeFileLogin === true,
                 signal: opts?.signal,
             });
             if (usage.snapshot) {
@@ -935,9 +938,10 @@ async function getClaudeUsageInfo(options) {
         // requires (the setup-token is user:inference → 403, RUSH-2392). It is unset
         // for every background caller, so the RUSH-1822 guarantee is untouched there.
         const oauth = await loadClaudeOauth(options?.home, {
-            accessTokenCache: true,
-            fileOnly: options?.fileOnly === true,
+            accessTokenCache: options?.nativeFileLogin !== true,
+            fileOnly: options?.fileOnly === true || options?.nativeFileLogin === true,
             allowInteractiveLogin: options?.allowInteractiveLogin === true,
+            nativeFileLogin: options?.nativeFileLogin === true,
         });
         if (!oauth?.accessToken) {
             // NOT the shared no-credential message: "sign in" is not a remedy here.
@@ -1612,7 +1616,33 @@ function deleteCachedClaudeOauth(service) {
  * `.credentials.json` only. Used by the daemon usage refresher so a background
  * tick can never pop Touch ID.
  */
+/** True when `<home>/.claude/.credentials.json` is a native rotating OAuth blob. */
+export function claudeHomeHasNativeOauthFile(home) {
+    return readClaudeNativeCredentialsFile(home) !== null;
+}
+function readClaudeNativeCredentialsFile(home) {
+    const credsPath = path.join(home ?? os.homedir(), '.claude', '.credentials.json');
+    try {
+        if (!fs.existsSync(credsPath))
+            return null;
+        const parsed = parseClaudeOauthPayload(fs.readFileSync(credsPath, 'utf-8'));
+        // A native rotating blob has a refresh token. A setup-token-shaped file
+        // (access only) is not a native login and must not be polled as one.
+        if (!parsed?.accessToken?.trim() || !parsed.refreshToken?.trim())
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
 export async function loadClaudeOauth(home, opts) {
+    // Headed usage poller: the native rotating blob in `.credentials.json` is
+    // the only credential that carries `user:profile` without opening the ACL
+    // keychain (Touch ID) or firing a setup-token that 403s on /oauth/usage.
+    if (opts?.nativeFileLogin === true) {
+        return readClaudeNativeCredentialsFile(home);
+    }
     // Read-only usage/probe callers (accessTokenCache) authenticate ONLY with a
     // file-based setup-token from the `auth` bundle — never Claude Code's
     // interactive login. The usage endpoint accepts any sk-ant-oat01 bearer, and
@@ -1963,6 +1993,8 @@ function serializeClaudeUsageSnapshot(snapshot) {
             resetsAt: window.resetsAt?.toISOString() || null,
             windowMinutes: window.windowMinutes,
         })),
+        freshnessSource: snapshot.freshness?.source,
+        pollerDevice: snapshot.freshness?.poller,
     };
 }
 /**
@@ -2028,6 +2060,9 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         plan: snapshot.plan ?? null,
         refreshHint: snapshot.refreshHint ?? null,
         unavailable,
+        freshness: snapshot.freshnessSource
+            ? { source: snapshot.freshnessSource, poller: snapshot.pollerDevice }
+            : undefined,
     };
 }
 /**

package/dist/lib/auth-health.js

@@ -25,6 +25,8 @@ import { getCacheDir, readMeta } from './state.js';
 import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, readClaudeUsageCache, } from './accounting/usage.js';
 import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+import { selfConfiguredDeviceRole } from './device-config.js';
+import { mayIssueUsageEndpointProbe, trySpendUsageApiCall } from './usage-refresh.js';
 /** Maximum age of an auth verdict used for automatic routing decisions. */
 export const AUTH_PROBE_MAX_AGE_MS = 20 * 60_000;
 /** Agents with a live network probe wired up today. The rest are best-effort. */
@@ -455,6 +457,23 @@ export async function probeAuthHealth(agent, home, opts) {
             if (derived)
                 return derived;
         }
+        if (!mayIssueUsageEndpointProbe({
+            role: selfConfiguredDeviceRole(),
+            forceLive: opts?.forceLive,
+        })) {
+            return {
+                verdict: 'unverified',
+                checkedAt,
+                detail: 'setup-token box does not probe the usage endpoint',
+            };
+        }
+        if (opts?.forceLive !== true && usageScope && !trySpendUsageApiCall(usageScope, agent, checkedAt)) {
+            return {
+                verdict: 'unverified',
+                checkedAt,
+                detail: 'usage-endpoint budget already spent this hour',
+            };
+        }
         let probe;
         if (agent === 'claude')
             probe = await probeClaudeStatus(home, opts?.cliVersion, usageScope, opts?.signal);

package/dist/lib/claude-statusline.js

@@ -8,6 +8,7 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { mergeClaudeUsageCacheWindows } from './accounting/usage.js';
 import { loadReminders, pickReminderForSession } from './reminders.js';
 import { readMeta } from './state.js';
+import { machineId } from './machine-id.js';
 export const CLAUDE_STATUSLINE_COMMAND = 'agents __claude-statusline';
 const DELEGATE_FILE = path.join('.agents', 'claude-statusline-delegate');
 // The private subcommand this feature runs. It is only ever invoked internally,
@@ -77,7 +78,11 @@ export function ingestClaudeStatusLineUsage(payload, identity) {
         sourceLabel: 'Claude response rate limits',
         capturedAt: new Date(),
         windows,
+        freshness: { source: 'statusline', poller: machineId() },
     });
+    void import('./accounting/usage-sync.js')
+        .then((mod) => mod.pushUsageSnapshotNow())
+        .catch(() => { });
     return true;
 }
 /**