@sergeychuvayev/claude-fleet 0.7.0 → 0.8.0

package/README.md

@@ -121,6 +121,55 @@ session's own process and never appear as separate rows at all.
 
 </details>
 
+### The status bar watches the account, not the session
+
+Context pressure is per conversation. The five-hour and weekly plan windows are not:
+every Claude process on the machine draws on the same ones, including the terminal
+sessions Fleet only watches. They get one line along the bottom of the window.
+
+```
+5h ▇▇▇▇▇▇░░░░ 62%  resets 13:28   ·   week 31%   ·   opus wk 48%
+```
+
+Only the window closest to stopping you gets a bar; the rest stay bare numbers. The
+same 75% amber and 90% red as context, so "nearly full" reads the same way everywhere.
+Past 90% the countdown replaces the bar, because by then the question is when it clears,
+not how full it is.
+
+When a request is actually refused, the bar turns into the refusal, and the new-agent
+dialog says so before you write a prompt:
+
+```
+⊘ Rate limited · five-hour window · resets 11:42 (35m) · organisation spend cap reached
+```
+
+<details>
+<summary><b>Where the numbers come from, and when they are missing</b></summary>
+
+Three sources, none of them available all the time:
+
+| Source | Gives | Available |
+|---|---|---|
+| `rate_limit_event` | utilisation, reset | only while a Fleet agent streams |
+| The runtime's `/usage` data | every window, the plan | pulled once at the end of a turn |
+| A refused request in any transcript | the wall and its reset | whenever it happened, to any session |
+
+Nothing here ever spends a token to find out: a synthetic request would consume the
+window it claims to measure. That has consequences the bar is explicit about.
+
+Utilisation only refreshes while an agent is running, so after an idle stretch the
+cluster dims and stamps itself `as of 09:38` rather than presenting an old reading as
+current. Nothing measured yet shows nothing at all, never `0%`. On an API key, Bedrock
+or Vertex, where plan limits do not apply, the cluster is absent entirely.
+
+A refusal is the one signal that survives Fleet being idle, because it is written into
+the transcript of whichever session hit it. It expires by itself at its reset time, and
+a refusal with no reset time is discarded rather than shown: a warning that cannot
+clear itself is worse than none. Being blocked never disables anything. Fleet says what
+it knows and leaves the decision where it belongs.
+
+</details>
+
 ### Old sessions can be put away
 
 Every transcript Claude has ever written is a row, so a machine that has been

package/fleet.js

