Plan-aware usage windows: a release-shipped plan catalog

Goal

jacked assumes every account has a 5-hour window. On 2026-10-30 Anthropic renamed Max 5x to Max and Max 20x to Ultra, and removed the 5-hour limit for verified Ultra accounts (weekly limits unchanged, plus a separate weekly Fable limit). ChatGPT Pro also has no 5-hour limit in Codex. This change moves "which windows does this account type have, what is it called, and how long is each window" into a data file that ships with each jacked release (jacked/data/usage_plans.json), so the next provider change is a data edit, and makes every consumer read windows through it. It also fixes the missing week-elapsed marker on the Fable row, for the whole class of model-scoped bars.

Evidence

• Anthropic help center, "What is the Ultra plan?" (support.claude.com/en/articles/17728952): "The Max 20x plan is now called the Ultra plan." "Verified Ultra accounts don't have a five-hour limit." "If your account isn't verified yet, a temporary limit applies." "If you don't see a Current session bar, your account is verified." Separate weekly Fable limit.
• Help center, "How do usage and length limits work?" (articles/11647753): weekly limits reset at a fixed time per account.
• Live payloads on this machine (2026-11-01): all 5 default_claude_max_20x accounts return five_hour: null and a limits[] with only weekly_all + weekly_scoped (Fable). Max 5x and Team return kind: "session". Profiles carry organization.plan_display_name: "Ultra" on the 20x rows.
• Codex Pro payload: one primary window, windowDurationMins: 10080, secondary: null.
• Keeper log: pings jumped from ~28/day to ~150/day on 2026-10-31; 290 pings at the 5 Ultra accounts since 10-30, each ping_ok_no_window, backoff stuck at 600 s ("1 consecutive failures" every time).
• Dashboard before: Ultra cards show "5h limit 0% retry due" and "Max subscription (20x tier)"; Fable rows have no marker.

Spec: acceptance criteria and non-goals

User-facing goal

Every surface shows the windows an account really has, under the plan's current name, with a week-elapsed marker on every bar; jacked stops spending pings and quota on windows that cannot exist; a future provider change is a catalog edit in a release.

Acceptance criteria

1. AC1 Catalog. jacked/data/usage_plans.json ships in the wheel, has version, verified_at, per-plan sources, window lengths, and plan entries for Claude (Ultra, Max, Team, Pro, Enterprise, Free, unknown-tier Max) and Codex (Pro, Plus). A missing or malformed file degrades to built-in defaults with a WARNING, never a crash. A newer version warns and reads best-effort.
2. AC2 Resolution. Given a verified Ultra row (payload without a session limit), the resolver returns session state absent; an unverified Ultra (payload with a session limit) returns present + temporary; a Max or Team row returns present whether or not a window is open; Codex Pro returns absent; a Codex partial read returns unknown.
3. AC3 Labels. Plan label precedence: provider plan_display_name, then catalog label, then the raw subscription type. Ultra rows read "Ultra" (hover "Formerly Max 20x"), Max 5x rows read "Max", Team reads "Team". No regex on the tier multiplier remains.
4. AC4 API. GET /api/auth/accounts and every WebSocket account payload carry plan and windows; usage.five_hour is null (not 0) for an absent window; every per-model and binding entry carries window_seconds.
5. AC5 Marker. Every usage bar that has a future reset shows the white elapsed marker, including the Fable binding row on the card, the per-model details list, the WebSocket live refresh, and the menu-bar panel. A source-scan test fails if any renderUsageBar call passes a literal null elapsed fraction.
6. AC6 Display. An absent 5h window renders an empty track, "none", and "not on Ultra" (hover: the catalog note); the panel caption reads "not on Ultra"; the tray pill reads "-·33%"; jacked usage shows "none" in the 5h columns and the plan label.
7. AC7 Keeper. The keeper never pings for a 5h window on an account whose session is absent (skip reason no_session_window); it still pings for a turned-over weekly window, and a 7d-only header reading is stored for such accounts; a ping_ok_no_window backoff escalates 600, 1200, 2400, 3600 s instead of resetting to 600 s.
8. AC8 Crashes. "Refresh all usage" and OAuth add/re-auth both succeed for an account whose payload has five_hour: null.
9. AC9 Decisions. Auto-swap's 5h headroom gate is explicit for absent windows; the 5h critical threshold comes from the catalog (Ultra 95, Max 90, Team 90, Pro/Free/Enterprise/unknown 80, unknown-tier Max 90); poll urgency for a no-session account follows its weekly and model-weekly windows; the burn-rate tracker updates when only 7d moves; the exhaustion banner's recovery time comes from each account's constrained windows and its text names no 5h window.
10. AC10 Pacing + skill text. jacked usage --json rows add plan, plan_id, session_window, model_limits; the summary adds best_account_worst_window, best_account_worst_window_resets_at, plan_catalog; the pinned fields keep their meaning. chain-of-command rule 7 reads the plan-agnostic fields.
11. AC11 Aging. A payload that contradicts the catalog (session on a never plan, silence on an always plan, an unlisted tier of a tier-split subscription, a provider plan name that differs from the catalog) logs one WARNING per shape per process and appears in plan.drift and summary.plan_catalog.drift.

