@usagefleet/cli 1.2.172 → 1.2.173

package/README.md

@@ -97,15 +97,28 @@ directory, git branch. Prompts, responses and file contents are never read.
 
 ## Desktop notifications
 
-The first time a window crosses a threshold (default `80` and `95`) you get a
-desktop notification — once per threshold per window, re-armed when the window
-resets. macOS shows it from a small bundled UsageFleet app (allow it once when
+The first time a window crosses a threshold you get a desktop notification —
+once per threshold per window, re-armed when the window resets or usage falls
+5 points under the last alert. Which thresholds is the alert **mode**:
+
+| Mode | Alerts at (% of the window) |
+|------|-----------------------------|
+| `off` | never |
+| `quiet` | 95, 100 |
+| `standard` (default) | 80, 95 |
+| `steady` | 50, 60, 70, 80, 90, 95, 100 |
+| `critical` | 80, 90, 95, 96, 97, 98, 99, then every 0.1 (99.1, 99.2 … 99.9), 100 |
+
+Pick one per device on the **Devices** page, or pin it on the machine with
+`USAGEFLEET_NOTIFY_MODE=critical` / `"notifyMode": "critical"` in the config
+file (the local value wins over the Devices page). macOS shows it from a small bundled UsageFleet app (allow it once when
 macOS asks; a click opens the dashboard), Linux uses `notify-send` (falling back to
 `kdialog --passivepopup`; install `libnotify-bin` if neither exists), Windows a
 WinRT toast via `powershell.exe`.
 
-`usagefleet notify-test` confirms it works. Tune with
-`USAGEFLEET_NOTIFY_THRESHOLDS="50,80,95"`, disable with `USAGEFLEET_NOTIFY=0`.
+`usagefleet notify-test` confirms it works and prints the thresholds in effect.
+For a list of your own use `USAGEFLEET_NOTIFY_THRESHOLDS="50,80,99.5"` (it
+replaces the mode's list), disable everything with `USAGEFLEET_NOTIFY=0`.
 
 ## Blocking prompts over the limit
 
@@ -165,7 +178,8 @@ it (`usagefleet config` prints this same table):
 | `interval` | `USAGEFLEET_INTERVAL` | watch poll seconds (default 15) |
 | `limitsInterval` | `USAGEFLEET_LIMITS_INTERVAL` | seconds between limit reports (default 60; 300 on API keys, where each report costs a 1-token ping) |
 | `notifications` | `USAGEFLEET_NOTIFY` | desktop notifications, on by default (`false`/`0` disables) |
-| `notifyThresholds` | `USAGEFLEET_NOTIFY_THRESHOLDS` | utilization % that trigger an alert — array in the file, comma list in env (default `80,95`) |
+| `notifyMode` | `USAGEFLEET_NOTIFY_MODE` | alert preset: `off`, `quiet`, `standard`, `steady`, `critical` (default: the Devices page value, else `standard`) |
+| `notifyThresholds` | `USAGEFLEET_NOTIFY_THRESHOLDS` | utilization % that trigger an alert, replacing the mode's list — array in the file, comma list in env, one decimal kept |
 | `batch` | `USAGEFLEET_BATCH` | records per upload (default 100, server caps at 1000) |
 | `update` | `USAGEFLEET_UPDATE` | `false`/`0` turns the self-update check off |
 | `updateInterval` | `USAGEFLEET_UPDATE_INTERVAL` | seconds between update checks (default `21600` = 6h) |

package/dist/collector.js

@@ -6,7 +6,7 @@ import { detectClaudeCreds, macKeychainDenied } from './claude-creds.js';
 import { fetchLimits } from './claude-limits.js';
 import { ENDPOINT } from './config.js';
 import { listJcodeSessions, readJcodeSession } from './jcode.js';
-import { maybeNotify } from './notifier.js';
+import { loadNotifyConfig, maybeNotify } from './notifier.js';
 import { detectOs } from './os.js';
 import { RELEASE_VERSION } from './release.js';
 import { listJsonlFiles } from './scanner.js';
@@ -461,7 +461,9 @@ async function reportClaudeCodeLimits(cfg, log) {
     if (groupLimits) {
         maybeNotify(groupLimits.group === null
             ? report
-            : { ...report, fiveHourPct: groupLimits.sessionPct, sevenDayPct: groupLimits.weeklyPct }, undefined, log);
+            : { ...report, fiveHourPct: groupLimits.sessionPct, sevenDayPct: groupLimits.weeklyPct }, 
+        // The device's mode from the Devices page rides along on the same answer.
+        loadNotifyConfig(undefined, undefined, groupLimits.notifyMode), log);
     }
     return { ...report, account };
 }

package/dist/index.js

@@ -166,7 +166,7 @@ async function cmdWatch() {
 function cmdNotifyTest() {
     const cfg = loadNotifyConfig();
     if (!cfg.enabled) {
-        console.log(warn('notify', 'disabled · unset USAGEFLEET_NOTIFY=0 / `"notifications": false` to enable'));
+        console.log(warn('notify', 'disabled · mode off, or USAGEFLEET_NOTIFY=0 / `"notifications": false` · see `usagefleet config`'));
         return;
     }
     sendNotification('usagefleet', 'Test notification — desktop alerts are working.', {
@@ -294,7 +294,8 @@ function cmdConfig() {
         ],
         ['batch', 'USAGEFLEET_BATCH', 'records per upload (default 100, max 1000)'],
         ['notifications', 'USAGEFLEET_NOTIFY', 'desktop notifications (false/0 disables)'],
-        ['notifyThresholds', 'USAGEFLEET_NOTIFY_THRESHOLDS', '% alerts · array; env comma list (default 80,95)'],
+        ['notifyMode', 'USAGEFLEET_NOTIFY_MODE', 'alert preset: off | quiet | standard | steady | critical'],
+        ['notifyThresholds', 'USAGEFLEET_NOTIFY_THRESHOLDS', '% alerts · array; env comma list (replaces the preset)'],
         ['hook', 'USAGEFLEET_HOOK', 'register the prompt guard on install (false/0 skips)'],
         ['update', 'USAGEFLEET_UPDATE', 'self-update while watching (false/0 disables)'],
         ['updateInterval', 'USAGEFLEET_UPDATE_INTERVAL', 'seconds between update checks (default 21600)'],

package/dist/notifier.js

@@ -1,17 +1,41 @@
 import { flagOff } from './config.js';
 import { sendNotification } from './notify.js';
 import { readStore, storePath, updateStore } from './store.js';
-const DEFAULT_THRESHOLDS = [80, 95];
+/** Thresholds per mode. `critical` thins out near the wall on purpose: the last
+ *  few points are where a window is actually lost, so they get a tenth-of-a-point
+ *  step. Mirrored by the Devices page (apps/web/src/lib/notify-modes.ts). */
+export const NOTIFY_MODES = {
+    critical: [80, 90, 95, 96, 97, 98, 99, 99.1, 99.2, 99.3, 99.4, 99.5, 99.6, 99.7, 99.8, 99.9, 100],
+    off: [],
+    quiet: [95, 100],
+    standard: [80, 95],
+    steady: [50, 60, 70, 80, 90, 95, 100],
+};
+const DEFAULT_MODE = 'standard';
+/** Points under the mark pct must fall before the mark is lowered and re-armed. */
+const REARM_MARGIN = 5;
+/** Utilization % from which an alert is urgent (`critical` on Linux). */
+const DANGER_ZONE = 95;
+/** Case-insensitive; anything that is not a mode name is null, so a typo in one
+ *  layer falls through to the next instead of silencing every alert. */
+export function parseNotifyMode(value) {
+    const mode = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return Object.hasOwn(NOTIFY_MODES, mode) ? mode : null;
+}
 /** Resolve notify config, env first then the config file. Enabled by default;
  *  disable with USAGEFLEET_NOTIFY=0 (also: false/off/no) or `"notifications":
- *  false`. Thresholds from USAGEFLEET_NOTIFY_THRESHOLDS as a comma list
- *  (e.g. "50,80,95") or a `notifyThresholds` array. */
-export function loadNotifyConfig(env = process.env, file = readStore()) {
-    const enabled = !flagOff(env.USAGEFLEET_NOTIFY, file.notifications);
+ *  false`. The preset comes from USAGEFLEET_NOTIFY_MODE, the `notifyMode` file
+ *  key, then `serverMode` (the one set for this device on the Devices page);
+ *  an explicit list from USAGEFLEET_NOTIFY_THRESHOLDS (comma list, e.g.
+ *  "50,80,95") or a `notifyThresholds` array replaces the preset's thresholds. */
+export function loadNotifyConfig(env = process.env, file = readStore(), serverMode = null) {
+    const mode = parseNotifyMode(env.USAGEFLEET_NOTIFY_MODE) ?? parseNotifyMode(file.notifyMode) ?? serverMode ?? DEFAULT_MODE;
+    const enabled = !flagOff(env.USAGEFLEET_NOTIFY, file.notifications) && mode !== 'off';
     const raw = env.USAGEFLEET_NOTIFY_THRESHOLDS;
     const candidates = raw?.trim() ? raw.split(',').map(s => Number(s.trim())) : (file.notifyThresholds ?? []);
-    const parsed = candidates.map(Math.round).filter(n => Number.isFinite(n) && n > 0 && n <= 100);
-    const thresholds = parsed.length > 0 ? [...new Set(parsed)].toSorted((a, b) => a - b) : DEFAULT_THRESHOLDS;
+    // One decimal, like the readings themselves: 99.1 must stay 99.1.
+    const parsed = candidates.map(n => Math.round(n * 10) / 10).filter(n => Number.isFinite(n) && n > 0 && n <= 100);
+    const thresholds = parsed.length > 0 ? [...new Set(parsed)].toSorted((a, b) => a - b) : NOTIFY_MODES[mode];
     return { enabled, thresholds };
 }
 /**
@@ -20,8 +44,10 @@ export function loadNotifyConfig(env = process.env, file = readStore()) {
  *
  * A window rollover (resetsAt moves) resets the high-water mark first, so the
  * first crossing in a new window always re-notifies. If utilization later drops
- * below the mark within the SAME window (e.g. a server correction), the mark is
- * lowered so a subsequent re-cross notifies again.
+ * well below the mark within the SAME window (e.g. a server correction), the mark
+ * is lowered so a subsequent re-cross notifies again. A small dip does not move
+ * it: a group's slice is derived and wobbles between readings, and a mark that
+ * followed every wobble would re-alert each time pct straddled a threshold.
  */
 export function evaluateWindow(prev, pct, resetsAt, thresholds) {
     const rolledOver = !prev || !sameWindow(prev.resetsAt, resetsAt);
@@ -30,7 +56,7 @@ export function evaluateWindow(prev, pct, resetsAt, thresholds) {
     const windowResetsAt = rolledOver ? resetsAt : prev.resetsAt;
     if (pct == null) {
         // No reading this cycle — keep the mark, just track the (possibly new) window.
-        return { fire: null, next: { lastBucket, resetsAt: windowResetsAt } };
+        return { fire: null, urgent: false, next: { lastBucket, resetsAt: windowResetsAt } };
     }
     // Highest threshold the current pct has reached (thresholds are ascending).
     let top = 0;
@@ -40,10 +66,15 @@ export function evaluateWindow(prev, pct, resetsAt, thresholds) {
         }
     }
     if (top > lastBucket) {
-        return { fire: top, next: { lastBucket: top, resetsAt: windowResetsAt } };
+        // `critical` is sticky on most Linux daemons, so only entering the danger zone and
+        // the wall get it; a dense tail (99.1, 99.2, ...) must not pile up.
+        const urgent = (lastBucket < DANGER_ZONE && top >= DANGER_ZONE) || top >= 100;
+        return { fire: top, urgent, next: { lastBucket: top, resetsAt: windowResetsAt } };
     }
-    // top <= lastBucket: the mark follows pct down (or holds); nothing fires.
-    return { fire: null, next: { lastBucket: top, resetsAt: windowResetsAt } };
+    // top <= lastBucket: nothing fires. The mark holds through a wobble and follows
+    // pct down only on a real drop.
+    const mark = pct < lastBucket - REARM_MARGIN ? top : lastBucket;
+    return { fire: null, urgent: false, next: { lastBucket: mark, resetsAt: windowResetsAt } };
 }
 // oauth/usage jitters resets_at by milliseconds per request; a real rollover moves it by hours.
 function sameWindow(a, b) {
@@ -71,9 +102,6 @@ function resetSuffix(resetsAt) {
     }
     return ` · resets in ${Math.round(h / 24)}d`;
 }
-function urgencyFor(bucket) {
-    return bucket >= 95 ? 'critical' : 'normal';
-}
 /**
  * Notify on freshly-crossed 5h/weekly thresholds, deduped across runs via the
  * store's `notify` section. Best-effort and self-contained: it owns its state
@@ -96,11 +124,11 @@ export function maybeNotify(report, cfg = loadNotifyConfig(), log = () => {
         const fivePct = fmt(report.fiveHourPct ?? 0);
         const sevenPct = fmt(report.sevenDayPct ?? 0);
         if (five.fire != null) {
-            sendNotification('Claude usage · 5-hour limit', `${fivePct}% of your 5-hour limit used${resetSuffix(report.fiveHourResetsAt)}.`, { urgency: urgencyFor(five.fire) });
+            sendNotification('Claude usage · 5-hour limit', `${fivePct}% of your 5-hour limit used${resetSuffix(report.fiveHourResetsAt)}.`, { urgency: five.urgent ? 'critical' : 'normal' });
             log('ok', `notified · 5h at ${fivePct}% · crossed ${five.fire}%`);
         }
         if (seven.fire != null) {
-            sendNotification('Claude usage · weekly limit', `${sevenPct}% of your weekly limit used${resetSuffix(report.sevenDayResetsAt)}.`, { urgency: urgencyFor(seven.fire) });
+            sendNotification('Claude usage · weekly limit', `${sevenPct}% of your weekly limit used${resetSuffix(report.sevenDayResetsAt)}.`, { urgency: seven.urgent ? 'critical' : 'normal' });
             log('ok', `notified · weekly at ${sevenPct}% · crossed ${seven.fire}%`);
         }
         updateStore(path, store => {

package/dist/release.js

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

package/dist/store.js

@@ -61,6 +61,7 @@ function normalize(raw) {
             fiveHour: { ...freshWindow(), ...raw.notify?.fiveHour },
             sevenDay: { ...freshWindow(), ...raw.notify?.sevenDay },
         },
+        notifyMode: raw.notifyMode,
         notifyThresholds: raw.notifyThresholds,
         piDir: raw.piDir,
         pjDir: raw.pjDir,

package/dist/uploader.js

@@ -1,4 +1,5 @@
 import { ENDPOINT, tokenFor } from './config.js';
+import { parseNotifyMode } from './notifier.js';
 const MAX_ATTEMPTS = 6;
 const REQUEST_TIMEOUT_MS = 15_000;
 function sleep(ms) {
@@ -115,7 +116,12 @@ export async function fetchGroupLimits(cfg, accountExtId) {
         if (typeof body?.sessionPct !== 'number' || typeof body.weeklyPct !== 'number') {
             return null;
         }
-        return { group: body.group ?? null, sessionPct: body.sessionPct, weeklyPct: body.weeklyPct };
+        return {
+            group: body.group ?? null,
+            notifyMode: parseNotifyMode(body.notifyMode),
+            sessionPct: body.sessionPct,
+            weeklyPct: body.weeklyPct,
+        };
     }
     catch {
         return null;

package/package.json

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