@ucsandman/legcli 0.12.0 → 0.13.0

package/src/server.mjs

@@ -33,11 +33,13 @@ import { sessionDetail, sessionDiff, DiffInputError } from './session-detail.mjs
 import { hasRecentSynthesis } from './synthesis.mjs'
 import { refreshPointers } from './resume.mjs'
 import { landSession, landBlocker, landingNow, pruneSessionWorktree, canLand, prepareLanding, applyLandFix } from './land.mjs'
-import { readUsage, recordUsage, usageIsStale, candidates, isAvailable, fmtReset, binding, evaluateLadder, rungLabel, wallActive } from './usage.mjs'
-import { readAccounts, envFor, LAYOUT } from './accounts.mjs'
+import { readUsage, usageIsStale, candidates, isAvailable, fmtReset, binding, evaluateLadder, rungLabel, wallActive } from './usage.mjs'
+import { readAccounts } from './accounts.mjs'
+import { createUsagePollers, USAGE_AGENTS } from './usage-poll.mjs'
 import { readCodexUsage, transcriptTail as codexTranscriptTail } from './taps/codex.mjs'
 import { readPreferences, writePreferences, normalizeHandoffOrder, requireHandoffOrder, ladderFor, requireHandoffLadder, requireClimbBack, requireReserve, orderFromLadder } from './preferences.mjs'
 import { isDownshift } from './buckets.mjs'
+import { listModels } from './models.mjs'
 import { listHistory, findRecord, recordDetail, refreshIndex, readIndex, providerSupport, HistoryInputError, PROVIDER_NAMES } from './history/index.mjs'
 import { listWorktrees } from './history/worktrees.mjs'
 
@@ -575,6 +577,14 @@ function scrubOwnerUsage(s) {
   return out
 }
 
+// The usage poller appends `claude usage unavailable since 9:03 AM: <reason>`
+// to every active session of a login, a guest's own terminal included
+// (src/usage-poll.mjs). That line is the owner's reading — the reason their
+// endpoint is refusing and the clock it started — so it leaves with the rest of
+// the figures scrubOwnerUsage withholds. The recovery line says nothing about
+// the login and stays.
+const isUsageFailureEvent = (e) => e?.type === 'status' && /^\w+ usage unavailable since /.test(String(e?.summary ?? ''))
+
 // A guest owns their own terminal, so its picker rows are theirs to read, but
 // a rung's reason can quote this machine's usage ("at 63%, not below 80%",
 // "past your 10% reserve"), and a percentage of this machine's login belongs to
@@ -683,7 +693,11 @@ export function sessionsView({ viewer = null, share = null } = {}) {
     // the percentages are: they say how much of this machine's login is gone.
     // The guest branch at the bottom of this function drops the slot to
     // {agent, account, live, shared}, so nothing here reaches them.
-    accounts.push({ agent, account, five_hour: u.five_hour, seven_day: u.seven_day, limited_until: u.limited_until, limited_reason: u.limited_reason, source: u.source, observed_at: u.observed_at, updated_at: u.updated_at, stale: usageIsStale(u), live: sessions.filter((s) => s.active && s.agent === agent && s.account === account).length, buckets: u.buckets ?? [], walls: u.walls ?? {}, extra_usage: u.extra_usage ?? null, facts: u.facts ?? null })
+    // `error`/`error_since` are the READING's health, not the login's: they say
+    // the board could not ask, which is why a percentage is old. Owner-only for
+    // the same reason the percentages are, and dropped by the guest branch below
+    // with the rest of the slot.
+    accounts.push({ agent, account, five_hour: u.five_hour, seven_day: u.seven_day, limited_until: u.limited_until, limited_reason: u.limited_reason, source: u.source, observed_at: u.observed_at, updated_at: u.updated_at, stale: usageIsStale(u), live: sessions.filter((s) => s.active && s.agent === agent && s.account === account).length, buckets: u.buckets ?? [], walls: u.walls ?? {}, extra_usage: u.extra_usage ?? null, facts: u.facts ?? null, error: u.error ?? null, error_since: u.error_since ?? null })
   }
   const repos = new Map()
   for (const s of sessions) if (s.repo && (s.active || s.worktree) && !repos.has(canonPath(s.repo))) repos.set(canonPath(s.repo), s.repo)
