claude-nonstop 0.3.0 → 0.4.0

package/README.md

@@ -45,7 +45,7 @@ On launch, claude-nonstop checks usage across all accounts and picks the one wit
 
 | Command | Description |
 |---------|-------------|
-| `status` | Show usage with progress bars and reset times |
+| `status` | Show usage with progress bars and reset times (Enterprise usage-based accounts show a spend bar instead) |
 | `add <name>` | Add a new Claude account (opens browser for OAuth) |
 | `remove <name>` | Remove an account |
 | `list` | List accounts with auth status |
@@ -72,6 +72,53 @@ On launch, claude-nonstop checks usage across all accounts and picks the one wit
 
 Any unrecognized arguments are passed through to `claude` directly. Use `-a <name>` to select a specific account.
 
+## How Enterprise usage limits are tracked
+
+Subscription accounts (Pro/Max) and Enterprise usage-based accounts are metered
+differently, and claude-nonstop handles both transparently.
+
+**Two kinds of meter.** Every account is checked against the same OAuth usage
+endpoint (`GET /api/oauth/usage`), but the response shape differs:
+
+- **Window-metered** (Pro/Max): the API returns rolling `five_hour` and
+  `seven_day` utilization percentages. `status` shows these as the 5-hour / 7-day
+  bars. This is the meter you hit mid-work.
+- **Spend-metered** (Enterprise usage-based): the API returns `five_hour` and
+  `seven_day` as `null` and instead a `spend` block with `used`, `limit`, and
+  `percent` in USD (minor units / cents). `status` shows a dollar bar, e.g.
+  `spend: ████████░░ 65% ($649.13 / $1,000.00)`.
+
+An account is treated as spend-metered **only when both rolling windows are
+null**. Enterprise's plan is purely dollar-based; Pro/Max accounts also carry a
+`spend` block (their extra-usage overage cap), but their real meter is the
+rolling window, so they stay window-metered and their live session/weekly usage
+is never hidden behind the overage number.
+
+**The cap is always read live.** The spend limit is taken from the API's
+`spend.limit` on every check — there is no cached or hardcoded cap — so if your
+org's limit changes, claude-nonstop picks it up on the next `status` or account
+selection. The percentage is computed locally from `used / limit` rather than
+trusting the API's reported `percent`, which has been observed to briefly lag
+during high-traffic periods.
+
+**Kept up to date automatically.** Usage is re-fetched fresh on every `status`
+call and every account selection (launch, switch, `use --best`), and the
+preemption watcher re-polls every 5 minutes while running. There is no
+separate polling daemon — freshness comes from fetching on demand. An Enterprise
+account that is over its monthly cap (`spend.percent` ≥ 100%) folds into the same
+effective-utilization logic as a rate-limited subscription account, so the scorer
+stops routing to it and resumes after the monthly reset.
+
+**Monthly reset.** Enterprise spend caps reset at **00:00 UTC on the 1st of each
+calendar month** — a fixed, universal rule confirmed against Anthropic's official
+Spend Limits API documentation (the same for every org, independent of the
+subscription start date). The API does not expose the reset datetime, so
+claude-nonstop computes it locally and displays it in US Pacific time, labeled
+`(computed)` — e.g. `Resets: Jun 30, 5:00 PM PDT (computed)`. Note this is the
+*spend* reset specifically; it is distinct from the rolling 5-hour/7-day rate
+limits (which reset on their own rolling windows) and from Enterprise seat-fee
+billing (charged on the contract anniversary, not the 1st).
+
 ## Install
 
 The easiest way to install is to ask Claude Code:
