@usagefleet/cli 1.2.79 → 1.2.80

package/README.md

@@ -63,11 +63,11 @@ shell once. `uninstall` removes both again, and self-update keeps them current.
   is at-least-once — the server dedups on `uuid`.
 - **Your real limit %** — the collector uses the Claude login already on the
   machine (subscription OAuth from `claude`: macOS login Keychain, elsewhere
-  `<config dir>/.credentials.json`; falling back to `ANTHROPIC_API_KEY`), sends a
-  1-token ping to the Messages API, and reads Anthropic's
-  `anthropic-ratelimit-unified-5h/7d-utilization` headers. Credentials never
-  leave the machine — only the percentages do. `usagefleet status` shows which
-  login was found.
+  `<config dir>/.credentials.json`; falling back to `ANTHROPIC_API_KEY`) and
+  reads the same 5h/weekly percentages Claude's own `/usage` screen shows —
+  from the free OAuth usage endpoint for subscriptions, or a 1-token Messages
+  ping for API keys. Credentials never leave the machine — only the percentages
+  do. `usagefleet status` shows which login was found.
 
 Uploaded per record: token counts, model, session id, hostname, working
 directory, git branch. Prompts, responses and file contents are never read.
@@ -127,7 +127,7 @@ Env vars override the file:
 | `USAGEFLEET_DESKTOP` | override the Claude Desktop sessions dir; `off` to skip it |
 | `USAGEFLEET_PI` | override the pi sessions dirs, comma-separated; `off` to skip |
 | `USAGEFLEET_INTERVAL` | watch poll seconds (default 15) |
