@modelprofile.com/authswitch 3.3.0 → 5.0.0

package/readme.md

@@ -58,9 +58,11 @@ authswitch active                 # which account each provider is using right n
 authswitch codex stash            # save the active credential under its account email
 authswitch codex list             # Codex accounts, including an unsaved active login, with live status
 authswitch codex use [email]      # activate one; prompts when no email is given
-authswitch claude use [email] --stop        # stop running Claude Code instances first
-authswitch claude use [email] --keep-running  # switch without stopping anything
+authswitch opencode use [email] --stop        # stop running OpenCode instances first
+authswitch opencode use [email] --keep-running  # switch without stopping anything
 authswitch codex preuse <email>   # send the default prompt without activating the account
+authswitch watch                  # check usage every 2 minutes and switch when an account runs out
+authswitch claude watch --threshold 90 --dry-run  # report what it would switch, for one harness
 authswitch codex current          # print the account currently in use
 authswitch codex drop <email>     # forget a stash
 authswitch codex doctor           # report credential storage and remote-control state
@@ -81,25 +83,42 @@ the management TUI and human/JSON lists. With an AGL installation that supports
 authswitch coordination, the CLI delegates credential changes to AGL. AGL owns
 stopping and restarting its OpenCode runtime. Idle changes need no additional
 restart confirmation; active work requires consent to wait for it to finish.
-Every operation, including `use` and `stash`, now works while OpenCode or Claude
+Every operation, including `use` and `stash`, works while OpenCode or Claude
 Code is running: the credential file is written atomically, the outgoing login is
 re-saved from disk first, and a write that races a native rewrite is detected and
-refused rather than half-applied. Status lookups remain read-only. `preuse`
-remains a Codex capability.
+refused rather than half-applied. A running Claude Code picks a switch up on its next
+request, so it never needs a restart. Status lookups never activate, switch or clear a
+login; reading a saved Claude login whose access token has expired does renew that saved
+copy's own tokens, and nothing else. `preuse` remains a Codex capability.
 
 #### Running instances during a switch
 
-A harness that keeps running through a switch still costs something: it holds the
-previous login in memory and can write it back at its next OAuth token refresh.
-So before `use` and before `stash` without `--keep`, authswitch lists that
-harness's own running instances -- pid, start time and command line -- and offers
-to stop them:
+**Claude Code picks a switch up live.** A running session re-reads its credential
+file whenever the file changes, before its next request, and reloads `.claude.json`
+when that changes (verified against Claude Code 2.1.273). So `use`, `stash` and a
+backend activation never ask for Claude Code to be stopped and never suggest a
+restart; a switch reports `Running Claude Code sessions use it from their next
+request.` What authswitch must not do is write in the middle of that session's own
+writes, so every Claude Code operation that reads or writes the native login runs
+while holding Claude Code's own locks, taken with its own library and options: the
+OAuth refresh lock (`<config dir>/.oauth_refresh.lock` and its legacy twin
+`<config dir>.lock`), the credential write lock (`<config dir>/.storage-write.lock`)
+and the global config lock (`.claude.json.lock`). A lock Claude Code holds is waited
+for up to 15 seconds, without holding the others meanwhile, so a live session is
+never blocked by a waiting switch; after that the operation fails with nothing
+changed. A lock left behind by a Claude Code that died goes stale after its own
+threshold and is taken over, as Claude Code itself would.
+
+**OpenCode keeps the previous login until it restarts.** It holds that login in
+memory and can write it back at its next OAuth token refresh. So before `use` and
+before `stash` without `--keep`, authswitch lists OpenCode's own running instances --
+pid, start time and command line -- and offers to stop them:
 
 ```
-2 Claude Code process(es) are running:
-  pid 4821  started 2026-09-16 14:02 UTC  claude --session-id 9f2c
-  pid 5533  started 2026-09-16 14:02 UTC  claude agents
-? Stop these 2 Claude Code process(es) first? (y/N)
+2 OpenCode process(es) are running:
+  pid 4821  started 2026-09-16 14:02 UTC  opencode
+  pid 5533  started 2026-09-16 14:02 UTC  opencode serve
+? Stop these 2 OpenCode process(es) first? (y/N)
 ```
 
 Answering yes sends `SIGTERM` to exactly those pids and waits up to ten seconds;
@@ -112,6 +131,10 @@ decide the same thing without a prompt:
 | `--force-stop` | the same, then `SIGKILL` the ones that ignored `SIGTERM` |
 | `--keep-running` | switch without stopping anything |
 
+`--stop` and `--force-stop` also stop Claude Code's instances when you ask for it;
+without them nothing about Claude Code's processes is listed or offered, and
+`--keep-running` is accepted and changes nothing.
+
 Without a terminal and without a flag, nothing is ever signalled: the instances are
 listed, the switch proceeds, and the command says which flag would have changed that.
 `SIGKILL` is only ever sent for `--force-stop`. Only pids authswitch enumerated for