@@ -903,8 +917,25 @@ function createSse({ healthIntervalMs = 10000, debounceMs = 30, sessionsDebounce
   return { add, stop, broadcast, clients }
 }
 
+// Which logins this board reads usage for. LEG_CLAUDE_BIN and LEG_GROK_BIN say
+// where a CLI lives, not that its login is fake, and gating on them switched
+// every percentage, every 5h/7d number and every usage_error off for a user
+// whose claude simply lives somewhere Leg's resolver does not look — with
+// nothing on the board to say why. codex is the one agent whose binary the
+// poller really needs, because it spawns the app-server to ask it; a stub there
+// cannot answer, so codex alone is skipped on its BIN var. A suite that must
+// reach no endpoint at all says so in one variable, LEG_NO_USAGE_POLL=1
+// (test/helpers.mjs sets it for every spawned board), and an injected fetcher
+// always wins: a test that supplied a reader is asking for it to be used.
+export function usageAgentsFor({ env = process.env, injected = {} } = {}) {
+  const set = (name) => env[`LEG_${name}`] || env[`BATON_${name}`]
+  const off = set('NO_USAGE_POLL') === '1'
+  const stubbedCodex = Boolean(set('CODEX_BIN'))
+  return USAGE_AGENTS.filter((a) => injected[a] || (!off && !(a === 'codex' && stubbedCodex)))
+}
+
 // ---- the server ----
-export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN || process.env.BATON_TOKEN || '', scheduler = (process.env.LEG_NO_SCHEDULER || process.env.BATON_NO_SCHEDULER) !== '1', share, usagePolling = false, usageReader = readCodexUsage } = {}) {
+export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN || process.env.BATON_TOKEN || '', scheduler = (process.env.LEG_NO_SCHEDULER || process.env.BATON_NO_SCHEDULER) !== '1', share, usagePolling = false, usageReader = readCodexUsage, usageFetchers = {} } = {}) {
   // An explicit `share` (tests) is fixed; the real server passes none and reads
   // share.json from disk, re-reading it per request (mtime-cached) so `leg
   // share add|rotate|rm` takes effect on a live board — a new link works at
@@ -991,27 +1022,19 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
     arm()
   }
   let sched = null