Non-goals

• No new auto-swap departure rule for an account walled on its weekly or Fable limit (filed, see below).
• No change to the tray pill's color formula (the Fable cap does not tint the pill yet; filed).
• No user-editable override of the catalog; the catalog changes only with a release.
• No reading of pace, weekly_scoped_shares, seven_day_breakdown, or the dollar-denominated codename windows.
• No change to the 5h-window throughput heuristic in auto_swap/burn.py.

Architecture

flowchart LR
    J[jacked/data/usage_plans.json] --> L[jacked/usage_plans.py loader + resolver]
    R[(accounts row: subscription_type, rate_limit_tier, profile_json, cached_usage_raw)] --> L
    L --> P[resolve_plan: label, policy, critical pct, drift]
    L --> S[session_window: present / absent / unknown, temporary, seconds]
    L --> M[model window_seconds]
    P & S & M --> API[routes/auth.py AccountResponse.plan + windows]
    P & S & M --> WS[usage_monitor WS payload plan + windows]
    S --> K[window keeper skip + 7d-only cache]
    P --> D[auto_swap thresholds + labels]
    S --> U[compute_urgency_tier]
    S --> C[jacked usage + pacing summary]
    API & WS --> JS[usage.js renderModelBar + usageBarOpts per window key]
  

json catalog + account row -> usage_plans resolver -> {plan, session window, model window lengths}
-> API/WS payloads -> JS bars; -> keeper, auto-swap, urgency, CLI/pacing
  

Session resolution (evidence order)

1. The payload reports a session window (a limits[] entry with kind == "session", a five_hour object with a non-null utilization or reset, or a Codex short window): present; temporary on an until_verified plan; drift session_on_never_plan on a never plan (the payload still wins).
2. The payload is authoritative and silent: absent, except a Claude always plan, which stays present (silence can mean "no window open") with drift session_missing. A Codex always plan reads absent with drift session_missing (Codex lists every window an account has).
3. The payload is not authoritative, but the row still holds a 5-hour reading or reset (prior evidence): present (temporary on until_verified). A partial read must never erase a live window.
4. No evidence: never → absent; until_verified or any Codex plan → unknown; Claude always/reported → present (legacy idle reading).

"Authoritative" for Claude: the raw payload has a limits list AND every entry's kind is one jacked knows (session, weekly_all, weekly_scoped). An unknown kind makes the list non-authoritative and is drift unknown_limit_kind, so a renamed session kind can never read as "no 5-hour limit". For Codex: jacked.codex.usage.normalize_rate_limits(raw) gives five_hour.reported and windows_complete (authoritative). unknown counts as having a window for every decision (keeper, headroom, urgency): jacked never skips a window it cannot rule out.

Payload contract

"plan": {
  "id": "ultra",                 // catalog id, or null when no entry matched
  "label": "Ultra",              // provider plan_display_name > catalog label > raw subscription type (Title Case)
  "formerly": "Max 20x",         // or null
  "label_source": "provider",    // provider | catalog | raw
  "drift": [],                   // codes: session_missing, session_on_never_plan, unknown_tier, unknown_limit_kind, renamed
  "catalog_verified_at": "2026-11-01"
}
"windows": {
  "five_hour": {"state": "absent", "temporary": false, "seconds": 18000,
                "note": "Verified Ultra accounts have no 5-hour limit. Weekly limits still apply."},
  "seven_day": {"state": "present", "temporary": false, "seconds": 604800, "note": null}
}
ModelUsage / binding entries: + "window_seconds": 604800

AccountUsage.five_hour: the cached value; when the cached value is null it is 0 only for a Claude account whose session state is present, otherwise null. seven_day keeps today's rule (Codex null stays null, Claude null reads 0). menubar_summary.summarize_account uses the same rule.

File structure and ownership

Tasks

Task 0 (core, main loop): catalog, resolver, pacing helpers, TDD — DONE before dispatch