@@ -189,6 +189,9 @@ function readTranscript(file) {
     events: [],
     cwd: null,
     gitBranch: null,
+    // The newest 429 this transcript recorded, if any. Plan limits are account-wide, so
+    // a rejection here describes the whole machine, not only this session.
+    rateLimit: null,
   }
 
   for (const line of text.split('\n')) {
@@ -209,6 +212,16 @@ function readTranscript(file) {
       if (!data.firstTs) data.firstTs = d.timestamp
       data.lastTs = d.timestamp
     }
+    // Claude records the quota it hit only when a request was actually refused. There is
+    // no routine utilisation record to read here, so this is a wall, never a gauge.
+    if (d.quotaLimits && d.quotaLimits.status === 'rejected') {
+      data.rateLimit = {
+        at: d.timestamp ? Date.parse(d.timestamp) || null : null,
+        rateLimitType: d.quotaLimits.rateLimitType || null,
+        resetsAt: d.quotaLimits.resetsAt || null,
+        reason: d.quotaLimits.overageDisabledReason || null,
+      }
+    }
     if (d.timestamp) {
       const at = Date.parse(d.timestamp)
       if (at) for (const event of classify(d)) {
@@ -349,6 +362,7 @@ function collect() {
   const index = transcriptIndex()
   const now = Date.now()
   const sessions = []
+  let rateLimit = null
 
   // The registry describes running processes, not saved conversations: Claude
   // removes registrations on exit. Join it with durable transcripts so handoff
@@ -373,6 +387,10 @@ function collect() {
     const file = meta.sessionId ? index.get(meta.sessionId) : null
     const t = file ? readTranscript(file) : null
 
+    // Whoever hit the wall, the wall is the account's. The freshest rejection on this
+    // machine describes the whole fleet, including sessions Fleet only watches.
+    if (t && t.rateLimit && (!rateLimit || (t.rateLimit.at || 0) > (rateLimit.at || 0))) rateLimit = t.rateLimit
+
     const lastActivity = Math.max(
       meta.updatedAt || 0,
       t && t.lastTs ? Date.parse(t.lastTs) : 0
@@ -436,7 +454,7 @@ function collect() {
   const counts = { busy: 0, idle: 0, stale: 0, dead: 0 }
   for (const s of sessions) counts[s.state] = (counts[s.state] || 0) + 1
 
-  return { generatedAt: now, counts, total: sessions.length, sessions }
+  return { generatedAt: now, counts, total: sessions.length, sessions, rateLimit }
 }
 
 // Look up a transcript by session id without going through the process registry.

package/managed.js

@@ -9,6 +9,7 @@ const { askReason, normaliseMode, MODES, DEFAULT_MODE } = require('./permissions
 const { stateDir } = require('./paths')
 const { getTeam, compile } = require('./teams')
 const { TeamStore } = require('./team-store')
+const { UsageTracker } = require('./usage')
 const tasks = require('./tasks')
 const worktrees = require('./worktree')
 
@@ -63,6 +64,10 @@ class ManagedSessions extends EventEmitter {
     this.closed = false
     this.models = null
     this.saveTimer = null
+    // Plan windows belong to the account, so one tracker serves every session and
+    // outlives all of them. It is deliberately not persisted: a utilisation figure from
+    // before a restart describes a window that has probably already turned over.
+    this.usage = new UsageTracker()
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
     this.file = path.join(directory, 'sessions.json')
     this.attachmentsDir = path.join(directory, 'attachments')
@@ -353,6 +358,8 @@ class ManagedSessions extends EventEmitter {
   }
   event(s,run,event) {
     if (event.session_id && !event.parent_tool_use_id) s.sessionId=event.session_id
+    // Account-wide, so it is recorded whoever emitted it, sub-agent turns included.
+    if (event.type==='rate_limit_event') this.usage.recordEvent(event.rate_limit_info)
     if (s.taskBoard && event.parent_tool_use_id) {
       const d=s.taskBoard.delegations.find(d=>d.id===event.parent_tool_use_id)
       if (d && event.type==='assistant') {
@@ -418,9 +425,21 @@ class ManagedSessions extends EventEmitter {
       else if (event.result && !s.messages.some(m=>m.role==='assistant' && m.text===event.result.slice(-24000))) s.messages.push({id:randomUUID(),role:'assistant',text:event.result.slice(-24000),at:Date.now()})
       s.costUsd=(s.costUsd||0)+(event.total_cost_usd||0)
       s.messages=s.messages.slice(-MAX_MESSAGES)
+      this.captureUsage(run)
     }
     this.changed(s)
   }
+  // The end of a turn is the one moment a query is both idle and still open, so it is
+  // where the every-window reading is taken. Fire and forget: the push event already
+  // carries the window that matters, this only fills in the rest. The method is marked
+  // experimental upstream and may simply not be there, which is not an error.
+  captureUsage(run) {
+    if (!run || run.usagePulled) return
+    const pull=run.query?.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET
+    if (typeof pull!=='function') return
+    run.usagePulled=true
+    Promise.resolve(pull.call(run.query)).then(response=>this.usage.recordUsage(response)).catch(()=>{})
+  }
   // A tool call becomes its own conversation entry so the UI can render it as a command block.
   toolStarted(s,run,block) {
     if (!block.id || run.tools?.has(block.id)) return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sergeychuvayev/claude-fleet",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A local control room for Claude Code sessions",
   "keywords": [
     "claude",
@@ -39,7 +39,8 @@
     "update.js",
     "worktree.js",
     "team-store.js",
-    "tasks.js"
+    "tasks.js",
+    "usage.js"
   ],
   "scripts": {
     "start": "node bin/claude-fleet.js start",

package/public/app.js

@@ -115,6 +115,68 @@ const childRowsHtml = s => {
   return (earlier ? `<div class="session-child-more">+${earlier} earlier</div>` : '') + shown.map(d => childRowHtml(s, d)).join('')
 }
 
+// ── Account usage ─────────────────────────────────────────────────────────────
+// The plan windows belong to the account, not to a session: every Claude process on
+// this machine draws on them, including the terminal sessions Fleet only watches. The
+// bar says so, and it uses the same thresholds and colours as context pressure so
+// "nearly full" reads the same way everywhere.
+const WINDOW_WORD = { five_hour:'five-hour', seven_day:'weekly', seven_day_opus:'weekly Opus', seven_day_sonnet:'weekly Sonnet', seven_day_oauth_apps:'weekly apps' }
+const BLOCK_REASON = {
+  org_spend_cap_reached:'organisation spend cap reached', out_of_credits:'out of credits',
+  overage_not_provisioned:'no overage configured', org_level_disabled:'overage off for this organisation',
+  member_level_disabled:'overage off for this member', no_limits_configured:'no overage limits set',
+  fetch_error:'usage lookup failed',
+}
+const clockAt = ms => new Date(ms).toLocaleTimeString([], {hour:'2-digit',minute:'2-digit'})
+const untilReset = (ms, now) => {
+  const left = ms - now
+  if (left <= 0) return 'any moment'
+  return left < 3600000 ? `${Math.max(1, Math.round(left / 60000))}m` : `${Math.floor(left / 3600000)}h ${Math.round(left % 3600000 / 60000)}m`
+}
+const blockReason = r => BLOCK_REASON[r] || (r ? String(r).replace(/_/g, ' ') : null)
+const windowWord = name => WINDOW_WORD[name] || String(name || '').replace(/_/g, ' ')
+function usageHtml(usage, now) {
+  // Unknown is not zero. With nothing measured, and on an API key or a third-party
+  // provider where plan limits do not apply at all, the cluster is simply absent.
+  if (!usage || !usage.available || !usage.known) return ''
+  const blocked = usage.blocked
+  if (blocked) return `<span class="usage-blocked hot" title="A request was refused by this window. Every Claude session on this machine is affected until it resets.">⊘ Rate limited · ${esc(windowWord(blocked.rateLimitType))} window · resets ${clockAt(blocked.resetsAt)} (${untilReset(blocked.resetsAt, now)})${blockReason(blocked.reason) ? ` · ${esc(blockReason(blocked.reason))}` : ''}</span>`
+  const binding = usage.windows.find(w => w.name === usage.binding) || usage.windows[0]
+  if (!binding) return ''
+  const cls = heat(binding.utilization)
+  // Past 90% the countdown is the decision and the percentage is trivia, so they swap.
+  const critical = binding.utilization >= 90
+  const reset = binding.resetsAt ? (critical ? `${untilReset(binding.resetsAt, now)} left` : `resets ${clockAt(binding.resetsAt)}`) : ''
+  const detail = [
+    usage.subscription ? `Plan: ${usage.subscription}.` : '',
+    'Account-wide, including the terminal sessions Fleet only watches.',
+    usage.observedAt ? `Last read ${clockAt(usage.observedAt)}.` : '',
+  ].filter(Boolean).join(' ')
+  // One bar, on whichever window is closest to stopping the fleet. The rest are bare
+  // numbers: a second bar would just be a second thing to look at.
+  const others = usage.windows.filter(w => w !== binding)
+    .map(w => `<span class="usage-other ${heat(w.utilization)}"><b>${esc(w.label)}</b> ${w.utilization}%</span>`).join('')
+  return `<span class="usage-window ${cls}${usage.stale ? ' is-stale' : ''}" title="${esc(detail)}"><b>${esc(binding.label)}</b>${critical ? `<em>${reset}</em><span class="usage-pct">${binding.utilization}%</span>` : `<span class="mini-bar"><i class="${cls}" style="width:${binding.utilization}%"></i></span><span class="usage-pct">${binding.utilization}%</span>${reset ? `<small>${reset}</small>` : ''}`}</span>${others}${usage.stale && usage.observedAt ? `<small class="usage-stale" title="Utilisation only updates while a Fleet agent is running.">as of ${clockAt(usage.observedAt)}</small>` : ''}`
+}
+function renderStatusbar(usage, sessions) {
+  const now = Date.now()
+  update('status-usage', usageHtml(usage, now))
+  const managed = sessions.filter(s => s.managed && !s.archived)
+  const waiting = managed.filter(s => s.managedStatus === 'approval').length
+  const working = sessions.filter(s => !s.archived && isWorkingRow(s)).length
+  const spend = managed.reduce((sum, s) => sum + (s.costUsd || 0), 0)
+  update('status-fleet', [
+    `<span>${working} working</span>`,
+    waiting ? `<span class="warn">${waiting} needs you</span>` : '',
+    money(spend) ? `<span title="Reported for Fleet’s own conversations only. Terminal sessions are not included, and a Claude subscription is not billed for this.">${esc(money(spend))}</span>` : '',
+  ].filter(Boolean).join('<span class="status-sep" aria-hidden="true">·</span>'))
+  // The same wall, said where it changes a decision: in the dialog that starts agents.
+  const banner = $('launch-blocked')
+  if (banner) {
+    banner.hidden = !usage?.blocked
+    if (usage?.blocked) banner.textContent = `Rate limited until ${clockAt(usage.blocked.resetsAt)} (${untilReset(usage.blocked.resetsAt, now)}). A new agent will not get past its first message until this window resets.`
+  }
+}
 function render() {
   if (!snapshot) return
   const {sessions, total} = snapshot
@@ -137,6 +199,7 @@ function render() {
   const shown = pool.filter(s => filter === 'all' || filter === 'background' || filter === 'archived' || s.state === filter)
   if (!shown.some(s => key(s) === selected)) selected = shown[0] ? key(shown[0]) : null
   $('shown-count').textContent = shown.length
+  renderStatusbar(snapshot.usage, live)
   update('filters', [['all','All sessions',foreground.length],...STATES.map(s => [s,LABELS[s],(visibleCounts[s] || 0)]),...(background.length ? [['background','Background',background.length]] : []),...(archived.length ? [['archived','Archived',archived.length]] : [])].map(([s,label,n]) => `<button class="filter" data-filter="${s}" aria-pressed="${filter === s}">${label}<span>${n}</span></button>`).join(''))
   renderArchiveBar(live.filter(s => s.state === 'dead'), archived.length)
   update('session-list', shown.length ? shown.map(s => {

package/public/index.html

@@ -1,10 +1,11 @@
 <!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="dark"><title>Fleet — Claude Code control room</title><link rel="manifest" href="/manifest.webmanifest"><link rel="icon" href="/icons/fleet-192.png" type="image/png"><link rel="apple-touch-icon" href="/icons/fleet-192.png"><meta name="apple-mobile-web-app-capable" content="yes"><meta name="apple-mobile-web-app-title" content="Fleet"><link rel="stylesheet" href="/theme.css"><link rel="stylesheet" href="/styles.css"><script src="/vendor/libs.js" defer></script><script src="/app.js" defer></script><script src="/blocks.js" defer></script><script src="/control.js" defer></script><script src="/teams.js" defer></script><script src="/ask.js" defer></script></head>
-<body><header class="topbar"><a class="brand" href="/" aria-label="Fleet home"><span class="brandmark">✳</span> fleet <span class="brand-sub">/ CLAUDE CODE</span></a><span class="app-version" id="app-version" title="The version of Fleet this server is running"></span><div class="connection"><span id="connection-dot" class="dot busy"></span><span id="connection">Connecting</span><span class="local">LOCAL CONTROL ROOM</span></div><div class="refresh-info"><button id="update-pill" class="button update-pill" hidden></button><span id="updated">Waiting for first snapshot</span><button id="refresh" class="button">↻ Refresh</button><button id="ask-sessions" class="button" aria-expanded="false" aria-controls="ask-backdrop" title="Ask a question across every session on this machine">⌕ Ask <kbd id="ask-shortcut">⌘K</kbd></button><button id="new-session" class="button resume" aria-expanded="false" aria-controls="launch-backdrop">＋ New agent</button></div></header>
+<body><header class="topbar"><a class="brand" href="/" aria-label="Fleet home"><span class="brandmark">✳</span> fleet <span class="brand-sub">/ CLAUDE CODE</span></a><span class="app-version" id="app-version" title="The version of Fleet this server is running"></span><div class="refresh-info"><button id="update-pill" class="button update-pill" hidden></button><button id="refresh" class="button">↻ Refresh</button><button id="ask-sessions" class="button" aria-expanded="false" aria-controls="ask-backdrop" title="Ask a question across every session on this machine">⌕ Ask <kbd id="ask-shortcut">⌘K</kbd></button><button id="new-session" class="button resume" aria-expanded="false" aria-controls="launch-backdrop">＋ New agent</button></div></header>
 <main>
 <div id="error" class="error" role="status" hidden></div>
 <section class="workspace" aria-label="Sessions"><div class="sessions-pane"><div class="section-heading"><h2>Sessions <span id="shown-count">0</span></h2></div><div class="filters" id="filters" aria-label="Filter sessions by status"></div><div class="archive-bar" id="archive-bar" role="group" aria-label="Archive" hidden></div><div class="list-head"><span>SESSION / PROJECT</span><span>CONTEXT</span></div><div id="session-list" class="session-list"><div class="empty">Loading your sessions…</div></div></div><div id="splitter" class="splitter" role="separator" aria-orientation="vertical" aria-label="Resize the session inspector" aria-valuemin="25" aria-valuemax="75" aria-valuenow="58" tabindex="0" title="Drag to resize · double-click to reset"></div><aside id="detail" class="detail" aria-label="Session details"><section id="control-panel" aria-label="Agent controls"></section><button type="button" id="details-toggle" class="details-toggle" aria-expanded="true" aria-controls="detail-content" hidden><span class="details-chevron" aria-hidden="true">›</span>Session details</button><div id="detail-content"></div></aside></section>
 </main>
+<footer class="statusbar" id="statusbar"><div class="status-usage" id="status-usage"></div><div class="status-fleet" id="status-fleet"></div><div class="status-conn"><span id="connection-dot" class="dot busy"></span><span id="connection">Connecting</span><span id="updated">Waiting for first snapshot</span><span class="local">LOCAL CONTROL ROOM</span></div></footer>
 <div class="modal-backdrop" id="ask-backdrop" hidden>
   <section class="modal modal-ask" role="dialog" aria-modal="true" aria-labelledby="ask-title">
     <header class="modal-head">
@@ -31,6 +32,7 @@
   <section class="modal modal-launch launch-panel" role="dialog" aria-modal="true" aria-labelledby="launch-title">
     <header class="modal-head"><div class="modal-heading"><span class="modal-spark" aria-hidden="true">✳</span><div><span class="modal-eyebrow">A FRESH PAIR OF HANDS</span><h2 id="launch-title">Give your next task a home.</h2><p>A little context. A clear task. Off you go.</p></div></div><button type="button" id="close-launch" class="modal-close" data-close-modal aria-label="Close new agent form">✕</button></header>
     <form id="launch-form" class="modal-body">
+      <p id="launch-blocked" class="rate-warning" role="status" hidden></p>
       <div class="launch-layout">
         <div class="launch-task"><label for="launch-prompt">What are we working on?</label><textarea id="launch-prompt" name="prompt" rows="8" placeholder="There’s something I’d love your help with…&#10;&#10;Describe the task, what a good result looks like, and anything your agent should know." required maxlength="16000"></textarea><p class="note launch-task-note">Big ideas, small fixes. Every task starts here.</p></div>
         <div class="launch-fields">

package/public/styles.css

@@ -463,7 +463,10 @@ body[data-modal]{overflow:hidden}
 .delegation-mandate .block-prose,.delegation-report .block-prose{padding:12px 0 0}
 .delegation-mandate .block-plain,.delegation-report .block-plain{white-space:pre-wrap;overflow-wrap:anywhere}
 
-.app-version{align-self:center;margin-left:8px;color:var(--muted);font-size:10px;letter-spacing:.04em;font-variant-numeric:tabular-nums}
+/* The version belongs to the wordmark. With connection state moved to the status bar
+   it is the only thing left between the brand and the buttons, so it is pinned here
+   rather than left to drift into the middle of the bar. */
+.app-version{align-self:center;margin-left:8px;margin-right:auto;color:var(--muted);font-size:10px;letter-spacing:.04em;font-variant-numeric:tabular-nums}
 .session-cost{font-variant-numeric:tabular-nums}
 
 /* Configurable teams share the launch dialog and the Warp console palette. */
@@ -522,3 +525,38 @@ body[data-modal]{overflow:hidden}
 .child-step-detail summary{cursor:pointer;color:var(--muted);padding:4px 0}
 .child-step-detail pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:320px;overflow:auto;font-size:12px}
 .child-step-detail h4{margin:10px 0 4px;font-size:12px}
+
+/* ── Status bar ────────────────────────────────────────────────────────────────
+   Ambient telemetry at the bottom, actions at the top. The plan windows belong to
+   the account rather than to any one session, so they are drawn once here and never
+   on a row: every Claude process on this machine spends the same five hours. */
+.statusbar{flex:none;display:flex;align-items:center;gap:14px;height:26px;padding:0 14px;border-top:1px solid var(--line);background:color-mix(in oklab,var(--w-bg) 96%,var(--w-fg));font:10.5px/1 var(--mono);color:var(--muted);font-variant-numeric:tabular-nums;white-space:nowrap;overflow:hidden}
+.status-usage{display:flex;align-items:center;gap:12px;min-width:0;overflow:hidden}
+.status-fleet{display:flex;align-items:center;gap:7px;margin-left:auto;flex:none}
+.status-conn{display:flex;align-items:center;gap:8px;flex:none;border-left:1px solid var(--line);padding-left:14px}
+.status-conn .local{border:0;margin:0;padding:0;font-size:9px}
+.status-sep{color:var(--line)}
+.usage-window{display:flex;align-items:center;gap:7px}
+.usage-window b,.usage-other b{font-weight:600;letter-spacing:.3px;color:var(--text)}
+.usage-window.warn b,.usage-window.hot b{color:currentColor}
+/* The countdown, shown instead of the bar once the window is nearly gone. */
+.usage-window em{font-style:normal;font-weight:600}
+.usage-window small,.usage-stale{color:var(--faint);font-size:10px}
+.status-usage .mini-bar{display:block;width:58px;height:4px;margin:0;flex:none}
+.usage-pct{color:var(--text)}
+.usage-window.warn .usage-pct,.usage-window.hot .usage-pct{color:currentColor}
+.usage-other{display:flex;align-items:center;gap:5px;color:var(--faint)}
+.usage-other b{font-weight:500;color:var(--muted)}
+/* A reading only refreshes while an agent runs. An idle hour must not look live, and
+   every window in the cluster shares the one timestamp, so they dim together. */
+.status-usage:has(.is-stale){opacity:.55}
+.usage-blocked{display:flex;align-items:center;gap:7px;font-weight:600}
+/* The same wall, repeated where it changes a decision rather than only informing one. */
+.rate-warning{font-size:12px;line-height:1.6;color:var(--stale);border:1px solid color-mix(in oklab,var(--stale) 45%,var(--line));background:color-mix(in oklab,var(--stale) 9%,var(--panel));border-radius:8px;padding:11px 14px;margin:0 32px 14px}
+@media(max-width:720px){.rate-warning{margin:0 20px 12px}}
+/* The form scrolls inside the dialog and was already within a few pixels of pushing its
+   own submit button out of sight. Anything added above the fields, this warning
+   included, would have hidden it, so the action bar now holds the bottom edge. */
+.modal-launch .launch-footer{position:sticky;bottom:0;z-index:1}
+@media(max-width:900px){.statusbar .local,.usage-other{display:none}}
+@media(max-width:720px){.statusbar{height:auto;flex-wrap:wrap;gap:8px;padding:8px 14px;white-space:normal}.status-fleet{margin-left:0}.status-conn{border:0;padding-left:0}}

package/server.js

@@ -92,7 +92,11 @@ function createApp({manager = new ManagedSessions({externalSessions:()=>collect(
       if(s.archived) archived++
       else counts[s.state]++
     }
-    return {...snap,sessions,counts,total:sessions.length-archived,archived,archiveRule:archive.rule,storageError}
+    // The transcript rejection is merged into the account view rather than shipped
+    // beside it: the dashboard should never have to reconcile two rate-limit stories.
+    const {rateLimit,...rest}=snap
+    const usage=manager.usage ? manager.usage.snapshot({rejection:rateLimit}) : null
+    return {...rest,sessions,counts,total:sessions.length-archived,archived,archiveRule:archive.rule,storageError,usage}
   }
   const authorized=(req)=>{
     const supplied=req.headers['x-fleet-token']

package/usage.js

@@ -0,0 +1,111 @@
+'use strict'
+// Plan usage is an account fact, not a session one: the five-hour and weekly windows
+// are shared by every Claude process on this machine, including the terminal sessions
+// Fleet only watches. Three sources feed this, none of them available all of the time:
+//   - `rate_limit_event`, pushed by the SDK while a Fleet run is streaming
+//   - the runtime's own /usage data, pulled once at the end of a turn
+//   - a rejected `quotaLimits` record in any transcript, which is the only signal that
+//     survives Fleet being idle and the only one that says "you are blocked right now"
+// Nothing here spends a token to find out. A synthetic request would consume the very
+// window it claims to measure.
+const WINDOWS=['five_hour','seven_day','seven_day_opus','seven_day_sonnet','seven_day_oauth_apps']
+const LABELS={five_hour:'5h',seven_day:'week',seven_day_opus:'opus wk',seven_day_sonnet:'sonnet wk',seven_day_oauth_apps:'apps wk'}
+// A live reading only arrives while a run streams. Past this age the bar says "as of",
+// because presenting an hour-old number as current is the one thing it must never do.
+const STALE_MS=120000
+// Utilisation is a whole percentage. A value outside the range is discarded rather than
+// clamped: that far off is a change of shape, not a reading worth drawing.
+const valid=n=>typeof n==='number' && Number.isFinite(n) && n>=0 && n<=100
+// `resetsAt` is unix seconds on the push event and an ISO string on the pull.
+function resetTime(value) {
+  if (typeof value==='number' && Number.isFinite(value) && value>0) return Math.round(value<1e12 ? value*1000 : value)
+  if (typeof value==='string') {const parsed=Date.parse(value);return Number.isFinite(parsed) ? parsed:null}
+  return null
+}
+// A block with no reset time cannot be shown honestly and cannot expire on its own, so
+// it is dropped: a red bar that never clears is worse than no bar.
+const live=(block,now)=>block && block.resetsAt && block.resetsAt>now ? block:null
+
+class UsageTracker {
+  constructor() {
+    this.windows=new Map()
+    this.observedAt=null
+    this.subscription=null
+    // null until something says either way. Unknown is not "no limits": the bar stays
+    // empty rather than reporting a zero it never measured.
+    this.available=null
+    this.blocked=null
+  }
+  // The SDK's push event carries one window at a time and is the only source that
+  // updates mid-turn.
+  recordEvent(info,now=Date.now()) {
+    if (!info || typeof info!=='object') return false
+    const type=typeof info.rateLimitType==='string' ? info.rateLimitType:null
+    let changed=false
+    if (type && valid(info.utilization)) {
+      this.windows.set(type,{utilization:info.utilization,resetsAt:resetTime(info.resetsAt)})
+      this.observedAt=now
+      this.available=true
+      changed=true
+    }
+    if (info.status==='rejected' && type) {
+      this.blocked={rateLimitType:type,resetsAt:resetTime(info.resetsAt),reason:info.overageDisabledReason || null,at:now,source:'run'}
+      changed=true
+    } else if (info.status && this.blocked) {this.blocked=null;changed=true}
+    return changed
+  }
+  // The pull at turn end: every window at once, plus the plan behind them. Experimental
+  // upstream, so absence and malformed shapes are ordinary outcomes, never errors.
+  recordUsage(response,now=Date.now()) {
+    if (!response || typeof response!=='object') return false
+    if (response.rate_limits_available===false) {
+      const had=this.available!==false
+      this.available=false;this.windows.clear();this.observedAt=now
+      return had
+    }
+    let changed=false
+    const limits=response.rate_limits
+    if (limits && typeof limits==='object') for (const name of WINDOWS) {
+      const window=limits[name]
+      if (!window || typeof window!=='object' || !valid(window.utilization)) continue
+      this.windows.set(name,{utilization:window.utilization,resetsAt:resetTime(window.resets_at)})
+      changed=true
+    }
+    if (typeof response.subscription_type==='string' && response.subscription_type!==this.subscription) {
+      this.subscription=response.subscription_type
+      changed=true
+    }
+    if (changed) {this.observedAt=now;this.available=true}
+    return changed
+  }
+  // A rejection read out of a transcript. Any session on this machine can supply it,
+  // which is what makes a block visible while Fleet itself is driving nothing.
+  static rejection(record) {
+    if (!record || typeof record!=='object') return null
+    const resetsAt=resetTime(record.resetsAt)
+    if (!resetsAt) return null
+    return {rateLimitType:record.rateLimitType || null,resetsAt,reason:record.reason || null,at:record.at || null,source:'transcript'}
+  }
+  snapshot({now=Date.now(),rejection=null}={}) {
+    // Whichever block is newer wins; both expire by themselves at their reset time.
+    const blocks=[live(this.blocked,now),live(UsageTracker.rejection(rejection),now)].filter(Boolean)
+    const blocked=blocks.sort((a,b)=>(b.at || 0)-(a.at || 0))[0] || null
+    const windows=[...this.windows.entries()]
+      .map(([name,w])=>({name,label:LABELS[name] || name,utilization:Math.round(w.utilization),resetsAt:w.resetsAt}))
+      .sort((a,b)=>WINDOWS.indexOf(a.name)-WINDOWS.indexOf(b.name))
+    // One bar on screen, drawn for whichever window is closest to stopping the fleet.
+    const binding=windows.reduce((worst,w)=>!worst || w.utilization>worst.utilization ? w:worst,null)
+    return {
+      available:this.available!==false,
+      known:windows.length>0 || !!blocked,
+      windows,
+      binding:binding ? binding.name:null,
+      subscription:this.subscription,
+      observedAt:this.observedAt,
+      stale:this.observedAt ? now-this.observedAt>STALE_MS:true,
+      blocked,
+    }
+  }
+}
+
+module.exports={UsageTracker,WINDOWS,LABELS,STALE_MS}