# 0015: Claude Code's subscription windows come from the status line, not the credential

Status: accepted; bridge installed and verified end to end.

Decision 0014 concluded that Claude Code cannot report a remaining balance.
That was wrong, and the error was one of not looking rather than of reasoning:
the transcript genuinely carries no quota, and that fact was generalised into a
claim about the harness. Claude Code reports its quota through three other
channels.

## The four surfaces

| Surface | Carries | Cost | Needs a credential |
|---|---|---|---|
| **Status line `rate_limits`** | `five_hour`, `seven_day` — `used_percentage` + `resets_at` | none; relayed from headers the CLI already received | no |
| Account usage endpoint | the same windows, plus per-model scoped limits | tight budget; 429s under polling | **yes** |
| Stream `rate_limit_info` | `status`, `rateLimitType`, `unifiedWindows` | none | no, but requires driving the harness |
| `/usage` in a PTY | rendered text | a turn | no, but screen-scraped |

The status-line shape is documented inside the CLI itself:

```text
"five_hour": {   // present only while the API reports it and its resets_at has not passed
  "used_percentage": number,  // Percentage of limit used (0-100)
  "resets_at": number         // Unix epoch seconds when this window resets
}
```

`rate_limits_available` is the honest-gap signal, also documented: "False when
plan rate limits do not apply (API key, Bedrock, Vertex, or missing profile
scope)". An account with no subscription window says so, rather than leaving
Lumbridge to infer it from an absence.

## Why the status line and not the endpoint

The account usage endpoint is more authoritative — it answers without an active
session and exposes per-model scoped limits. It also requires reading Claude
Code's OAuth credential, and AGENTS.md says Lumbridge "must not scrape their
private credentials." Other tools in this space do read it; that is their call
to make, and it is a real capability difference.

Lumbridge keeps the rule. The status line is pushed *to* a command the user
installs, so no credential is ever touched, and the data is free because the
CLI is relaying rate-limit headers it already received on its own API calls.
The cost is that a window only appears once a session has run, and that
installation edits `settings.json`.

The endpoint is recorded here as a rejected-for-now alternative rather than an
unconsidered one. Reopening it means amending AGENTS.md first.

## Provenance

`ProviderReported`. Under decision 0013's test the CLI forwards the provider's
number rather than computing one — the same standing as Codex's forwarded
`x-codex-*` headers. The footer shows `provider · exact`.

## The bridge

`scripts/claude-statusline-bridge.sh` is installed as Claude Code's
`statusLine` command. It appends the rate-limit fields — and only those — to
`$XDG_DATA_HOME/lumbridge/claude-rate-limits.jsonl`, and prints a status line.

Three properties it must hold:

- **It cannot fail.** A status-line command that errors or hangs degrades the
  user's session, so every step is guarded and it always exits 0 having
  printed something.
- **It copies nothing else.** The payload also carries the session's cost,
  transcript path, working directory, and model. The bridge builds a fresh
  record from three numeric fields per window rather than filtering the
  original, so there is no path by which the rest travels.
- **It stays bounded.** The feed rotates past 256 KB. Lines are appended rather
  than overwritten so concurrent sessions do not clobber each other; the probe
  reads the newest line, because each line is a complete snapshot and an older
  one is superseded, never summed.

Installation is a separate, explicit, reversible script — not something a probe
does on the user's behalf. It backs up `settings.json`, writes through a
temporary file, refuses to replace a `statusLine` someone else configured, and
supports `--dry-run` and `--uninstall`.

## Window handling

Each window becomes its own account-free profile — `claude-code-five-hour` and
`claude-code-seven-day` — because two windows are two facts about two quota
periods, and merging them means silently picking one. The pane maps to the
five-hour window: it is the limit that actually stops work.

A reading's window start is derived from `resets_at` minus the documented
window length, which is what lets the ledger scope a burn rate to one quota
period. Two rules follow decision 0012 unchanged: a window whose `resets_at`
has passed is stale, so its reset is dropped and only the percentage survives;
and a start the local clock places in the future costs the start, not the
reset, which is the half that bounds a forecast.

A percentage above 100 — possible on a gateway spend limit once breached — is
clamped to the whole rather than stored as more than a full window.