• tests/unit/test_usage_plans.py (91 tests) + module doctests; tests/unit/test_usage_pacing_windows.py; the pinned tests/unit/test_usage_cmd.py contract still passes.
• jacked/data/usage_plans.json, jacked/usage_plans.py (stdlib only at import; the Codex parser is imported lazily).
• usage_pacing.account_windows / worst_window / account_recovery_at; summary adds best_account_worst_window, best_account_worst_window_resets_at, plan_catalog.
• Plan-review cycle 2 fixes (core): a non-string limits[] kind is unknown_limit_kind drift, never a crash; normalize_rate_limits exposes each selected window's window_minutes and the resolver reuses it (a dropped or positional window never lends its length); model_window_seconds(..., plan=) honors per-plan lengths, and menubar_summary.parse_per_model(raw, plan=None) / binding_model_compact(raw, plan=None) emit window_seconds (+ is_active on the compact form) for every model entry (moved from B1 to core).

Public API (jacked/usage_plans.py)
load_catalog(data_root=None) -> Catalog ; catalog() -> Catalog (cached)
window_seconds(provider, kind) -> int                 # provider length (session | weekly | weekly_model)
resolve_plan(row) -> PlanMatch                        # id, label, formerly, label_source, session policy, session_critical_pct, drift, window_seconds(kind)
session_window(row, raw=MISSING, plan=None) -> SessionWindow   # state present|absent|unknown, temporary, seconds, note, drift
has_session(row, raw=MISSING) -> bool                  # False only for absent; unknown counts as a window
account_view(row, raw=MISSING) -> AccountView         # .plan .session .weekly_state .weekly_seconds
    .plan_payload() .windows_payload() .five_hour_reading() .projected_row()
project_row(row) -> row                               # 5h value and reset dropped when the window is absent
model_window_seconds(provider, window=None, slot="weekly_model") -> int
raw_usage(row) -> dict | None

jacked/service/usage_pacing.py
account_windows(acct, now) -> [(kind, pct, reset)]    # "5h" only when the plan has one
worst_window(acct, now) -> (kind, pct, reset) | None  # 7d wins ties
account_recovery_at(acct, now, constrained_threshold=90.0) -> datetime | None

Task B1: API and display backend (Opus builder, worktree pw-b1)

• routes/auth.py: PlanInfo, WindowInfo, AccountWindows; AccountResponse.plan, .windows; ModelUsage.window_seconds; _build_account_usage five_hour from five_hour_reading(); a resolver error never 500s the list.
• Bulk refresh row from the DB row read after the fetch; regression tests (Claude null five_hour, Codex raw result).
• web/oauth.py: seed with usage_cache_updates(usage); regression test.
• menubar_summary.py: summarize_account via five_hour_reading() (all-None guard); the API passes the row's plan into parse_per_model (window lengths are already in core).
• web/database.py raw-payload guard: the silent 10 KB skip becomes a generous bound (256 KiB); a payload over it CLEARS cached_usage_raw (never keeps the previous payload as evidence for fresh readings) and logs a WARNING that names the account and size (data-integrity rule: no silent drop); tests for both.
• Delete dead _tier_label + re-export + its test.

Task B2a: monitor and keeper (Opus builder, worktree pw-b2a)

• Keeper skip (no_session_window), 7d-only header cache, success confirmed against the windows that required the ping (a needed 5h window must show a future reset; a needed 7d window is confirmed by a fresh read with no reset at all, because the API omits it for days at a time, or by a reset that is no longer lapsed; a non-null reset that is still lapsed is not confirmed), backoff popped only on success; repeated-sweep, read-back-timeout and restart tests.
• Projection: every account dict the active poll loop, the candidate refresh, the poll-interval inputs and the clamps read passes through project_row, so no decision sees a stale 5h value on an absent window (cross-consumer regression test with a stale 5h=100 Ultra row: no 5h-critical departure, no 5h urgency).
• usage_cache_updates: an authoritative payload (a limits list whose kinds jacked knows) with no session entry and no five_hour object clears the 5h columns, even when the five_hour key is missing.
• Burn rate: unchanged only when 5h and 7d are both unchanged.
• WS payloads that carry an account row: add plan and windows.
• Exhaustion: next_recovery_at = min of account_recovery_at; log lines print "n/a" for a null 5h.
• compute_urgency_tier(..., *, has_session=True, usage_model=None) and its two callers.
• Decision reason reads "(plan Ultra)": usage_monitor stops importing tier_label (B2b deletes it) and uses resolve_plan(active_acct).label directly.