@@ -123,8 +146,8 @@ On Windows the instances are listed but not stopped, because its process list do
 not identify their owner. `stash --keep` needs none of this: it writes no native
 file and is guarded by proving the native sources unchanged around the read.
 
-After a switch that left instances running, the command says so explicitly, because
-one of them refreshing its token can put the previous account back. A backend
+After an OpenCode switch that left instances running, the command says so explicitly,
+because one of them refreshing its token can put the previous account back. A backend
 activation through `AuthSwitchService` gets that same caveat in its outcome, but no
 listing and no offer: a host has no terminal to consent with, and a supervisor that
 completed the mutation itself owns its own runtime's lifecycle.
@@ -206,7 +229,43 @@ and model windows.
 These endpoints require the `user:profile` scope and may reject expired or restricted
 logins. A null reset timestamp is shown as **Not scheduled**. Billing renewal and
 cancellation dates and earned reset credits are unavailable from these endpoints;
-authswitch does not infer them from account creation or token expiry dates.
+authswitch does not infer them from account creation or token expiry dates. The
+Claude Code adapter declares that, so `limits` explains it once for the provider
+instead of per account.
+
+Nothing but Claude Code refreshes a Claude login, so a saved one stops being readable
+a few hours after it was saved. Reading a **saved, inactive** account's status therefore
+refreshes it first, exactly as Claude Code would: when its access token expires within
+five minutes, authswitch exchanges the stored refresh token at Claude's token endpoint,
+keeps every other field of the login, and writes the result only while the saved record
+still holds the refresh token it sent. The refresh holds the account store's lock, so a
+switch started at the same time waits for it and then activates the refreshed login. The
+**active** login is never refreshed -- Claude Code owns it, and two parties refreshing one
+login can invalidate the grant. A refusal is reported, never worked around -- a rejected
+grant says so and says what fixes it (below), and a service failure, an unreachable service
+or an unsupported response leave the saved login untouched. Requests carry `User-Agent:
+authswitch/<version>`, and HTTP 429 is reported as rate limiting with the service's retry
+time -- never as an exhausted or expired account.
+
+Claude Code also rotates the refresh token of the login it **is** running on, so reading the
+accounts (`list`, `limits`, `active`, `current`, `watch`, the dashboard) mirrors that login
+into its own saved record whenever the two differ. Without it a login replaced outside
+authswitch -- a `/login` in Claude Code, a new device login -- left the stash holding the
+token from before the rotation, which the sign-in service can refuse: it did for two saved
+logins on 2026-09-18. The record keeps its account, its identity and its save time, Claude
+Code's own files are only ever read, and a login with no saved record of its own is never
+saved implicitly; `stash` is what saves a login. An installation whose native login
+authswitch cannot read mirrors nothing, and a read waits at most a second for a lock a
+switch or Claude Code holds before leaving the saved copy to the next read.
+
+A grant the sign-in service refused is remembered in the saved record itself, as a hash of
+the refresh token -- never the token -- so a new authswitch run, a restarted watch or a
+second dashboard does not replay a dead login. Saving that login again clears it, as does
+any refresh that replaces the saved credential. Such a login reports `Login expired or was
+rejected. Log in again with Claude Code and save it. Claude Code rotates a login's refresh
+token as it uses it, and the service can refuse the older one a saved copy still holds once
+that login has been replaced outside authswitch; authswitch claude stash --keep saves the
+new one.`
 
 OpenCode and Claude saved records are separate owner-only files under
 `~/.authswitch/opencode` and `~/.authswitch/claude`. Emails are accepted as account
@@ -251,6 +310,70 @@ inference failure exits with 1, invalid arguments or unsupported harnesses with
 2, and an interrupted prompt with 130. Check `authswitch list` before repeating
 an uncertain request. `--json` remains a list-only option.
 
