@phnx-labs/agents-cli 1.22.109 → 1.22.111

package/dist/lib/usage-refresh.d.ts

@@ -1,5 +1,6 @@
 import { type UsageHeadroom, type UsageSnapshot, type UsageInfo } from './accounting/usage.js';
 import type { AgentId } from './types.js';
+import { type ConfiguredDeviceRole } from './device-config.js';
 /**
  * Default schedule between successful (or attempted) live usage fetches for one
  * account. Floor and ceiling of the delay helper are pinned to this so the
@@ -146,6 +147,48 @@ export declare function providerLastCall(accounts: LocalUsageAccount[], cache: R
  * gate that binds it.
  */
 export declare function providerSpacingTokens(lastCallMs: number, now: number): number;
+/** One account considered for the headed poller. */
+export interface UsagePollCandidate {
+    usageKey: string;
+    agentId: AgentId;
+    home: string;
+    holdsNativeLogin: boolean;
+}
+/**
+/** Daemon auth-health may hit `/oauth/usage` only on a headed box, unless forceLive. */
+export declare function mayIssueUsageEndpointProbe(opts: {
+    role: ConfiguredDeviceRole | undefined;
+    forceLive?: boolean;
+}): boolean;
+/**
+ * Sticky one-poller election: lex-least among this box (if it holds a native
+ * login) and peer devices that published a `freshnessSource=poll` row. Statusline
+ * ingest does not claim. Two headed boxes therefore converge on one poller
+ * instead of each deferring to the other.
+ */
+export declare function electUsagePoller(opts: {
+    selfDevice: string;
+    selfHoldsNativeLogin: boolean;
+    peerPollers?: string[];
+}): string | null;
+export declare function shouldPollUsageAccount(candidate: Pick<UsagePollCandidate, 'usageKey' | 'holdsNativeLogin'>, opts: {
+    role: ConfiguredDeviceRole | undefined;
+    selfDevice: string;
+    peerPollers?: string[];
+    /** @deprecated use peerPollers; kept so older tests that pass claimedBy still compile */
+    claimedBy?: Record<string, string>;
+}): boolean;
+/** Native rotating login on this home — Claude's `.credentials.json` blob, else a credential file. */
+export declare function homeHoldsNativeLogin(agentId: AgentId, home: string): boolean;
+/** usageKey → devices that published a `poll` row (statusline/sync do not claim). */
+export declare function pollerClaimsFromSharedStore(selfDevice: string, userAgentsDir?: string): Record<string, string[]>;
+/**
+ * Spend one live usage-endpoint call from the shared per-account / per-provider
+ * budget. Auth-health and the usage poller both go through here so they cannot
+ * together exceed {@link PROVIDER_HOURLY_BUDGET} (~30/hr, well under ~100/hr).
+ * Returns false when the call must not fire.
+ */
+export declare function trySpendUsageApiCall(usageKey: string, agentId: AgentId, now: number): boolean;
 /** An account whose credentials live on the publisher host. */
 export interface LocalUsageAccount {
     usageKey: string;
@@ -178,15 +221,19 @@ export declare function orderUsageAccounts(accounts: LocalUsageAccount[], cache:
  * have no rate-limited endpoint to budget.
  */
 export declare function providerRecentCalls(accounts: LocalUsageAccount[], cache: Record<string, HeadroomEntry>, now: number): Map<AgentId, number>;
+export interface BuildLocalUsageAccountsOpts {
+    role?: ConfiguredDeviceRole;
+    device?: string;
+    userAgentsDir?: string;
+    holdsNativeLogin?: (agentId: AgentId, home: string) => boolean;
+    claimedBy?: Record<string, string[]>;
+}
 /**
- * Enumerate the usage accounts whose credentials live on THIS host — one
- * per unique usage key, deduped to the most-recently-active version (the same
- * canonicalization `getUsageInfoByIdentity` uses). Each carries a closure that
- * live-fetches its usage. This is the daemon's `listAccounts`; because it only
- * ever lists local, signed-in accounts, each host is the sole writer for its own
- * accounts' caches. `runUsageRefreshTick` calls this on every host.
+ * Enumerate the usage accounts THIS headed box should poll — native logins it
+ * holds, minus accounts another headed poller already claims. A worker or
+ * setup-token-only box returns [].
  */
-export declare function buildLocalUsageAccounts(): Promise<LocalUsageAccount[]>;
+export declare function buildLocalUsageAccounts(opts?: BuildLocalUsageAccountsOpts): Promise<LocalUsageAccount[]>;
 /** Injectable side effects, so `runUsageRefresh` is drivable without the daemon. */
 export interface UsageRefreshDeps {
     now?: number;
@@ -212,6 +259,10 @@ export interface UsageRefreshDeps {
     readCachedSnapshot?: (usageKey: string) => UsageSnapshot | null;
     /** Daemon tick deadline signal, forwarded to each account's provider fetch (PHNX-3608). */
     signal?: AbortSignal;
+    /** Stamp D8 provenance on a successful poll write. */
+    pollerDevice?: string;
+    /** Fire after at least one snapshot was written (push-on-change). */
+    onSnapshotsChanged?: (usageKeys: string[]) => Promise<void> | void;
 }
 export interface UsageRefreshResult {
     refreshed: number;

package/dist/lib/usage-refresh.js

@@ -1,12 +1,13 @@
 /**
- * Daemon-owned usage refresher — runs on every host.
+ * Daemon-owned usage refresher — one poller per account, on a headed box.
  *
  * The routing hot path (`agents run` → collectRunCandidates) reads usage
  * CACHE-ONLY (`getUsageInfoForIdentity`, RUSH-2061) and never blocks
- * on a provider fetch. Something still has to keep that cache fresh — this
- * module is that something, running inside the daemon on every host
- * (RUSH-3193 #15: no primary/subscriber split — each host refreshes only
- * the accounts it holds credentials for).
+ * on a provider fetch. A headed box (`isHeadedDeviceRole`) polls only the
+ * accounts it holds native logins for; a setup-token-only box never polls.
+ * A stray `.credentials.json` for an account another headed box already
+ * publishes defers to that poller. Auth-health draws from the same
+ * per-account call budget so the two stay under the ~100/hr ceiling.
  *
  * Design:
  *
@@ -48,11 +49,15 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { getCacheDir } from './state.js';
+import { getCacheDir, getUserAgentsDir } from './state.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
-import { deriveUsageHeadroom, buildCanonicalUsageContext, agentUsesNetworkUsage, USAGE_SOURCE_AGENT_IDS, } from './accounting/usage.js';
-import { getAccountInfo } from './agents.js';
+import { deriveUsageHeadroom, buildCanonicalUsageContext, agentUsesNetworkUsage, USAGE_SOURCE_AGENT_IDS, claudeHomeHasNativeOauthFile, } from './accounting/usage.js';
+import { getAccountInfo, credentialPresence } from './agents.js';
 import { listInstalledVersions, getVersionHomePath } from './installations/versions.js';
+import { isHeadedDeviceRole, selfConfiguredDeviceRole } from './device-config.js';
+import { machineId, normalizeHost } from './session/sync/config.js';
+import { readFleetSharedDeviceStates } from './fleet-shared-state.js';
+import { USAGE_SYNC_INTERVAL_MS } from './accounting/usage-sync.js';
 /**
  * Default schedule between successful (or attempted) live usage fetches for one
  * account. Floor and ceiling of the delay helper are pinned to this so the
@@ -319,6 +324,112 @@ function failedHeadroomEntry(prev, now) {
     }
     return next;
 }
+/**
+/** Daemon auth-health may hit `/oauth/usage` only on a headed box, unless forceLive. */
+export function mayIssueUsageEndpointProbe(opts) {
+    if (opts.forceLive === true)
+        return true;
+    return isHeadedDeviceRole(opts.role);
+}
+/**
+ * Sticky one-poller election: lex-least among this box (if it holds a native
+ * login) and peer devices that published a `freshnessSource=poll` row. Statusline
+ * ingest does not claim. Two headed boxes therefore converge on one poller
+ * instead of each deferring to the other.
+ */
+export function electUsagePoller(opts) {
+    const names = new Set();
+    if (opts.selfHoldsNativeLogin)
+        names.add(normalizeHost(opts.selfDevice));
+    for (const peer of opts.peerPollers ?? [])
+        names.add(normalizeHost(peer));
+    if (names.size === 0)
+        return null;
+    return [...names].sort()[0];
+}
+export function shouldPollUsageAccount(candidate, opts) {
+    if (!isHeadedDeviceRole(opts.role))
+        return false;
+    if (!candidate.holdsNativeLogin)
+        return false;
+    const peerPollers = opts.peerPollers
+        ?? (opts.claimedBy?.[candidate.usageKey] ? [opts.claimedBy[candidate.usageKey]] : []);
+    const elected = electUsagePoller({
+        selfDevice: opts.selfDevice,
+        selfHoldsNativeLogin: true,
+        peerPollers,
+    });
+    return elected === normalizeHost(opts.selfDevice);
+}
+/** Native rotating login on this home — Claude's `.credentials.json` blob, else a credential file. */
+export function homeHoldsNativeLogin(agentId, home) {
+    if (agentId === 'claude')
+        return claudeHomeHasNativeOauthFile(home);
+    return credentialPresence(agentId, home).perVersion;
+}
+/** usageKey → devices that published a `poll` row (statusline/sync do not claim). */
+export function pollerClaimsFromSharedStore(selfDevice, userAgentsDir = getUserAgentsDir()) {
+    const claims = {};
+    const read = readFleetSharedDeviceStates(userAgentsDir);
+    const self = normalizeHost(selfDevice);
+    for (const state of read.states) {
+        if (!state.usage)
+            continue;
+        for (const [key, row] of Object.entries(state.usage.rows)) {
+            if (row.freshnessSource !== 'poll')
+                continue;
+            const capturedMs = row.capturedAt ? Date.parse(row.capturedAt) : NaN;
+            if (!Number.isFinite(capturedMs) || Date.now() - capturedMs > USAGE_SYNC_INTERVAL_MS)
+                continue;
+            const poller = normalizeHost(row.pollerDevice ?? state.device);
+            if (!poller || poller === self)
+                continue;
+            const list = claims[key] ?? [];
+            if (!list.includes(poller))
+                list.push(poller);
+            claims[key] = list;
+        }
+    }
+    return claims;
+}
+/**
+ * Spend one live usage-endpoint call from the shared per-account / per-provider
+ * budget. Auth-health and the usage poller both go through here so they cannot
+ * together exceed {@link PROVIDER_HOURLY_BUDGET} (~30/hr, well under ~100/hr).
+ * Returns false when the call must not fire.
+ */
+export function trySpendUsageApiCall(usageKey, agentId, now) {
+    if (!agentUsesNetworkUsage(agentId))
+        return true;
+    const cache = readHeadroomCache();
+    const entry = cache[usageKey];
+    const recent = pruneCallTimestamps(entry?.callTimestamps ?? [], now);
+    if (recent.length >= HOURLY_CALL_CAP)
+        return false;
+    let providerSpent = recent.length;
+    for (const [key, other] of Object.entries(cache)) {
+        if (key === usageKey)
+            continue;
+        if (!key.startsWith(`${agentId}:`))
+            continue;
+        providerSpent += pruneCallTimestamps(other.callTimestamps ?? [], now).length;
+    }
+    if (providerSpent >= PROVIDER_HOURLY_BUDGET)
+        return false;
+    writeHeadroomEntries({
+        [usageKey]: {
+            status: entry?.status ?? null,
+            minutesToLimit: entry?.minutesToLimit ?? null,
+            sessionUsedPercent: entry?.sessionUsedPercent ?? null,
+            capturedAt: entry?.capturedAt ?? null,
+            nextRefreshAt: entry?.nextRefreshAt ?? now,
+            callTimestamps: [...recent, now],
+            computedAt: now,
+            consecutiveFailures: entry?.consecutiveFailures ?? 0,
+        },
+    });
+    return true;
+}
 /**
  * Order a pass STALEST-FIRST so a scarce per-provider budget
  * ({@link PROVIDER_HOURLY_BUDGET}) is always spent on the accounts most in need
@@ -362,14 +473,17 @@ export function providerRecentCalls(accounts, cache, now) {
     return counts;
 }
 /**
- * Enumerate the usage accounts whose credentials live on THIS host — one
- * per unique usage key, deduped to the most-recently-active version (the same
- * canonicalization `getUsageInfoByIdentity` uses). Each carries a closure that
- * live-fetches its usage. This is the daemon's `listAccounts`; because it only
- * ever lists local, signed-in accounts, each host is the sole writer for its own
- * accounts' caches. `runUsageRefreshTick` calls this on every host.
+ * Enumerate the usage accounts THIS headed box should poll — native logins it
+ * holds, minus accounts another headed poller already claims. A worker or
+ * setup-token-only box returns [].
  */
-export async function buildLocalUsageAccounts() {
+export async function buildLocalUsageAccounts(opts = {}) {
+    const role = opts.role ?? selfConfiguredDeviceRole();
+    if (!isHeadedDeviceRole(role))
+        return [];
+    const selfDevice = opts.device ?? machineId();
+    const claimedBy = opts.claimedBy ?? pollerClaimsFromSharedStore(selfDevice, opts.userAgentsDir);
+    const nativeAt = opts.holdsNativeLogin ?? homeHoldsNativeLogin;
     const accounts = [];
     for (const agentId of USAGE_SOURCE_AGENT_IDS) {
         const versions = listInstalledVersions(agentId);
@@ -384,14 +498,15 @@ export async function buildLocalUsageAccounts() {
             const canonical = canonicalByUsageKey.get(usageKey);
             if (!canonical?.signedIn)
                 continue; // only refresh accounts actually usable here
+            const home = fetchInput.home ?? getVersionHomePath(agentId, fetchInput.cliVersion ?? '');
+            if (!shouldPollUsageAccount({ usageKey, holdsNativeLogin: nativeAt(agentId, home) }, { role, selfDevice, peerPollers: claimedBy[usageKey] }))
+                continue;
             accounts.push({
                 usageKey,
                 agentId,
-                // fileOnly: never open the ACL-bound keychain item from the daemon —
-                // that path is the Touch ID storm. Usage reads the file-based setup-token
-                // only, never the interactive login (see loadClaudeOauth); no setup-token
-                // reads as "usage unavailable (no usage credential)" — "usage pending"
-                // is now the cold-cache state only (#2987).
+                // Native file login: skip setup-token (403s on /oauth/usage) and the
+                // ACL keychain (Touch ID). Linux headed boxes store the rotating blob
+                // in `.credentials.json`; a missing file is a no-op fetch.
                 fetch: async (signal) => {
                     const { getUsageInfoForIdentity } = await import('./accounting/usage.js');
                     return getUsageInfoForIdentity({
@@ -399,7 +514,7 @@ export async function buildLocalUsageAccounts() {
                         home: fetchInput.home,
                         cliVersion: fetchInput.cliVersion,
                         info: canonical,
-                    }, { forceRefresh: true, fileOnly: true, signal });
+                    }, { forceRefresh: true, fileOnly: true, nativeFileLogin: true, signal });
                 },
             });
         }
@@ -441,6 +556,7 @@ export async function runUsageRefresh(deps) {
         spacingTokens.set(agent, providerSpacingTokens(last, now));
     const spacingUsed = new Map();
     const updates = {};
+    const refreshedKeys = [];
     for (const [index, account] of accounts.entries()) {
         const entry = cache[account.usageKey] ?? null;
         const network = agentUsesNetworkUsage(account.agentId);
@@ -492,9 +608,13 @@ export async function runUsageRefresh(deps) {
                 // `source` is provenance, not freshness. A forced collection that just
                 // reread a local harness event returns `last_seen`; that is still a
                 // successful collection and belongs in the shared read cache.
-                deps.writeUsageCache(account.usageKey, usage.snapshot);
-                updates[account.usageKey] = nextHeadroomEntry(entry, usage.snapshot, now);
+                const stamped = deps.pollerDevice
+                    ? { ...usage.snapshot, freshness: { source: 'poll', poller: deps.pollerDevice } }
+                    : usage.snapshot;
+                deps.writeUsageCache(account.usageKey, stamped);
+                updates[account.usageKey] = nextHeadroomEntry(entry, stamped, now);
                 result.refreshed += 1;
+                refreshedKeys.push(account.usageKey);
             }
             else {
                 // No live snapshot (expired token / fetch miss): don't rewrite the usage
@@ -511,5 +631,7 @@ export async function runUsageRefresh(deps) {
     }
     if (Object.keys(updates).length > 0)
         writeHeadroomEntries(updates);
+    if (refreshedKeys.length > 0)
+        await deps.onSnapshotsChanged?.(refreshedKeys);
     return result;
 }

package/dist/lib/watchdog/runner.d.ts

@@ -142,6 +142,9 @@ export interface SessionOutcome {
     project?: string | null;
     label?: string;
     name?: string;
+    /** The daemon-generated headline (PHNX-3797); carried so the report renders the
+     * same name every other surface shows, not the raw first prompt. */
+    generatedTitle?: string;
     topic?: string;
     preview?: string;
     activity?: ActiveSession['activity'];

package/dist/lib/watchdog/runner.js

@@ -444,6 +444,7 @@ export async function runWatchdogTick(opts = {}) {
             project: session.project,
             label: session.label,
             name: session.name,
+            generatedTitle: session.generatedTitle,
             topic: session.topic,
             preview: session.preview,
             activity: session.activity,

package/dist/session-tracker/dist/install-hook.js

@@ -17,11 +17,11 @@ function hookCommand(agent, opts) {
     const hook = opts.hookPathOverride ?? HOOK_PATH;
     return `${hook} ${agent}`;
 }
-/** True when a stored command string is a prior registration of this package's
- *  `hook.sh` (src or dist). Used for idempotency when stripping old entries. */
+/** Recognize current registrations and the retired builtin sidecar writer. */
 function isOwnHookCommand(command) {
     const first = command.trim().split(/\s+/)[0];
-    return first.endsWith('hook.sh') && first.includes('session-tracker');
+    return (first.endsWith('hook.sh') && first.includes('session-tracker'))
+        || first.endsWith('/.agents/.cache/shims/builtin-hooks/session-tracker.sh');
 }
 async function readJson(p) {
     try {
@@ -131,7 +131,7 @@ async function installDroid(opts) {
     for (const entry of cfg.hooks.SessionStart) {
         if (!entry || !Array.isArray(entry.hooks))
             continue;
-        entry.hooks = entry.hooks.filter((hook) => !(hook?.command && String(hook.command).includes('packages/session-tracker/src/hook.sh')));
+        entry.hooks = entry.hooks.filter((hook) => !(hook?.command && isOwnHookCommand(String(hook.command))));
     }
     let group = cfg.hooks.SessionStart.find((entry) => entry?.matcher === '');
     if (!group) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.109",
+  "version": "1.22.111",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",