Task B2b: auto-swap and the usage CLI (Opus builder, worktree pw-b2b)

• diagnostics.tier_critical_threshold from the catalog; tier_label replaced by plan_label; exports and tests (realistic fixture for the fake 10x tier; Team and Codex Pro cases).
• selection._has_5h_headroom: True when the window is absent; docstring of consulted fields.
• tiers.white_bar and the 7d constant: the account's weekly length (account_view(acct).weekly_seconds).
• jacked usage: rows add plan, plan_id, session_window, model_limits, worst_window_pct, worst_window, worst_window_resets_at, active (the provider's active account in jacked's database, db.get_active_account_id(provider); no credential-store read); --provider claude|codex filters rows and the summary; table: plan label, "none" 5h cells, a Model column.

Task B3: frontend (Opus builder, worktree pw-b3)

• usage.js: computeElapsedFraction(resetsAt, windowSeconds); the 5h/7d helpers delegate to it; windowElapsed(acct, key) uses acct.windows[key].seconds; renderModelBar(model, opts) uses model.window_seconds; usageBarOpts(acct, windowKey, base); windowReason(acct, windowKey, nowMs): absent returns "not on <Plan>" / short form, absent + none, hint = note; unknown keeps "not reported"; renderUsageBar prints "none" for reason.none.
• accounts.js: plan text from acct.plan.label in a stable [data-plan-label] target (title "Formerly Max 20x", drift hint); binding + per-model bars through renderModelBar; card bars through the new helpers; the poll-tier fallback no longer guesses from 5h.
• panel.js: plan badge from org.plan.label; BOTH aggregate bars migrate to the window-key helpers; binding bar through renderModelBar.
• websocket.js: bars through the new helpers; binding through renderModelBar; refresh [data-plan-label] from the merged account (an event without plan keeps the current label).
• auto-swap.js: banner "Usage is available again in 3h 20m".
• Tests with the real shared helpers: markers on every bar class; absent 5h reads "none" + "not on Ultra" on the card and in the panel; plan labels; a WebSocket plan transition; call-site guard (no literal null elapsed fraction in any renderUsageBar call).

Task 4 (main loop): text

• chain-of-command rule 7: jacked usage --json --provider claude; read the row with active: true (worst_window_pct, worst_window_resets_at), and its Fable entry in model_limits for a Fable fan-out; fall back to summary.best_account_worst_window_pct when no row is active; keep the phrases the tests pin.
• README, docs/architecture/auto-swap-system.md sections 3 and 11.1, lessons.md.

Task 5 (main loop): combine, gate, review, prove

• Merge pw-b1, b2a, b2b, b3 into the feature branch; full local CI once (uv run --frozen ruff check ., uv run --frozen python -m pytest) to a log with the exit captured.
• /dcr at LARGE tier beside the gate.
• Proof with zero side effects (never start a server on real tokens): (1) a read-only script resolves account_view for every real row of ~/.claude/jacked.db (opened read-only) and prints plan + windows + projected 5h, compared against the live payload facts; (2) the dashboard and panel rendered by the branch in the scratch-HOME rig (temporary HOME, seeded fake accounts whose cached_usage_raw copies the real payload SHAPES with no tokens or emails, auto-swap and the keeper off, so no outbound call) and screenshotted; (3) the keeper exercised only through tests with every external call stubbed.
• PR with evidence; file the two issues below and link them.

Filed, not fixed here

• Auto-swap has no departure rule for an active account walled on its weekly (T2/T3) or Fable weekly limit; with no 5h window, Ultra accounts lose the de-facto exhaustion trigger. Pre-existing, account-switching behavior change, own PR.
• Tray pill color and max_pct ignore the model-scoped weekly cap (a Fable cap at 96% with 7d at 60% shows green). Product choice plus ranking change, own PR.

Decisions made (reviewable)

• Known plans documented to have a 5h limit use always (silence reads as an idle window), so an idle Max is never mistaken for a plan without the limit; drift logs if Anthropic ever drops the window for them.
• An Ultra row with no authoritative payload and no cached reading is unknown (treated as having a window), and a cached reading keeps a temporary window alive through a partial read: a wrong "absent" would also bypass the headroom gate and pacing, not just one keeper ping (pre-mortem finding).
• The 5h row stays on every card (empty track, "none", "not on Ultra") instead of disappearing: it states the plan fact, keeps cards in the grid aligned, and keeps the WebSocket child indexing stable.
• The provider's own plan name wins over the catalog label, so a rename shows up without a release; a mismatch is drift, not an error.