+### Watching usage and switching automatically
+
+`authswitch watch` reads every account's usage on an interval and switches a harness to a
+better saved account when the one in use runs out:
+
+```bash
+authswitch watch                              # every harness that supports it, every 2m, at 95%
+authswitch claude watch                       # one harness (also: authswitch watch claude)
+authswitch watch --interval 5m --threshold 90 # check less often, switch earlier
+authswitch watch --dry-run                    # report decisions, change nothing
+authswitch watch --once                       # one check, then exit
+authswitch watch --json                       # one JSON event per line
+```
+
+```
+14:02:07 Watching Claude Code, Codex every 2m; switching at 95%.
+14:02:07 Running Codex sessions keep the login they loaded; new sessions use the switched one.
+14:02:09 Claude Code alice@example.com (type:Max) (5h:17%) (w:4%) ok
+14:02:10 Codex switched bob@example.com → carol@example.com (type:Pro) (5h:3%) (w:12%) — Codex weekly 96% ≥ 95%
+14:04:09 Claude Code alice@example.com (type:Max) (5h:21%) (w:4%) ok
+14:04:10 Codex carol@example.com (type:Pro) (5h:4%) (w:12%) ok
+```
+
+Watch covers the harnesses whose adapter declares `autoSwitch`: Claude Code and Codex.
+OpenCode is not watched, because most of its providers report no usage and its lifecycle
+belongs to its supervisor. Naming an unsupported harness exits with 2, as does an interval
+outside 1 minute to 1 day, a threshold outside 50 to 100, or any other argument the command
+cannot act on. `--interval` takes seconds or a unit (`120`, `90s`, `2m`, `1h`, `1d`).
+
+**How it decides.** Each check reads the harness's accounts and every account's usage, then
+applies one rule set per harness:
+
+- The account in use is *used up* when any of its general account windows has reached the
+  threshold. The watch then switches to the saved account whose account windows are all at
+  least ten points below the threshold, preferring the one whose longest window resets
+  soonest (capacity that expires first is used first), then the least used, then by name.
+- When every other saved account is used up too, it switches to the one that is usable
+  again first, and only when that is more than one interval sooner than the account in use.
+- An account limited only on a feature window (one model or surface) is traded for an
+  account that is below the margin on *every* window; without one it stays, because it
+  still serves everything else.
+- A reading that is unknown, too old, rejected or rate limited never counts as used up and
+  never makes an account a target. The line then says so instead of saying `ok`.
+
+**What it does and does not do.** A switch goes through the same path as `use`, including
+AGL coordination when AGL manages the login, and never asks for a session of yours to be
+stopped: Claude Code picks the new login up on its next request, and running Codex sessions
+keep the login they loaded while new ones use the switched account (the start line says so
+once). A Codex switch does stop and start Codex' own managed app-server, because `auth.json`
+cannot be rewritten underneath it, so its remote-control connection drops for a moment. A
+switch that is refused or fails is reported and decided again on the next check. Checks
+never overlap; a check that takes longer than the interval is followed by the next one at
+once. An account whose lookup a provider refused (HTTP 429) or whose lookup failed is not
+asked about again until the time the provider named, or after a delay that doubles from one
+interval up to half an hour, and the account's last reading stands in meanwhile while it is
+less than ten minutes old. Claude's profile is read at most once an hour per account while
+watching; usage is always live.
+
+One watch runs per `AUTHSWITCH_HOME`: a second one exits with 1 and names the running pid,
+and a lock left behind by a watch that died is taken over. Ctrl-C or `SIGTERM` cancels the
+lookups in flight, releases the lock and exits with 0. `--once` exits with 0, or 1 when a
+switch it attempted did not complete. `--json` writes one event per line
+(`start`, `tick`, `switch`, `error`) with accounts, readings and reasons, and no credential.
+
 ### Management dashboard
 
 `authswitch --tui` opens a resizable account table with subscription, usage and
@@ -258,7 +381,7 @@ reset availability, usage bars for the lead window and the next general window,
 scrollable account details and an activity log.
 With multiple registered adapters, a harness selector switches the view; account
 selection and mutations always belong to the displayed harness. Status loads
-incrementally through each account's read-only API, without activating it.
+incrementally through each account's status API, without activating it.
 
 | Key | Action |
 | --- | --- |
@@ -322,11 +445,12 @@ The badge appears in the account picker of `use`, in the dashboard's switch
 confirmation and on the `Now active:` line that reports a completed switch (in the
 dashboard, its activity log). `type` is the account type as `limits` shows it; `5h`
 and `w` are the account's five-hour and weekly usage windows, rounded to whole
-percent. Feature limits never appear in it, and when several account windows share a
+percent -- except that a window the provider reports below 100% never reads as the
+exhausted `100%`. Feature limits never appear in it, and when several account windows share a
 period without the provider picking one of them, that part is left out rather than
 guessed.
 
-Usage is read live, read-only and once per command. The picker looks up the offered
+Usage is read live and once per command. The picker looks up the offered
 accounts, at most four at a time, before it asks; a switch named on the command line
 switches first and then looks up only its target for the `Now active:` line. Whatever
 has not answered after 2.5 seconds is left out and its requests are cancelled, so the
@@ -361,90 +485,167 @@ by an interrupted write.
 ## Account status
 
 `authswitch list` lists every registered harness; `authswitch codex list` limits the