@@ -201,6 +248,8 @@ This creates a tmux session named after the current directory, enables `--danger
 
 **Multi-account switching** queries the Anthropic usage API for all accounts (~200ms), picks the one with the most headroom, then monitors Claude's output for rate limit messages in real-time. On detection: kill, migrate session files to the next account, resume with `claude --resume`.
 
+**Preempting back to a higher-priority account.** Rate-limit switching only moves *down* the priority list — it reacts to a limit on the current account and never climbs back on its own. Without a counterpart, a long session that fell back to a last-resort account (e.g. a metered Enterprise account) would stay there for hours even after the preferred account's rolling window reset, because no rate limit fires to trigger a re-check. So while parked on a non-top-priority account, a background watcher re-polls usage every 5 minutes and, the moment a strictly higher-priority account drops below the "freed up" threshold (90% by default, kept under the 98% exhaustion cutoff so it never swaps onto a near-full account), it migrates the session back up. Preemptive swaps reuse the same migrate/resume path and don't count against the swap budget. The watcher only arms when you've set account priorities and at least one account outranks the current one; tune it with `CLAUDE_NONSTOP_PREEMPT_INTERVAL_MS` (poll interval in ms — set to `0` to disable) and `CLAUDE_NONSTOP_PREEMPT_THRESHOLD` (the freed-up percentage).
+
 **Slack remote access** uses Claude Code [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) — `SessionStart` creates a Slack channel, `Stop` posts a completion summary. A separate webhook process connects via Slack Socket Mode and relays channel messages to tmux. The runner scrapes PTY output for tool activity and posts progress updates to Slack every ~10 seconds.
 
 ## Architecture

package/bin/claude-nonstop.js

@@ -449,6 +449,8 @@ async function cmdStatus() {
 
       if (account.usage.error) {
         console.log(`    Usage: error (${account.usage.error})`);
+      } else if (account.usage.meterType === 'spend') {
+        renderSpendUsage(account.usage);
       } else {
         const sessionBar = makeBar(account.usage.sessionPercent);
         const weeklyBar = makeBar(account.usage.weeklyPercent);
@@ -1677,3 +1679,68 @@ function formatResetTime(isoString) {
     return isoString;
   }
 }
+
+/**
+ * Render an absolute reset datetime in US Pacific time. The monthly spend reset
+ * is a fixed UTC instant (00:00 on the 1st), which the claude.ai UI shows in
+ * Pacific — 5:00 PM PDT in summer, 4:00 PM PST in winter. Using a real IANA
+ * zone (not a fixed offset) keeps the DST abbreviation correct year-round.
+ * e.g. "Jun 30, 5:00 PM PDT".
+ */
+function formatAbsoluteReset(isoString) {
+  try {
+    const date = new Date(isoString);
+    if (isNaN(date.getTime())) return isoString;
+    return new Intl.DateTimeFormat('en-US', {
+      timeZone: 'America/Los_Angeles',
+      month: 'short', day: 'numeric',
+      hour: 'numeric', minute: '2-digit',
+      timeZoneName: 'short',
+    }).format(date);
+  } catch {
+    return isoString;
+  }
+}
+
+/**
+ * Format a minor-unit amount (e.g. cents) as a currency string using the
+ * payload's own exponent, so non-USD / non-2-decimal currencies render right.
+ * e.g. (64913, 'USD', 2) -> "$649.13"; (5000, 'JPY', 0) -> "¥5000".
+ */
+function formatSpendAmount(amountMinor, currency = 'USD', exponent = 2) {
+  if (typeof amountMinor !== 'number') return '—';
+  const exp = typeof exponent === 'number' ? exponent : 2;
+  const major = amountMinor / Math.pow(10, exp);
+  try {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: currency || 'USD',
+      minimumFractionDigits: exp,
+      maximumFractionDigits: exp,
+    }).format(major);
+  } catch {
+    // Unknown currency code — fall back to a plain number with the code.
+    return `${major.toFixed(exp)} ${currency || ''}`.trim();
+  }
+}
+
+/**
+ * Render usage for a spend-metered (Enterprise usage-based) account: a dollar
+ * bar of spend-against-cap plus the locally-computed monthly reset. A null
+ * limit means the org has no spend cap (unlimited).
+ */
+function renderSpendUsage(usage) {
+  const { spendUsedMinor, spendLimitMinor, spendCurrency, spendExponent, spendPercent, spendResetsAt } = usage;
+  const used = formatSpendAmount(spendUsedMinor, spendCurrency, spendExponent);
+
+  if (spendLimitMinor == null) {
+    console.log(`    spend:   unlimited (${used} used)`);
+    return;
+  }
+
+  const limit = formatSpendAmount(spendLimitMinor, spendCurrency, spendExponent);
+  console.log(`    spend:   ${makeBar(spendPercent)} ${spendPercent}%  (${used} / ${limit})`);
+  if (spendResetsAt) {
+    console.log(`    Resets:  ${formatAbsoluteReset(spendResetsAt)} (computed)`);
+  }
+}

package/lib/runner.js

@@ -20,7 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readCredentials } from './keychain.js';
 import { checkAllUsage } from './usage.js';
-import { pickBestAccount, effectiveUtilization } from './scorer.js';
+import { pickBestAccount, effectiveUtilization, pickPreemptAccount, PREEMPT_THRESHOLD } from './scorer.js';
 import { findLatestSession, migrateSession } from './session.js';
 import { reauthExpiredAccounts } from './reauth.js';
 import { CONFIG_DIR } from './config.js';
@@ -51,6 +51,12 @@ const KILL_ESCALATION_DELAY = 3000;
 const EXHAUSTION_THRESHOLD = 99;
 /** Maximum sleep duration when waiting for a rate limit reset (6 hours). */
 const MAX_SLEEP_MS = 6 * 60 * 60 * 1000;
+/**
+ * How often the background watcher re-checks usage while parked on a
+ * lower-priority account, to see if a higher-priority account has freed up
+ * (default 5 minutes). Set CLAUDE_NONSTOP_PREEMPT_INTERVAL_MS=0 to disable.
+ */
+const PREEMPT_POLL_INTERVAL_MS = 5 * 60 * 1000;
 
 // ─── ANSI Stripping ────────────────────────────────────────────────────────
 
@@ -72,6 +78,37 @@ function spawnHookNotify(type, data) {
   child.unref();
 }
 
+/**
+ * Resolve the background-watcher poll interval (ms) from the environment,
+ * falling back to the default. A value of 0 (or negative/invalid) disables
+ * the watcher entirely.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {number} interval in ms, or 0 if disabled
+ */
+function resolvePreemptIntervalMs(env = process.env) {
+  const raw = env.CLAUDE_NONSTOP_PREEMPT_INTERVAL_MS;
+  if (raw === undefined || raw === '') return PREEMPT_POLL_INTERVAL_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return n;
+}
+
+/**
+ * Resolve the "freed up" utilization threshold (%) from the environment,
+ * falling back to the scorer default.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {number} threshold percent
+ */
+function resolvePreemptThreshold(env = process.env) {
+  const raw = env.CLAUDE_NONSTOP_PREEMPT_THRESHOLD;
+  if (raw === undefined || raw === '') return PREEMPT_THRESHOLD;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 100) return PREEMPT_THRESHOLD;
+  return n;
+}
+
 /**
  * Find the earliest reset time across all non-excluded accounts.
  *
@@ -205,7 +242,54 @@ export async function run(claudeArgs, selectedAccount, allAccounts, options = {}
   }
 
   while (swapCount <= maxSwaps) {
-    const result = await runOnce(claudeArgs, currentAccount, sessionId, { remoteAccess });
+    const result = await runOnce(claudeArgs, currentAccount, sessionId, {
+      remoteAccess,
+      allAccounts,
+    });
+
+    // Background watcher preempted: a higher-priority account freed up while we
+    // were parked on a lower-priority one. Treat like a swap, but force priority
+    // selection and don't charge it against the swap budget (it's a recovery,
+    // not a rate-limit retreat).
+    if (result.preemptDetected && result.preemptTo) {
+      const cwd = process.cwd();
+      const session = findLatestSession(currentAccount.configDir, cwd);
+      const nextAccount = result.preemptTo;
+      console.error(`\n[claude-nonstop] Switching to "${nextAccount.name}" (${result.preemptReason})`);
+
+      if (remoteAccess) {
+        spawnHookNotify('account-switch', {
+          session_id: sessionId || null,
+          cwd,
+          from_account: currentAccount.name,
+          to_account: nextAccount.name,
+          reason: result.preemptReason,
+          swap_count: swapCount,
+          max_swaps: maxSwaps,
+        });
+      }
+
+      if (session) {
+        const migration = migrateSession(currentAccount.configDir, nextAccount.configDir, cwd, session.sessionId);
+        if (migration.success) {
+          sessionId = session.sessionId;
+          console.error(`[claude-nonstop] Session ${sessionId} migrated successfully`);
+        } else {
+          console.error(`[claude-nonstop] Session migration failed: ${migration.error}`);
+          console.error('[claude-nonstop] Starting fresh session on new account');
+          sessionId = null;
+        }
+      } else {
+        sessionId = null;
+      }
+
+      if (sessionId) {
+        claudeArgs = buildResumeArgs(claudeArgs, sessionId, RATE_LIMIT_CONTINUE_MSG);
+      }
+
+      currentAccount = nextAccount;
+      continue;
+    }
 
     if (result.exitCode !== null && !result.rateLimitDetected) {
       // Normal exit — propagate the exit code
@@ -382,9 +466,11 @@ export async function run(claudeArgs, selectedAccount, allAccounts, options = {}
 }
 
 /**
- * Run Claude once, monitoring for rate limits.
+ * Run Claude once, monitoring for rate limits and (when a higher-priority
+ * account can outrank the current one) running a background watcher that
+ * preempts to that account once it frees up.
  *
- * @returns {Promise<{ exitCode: number|null, rateLimitDetected: boolean, resetTime: string|null, sessionId: string|null }>}
+ * @returns {Promise<{ exitCode: number|null, rateLimitDetected: boolean, resetTime: string|null, sessionId: string|null, preemptDetected: boolean, preemptTo: object|null, preemptReason: string|null }>}
  */
 function runOnce(claudeArgs, account, existingSessionId, options = {}) {
   return new Promise((resolve) => {
@@ -426,6 +512,54 @@ function runOnce(claudeArgs, account, existingSessionId, options = {}) {
     let resetTime = null;
     let outputBuffer = '';
 
+    // Background watcher: while parked on a lower-priority account, periodically
+    // check whether a higher-priority account has freed up and, if so, preempt
+    // (kill child -> caller migrates session -> resumes on the better account).
+    let preemptDetected = false;
+    let preemptTo = null;
+    let preemptReason = null;
+    let watcherBusy = false;
+    const allAccounts = options.allAccounts || [];
+    const pollMs = resolvePreemptIntervalMs();
+    const preemptThreshold = resolvePreemptThreshold();
+    // Only worth polling when the current account isn't already top priority and
+    // there's at least one account that could outrank it.
+    const currentPriority = allAccounts.find(a => a.name === account.name)?.priority;
+    const watcherEnabled = pollMs > 0
+      && currentPriority != null
+      && allAccounts.some(a => a.priority != null && a.priority < currentPriority);
+
+    async function pollForHigherPriority() {
+      if (watcherBusy || rateLimitDetected || preemptDetected) return;
+      watcherBusy = true;
+      try {
+        const withTokens = allAccounts
+          .map(a => ({ ...a, token: readCredentials(a.configDir).token }))
+          .filter(a => a.token);
+        const withUsage = await checkAllUsage(withTokens);
+        if (rateLimitDetected || preemptDetected) return; // raced with another path
+        const choice = pickPreemptAccount(withUsage, account.name, { threshold: preemptThreshold });
+        if (choice) {
+          preemptDetected = true;
+          preemptTo = choice.account;
+          preemptReason = choice.reason;
+          child.kill('SIGTERM');
+          setTimeout(() => {
+            try { child.kill('SIGKILL'); } catch {}
+          }, KILL_ESCALATION_DELAY);
+        }
+      } catch {
+        // Usage check failed (network/keychain) — skip this tick, try again next.
+      } finally {
+        watcherBusy = false;
+      }
+    }
+
+    const watcherTimer = watcherEnabled
+      ? setInterval(pollForHigherPriority, pollMs)
+      : null;
+    if (watcherTimer && typeof watcherTimer.unref === 'function') watcherTimer.unref();
+
     child.onData((data) => {
       process.stdout.write(data);
 
@@ -460,6 +594,8 @@ function runOnce(claudeArgs, account, existingSessionId, options = {}) {
       if (cleaned) return;
       cleaned = true;
 
+      if (watcherTimer) clearInterval(watcherTimer);
+
       for (const sig of signals) {
         process.removeListener(sig, signalHandlers[sig]);
       }
@@ -474,7 +610,7 @@ function runOnce(claudeArgs, account, existingSessionId, options = {}) {
 
     for (const sig of signals) {
       const handler = () => {
-        if (!rateLimitDetected) {
+        if (!rateLimitDetected && !preemptDetected) {
           try { child.kill(sig); } catch {}
         }
       };
@@ -491,6 +627,9 @@ function runOnce(claudeArgs, account, existingSessionId, options = {}) {
         rateLimitDetected,
         resetTime,
         sessionId: existingSessionId,
+        preemptDetected,
+        preemptTo,
+        preemptReason,
       });
     });
   });
@@ -563,4 +702,6 @@ export {
   RATE_LIMIT_CONTINUE_MSG, FLAGS_WITH_VALUES,
   findEarliestReset, formatDuration, sleep, deactivateStaleChannels,
   EXHAUSTION_THRESHOLD, MAX_SLEEP_MS,
+  resolvePreemptIntervalMs, resolvePreemptThreshold,
+  PREEMPT_POLL_INTERVAL_MS,
 };

package/lib/scorer.js

@@ -12,6 +12,17 @@
 
 const PRIORITY_THRESHOLD = 98;
 
+/**
+ * Short human-readable usage descriptor for log/reason strings. Spend-metered
+ * accounts report their dollar utilization; window accounts report session/weekly.
+ */
+function describeUsage(usage) {
+  if (usage?.meterType === 'spend') {
+    return `spend: ${usage.spendPercent ?? 0}%`;
+  }
+  return `session: ${usage?.sessionPercent ?? 0}%, weekly: ${usage?.weeklyPercent ?? 0}%`;
+}
+
 /**
  * Pick the best account from a list of accounts with usage data.
  *
@@ -59,7 +70,7 @@ export function pickBestAccount(accounts, excludeName, options = {}) {
 
     return {
       account: best,
-      reason: `priority selection (session: ${best.usage.sessionPercent}%, weekly: ${best.usage.weeklyPercent}%${pri})`,
+      reason: `priority selection (${describeUsage(best.usage)}${pri})`,
     };
   }
 
@@ -74,7 +85,7 @@ export function pickBestAccount(accounts, excludeName, options = {}) {
 
   return {
     account: best,
-    reason: `lowest utilization (session: ${best.usage.sessionPercent}%, weekly: ${best.usage.weeklyPercent}%)`,
+    reason: `lowest utilization (${describeUsage(best.usage)})`,
   };
 }
 
@@ -90,11 +101,76 @@ export function pickByPriority(accounts) {
 }
 
 /**
- * Calculate effective utilization — the higher of session or weekly.
+ * Calculate effective utilization — the highest of session, weekly, or spend.
+ *
+ * Spend-metered (Enterprise usage-based) accounts have null session/weekly
+ * windows, so their utilization is driven by spendPercent. Folding it into the
+ * same max() means an Enterprise account that is over its monthly dollar cap
+ * (spendPercent >= 100) is treated as exhausted by every selection path —
+ * routing, priority, and preemption — with no other changes needed.
  */
 export function effectiveUtilization(usage) {
   if (!usage) return 100;
-  return Math.max(usage.sessionPercent || 0, usage.weeklyPercent || 0);
+  return Math.max(usage.sessionPercent || 0, usage.weeklyPercent || 0, usage.spendPercent || 0);
+}
+
+/**
+ * Default utilization (%) below which a higher-priority account is considered
+ * "freed up" enough to preempt the current lower-priority account.
+ * Kept below PRIORITY_THRESHOLD so we never swap back to an account that the
+ * normal switch logic would immediately reject as near-exhausted.
+ */
+const PREEMPT_THRESHOLD = 90;
+
+/**
+ * Decide whether to preempt the current account in favor of a higher-priority
+ * one that has freed up. Used by the background watcher so a last-resort account
+ * (e.g. priority 4) is abandoned as soon as priorities 1–N recover.
+ *
+ * A swap is recommended only when some account with a STRICTLY lower priority
+ * number than the current account has effective utilization below `threshold`.
+ * Among qualifying accounts, the lowest priority number wins (utilization breaks
+ * ties), matching pickByPriority semantics.
+ *
+ * Returns null when no swap is warranted: current account has no priority, is
+ * already top priority, has a usage error, or no higher-priority account is
+ * sufficiently free.
+ *
+ * @param {Array<{name, usage, token?, priority?}>} accounts - accounts with usage
+ * @param {string} currentName - the account currently in use
+ * @param {object} [options]
+ * @param {number} [options.threshold=PREEMPT_THRESHOLD] - free-enough cutoff (%)
+ * @returns {{ account: object, reason: string } | null}
+ */
+export function pickPreemptAccount(accounts, currentName, options = {}) {
+  const threshold = options.threshold ?? PREEMPT_THRESHOLD;
+  const current = accounts.find(a => a.name === currentName);
+  // Only preempt away from an account that has a priority. A null/undefined
+  // priority is treated as lowest rank, but nothing can outrank "lowest" in a
+  // way that matters here, so there is no higher-priority target to jump to.
+  if (!current || current.priority == null) return null;
+
+  const candidates = accounts.filter(a => {
+    if (a.name === currentName) return false;
+    if (!a.token) return false;
+    if (a.usage?.error) return false;
+    if (a.priority == null) return false;
+    if (a.priority >= current.priority) return false; // must outrank current
+    return effectiveUtilization(a.usage) < threshold;
+  });
+
+  if (candidates.length === 0) return null;
+
+  candidates.sort((a, b) => {
+    if (a.priority !== b.priority) return a.priority - b.priority;
+    return effectiveUtilization(a.usage) - effectiveUtilization(b.usage);
+  });
+
+  const best = candidates[0];
+  return {
+    account: best,
+    reason: `higher-priority account freed up (now priority ${best.priority}, was on ${currentName} priority ${current.priority}; ${describeUsage(best.usage)})`,
+  };
 }
 
-export { PRIORITY_THRESHOLD };
+export { PRIORITY_THRESHOLD, PREEMPT_THRESHOLD };

package/lib/usage.js

@@ -19,11 +19,126 @@ export function normalizePercent(value) {
   return Math.round(value);
 }
 
+/**
+ * Compute the next monthly spend-limit reset instant.
+ *
+ * Enterprise usage-based orgs reset their spend cap on the calendar-month
+ * boundary at 00:00 UTC on the 1st (NOT the subscription anniversary). The
+ * OAuth usage API does not expose this datetime, so we compute it locally.
+ * The same instant renders as 5:00 PM PDT in summer and 4:00 PM PST in winter
+ * — that DST difference is handled at display time via a real IANA zone.
+ *
+ * Why this is safe to hardcode (researched + cross-validated 2026-06-17):
+ * Anthropic's official Spend Limits API doc states verbatim that "monthly spend
+ * resets at 00:00 UTC on the first of each calendar month" — a fixed, universal
+ * rule, the same for every org, independent of when the subscription started.
+ * This is the SPEND/usage-credit reset specifically. Do not conflate it with:
+ *   - rolling rate limits (5-hour / 7-day windows), which reset on a per-account
+ *     rolling basis, NOT on a calendar or billing boundary; or
+ *   - seat-fee billing, which is charged on the contract anniversary, NOT the 1st.
+ * The API doc notes `period` is an "open set" (only `monthly` exists today), so
+ * if Anthropic ever adds a non-monthly cadence this assumption would need a
+ * revisit — which is why the reset is surfaced to users labeled "(computed)".
+ *
+ * @param {Date} [now] - reference instant (defaults to current time)
+ * @returns {Date} first day of the next calendar month at 00:00:00.000 UTC
+ */
+export function nextMonthlyResetUTC(now = new Date()) {
+  // Date.UTC rolls month 12 into the next year automatically.
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0));
+}
+
+/**
+ * Empty/disabled spend fields — merged into every usage result so callers can
+ * treat the shape uniformly regardless of meter type.
+ */
+const NO_SPEND = {
+  meterType: 'window',
+  spendUsedMinor: null,
+  spendLimitMinor: null,
+  spendCurrency: null,
+  spendExponent: null,
+  spendPercent: 0,
+  spendResetsAt: null,
+};
+
+/**
+ * Detect and normalize a spend-metered (Enterprise usage-based) payload.
+ *
+ * Precedence: the `spend` block is authoritative; the older `extra_usage`
+ * block is the fallback when `spend` is absent. Returns null when the payload
+ * is window-metered (no usable spend signal), so the caller keeps existing
+ * behavior.
+ *
+ * Percent is computed locally from used/limit and preferred over the reported
+ * `spend.percent`, which has been observed to lag (a transient stale reading
+ * returned 100% while used/limit said 65%). A null limit means UNLIMITED and a
+ * zero limit means included-only — both yield 0% and are never "exhausted".
+ *
+ * @param {object} data - raw usage API payload
+ * @returns {object|null} normalized spend fields, or null if window-metered
+ */
+export function parseSpend(data) {
+  // A spend block is the PRIMARY meter only when the rolling windows are absent
+  // (true Enterprise usage-based orgs return five_hour/seven_day = null). Max and
+  // Pro accounts also carry a spend block, but it is just their extra-usage
+  // overage cap — their real meter is the rolling window, so we must NOT flip
+  // them to spend-metering or we would hide live session/weekly usage.
+  const windowMetered = data?.five_hour != null || data?.seven_day != null;
+  if (windowMetered) return null;
+
+  const spend = data?.spend;
+  const extra = data?.extra_usage;
+
+  let usedMinor = null;
+  let limitMinor = null;
+  let currency = null;
+  let exponent = null;
+  let reportedPercent = null;
+
+  if (spend && (spend.used || spend.limit)) {
+    usedMinor = typeof spend.used?.amount_minor === 'number' ? spend.used.amount_minor : null;
+    limitMinor = typeof spend.limit?.amount_minor === 'number' ? spend.limit.amount_minor : null;
+    currency = spend.used?.currency ?? spend.limit?.currency ?? null;
+    exponent = spend.used?.exponent ?? spend.limit?.exponent ?? null;
+    reportedPercent = typeof spend.percent === 'number' ? spend.percent : null;
+  } else if (extra && extra.is_enabled && typeof extra.monthly_limit === 'number') {
+    usedMinor = typeof extra.used_credits === 'number' ? Math.round(extra.used_credits) : null;
+    limitMinor = extra.monthly_limit;
+    currency = extra.currency ?? null;
+    exponent = typeof extra.decimal_places === 'number' ? extra.decimal_places : null;
+    reportedPercent = typeof extra.utilization === 'number' ? extra.utilization : null;
+  } else {
+    return null; // window-metered
+  }
+
+  let percent;
+  if (limitMinor == null || limitMinor === 0) {
+    // Unlimited (null) or included-only (0): no meaningful ratio; never over budget.
+    percent = 0;
+  } else if (usedMinor != null) {
+    percent = Math.min(100, normalizePercent((usedMinor / limitMinor) * 100));
+  } else {
+    // used missing but limit present: fall back to the reported percent.
+    percent = normalizePercent(reportedPercent ?? 0);
+  }
+
+  return {
+    meterType: 'spend',
+    spendUsedMinor: usedMinor,
+    spendLimitMinor: limitMinor,
+    spendCurrency: currency,
+    spendExponent: exponent,
+    spendPercent: percent,
+    spendResetsAt: nextMonthlyResetUTC().toISOString(),
+  };
+}
+
 /**
  * Check usage for a single account token.
  *
  * @param {string} token - OAuth access token
- * @returns {Promise<{sessionPercent: number, weeklyPercent: number, sessionResetsAt: string|null, weeklyResetsAt: string|null, error: string|null}>}
+ * @returns {Promise<{sessionPercent: number, weeklyPercent: number, sessionResetsAt: string|null, weeklyResetsAt: string|null, meterType: string, spendUsedMinor: number|null, spendLimitMinor: number|null, spendCurrency: string|null, spendExponent: number|null, spendPercent: number, spendResetsAt: string|null, error: string|null}>}
  */
 export async function checkUsage(token) {
   try {
@@ -49,12 +164,19 @@ export async function checkUsage(token) {
         weeklyPercent: 0,
         sessionResetsAt: null,
         weeklyResetsAt: null,
+        ...NO_SPEND,
         error: `HTTP ${res.status}`,
       };
     }
 
     const data = await res.json();
 
+    // Enterprise usage-based orgs are spend-metered: five_hour/seven_day are
+    // null and a `spend` (or `extra_usage`) block carries the dollar meter.
+    // parseSpend returns null for window-metered accounts, so we fall back to
+    // the existing window fields then.
+    const spend = parseSpend(data) ?? NO_SPEND;
+
     // New nested format: { five_hour: { utilization: N, resets_at: "..." }, seven_day: { ... } }
     if (data.five_hour !== undefined || data.seven_day !== undefined) {
       return {
@@ -62,6 +184,7 @@ export async function checkUsage(token) {
         weeklyPercent: normalizePercent(data.seven_day?.utilization ?? 0),
         sessionResetsAt: data.five_hour?.resets_at ?? null,
         weeklyResetsAt: data.seven_day?.resets_at ?? null,
+        ...spend,
         error: null,
       };
     }
@@ -72,6 +195,7 @@ export async function checkUsage(token) {
       weeklyPercent: normalizePercent(data.seven_day_utilization ?? 0),
       sessionResetsAt: data.five_hour_reset_at ?? null,
       weeklyResetsAt: data.seven_day_reset_at ?? null,
+      ...spend,
       error: null,
     };
   } catch (error) {
@@ -80,6 +204,7 @@ export async function checkUsage(token) {
       weeklyPercent: 0,
       sessionResetsAt: null,
       weeklyResetsAt: null,
+      ...NO_SPEND,
       error: error.name === 'AbortError' ? 'timeout' : error.message,
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nonstop",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Automatic Claude Code account switching on rate limits + Slack remote access",
   "type": "module",
   "bin": {

package/remote/data/channel-map.json

@@ -0,0 +1 @@
+{}