Anthropic's quota UI has a state where no quota window is currently open: the corresponding row replaces its "Resets in N hr M min" / "Resets H:MM PM" hint with the phrase "Starts when a message is sent." This applies independently to the 5-hour "Current session" row and the weekly "All models" row. This page documents how that state propagates end-to-end through the trayapp, from userscript detection to the slack gate, so behaviour in limbo is consistent and intentional rather than an accident of which component happens to default to what.
Without explicit handling, "no active session" produces wrong answers at every layer:
- The window engine could mint a phantom 5-hour window from a snapshot alone, even though the user has not actually started a session.
- Once such a phantom exists, dashboard charts would render a real session window and users would think their quota was burning down.
- The slack endpoint's session headroom gate measures
percent_usedagainstsession_absolute_threshold; if no real window exists,percent_usedis undefined and the gate would stay closed forever, deadlocking the queue exactly when the user has the most slack available.
The fix is to treat "no active session" as a first-class state with a tri-valued signal carried from the source through to the gate. No component invents the state on its own; each one acts on the same authoritative bit.
Throughout the system, session_active and weekly_active are each
tri-valued:
true— the corresponding window is genuinely active.false— limbo is positively detected. There is no active window and the source is sure of it.unknown(NULL / field absent) — the source cannot positively decide. Downstream consumers must not infer either presence or absence.
true is rarely emitted. The userscript never sets it; it relies on
the absence of the field to mean "I saw a normal Resets hint, so
nothing limbo-specific to report." Other ingestion paths may set it
explicitly when they have a positive truth signal.
The weekly path mirrors the session path one-to-one: same DOM scan,
same nullable INTEGER column (weekly_active, migration v6), same
"refuse to mint phantoms" guard in the windows engine, same
hypothetical placeholder in the dashboard. The only behavioural
asymmetry is that the weekly engine does not early-close an
existing real weekly row when limbo is observed (no analogue of the
session early-closure path); a stale phantom weekly row heals via
re-anchor when a snapshot supplies a real weekly_window_ends, or
via natural expiry.
userscript/claude-usage-snapshot.user.js scans both the Current
session row's DOM and the Weekly row's DOM for the literal text
"Starts when a message is sent" (case-insensitive) via a shared
isLimboLabel(bar) helper. When found on the session row, the
snapshot POST body includes "session_active": false; when found on
the weekly row, it includes "weekly_active": false. When not found,
the corresponding field is omitted — absence encodes "unknown," not
"active." Both fields are independent: the page commonly shows one
row in limbo while the other is normal. See docs/userscript.md and
docs/data-sources.md.
Cadence under limbo is sparse and freshness-driven, not periodic.
The userscript's freshness-driven dedup gate (see docs/userscript.md)
emits only on a meaningful-change signal. Inside limbo the visible
percent is frozen and the row text is constant ("Starts when a
message is sent"), so the only signals that fire are the limbo
text appearing or disappearing and — once the userscript is in limbo
— a strict decrease in the parsed "Last updated" age, which
indicates that claude.ai's own poll fetched a fresh page. Consequently
any consumer that previously assumed a snapshot every backstop tick
must instead treat the limbo observation stream as event-driven:
an event happens when limbo is entered, an event happens each time
a fresh poll lands, and an event happens when limbo is exited.
There is no fixed interval.
What reaches the DB is sparser still: the limbo-entered observation
inserts a new row, but each subsequent fresh-poll observation
typically matches every "match" field of the previous one, so the
server-side write-time slide (docs/data-model.md) collapses them
onto the existing row by refreshing its observed_at/received_at.
A limbo run therefore tends to surface as a single row whose
timestamps creep forward as fresh polls land, bracketed by the
limbo-entered start and a continuity-flagged-false row when limbo
exits.
The /snapshot handler accepts session_active and weekly_active
as nullable booleans. The quota_snapshots.session_active column
(added by migration v4 add_quota_snapshots_session_active) and
quota_snapshots.weekly_active column (added by migration v6
add_quota_snapshots_weekly_active) are both nullable INTEGER
storing 0 for false, 1 for true, and NULL for unknown. The
pointer-typed DTO fields preserve the absent / explicit-false
distinction across the JSON boundary. See docs/data-model.md.
The windows engine treats session_active=false / weekly_active=false
as authoritative for the moment of observation.
For session windows, three behaviours flow from that:
- Refuse to mint phantoms. When ensuring a session window from a
snapshot, the engine consults the most recent
session_activevalue. If it isfalse, no window is created. Zero session windows is a permitted state. - Early closure of the active window. When an active session
window already exists and a snapshot reports
session_active=false(withsession_used=0as a defensive contradiction check), the engine closes the window at the snapshot'sobserved_atrather than waiting for the calendar 5-hour expiry. A limbo snapshot whose (backdated)observed_atprecedes the window'sstarted_atdoes not close it: it describes the gap before this session, and closing on it would invert the window. This produces a clean boundary between "real session" and "post-closure limbo" so later evidence can be attributed correctly. - Event-anchored open (fallback). When no session window is
active,
session_activeis notfalse, and the most recent snapshot lacks a futuresession_window_ends, the engine falls back to ausage_events-based opening: a window opens iff an event exists whoseoccurred_atpostdates the most recent closed session window'sends_at(or no closed session window exists at all). The preferred path is still the snapshot's authoritative reset boundary when one is available; event-anchored opening exists so a tailer-only or hook-only host (no recent snapshot) can still produce a window when real activity is observed, instead of guessing a 5-hour boundary out of thin air.
For weekly windows, only the refuse-to-mint behaviour applies,
and it is gated on the boundary alone: when no real open weekly row
exists and no snapshot supplies a weekly_window_ends that is
strictly in the future (findWeeklyBoundary() returns zero, or
returns a timestamp ≤ now), the engine returns without inserting
a row — regardless of whether weekly_active is false, true,
or absent. The After(now) clause is critical: at every weekly
reset findWeeklyBoundary() returns the just-passed boundary from
pre-rollover snapshots, and a stale boundary is functionally the
same as no boundary — minting with it would produce a born-expired
row that the next tick closes and re-mints, a loop that floods the
table with zombie rows (38 closed rows accumulated in a single
~38-minute limbo gap before this guard was added). The engine has
no calendar fallback: anchoring a window on a guess (e.g. last
Monday UTC) would surface a real-looking week with no data instead
of letting the dashboard project a hypothetical [now, now + 7d]
from the current time. There is no early-closure path for weekly
either: an existing real weekly row is left alone and heals via
re-anchor (when a snapshot supplies a real future boundary) or
natural expiry.
reanchorIfStale carries the same future-only guard for the
existing-row path: it refuses to push an active window's ends_at
onto a past snapshot boundary, which would otherwise produce the
same born-expired loop one layer deeper.
The combined effect is that the windows table reflects what actually
happened, not what a snapshot's session_used / weekly_used value
alone would imply.
When the dashboard's /api/dashboard/state finds no active session
window, the backend synthesizes a hypothetical session window
spanning [now, now + 5h]; the frontend renders it ghosted: lighter
fill and stroke, italic font, with a two-line annotation reading "No
active session / projection if started now." The same treatment
applies to the weekly chart: when no active weekly window exists, the
backend synthesizes a hypothetical weekly window spanning
[now, now + 7d] and the frontend annotates it "No active weekly
window / projection if started now." The chart still has a curve to
look at, but the styling makes it unmistakable that this is a
projection rather than a measurement.
The Status panel reflects the same fact in text form: "not active"
when state.session_active is false, "active (Xh Ym remaining)"
otherwise. state.session_active is derived from the windows table
(a non-hypothetical real session row exists), not directly from the
raw snapshot column. The snapshot column reaches the panel only
indirectly: it triggers the windows engine to close or refuse the
real row, which then flips state.session_active. The panel and the
chart therefore always agree on whether a real session is open.
The session headroom gate in GET /slack is a disjunction of three
legs:
- Pace-relative surplus:
slack_fraction >= session_surplus_threshold. - Absolute floor:
percent_used <= 100 * (1 - session_absolute_threshold). - No active window at all — the deadlock-breaker.
The third leg fires when the response payload's session block is
nil, which happens precisely when the windows engine has no active
session window (because limbo closed it early or because event-anchored
opening has not yet been triggered). Without leg 3, legs 1 and 2 would
both evaluate against undefined values and the gate would never pass —
exactly when the user has the most free capacity to spare. With leg 3,
the queue is unblocked the moment limbo is observed.
session_absolute_threshold parameterises leg 2 only; setting it to
1.0 disables that leg without affecting the no-window short-circuit.
See docs/configuration.md for the threshold's semantics and
docs/slack-indicator.md for the full gate structure.
The weekly headroom gate has a parallel three-leg structure with the
same deadlock-breaker. When ensureWeeklyWindow refuses to mint —
under weekly_active=false limbo, an absent or stale
weekly_window_ends, or an empty DB — resp.Weekly is nil, and the
third leg fires so the queue is unblocked, symmetric to the session
path.
- The userscript never emits
session_active=trueorweekly_active=true. Absence of either field is the only way "I saw a normal Resets hint" is communicated. - The trayapp never invents
session_active/weekly_activefrom*_used. A snapshot withweekly_used=0and noweekly_activefield is "unknown," not "limbo." - A hypothetical window in the dashboard is never persisted to
windows. It is a backend-synthesized rendering construct only. - While the most recent snapshot has
session_active=false, no new session window opens, regardless of arrivingusage_eventsor later snapshots that still assert limbo. Recovery requires a newer snapshot whosesession_activeis notfalse(typically the userscript seeing a normal "Resets in …" hint again); from there either a futuresession_window_endsor a freshusage_eventpast the last closed window can mint a new row. - The weekly equivalent is narrower:
weekly_active=falseonly blocks minting when no snapshot supplies aweekly_window_endsthat is strictly in the future. A stale (past) boundary is treated the same as no boundary, both for the open path (ensureWeeklyWindow) and the re-anchor path (reanchorIfStale). Without the future-only guard, the engine would loop on close-and-mint of born-expired windows at every weekly reset.