-output to Codex. Each section includes saved accounts and an identifiable active
-login even if it has never been saved. `*` marks the active account, and the saved
-marker checks the credential itself rather than just the existence of metadata.
-
-The overview compares login state, plan provenance, lead-window usage (the
-provider's headline window, otherwise weekly), earned resets and that window's
-reset countdown. Countdowns use days, hours and minutes, such as
-`7d 5h 6min`;
-`<1min` means less than a minute remains and `due` means the reported deadline has
-passed, without claiming the service has refreshed the quota. All countdowns share
-the same snapshot time.
-Usage and countdown refer to the same window. When the provider picks a headline
-window (Claude does, for example its Fable weekly limit), that window leads.
-Otherwise the
-general account window leads, preferring weekly; if no weekly window is reported,
-the longest general window is shown with its actual duration. Other exhausted
-general windows retain their own reset warning. A general window is named by its
-period (`Weekly`, `5h`) unless another shown general window has the same period; a
-feature limit, or a general window sharing its period, is named by its label
-(`Fable weekly: 100% used`, `Claude weekly (weekly_oauth) exhausted`). Feature
-limits such as Spark and code review have a separate table and determine the
-summary only when the provider picks one as its headline. The TUI uses the same
-selection and names.
-Window durations come from the provider, not from the plan name or
-primary/secondary position; a Pro account with only a general weekly window gets
-no invented 5-hour limit.
-
-Email addresses identify Codex accounts throughout the overview, usage/reset
-schedules, earned reset expiry details, grouped credits and activity metrics,
-saved-login notes and availability/actions tables. Other harnesses use their
-account labels. When accounts of one harness share a label, every table numbers
-the later ones (`alice@example.com (2)`), so each account keeps its own column in
-the metric comparisons and reads the same everywhere. Provider facts already
-represented by structured fields are not repeated. Narrow terminals use compact
-account sections. Missing
-data stays Unavailable or Not reported; known zeroes remain zero. Plans read as in
-`limits` and the switch badge (`Max`), and stored plans are marked unverified
-(`Plus, unverified`). Renewal/cancellation dates are shown only when an adapter can
-provide live billing data. Codex uses the desktop app's account-check endpoint for
-automatic renewal, explicit renewal/cancellation dates and subscription expiry.
-
-Tables that list an account on several rows (the usage/reset schedule,
-feature-specific limits, earned reset details, and availability/actions) draw a
-divider between one account and the next. The divider follows the account id, not
-the email, so two accounts that share an address stay separate blocks, and the
-harness-level availability row is a block of its own. The overview and the metric
-comparisons show each account once and have no dividers. Each `list` section covers
-one harness, so no colour line is drawn. Narrow terminals separate the same blocks
-with a rule line.
+output to Codex. Harnesses appear in the order `limits` uses, by provider name. Each
+section includes saved accounts and an identifiable active login even if it has
+never been saved, and draws up to four tables under the harness's name:
+
+```
+Codex
+┌───────────────────┬──────────────────┬────────────────────┬─────────────┬───────────────┐
+│ Account           │ Status           │ Usage              │ Renewal     │ Earned resets │
+├───────────────────┼──────────────────┼────────────────────┼─────────────┼───────────────┤
+│ alice@example.com │ active, saved    │ weekly 12% · 3d 4h │ 2026-10-08  │ 0             │
+│ Pro               │ 2026-09-17 13:32 │ 5h 37% · 2h 13m    │ auto-renews │               │
+├───────────────────┼──────────────────┼────────────────────┼─────────────┼───────────────┤
+│ bob@example.com   │ saved            │ usage n/a          │ n/a         │ n/a           │
+│ Plus, unverified  │ 2026-09-14 11:32 │                    │             │               │
+└───────────────────┴──────────────────┴────────────────────┴─────────────┴───────────────┘
+
+┌───────────────────┬────────────────────┬────────┬───────────┐
+│ Account           │ Limit type         │ Used % │ Resets in │
+├───────────────────┼────────────────────┼────────┼───────────┤
+│ alice@example.com │ Codex weekly       │    12% │     3d 4h │
+│ Pro               │ Codex five-hour    │    37% │    2h 13m │
+│                   │ Code review weekly │   100% │    3h 59m │
+└───────────────────┴────────────────────┴────────┴───────────┘
+
+┌────────────────┬───────────────────┐
+│ Metric         │ alice@example.com │
+├────────────────┴───────────────────┤
+│ Saved login                        │
+│ remote-control │ 1                 │
+└────────────────┴───────────────────┘
+
+┌─────────────────┬─────────────────────────────────────────────────────────┐
+│ Account         │ Problem                                                 │
+├─────────────────┼─────────────────────────────────────────────────────────┤
+│ bob@example.com │ Subscription and limits: Login expired or was rejected. │
+└─────────────────┴─────────────────────────────────────────────────────────┘
+```
+
+1. **Accounts** -- one row per account, divided from the next. **Account** is the
+   label (bold when active) with the account type beneath it, as in `limits`, and,
+   for a harness with several credential slots, the slot (`openai · Pro`).
+   **Status** says whether the login is active and saved, with the local date and
+   time of its last save beneath; an active login without a save reads `not saved`.
+   **Usage** holds one compact line per headline window, `<window> <used>% · <reset
+   countdown>`, lead window first as described below. **Renewal** is the same cell as
+   in `limits`, and a harness whose provider never reports billing dates, such as Claude
+   Code, gets one note beneath the table instead of an unexplained `n/a` per account.
+   **Earned resets** appears only when an account of the harness reports earned reset
+   credits: the available count, then one line per reported credit.
+2. **Limits** -- the `limits` table of this harness, without its Provider and
+   Renewal columns, for the accounts that report windows.
+3. **Details** -- one comparison of every remaining provider fact: **Metric** and
+   one column per account, split into pages when the terminal is too narrow, with a
+   full-width row per section. Facts already shown above are left out: those that
+   restate a displayed structured field, and one that only repeats the account's own
+   label. Dated rows, such as Codex's daily token totals, are merged across accounts
+   and keep the newest seven days. A sentence that every account of its section
+   states identically, such as Claude's note that it reports no billing dates, is
+   printed once beneath the table. Saved-login notes (Codex remote-control pairing,
+   account IDs) form the **Saved login** section; a note that only names the
+   account's credential slot is left out, because the Accounts table names it.
+4. **Problems** -- a login changed outside authswitch first (`Active login changed
+   outside authswitch: expected alice@example.com, now bob@example.com (not saved) —
+   authswitch claude stash --keep saves it`), then every account's problems, then the
+   harness's own. Problems of one account that share a message are merged with their
+   topics (`Profile, usage:` above the message), and accounts with the same problems
+   share one block, whose **Account** cell names them all on one line.
+
+Human output never prints a raw ISO timestamp: dates and times are local
+(`2026-10-08`, `2026-09-17 13:32`), and a timestamp inside provider text is rewritten
+the same way. `list --json` keeps every original value. A note beneath a table wraps to
+the terminal, with its continuation lines under the note's prefix.
+
+The lead window is the provider's headline window, otherwise weekly. Countdowns use
+two units, such as `3d 4h`; `due` means the reported deadline has passed, without
+claiming the service has refreshed the quota, and `not scheduled` means the provider
+reported no reset. All countdowns share the same snapshot time. When the provider
+picks a headline window (Claude does, for example its Fable weekly limit), that
+window leads. Otherwise the general account windows lead, weekly first. A general
+window is named by its period (`weekly`, `5h`) unless another shown general window
+has the same period; a feature limit, or a general window sharing its period, is
+named by its label (`Fable weekly 100% · 2d`). Feature limits such as Spark and code
+review appear in the Limits table and lead the usage cell only when the provider
+picks one as its headline. The TUI uses the same selection and names. Window
+durations come from the provider, not from the plan name or the slot a window
+arrives in; a Pro account with only a general weekly window gets no invented 5-hour
+limit.
+
+Every window label names the window by how long it is -- `Codex weekly`, `Codex
+five-hour`, `Claude weekly`, `Code review weekly` -- so the same length reads the
+same in every harness. The named lengths are `five-hour`, `daily`, `weekly`,
+`monthly` and `annual`, the same set Codex names its own windows with, and its
+primary/secondary slot is shown (`Codex weekly (secondary)`) only where two windows
+of one length would otherwise share a label. A length with no name of its own keeps
+its compact duration (`Codex 90m`) instead of reading as a period it is not.
+
+When accounts of one harness share a label, every table numbers the later ones
+(`alice@example.com (2)`), so each account keeps its own column in the Details
+comparison and reads the same everywhere. Missing data stays `n/a`; known zeroes
+remain zero. Plans read as in `limits` and the switch badge (`Max`), and stored plans
+are marked unverified (`Plus, unverified`). Renewal dates are shown only when an
+adapter can provide live billing data. Codex uses the desktop app's account-check
+endpoint for automatic renewal, explicit renewal/cancellation dates and subscription
+expiry.
+
+The layout follows the terminal width. From 120 columns every Accounts column stands
+alone; from 100 the earned resets join the usage cell; from 60 the status joins the
+account cell; below 60 one Status cell holds status, usage, renewal and earned resets;
+below 40 every table becomes labelled lines, separated by a rule line per block. Each
+`list` section covers one harness, so no colour line is drawn.
 
 ### Condensed views
 
-`authswitch limits` answers "how much is left, and when does it come back" in one
-table. It is one row per account **and** limit type, sorted by provider and then by
-account email with each harness and each account kept together, and a two-unit countdown (`2h 13m`, `3d 4h`, `45m`, `<1m`, `due`):
+`authswitch limits` answers "how much is left, when does it come back, and when does
+the subscription renew" in one table. It is one row per account **and** limit type,
+sorted by provider and then by account email with each harness and each account kept
+together, with a two-unit countdown (`2h 13m`, `3d 4h`, `45m`, `<1m`, `due`) and the
+account's next billing event:
 
 ```
 Account limits
-┌──────────────────────┬─────────────────────────┬───────────────────────┬────────┬───────────────┐
-│ Provider             │ Account                 │ Limit type            │ Used % │     Resets in │
-├──────────────────────┼─────────────────────────┼───────────────────────┼────────┼───────────────┤
-┃ Claude Code          │ phil@example.com        │ Claude weekly         │    75% │         4d 3h │
-┃                      │ Max                     │ Claude five-hour      │    12% │         1h 2m │
-┃                      │                         │ Fable weekly          │    88% │         2d 5h │
-├──────────────────────┼─────────────────────────┼───────────────────────┼────────┼───────────────┤
-┃ Codex                │ alice@example.com       │ Codex secondary       │    12% │         3d 4h │
-┃                      │ Pro                     │ Codex primary         │    37% │        2h 13m │
-┃                      │                         │ Code review secondary │   100% │        3h 59m │
-┃                      ├─────────────────────────┼───────────────────────┼────────┼───────────────┤
-┃                      │ bob@example.com         │ n/a                   │    n/a │           n/a │
-┃                      │ Plus, unverified        │                       │        │               │
-├──────────────────────┼─────────────────────────┼───────────────────────┼────────┼───────────────┤
-┃ OpenCode / anthropic │ anthropic API key 20e75 │ n/a                   │    n/a │           n/a │
-┃                      │ 1c3b707                 │                       │        │               │
-┃                      │ n/a                     │                       │        │               │
-├──────────────────────┼─────────────────────────┼───────────────────────┼────────┼───────────────┤
-┃ OpenCode / openai    │ alice@example.com       │ Codex primary         │     0% │ not scheduled │
-┃                      │ Pro                     │                       │        │               │
-└──────────────────────┴─────────────────────────┴───────────────────────┴────────┴───────────────┘
+┌──────────────────┬───────────────────┬───────────────────┬────────┬───────────────┬─────────────┐
+│ Provider         │ Account           │ Limit type        │ Used % │     Resets in │ Renewal     │
+├──────────────────┼───────────────────┼───────────────────┼────────┼───────────────┼─────────────┤
+┃ Claude Code      │ phil@example.com  │ Claude weekly     │    75% │         4d 3h │ n/a         │
+┃                  │ Max               │ Claude five-hour  │    12% │         1h 2m │             │
+┃                  │                   │ Fable weekly      │    88% │         2d 5h │             │
+├──────────────────┼───────────────────┼───────────────────┼────────┼───────────────┼─────────────┤
+┃ Codex            │ alice@example.com │ Codex weekly      │    12% │         3d 4h │ 2026-10-08  │
+┃                  │ Pro               │ Codex five-hour   │    37% │        2h 13m │ auto-renews │
+┃                  │                   │ Code review weekl │   100% │        3h 59m │             │
+┃                  │                   │ y                 │        │               │             │
+┃                  ├───────────────────┼───────────────────┼────────┼───────────────┼─────────────┤
+┃                  │ bob@example.com   │ n/a               │    n/a │           n/a │ n/a         │
+┃                  │ Plus, unverified  │                   │        │               │             │
+├──────────────────┼───────────────────┼───────────────────┼────────┼───────────────┼─────────────┤
+┃ OpenCode / anthr │ anthropic API key │ n/a               │    n/a │           n/a │ n/a         │
+┃ opic             │  20e751c3b707     │                   │        │               │             │
+┃                  │ n/a               │                   │        │               │             │
+├──────────────────┼───────────────────┼───────────────────┼────────┼───────────────┼─────────────┤
+┃ OpenCode / opena │ alice@example.com │ Codex five-hour   │     0% │ not scheduled │ 2026-10-02  │
+┃ i                │ Pro               │                   │        │               │ cancels     │
+└──────────────────┴───────────────────┴───────────────────┴────────┴───────────────┴─────────────┘
 
 n/a — Codex · bob@example.com: Subscription and limits: Login expired or was rejected.
-n/a — OpenCode / anthropic · anthropic API key 20e751c3b707: This provider login does not expose a supported subscription or quota API.
+n/a — OpenCode / anthropic · anthropic API key 20e751c3b707: This provider login does not expose a
+      supported subscription or quota API.
+n/a — Claude Code: renewal dates are not exposed by Claude's account API.
 ```
 
+The table fits 100 columns; at that width long provider names, account labels and
+limit types wrap inside their cells.
+
+**Renewal** spans the rows of its account with two lines: the local calendar date,
+and beneath it `auto-renews` when the provider says the subscription renews then, or
+`cancels` when it ends then -- a scheduled cancellation, or an expiry with automatic
+renewal off. Anything else reads `n/a`: the date comes only from live billing data,
+never from a plan, a quota reset, account creation or token expiry. A harness whose
+provider never reports billing dates, such as Claude Code, gets one footnote instead
+of an unexplained `n/a` per account.
+
 A number is never invented. An account whose provider exposes no quota API, whose
 lookup failed, or whose login cannot be read shows `n/a` in **Used %** and
 **Resets in**, and the footnote under the table says why — one line per distinct
@@ -502,7 +703,8 @@ Active accounts
 ┃ OpenCode / openai    │ alice@example.com              │  not saved │ credential file │
 └──────────────────────┴────────────────────────────────┴────────────┴─────────────────┘
 
-note — OpenCode / openai · alice@example.com: This active login is not saved yet; authswitch cannot restore it after a switch.
+note — OpenCode / openai · alice@example.com: This active login is not saved yet; authswitch cannot
+       restore it after a switch.
 ```
 
 **Source** is where the shown login comes from: `credential file` is the harness's
@@ -520,19 +722,27 @@ finds a different account in that slot, the row's source reads
 `credential file (changed)` and a note explains it:
 
 ```
-note — Claude Code · bob@example.test: The credential file changed since the last
-switch (likely a running instance refreshed the previous login). It now holds
-bob@example.test, which is saved. Run authswitch claude use alice@example.test again.
+note — Claude Code · bob@example.test: The active login changed outside authswitch since the last
+       switch (for example a new login). It now holds bob@example.test, which is saved; authswitch
+       claude use alice@example.test switches back.
 ```
 
+For a harness that does not pick up swaps live, such as OpenCode, the sentence also
+names the other cause: a running instance that wrote its previous login back. An
+unsaved current login adds how to keep it (`authswitch <harness> stash --keep saves
+it`).
+
 `authswitch <harness> current` prints the same sentence. The same account with a
-rotated token is that account refreshing itself and is not reported; re-running the
-switch re-arms the check against the file's current contents.
+rotated token is that account refreshing itself and is not reported; for Claude Code the
+rotation is copied into that account's saved record, and re-running the switch re-arms the
+check against the file's current contents.
 
 Both commands accept a harness qualifier (`authswitch claude limits`) and `--json`.
-Both are read-only: they never activate, save or clear a login, they need no harness
-stopped, and every provider lookup is bounded by the same 10-second timeout and
-isolated per account as `authswitch list`.
+Neither changes which account is in use: they never activate, switch or clear a login and
+they need no harness stopped. Like `list`, they may renew a saved Claude login's own tokens
+when its access token has expired, because otherwise its usage cannot be read at all. Every
+provider lookup is bounded by the same 10-second timeout and isolated per account as
+`authswitch list`.
 
 ### JSON output
 
@@ -547,7 +757,9 @@ the same rows as the tables, plus the machine-readable fields the tables condens
 `accountId`, `slotId`, `accountType` (`{ plan, source }` with the adapter's plan
 name, such as `max` or `pro`, sanitised but not display-formatted, and `source` `live`
 or `stored`; null when no type is known or the row names no account; both documents
-carry it), `scope`, `windowSeconds`, the ISO `resetAt` beside the human
+carry it), the limits rows' `billing` (the account's reported `hasActiveSubscription`,
+`autoRenew` and ISO `renewsAt`, `cancelsAt` and `expiresAt`, each omitted when not
+reported; null when the provider reported none or the row names no account), `scope`, `windowSeconds`, the ISO `resetAt` beside the human
 `resetsIn`, the provider's `severity` (`normal`, `warning`, `critical`, or null when
 it gave none) and `headline` (true for the window the provider picks for a
 single-value summary), the ISO `savedAt` beside the human `savedAgo`, the per-row
@@ -582,13 +794,13 @@ accept schema version 2 and handle null reset timestamps. Scripts should qualify
 mutation commands with `codex`, `opencode` or `claude`, since all three now register
 by default. Saved Codex credentials retain their existing format.
 
-For each ChatGPT login, Codex status includes the live plan, primary and secondary
-usage windows with remaining percentages and UTC reset times, additional limits
+For each ChatGPT login, Codex status includes the live plan, every usage window the
+service reports with remaining percentages and reset times, additional limits
 such as code review, credit availability and balance, spend limits when returned,
 earned reset availability and expiry details, lifetime and peak daily tokens,
 activity streaks, and the latest seven reported daily token totals.
 
-The Codex adapter implements the read-only GET requests used by Codex 0.154.0 at
+The Codex adapter implements the read-only GET requests used by Codex 0.155.0 at
 `chatgpt.com/backend-api/wham`: `usage`, `rate-limit-reset-credits`, and `profiles/me`.
 Billing uses `chatgpt.com/backend-api/accounts/check/v4-2023-04-27`, verified against
 the official desktop bundle 26.908.40834. It selects the exact credential account;
@@ -608,9 +820,9 @@ The returned usage plan is not a billing status. Billing dates come from the
 separate account-check response, never from a quota reset, token expiry or stored
 plan. Automatic renewal is on only when the provider says it will renew and no
 cancellation date is scheduled. A non-renewing account without a cancellation date
-does not acquire an invented date. The expiry of an entitlement is displayed
-separately. When renewal is off, a returned renewal timestamp is labelled Renewal
-boundary rather than promising a future charge.
+or expiry does not acquire an invented date. When renewal is off, a returned renewal
+timestamp is never shown as a renewal; the Renewal cell shows the expiry as the day
+the subscription ends. JSON keeps every returned field.
 
 The billing request uses a verified Chromium-compatible User-Agent because the
 service challenged the generic authswitch User-Agent in controlled comparisons.
@@ -640,11 +852,19 @@ process.exitCode = await cli.run(process.argv.slice(2));
 
 Each adapter owns discovery, identity matching, save verification, credential
 storage, switching and process lifecycle, live status APIs, and diagnostics.
-`readState()` and `readAccountStatus()` must be read-only. `readAccountStatus(accountId,
+`readState()` and `readAccountStatus()` must never activate, switch or clear a login.
+`readAccountStatus()` may renew the tokens of the saved copy it is reading, when the provider
+gives it no other way to answer (the Claude Code adapter does, under the store's lock, for
+saved and inactive logins only); it must never touch the active login's credential. `readAccountStatus(accountId,
 options)` receives an optional `IHarnessStatusOptions` whose `signal` cancels the
 lookup's requests; authswitch aborts it when a status is no longer wanted, such as a
 switch badge past its deadline or a closed dashboard, so an adapter should pass it to
-every request it makes. `switchAccount()` must
+every request it makes. Its optional `session` belongs to a caller that reads the same
+accounts repeatedly, such as `authswitch watch`: `session.reuse(key, maxAgeMs, lookup)`
+returns the value that key resolved to less than `maxAgeMs` ago, so an adapter can stop
+repeating a lookup whose answer rarely changes (the Claude adapter reuses its profile for
+an hour). Keys are the adapter's own and carry no secret; a rejected lookup is not
+remembered, and outside a session every lookup is live. `switchAccount()` must
 preserve and verify the outgoing credential without relying on the interactive
 save prompt. `removeAccount()` removes only the saved copy. Status facts carry
 provider-specific labels and units; unsupported capabilities are explicit. Adapter
@@ -678,7 +898,7 @@ count; if it fails, the limits response can still supply availability.
 
 Each usage window may set `scope: 'account' | 'feature'` (default `account`).
 Adapters mark model-specific or feature-specific quotas as `feature`; those quotas
-appear in the feature tables, JSON and details and lead the account summary only
+appear in the Limits table, JSON and details and lead the account summary only
 when the provider marks one as its headline (see below). Weekly windows are identified by `durationSeconds: 604800`;
 neither window labels nor plan names are parsed to infer limits.
 
@@ -700,7 +920,21 @@ Facts may supply a `section` label for grouped comparison and a `summaryKey`
 (`subscription`, `billing`, `usageWindows`, `resets`, or `resetDetails`) when the
 fact duplicates a structured field. The list hides such a fact only if that field
 is displayed; JSON retains every fact. Adapters without this metadata continue to
-display their facts in Additional information.
+display their facts in Additional information. A fact label ending in an ISO date
+(`Tokens 2026-09-15`) marks a daily series, which the list merges across accounts.
+
+Three optional adapter declarations shape the shared views. `liveSwap: true` says that
+running instances pick up a credential swap on their next request: the CLI and TUI
+then offer no stop before a switch (an explicit `--stop` or `--force-stop` is still
+honoured through `processes`), outcomes carry no restart advice, and the credential
+drift sentence names only a new login as the cause. `renewalUnavailableReason` is a
+lower-case clause for a provider that never reports renewal dates; `list` and `limits`
+print it once as `<label>: <reason>`. `autoSwitch: true` says that every saved account's
+usage can be read and that a switch needs no session of the user's stopped, which is what
+`authswitch watch` requires before it switches a harness by itself; a helper process the
+adapter manages itself may still be restarted by its own switch, as Codex' app-server is. The built-in Claude Code adapter declares
+all three; Codex declares `autoSwitch: true` with `liveSwap: false`, and OpenCode declares
+neither.
 
 With multiple adapters, the guide first asks which harness to manage and provides
 an action to choose another. Unqualified mutation commands prompt for a harness;
@@ -727,7 +961,7 @@ Account identity comes from the `id_token` inside the credential — the email c
 
 **Other Codex clients keep running.** Stopping the managed app-server does not stop an editor extension that spawned its own. Close it, or expect it to keep using the credential it already loaded.
 
-**A running OpenCode or Claude Code can undo a switch.** It holds the previous login in memory and rewrites the credential file at its next token refresh. Authswitch lists those instances, offers to stop them, warns when any keep running, and detects the overwrite afterwards — but it cannot prevent it while they run. Restart them after a switch.
+**A running OpenCode can undo a switch.** It holds the previous login in memory and rewrites the credential file at its next token refresh. Authswitch lists those instances, offers to stop them, warns when any keep running, and detects the overwrite afterwards — but it cannot prevent it while they run. Restart them after a switch. A running Claude Code picks the switch up instead; its guarantee rests on the behaviour and lock protocol verified against Claude Code 2.1.273, and `authswitch claude active` still reports a login that changed outside authswitch.
 
 **The Codex stash is keyed by email.** Two Codex workspaces with the same email
 cannot both be saved under that key. Their account IDs are distinguished during