-| `USAGEFLEET_LIMITS_INTERVAL` | seconds between limit pings (default 300, so the 1-token ping isn't every cycle) |
+| `USAGEFLEET_LIMITS_INTERVAL` | seconds between limit reports (default 60; 300 on API keys, where each report costs a 1-token ping) |
 | `USAGEFLEET_NOTIFY` | desktop notifications, on by default |
 | `USAGEFLEET_NOTIFY_THRESHOLDS` | utilization % that trigger an alert (default `80,95`) |
 | `USAGEFLEET_BATCH` | records per upload (default 100, server caps at 1000) |

package/dist/claude-limits.js

@@ -47,12 +47,12 @@ export function parseLimitsHeaders(source, get, names = []) {
 }
 const OAUTH_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 /**
- * Per-model limits for subscription logins. The Messages ping only returns the
- * account-wide 5h/7d headers; the per-model caps Claude's own UI shows (e.g.
- * "Fable · 24% used") come from the OAuth usage endpoint Claude Code queries
- * for /usage. Undocumented — parse defensively and return [] on any surprise.
+ * The OAuth usage endpoint Claude Code queries for /usage — the source of both
+ * the per-model caps its UI shows ("Fable · 24% used") and the account-wide
+ * numbers we trust over the response headers. Undocumented — parse defensively
+ * and return null on any surprise.
  */
-async function fetchOauthModelLimits(token) {
+async function fetchOauthUsage(token) {
     const res = await fetch(OAUTH_USAGE_URL, {
         headers: {
             'anthropic-beta': 'oauth-2025-04-20',
@@ -62,26 +62,57 @@ async function fetchOauthModelLimits(token) {
         signal: AbortSignal.timeout(15_000),
     });
     if (!res.ok) {
-        return [];
+        return null;
     }
     const body = await res.json().catch(() => null);
     if (process.env.USAGEFLEET_DEBUG_HEADERS) {
         console.error(`[debug] oauth/usage: ${JSON.stringify(body)}`);
     }
-    return parseOauthUsage(body);
+    return body;
+}
+/**
+ * Account-wide 5h/7d numbers from an oauth/usage payload: percentages
+ * (`{utilization: 14}`), exactly what Claude's /usage screen shows.
+ *
+ * These beat the `-utilization` response headers, which now carry a 0–1
+ * fraction (`0.13` for 13% used). Missing fields stay null so the header
+ * values survive.
+ */
+export function parseOauthAccount(body) {
+    const root = (typeof body === 'object' && body !== null ? body : {});
+    const window = (key) => {
+        const raw = root[key];
+        const entry = (typeof raw === 'object' && raw !== null ? raw : {});
+        return {
+            pct: typeof entry.utilization === 'number' ? clampPct(entry.utilization) : null,
+            resetsAt: typeof entry.resets_at === 'string' ? parseReset(entry.resets_at) : null,
+        };
+    };
+    const five = window('five_hour');
+    const seven = window('seven_day');
+    return {
+        fiveHourPct: five.pct,
+        fiveHourResetsAt: five.resetsAt,
+        sevenDayPct: seven.pct,
+        sevenDayResetsAt: seven.resetsAt,
+    };
 }
 /** Both sources report 0–100 percentages: the `-utilization` headers ("37") and
  *  oauth/usage's `utilization`/`percent` fields. Clamping is all they need — a
  *  0–1 "fraction form" heuristic would read a real 1% as 100%, which reaches the
  *  headline number, the critical notification and guard's prompt block.
  *
+ *  One decimal is kept (not rounded to whole): the server multiplies the group
+ *  split by the group count, so integer quantization would amplify to whole
+ *  points on the dashboard.
+ *
  *  Non-finite in, null out: `Infinity` (a JSON `1e999`, or a junk header) would
  *  otherwise clamp to a perfectly plausible 100 and block every prompt. */
 function clampPct(n) {
     if (!Number.isFinite(n)) {
         return null;
     }
-    return Math.min(100, Math.max(0, Math.round(n)));
+    return Math.min(100, Math.max(0, Math.round(n * 10) / 10));
 }
 /** Normalize a scope's model name to a header-safe key ("Fable" → "fable"). */
 function modelKeyOf(name) {
@@ -153,12 +184,38 @@ export function parseOauthUsage(body) {
     }
     return out;
 }
+/** Assemble a full LimitsReport from an oauth/usage payload, or null when the
+ *  payload carries no account-wide percentage (endpoint down, shape changed) —
+ *  the caller then falls back to the header ping. */
+export function oauthLimitsReport(body) {
+    const account = parseOauthAccount(body);
+    if (account.fiveHourPct == null && account.sevenDayPct == null) {
+        return null;
+    }
+    return { ...account, modelLimits: parseOauthUsage(body), source: 'sub' };
+}
 /**
- * Read the account's real rate-limit utilization. Sends a 1-token ping to the
- * Messages API; Anthropic returns the unified 5h/7d utilization in response
- * headers (same approach as Claude-Usage-Tracker's OAuth path).
+ * Read the account's real rate-limit utilization.
+ *
+ * Subscription logins ask the free OAuth usage endpoint first — it returns the
+ * exact numbers Claude's own /usage screen shows (account-wide AND per-model)
+ * and costs no tokens, so it can be polled often. Only when it yields nothing
+ * (or for API keys, which can't call it) does this fall back to a 1-token ping
+ * to the Messages API, whose response headers carry the unified utilization
+ * (same approach as Claude-Usage-Tracker's OAuth path).
  */
 export async function fetchLimits(creds) {
+    if (creds.source === 'sub') {
+        try {
+            const report = oauthLimitsReport(await fetchOauthUsage(creds.token));
+            if (report) {
+                return report;
+            }
+        }
+        catch {
+            /* fall through to the header ping */
+        }
+    }
     const headers = {
         'anthropic-version': '2023-06-01',
         'content-type': 'application/json',
@@ -204,16 +261,5 @@ export async function fetchLimits(creds) {
     if (!res.ok && !gotHeaders) {
         throw new Error(`limits unavailable: HTTP ${res.status} with no rate-limit headers`);
     }
-    // Subscription logins: merge in the per-model caps from the OAuth usage
-    // endpoint (the ping headers never include them). Best-effort — keep the
-    // header-derived report on any failure.
-    if (creds.source === 'sub' && report.modelLimits.length === 0) {
-        try {
-            report.modelLimits = await fetchOauthModelLimits(creds.token);
-        }
-        catch {
-            /* endpoint unavailable — report account-wide limits only */
-        }
-    }
     return report;
 }

package/dist/index.js

@@ -70,11 +70,14 @@ async function cmdWatch() {
     const cfg = loadConfig();
     const raw = Number(flag('interval') ?? process.env.USAGEFLEET_INTERVAL ?? 15);
     const interval = Math.max(1, Number.isFinite(raw) && raw > 0 ? raw : 15) * 1000;
-    // The limits ping hits the real Messages API (1 billable token) — don't run it
-    // every usage-scan tick. Report at most once per USAGEFLEET_LIMITS_INTERVAL
-    // seconds (default 300), decoupled from the much faster usage poll.
-    const rawLimits = Number(process.env.USAGEFLEET_LIMITS_INTERVAL ?? 300);
-    const limitsInterval = Math.max(interval / 1000, Number.isFinite(rawLimits) && rawLimits > 0 ? rawLimits : 300) * 1000;
+    // Limits reporting is decoupled from the much faster usage poll. Default
+    // interval depends on how the reading is fetched: subscription logins use the
+    // free oauth/usage endpoint (60s keeps the dashboard split fresh at zero token
+    // cost), API keys pay a 1-token Messages ping per reading (300s). An explicit
+    // USAGEFLEET_LIMITS_INTERVAL overrides both.
+    const rawLimits = Number(process.env.USAGEFLEET_LIMITS_INTERVAL);
+    const explicitLimits = Number.isFinite(rawLimits) && rawLimits > 0 ? rawLimits * 1000 : null;
+    let limitsInterval = explicitLimits ?? 60_000;
     let lastLimitsAt = 0;
     // Self-update: once at startup, then every USAGEFLEET_UPDATE_INTERVAL seconds
     // (default 6h — a release lands on a device the same day, not the next).
@@ -112,6 +115,9 @@ async function cmdWatch() {
                 if (limits) {
                     line(note, limitsSummary(limits));
                 }
+                if (explicitLimits === null) {
+                    limitsInterval = limits?.source === 'api' ? 300_000 : 60_000;
+                }
             }
         }
         catch (error) {
@@ -248,7 +254,7 @@ function cmdConfig() {
         ['USAGEFLEET_DESKTOP', 'override the Claude Desktop dir ("off" disables)'],
         ['USAGEFLEET_PI', 'override pi session dirs, comma-separated'],
         ['USAGEFLEET_INTERVAL', 'watch interval seconds (default 15)'],
-        ['USAGEFLEET_LIMITS_INTERVAL', 'seconds between limits pings (default 300)'],
+        ['USAGEFLEET_LIMITS_INTERVAL', 'seconds between limits reports (default 60; 300 on API keys)'],
         ['USAGEFLEET_BATCH', 'records per upload (default 100, max 1000)'],
         ['USAGEFLEET_NOTIFY', 'desktop notifications (0 disables)'],
         ['USAGEFLEET_NOTIFY_THRESHOLDS', 'comma list of % alerts (default 80,95)'],

package/dist/notifier.js

@@ -88,13 +88,16 @@ export function maybeNotify(report, cfg = loadNotifyConfig(), log = () => {
         const state = readStore(path).notify;
         const five = evaluateWindow(state.fiveHour, report.fiveHourPct, report.fiveHourResetsAt, cfg.thresholds);
         const seven = evaluateWindow(state.sevenDay, report.sevenDayPct, report.sevenDayResetsAt, cfg.thresholds);
+        // Readings can carry a decimal; notification copy rounds to whole.
+        const fivePct = Math.round(report.fiveHourPct ?? 0);
+        const sevenPct = Math.round(report.sevenDayPct ?? 0);
         if (five.fire != null) {
-            sendNotification('Claude usage · 5-hour limit', `${report.fiveHourPct}% of your 5-hour limit used${resetSuffix(report.fiveHourResetsAt)}.`, { urgency: urgencyFor(five.fire) });
-            log('ok', `notified · 5h at ${report.fiveHourPct}% · crossed ${five.fire}%`);
+            sendNotification('Claude usage · 5-hour limit', `${fivePct}% of your 5-hour limit used${resetSuffix(report.fiveHourResetsAt)}.`, { urgency: urgencyFor(five.fire) });
+            log('ok', `notified · 5h at ${fivePct}% · crossed ${five.fire}%`);
         }
         if (seven.fire != null) {
-            sendNotification('Claude usage · weekly limit', `${report.sevenDayPct}% of your weekly limit used${resetSuffix(report.sevenDayResetsAt)}.`, { urgency: urgencyFor(seven.fire) });
-            log('ok', `notified · weekly at ${report.sevenDayPct}% · crossed ${seven.fire}%`);
+            sendNotification('Claude usage · weekly limit', `${sevenPct}% of your weekly limit used${resetSuffix(report.sevenDayResetsAt)}.`, { urgency: urgencyFor(seven.fire) });
+            log('ok', `notified · weekly at ${sevenPct}% · crossed ${seven.fire}%`);
         }
         updateStore(path, store => {
             store.notify = { fiveHour: five.next, sevenDay: seven.next };

package/dist/parser.js

@@ -9,15 +9,15 @@ function validTimestamp(v) {
     }
     return new Date().toISOString();
 }
+/** Cache-write tokens, with the per-TTL breakdown when the log carries it.
+ *  5m and 1h writes are priced differently (1.25× vs 2× input), so the server
+ *  wants the split — null means "the log predates the breakdown", not zero. */
 function cacheCreation(u) {
-    if (typeof u.cache_creation_input_tokens === 'number') {
-        return u.cache_creation_input_tokens;
-    }
     const c = u.cache_creation;
-    if (c) {
-        return (c.ephemeral_5m_input_tokens ?? 0) + (c.ephemeral_1h_input_tokens ?? 0);
-    }
-    return 0;
+    const five = typeof c?.ephemeral_5m_input_tokens === 'number' ? c.ephemeral_5m_input_tokens : null;
+    const oneHour = typeof c?.ephemeral_1h_input_tokens === 'number' ? c.ephemeral_1h_input_tokens : null;
+    const total = typeof u.cache_creation_input_tokens === 'number' ? u.cache_creation_input_tokens : (five ?? 0) + (oneHour ?? 0);
+    return { five, oneHour, total };
 }
 /** pi agent session line: `{type:"message", id, timestamp, message:{role:"assistant",
  *  provider, model, responseId, usage:{input, output, cacheRead, cacheWrite}}}`.
@@ -47,6 +47,10 @@ function parsePiLine(o, sessionCwd) {
         return null;
     }
     return {
+        // pi's usage line does not say which TTL the cache write used — leave the
+        // breakdown unknown so the server prices it by the user's TTL setting.
+        cacheCreation1h: null,
+        cacheCreation5m: null,
         cacheCreationTokens: u.cacheWrite ?? 0,
         cacheReadTokens: u.cacheRead ?? 0,
         cwd: sessionCwd,
@@ -109,8 +113,11 @@ export function parseLine(line, source = 'cli', sessionCwd = null) {
         return null;
     }
     const u = message.usage;
+    const cache = cacheCreation(u);
     return {
-        cacheCreationTokens: cacheCreation(u),
+        cacheCreation1h: cache.oneHour,
+        cacheCreation5m: cache.five,
+        cacheCreationTokens: cache.total,
         cacheReadTokens: u.cache_read_input_tokens ?? 0,
         cwd: str(o.cwd),
         gitBranch: str(o.gitBranch),

package/dist/release.js

@@ -1,2 +1,2 @@
 // Generated by .github/workflows/release.yml.
-export const RELEASE_VERSION = "1.2.79";
+export const RELEASE_VERSION = "1.2.80";

package/dist/service.js

@@ -309,27 +309,36 @@ ${envXml}
         catch {
             /* not loaded yet — fine */
         }
+        let loaded = false;
         try {
             execFileSync('launchctl', ['bootstrap', domain, path], {
                 stdio: 'inherit',
             });
+            loaded = true;
         }
         catch {
             try {
                 execFileSync('launchctl', ['load', path], { stdio: 'inherit' });
+                loaded = true;
             }
             catch {
                 /* report below; user can load manually */
             }
         }
-        // Force a (re)start so an update takes effect immediately, not on next respawn.
-        try {
-            execFileSync('launchctl', ['kickstart', '-k', `${domain}/${LABEL}`], {
-                stdio: 'ignore',
-            });
-        }
-        catch {
-            /* best-effort */
+        // Only when the (re)load failed — i.e. the old job is still resident, so this
+        // is the one thing that can swap it. On a job launchd just started via
+        // RunAtLoad, `kickstart -k` kills that instance and the respawn waits out
+        // ThrottleInterval: a guaranteed 30s hole where `status` right after an
+        // update reads "stopped".
+        if (!loaded) {
+            try {
+                execFileSync('launchctl', ['kickstart', '-k', `${domain}/${LABEL}`], {
+                    stdio: 'ignore',
+                });
+            }
+            catch {
+                /* best-effort */
+            }
         }
         console.log(step('service', 'launchd · starts at login'));
         console.log(row('logs', tilde(macLogDir())));

package/dist/ui.js

@@ -86,9 +86,10 @@ export function line(glyph, text) {
 }
 /** Neutral stream glyph, for messages that are neither good nor bad news. */
 export const note = dim('·');
-/** Percentage as a fixed-width string, so successive log lines line up. */
+/** Percentage as a fixed-width string, so successive log lines line up.
+ *  Readings can carry a decimal; display rounds to whole. */
 export function pct(value) {
-    return `${value ?? '?'}%`.padStart(4);
+    return `${value === null ? '?' : Math.round(value)}%`.padStart(4);
 }
 /** Usage bar, coloured by how close the window is to its limit.
  *  Unknown usage renders as an empty bar rather than a missing column. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@usagefleet/cli",
-	"version": "1.2.79",
+	"version": "1.2.80",
 	"description": "Tails Claude Code, Claude Desktop, and pi agent JSONL logs and reports token usage to a UsageFleet server.",
 	"keywords": [
 		"claude",