-  let usageTimer = null
-  let usageController = null
-  let usageInFlight = null
-  const refreshCodexAccounts = () => {
-    if (!usagePolling || ((process.env.LEG_CODEX_BIN || process.env.BATON_CODEX_BIN) && usageReader === readCodexUsage) || usageInFlight) return usageInFlight
-    usageController = new AbortController()
-    const signal = usageController.signal
-    usageInFlight = Promise.all((readAccounts().codex ?? ['default']).map(async (account) => {
-      const codexHome = envFor('codex', account).CODEX_HOME || LAYOUT.codex.home()
-      const r = await usageReader({ codexHome, timeoutMs: 8000, signal })
-      if (!r.ok) return false
-      recordUsage('codex', account, r.limits, 'codex app-server account/rateLimits/read', { observed_at: r.observed_at, available: r.available })
-      return true
-    })).then((changed) => {
-      if (changed.some(Boolean)) sse.broadcast('sessions', (viewer) => viewFor(viewer))
-    }).catch((err) => log(`codex usage refresh: ${err.message}`)).finally(() => {
-      usageInFlight = null
-      usageController = null
-    })
-    return usageInFlight
-  }
+  // ---- usage polling: one poller per LOGIN, not one per terminal ----
+  // The terminals used to ask their agent's endpoint once a minute each, so a
+  // login with three of them drew three times the requests and three copies of
+  // every 429 (src/usage-poll.mjs). The board asks once per login, backs off on
+  // a failure, and pushes what it read onto that login's active sessions.
+  const usageFetchersFor = { codex: usageReader, ...usageFetchers }
+  const injectedUsage = { codex: usageReader !== readCodexUsage, claude: Boolean(usageFetchers.claude), grok: Boolean(usageFetchers.grok) }
+  const usagePollers = createUsagePollers({
+    agents: usageAgentsFor({ injected: injectedUsage }),
+    fetchers: usageFetchersFor,
+    onChange: () => sse.broadcast('sessions', (viewer) => viewFor(viewer)),
+    onLog: (msg) => log(msg),
+  })
 
   async function handle(req, res) {
     const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`)
@@ -1054,7 +1077,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
     const canMachine = !shared || mayUseMachine(viewer.role)
     const ownsSession = (s) => !shared || viewer.role === 'owner' || (s.owner ?? share.owner) === viewer.name
     const parts = path.split('/').filter(Boolean) // ['api', ...]
-    if (!canCards && ['cards', 'floor', 'presets', 'adapters', 'leases'].includes(parts[1])) return send(res, 403, { error: 'the pipeline board belongs to the owner and the operators of this machine' })
+    if (!canCards && ['cards', 'floor', 'presets', 'adapters', 'leases', 'models'].includes(parts[1])) return send(res, 403, { error: 'the pipeline board belongs to the owner and the operators of this machine' })
     if (!canMachine && ['trunk', 'history', 'worktrees', 'audit'].includes(parts[1])) return send(res, 403, { error: 'this is the map of the machine itself: every repository path and every conversation on it. It belongs to the owner of this machine.' })
     try {
       if (req.method === 'GET' && path === '/api/health') {
@@ -1065,6 +1088,13 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
       }
       if (req.method === 'GET' && path === '/api/adapters') return send(res, 200, { adapters: await adaptersInfo() })
       if (req.method === 'GET' && path === '/api/presets') return send(res, 200, { presets: PRESETS })
+      // Which models this machine can start each agent on (src/models.mjs).
+      // Sits beside /api/adapters because it answers the second half of the
+      // same question — an adapter says WHO can run, this says WHAT it runs as
+      // — and it is guarded the same way: a guest picking a model is a guest
+      // spending the owner's plan. Never waits on a child process: agy's and
+      // grok's lists come off an hourly cache and refresh behind the answer.
+      if (req.method === 'GET' && path === '/api/models') return send(res, 200, listModels())
       if (req.method === 'GET' && path === '/api/cards') {
         const cards = listCards()
         return send(res, 200, { columns: columnsFor(cards), cards: cards.map((c) => summarize(c)) })
@@ -1165,11 +1195,32 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
           sse.broadcast('sessions', (v) => viewFor(v))
           return send(res, 200, { ok: true, request: hit })
         }
-        if (req.method === 'GET' && parts.length === 3) return send(res, 200, { session: sess, events: readSessionEvents(id), requests: readRequests(id) })
+        // A guest owns their own terminal, so this route hands them the record
+        // verbatim — including the two window percentages, the reading source
+        // and the poller's usage_error, every one of which the LIST route
+        // scrubs (`scrubOwnerUsage`, sessionsView). One GET of their own
+        // session id was the whole share boundary walked around. The same scrub
+        // runs here, and the poller's failure line is kept off their timeline:
+        // it names the owner's reason and the clock it started.
+        if (req.method === 'GET' && parts.length === 3) {
+          const asGuest = shared && viewer.role !== 'owner'
+          const events = readSessionEvents(id)
+          return send(res, 200, {
+            session: asGuest ? scrubOwnerUsage(sess) : sess,
+            events: asGuest ? events.filter((e) => !isUsageFailureEvent(e)) : events,
+            requests: readRequests(id),
+          })
+        }
         // the card's drawer: what the agent last said, what it changed, what it
         // has done. Only ever this viewer's own terminal; the guard above sent
         // anyone else away before we read a transcript.
-        if (req.method === 'GET' && parts[3] === 'detail') return send(res, 200, sessionDetail(sess))
+        if (req.method === 'GET' && parts[3] === 'detail') {
+          const detail = sessionDetail(sess)
+          // the drawer of a guest's OWN terminal is theirs; the poller's line
+          // about the owner's login is not (the same event the route above drops)
+          if (shared && viewer.role !== 'owner') detail.events = detail.events.filter((e) => !isUsageFailureEvent(e))
+          return send(res, 200, detail)
+        }
         if (req.method === 'GET' && parts[3] === 'diff') {
           try {
             return send(res, 200, sessionDiff(sess, url.searchParams.get('file') ?? ''))
@@ -1596,9 +1647,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
             sched.run().catch((err) => log(`scheduler crashed: ${err.message}`))
           }
           if (usagePolling) {
-            refreshCodexAccounts()
-            usageTimer = setInterval(refreshCodexAccounts, 60000)
-            usageTimer.unref?.()
+            usagePollers.start().catch((err) => log(`usage polling: ${err.message}`))
           }
           if (loopbackCompanion) {
             loopbackCompanion.on('error', (err) => log(`loopback companion: ${err.message}`))
@@ -1609,8 +1658,7 @@ export function createBoardServer({ bind, port, token = process.env.LEG_TOKEN ||
       })
     },
     async stop() {
-      if (usageTimer) { clearInterval(usageTimer); usageTimer = null }
-      usageController?.abort()
+      usagePollers.stop()
       for (const t of enqueueTimers.values()) clearTimeout(t)
       enqueueTimers.clear()
       sse.stop()

package/src/taps/claude-usage.mjs

@@ -119,6 +119,18 @@ export function extraUsageFrom(j) {
   return Object.keys(out).length ? out : null
 }
 
+// What a failing answer is allowed to say: the status code and the `type` the
+// body names ('rate_limit_error'), never the body itself. A login shared by
+// several terminals answers 429 often, and the whole JSON on every one of them
+// turned the terminal's timeline into a wall of payloads.
+function errorType(text) {
+  try {
+    const j = JSON.parse(text)
+    const t = j?.error?.type ?? j?.type
+    return typeof t === 'string' && t && t !== 'error' ? t : null
+  } catch { return null }
+}
+
 function getJson(url, headers, timeoutMs) {
   return new Promise((resolvePromise) => {
     const u = new URL(url)
@@ -147,7 +159,10 @@ export async function fetchClaudeUsage({ configDir = LAYOUT.claude.home(), timeo
   if (!t) return { ok: false, limits: null, error: 'no claude.ai login found in ' + configDir }
   const r = await getJson(url, { Authorization: `Bearer ${t.token}`, 'anthropic-beta': 'oauth-2025-04-20', Accept: 'application/json', 'User-Agent': 'legcli' }, timeoutMs)
   if (r.error) return { ok: false, limits: null, status: 0, error: r.error }
-  if (r.status !== 200) return { ok: false, limits: null, status: r.status, expired: t.expired, error: `usage endpoint ${r.status}: ${r.text.slice(0, 120)}` }
+  if (r.status !== 200) {
+    const kind = errorType(r.text)
+    return { ok: false, limits: null, status: r.status, expired: t.expired, error: `usage endpoint ${r.status}${kind ? `: ${kind}` : ''}` }
+  }
   let j
   try { j = JSON.parse(r.text) } catch { return { ok: false, limits: null, status: r.status, error: 'usage endpoint returned no JSON' } }
   const limits = { five_hour: window(j.five_hour), seven_day: window(j.seven_day), extra_usage: extraUsageFrom(j) }

package/src/usage-poll.mjs

@@ -0,0 +1,260 @@
+// usage polling: one poller per LOGIN, living in the board process.
+//
+// Why here and not in the terminal: every attached terminal used to ask its
+// agent's usage endpoint once a minute (src/attach.mjs). Three claude
+// terminals on one login, next to Claude Code's own polling, drew a 429 every
+// other minute, and each failure wrote a session event, so the timeline read as
+// a wall of rate-limit payloads. A login has ONE poller now, wherever its
+// terminals are, and what it reads is pushed onto every active session of that
+// login exactly as the terminal used to write it.
+//
+// Backoff is per login: an answer that is not usable doubles the wait up to
+// USAGE_POLL_MAX_MS, and the first usable one puts it straight back to the base
+// interval. The failure is recorded ONCE, on the usage record (`error`,
+// `error_since`, src/usage.mjs), with one status event on that login's
+// sessions when it starts and one when it ends.
+//
+// What stays in the terminal: anything measured from that terminal's own files
+// (the codex rollout scan, the transcript's model line). Only the per-login
+// endpoint reads moved here.
+import { LAYOUT, readAccounts, envFor } from './accounts.mjs'
+import { listSessions, isActive, updateSession, appendEvent } from './sessions.mjs'
+import { recordUsage, noteUsageError } from './usage.mjs'
+import { fetchClaudeUsage } from './taps/claude-usage.mjs'
+import { fetchGrokUsage } from './taps/grok.mjs'
+import { readCodexUsage } from './taps/codex.mjs'
+
+// The interval is a knob a human types, so it arrives as "5m", "60_000" or
+// "60 000" as readily as a number. Number() turns all three into NaN, every
+// timer was then armed with NaN, Node rounds that to 1ms, and the board asked
+// the usage endpoint about a thousand times a second per login — with a backoff
+// that could never rescue it, because Math.max(NaN, delay) * 2 is NaN too.
+// A value Leg cannot read is the default; a value under the floor is the floor,
+// because no reading of a plan's percentages is worth a request every second.
+export const USAGE_POLL_FLOOR_MS = 5000
+
+export function clampPollMs(raw, fallback, floorMs = USAGE_POLL_FLOOR_MS) {
+  if (raw === undefined || raw === null || raw === '') return fallback
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n <= 0) return fallback
+  return Math.max(floorMs, n)
+}
+
+const rawInterval = process.env.LEG_USAGE_POLL_MS || process.env.BATON_USAGE_POLL_MS
+const rawMax = process.env.LEG_USAGE_POLL_MAX_MS || process.env.BATON_USAGE_POLL_MAX_MS
+export const USAGE_POLL_MS = clampPollMs(rawInterval, 60000)
+export const USAGE_POLL_MAX_MS = clampPollMs(rawMax, 10 * 60 * 1000, USAGE_POLL_MS)
+
+// A knob that was typed and not used says so once on the board's log: silence
+// there is how a user learns nothing, and keeps typing "5m".
+const unread = (name, raw, used) => (raw === undefined || raw === null || raw === '' || (Number.isFinite(Number(raw)) && Number(raw) > 0)
+  ? null
+  : `${name}=${String(raw).slice(0, 40)} is not a number of milliseconds; reading usage every ${used}ms instead`)
+export const USAGE_POLL_NOTES = [
+  unread('LEG_USAGE_POLL_MS', rawInterval, USAGE_POLL_MS),
+  unread('LEG_USAGE_POLL_MAX_MS', rawMax, USAGE_POLL_MAX_MS),
+].filter(Boolean)
+const said = new Set()
+
+export const USAGE_AGENTS = ['claude', 'codex', 'grok']
+
+// The wording on the card and in the record: one name per reading source, the
+// same strings the terminals wrote before this moved.
+const SOURCE = {
+  claude: 'claude usage endpoint',
+  codex: 'codex app-server account/rateLimits/read',
+  grok: 'grok billing proxy',
+}
+
+// "9:03 AM": the time a human reads on a card, not an ISO stamp.
+export function clockTime(iso) {
+  const ms = Date.parse(iso ?? '')
+  if (!Number.isFinite(ms)) return 'just now'
+  const d = new Date(ms)
+  const h = d.getHours()
+  return `${h % 12 || 12}:${String(d.getMinutes()).padStart(2, '0')} ${h < 12 ? 'AM' : 'PM'}`
+}
+
+function configDirFor(agent, account) {
+  const l = LAYOUT[agent]
+  if (!l) return null
+  return (l.env ? envFor(agent, account)[l.env] : null) || l.home()
+}
+
+// One reading for one login → { ok, error } or { ok: true, patch }, where the
+// patch is what every active session of that login gets.
+// `halted` is the answer when the board stopped while the endpoint was still
+// thinking: the reading is thrown away rather than recorded, because every
+// write it would make (the usage record, a session's percentages, a line on a
+// timeline, an SSE push) belongs to a board that no longer exists.
+async function readLogin(agent, account, { read, timeoutMs, signal, stopped = () => false }) {
+  const configDir = configDirFor(agent, account)
+  if (agent === 'codex') {
+    const r = await read.codex({ codexHome: configDir, timeoutMs, signal })
+    if (stopped()) return { halted: true }
+    if (!r.ok) return { ok: false, error: r.error ?? 'the codex app server answered with no rate limits' }
+    const u = recordUsage('codex', account, { ...r.limits, facts: r.facts }, SOURCE.codex, { observed_at: r.observed_at, available: r.available })
+    const patch = { limits: r.limits, usage_source: SOURCE.codex }
+    // an explicit "ordinary usage is unavailable" is the wall itself, and the
+    // terminal hands off on it (src/attach.mjs reads status from the record)
+    if (r.available === false) {
+      patch.status = 'limit'
+      patch.limit = { reason: 'usage_limit_exceeded', detail: 'Codex reports ordinary usage is unavailable', resets_at: u.limited_until, at: r.observed_at ?? new Date().toISOString() }
+    }
+    return { ok: true, patch }
+  }
+  const r = agent === 'claude'
+    ? await read.claude({ configDir, timeoutMs })
+    : await read.grok({ configDir, timeoutMs })
+  // neither reader takes an AbortSignal, so the wait is not cut short by stop();
+  // what it must not do is come back and write
+  if (stopped()) return { halted: true }
+  const usable = r.ok && r.limits && (r.limits.five_hour || r.limits.seven_day)
+  if (!usable) return { ok: false, error: r.error ?? 'the usage endpoint answered with no window' }
+  recordUsage(agent, account, r.limits, SOURCE[agent])
+  // the session record keeps the two windows it always had: the buckets live on
+  // the usage record, which is per login and not per terminal
+  const limits = agent === 'claude' ? { five_hour: r.limits.five_hour, seven_day: r.limits.seven_day } : r.limits
+  return { ok: true, patch: { limits, usage_source: SOURCE[agent] } }
+}
+
+// → { start, stop, pollNow, delayOf, logins }
+// `schedule`/`cancel` are seams: a test drives the clock by hand instead of
+// waiting minutes for a backoff to prove itself.
+export function createUsagePollers({
+  agents = USAGE_AGENTS,
+  fetchers = {},
+  intervalMs = USAGE_POLL_MS,
+  maxMs = USAGE_POLL_MAX_MS,
+  timeoutMs = 8000,
+  onChange = () => {},
+  onLog = () => {},
+  accounts = readAccounts,
+  schedule = (fn, ms) => { const t = setTimeout(fn, ms); t.unref?.(); return t },
+  cancel = (t) => clearTimeout(t),
+} = {}) {
+  const read = { claude: fetchClaudeUsage, grok: fetchGrokUsage, codex: readCodexUsage, ...fetchers }
+  const state = new Map()
+  let stopped = false
+  let controller = new AbortController()
+
+  const key = (agent, account) => `${agent}--${account}`
+  function slot(agent, account) {
+    const k = key(agent, account)
+    if (!state.has(k)) state.set(k, { agent, account, delay: intervalMs, timer: null, inFlight: null })
+    return state.get(k)
+  }
+
+  function sessionsOf(agent, account) {
+    try { return listSessions().filter((s) => s && s.agent === agent && s.account === account && isActive(s)) } catch { return [] }
+  }
+
+  // Write to one terminal of this login. The leg can hand off between the read
+  // and the write, so the patch is applied inside the record's own lock and
+  // only while the record still names this login: claude's percentages, and
+  // claude's failure line, must never follow codex onto the card. The event is
+  // written after, and only if the patch was the right terminal's.
+  function pushToSession(id, agent, account, patch, event) {
+    const next = updateSession(id, (cur) => (cur.agent === agent && cur.account === account && isActive(cur) ? patch : {}))
+    if (event && next && next.agent === agent && next.account === account) appendEvent(id, event)
+    return next
+  }
+
+  // One reading, then the fan-out. Single-flight per login: a slow endpoint
+  // never stacks two requests on one login, whatever the timer does.
+  function tick(agent, account) {
+    const st = slot(agent, account)
+    if (st.inFlight) return st.inFlight
+    const run = (async () => {
+      let r
+      try {
+        r = await readLogin(agent, account, { read, timeoutMs, signal: controller.signal, stopped: () => stopped })
+      } catch (err) {
+        r = { ok: false, error: String(err?.message ?? err).slice(0, 200) }
+      }
+      // stop() means stop: a reading that lands after the board has gone is
+      // dropped whole, so nothing is written and onChange never fires into a
+      // closed SSE hub.
+      if (stopped || r.halted) return { ok: Boolean(r.ok), changed: false }
+      let changed = false
+      if (r.ok) {
+        const cleared = noteUsageError(agent, account, null)
+        const event = cleared.changed ? { type: 'status', summary: `${agent} usage is back` } : null
+        for (const s of sessionsOf(agent, account)) pushToSession(s.session_id, agent, account, { ...r.patch, usage_error: null }, event)
+        changed = true
+      } else {
+        // The failure is the RECORD's, and the timeline hears about it once:
+        // the event is written on the transition alone, so a long outage is one
+        // line and not one line per refusal.
+        //
+        // The CARD is a different question. A reason that changes mid-outage
+        // (logged out, then a stale token answering 401) left every card naming
+        // the first cause for the rest of the outage, sending the user to fix
+        // something already fixed. The text is pushed whenever it differs from
+        // what the row carries; the event stays null, so the timeline is still
+        // one line per outage while the card stays truthful.
+        const noted = noteUsageError(agent, account, r.error)
+        const event = noted.changed ? { type: 'status', summary: `${agent} usage unavailable since ${clockTime(noted.error_since)}: ${r.error}` } : null
+        for (const s of sessionsOf(agent, account)) {
+          if (noted.changed || s.usage_error !== noted.error) pushToSession(s.session_id, agent, account, { usage_error: noted.error }, event)
+        }
+        changed = noted.changed
+        if (noted.changed) onLog(`${agent}/${account} usage: ${r.error}`)
+      }
+      st.delay = r.ok ? intervalMs : Math.min(maxMs, Math.max(intervalMs, st.delay) * 2)
+      return { ...r, changed }
+    })()
+    st.inFlight = run.finally(() => { st.inFlight = null })
+    return st.inFlight
+  }
+
+  function arm(agent, account) {
+    if (stopped) return
+    const st = slot(agent, account)
+    if (st.timer) return
+    st.timer = schedule(() => { st.timer = null; return cycle(agent, account) }, st.delay)
+  }
+
+  // A login added while the board is up (leg account add) starts polling on the
+  // next round rather than on the next restart.
+  function adopt(agent) {
+    if (stopped) return
+    for (const account of accounts()[agent] ?? ['default']) if (!state.has(key(agent, account))) cycle(agent, account)
+  }
+
+  async function cycle(agent, account) {
+    let r = null
+    try {
+      r = await tick(agent, account)
+      if (r?.changed) onChange()
+    } catch (err) {
+      onLog(`${agent}/${account} usage poll: ${err.message}`)
+    }
+    adopt(agent)
+    arm(agent, account)
+    return r
+  }
+
+  return {
+    // → a promise for the FIRST round, so a caller (or a test) can wait for one
+    // complete reading of every login without knowing the timer.
+    start() {
+      stopped = false
+      controller = new AbortController()
+      for (const note of USAGE_POLL_NOTES) if (!said.has(note)) { said.add(note); onLog(note) }
+      const acc = accounts()
+      const first = []
+      for (const agent of agents) for (const account of acc[agent] ?? ['default']) first.push(cycle(agent, account))
+      return Promise.all(first)
+    },
+    stop() {
+      stopped = true
+      for (const st of state.values()) { if (st.timer) cancel(st.timer); st.timer = null }
+      try { controller.abort() } catch {}
+      state.clear()
+    },
+    pollNow: (agent, account = 'default') => cycle(agent, account),
+    delayOf: (agent, account = 'default') => state.get(key(agent, account))?.delay ?? null,
+    logins: () => [...state.values()].map((s) => ({ agent: s.agent, account: s.account, delay: s.delay })),
+  }
+}

package/src/usage.mjs

@@ -46,7 +46,39 @@ export function readUsage(agent, account = 'default') {
 }
 
 function emptyUsage(agent, account) {
-  return { agent, account, five_hour: null, seven_day: null, limited_until: null, limited_reason: null, limited_at: null, source: null, observed_at: null, available_at: null, updated_at: null, buckets: [], walls: {}, history: {}, extra_usage: null, facts: null }
+  return { agent, account, five_hour: null, seven_day: null, limited_until: null, limited_reason: null, limited_at: null, source: null, observed_at: null, available_at: null, updated_at: null, buckets: [], walls: {}, history: {}, extra_usage: null, facts: null, error: null, error_since: null }
+}
+
+// The READING's health, which is not the login's health: a 429 from the usage
+// endpoint says nothing about how much of the plan is left, so it never touches
+// the windows, the buckets or a wall. It is written once — `error_since` keeps
+// the moment it started — and cleared by the first reading that works, so the
+// board can say "unavailable since 9:03 AM" instead of one line per failed
+// poll (src/usage-poll.mjs).
+// → { error, error_since, changed } — `changed` is the transition only, which
+// is what decides whether a session event is worth writing.
+export function noteUsageError(agent, account, error, { at = new Date().toISOString() } = {}) {
+  let changed = false
+  const value = mutate(agent, account, (u) => {
+    if (!error) {
+      if (!u.error && !u.error_since) return false
+      u.error = null
+      u.error_since = null
+      changed = true
+      return u
+    }
+    const why = String(error).slice(0, 300)
+    if (u.error) {
+      if (u.error === why) return false
+      u.error = why
+      return u
+    }
+    u.error = why
+    u.error_since = at
+    changed = true
+    return u
+  })
+  return { error: value.error ?? null, error_since: value.error_since ?? null, changed }
 }
 
 // The ring key for a bucket: the kind alone when it is account-wide, the kind