@modelprofile.com/authswitch 2.1.2

package/readme.md

@@ -0,0 +1,502 @@
+# @modelprofile.com/authswitch
+
+Manage Codex, OpenCode and Claude Code accounts, switch interactively, and inspect live subscription, usage and reset information. Codex switching also preserves ChatGPT remote-control pairings.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## The problem
+
+The Codex CLI holds exactly one active credential. Logging in as a second account overwrites the first, so working across two accounts means re-running the browser login every time.
+
+Remote control makes that worse. A ChatGPT client pairs with the local Codex app-server, and the pairing is recorded in Codex' state database keyed by the account id. Swap the credential naively and the running app-server keeps serving the old identity until it is restarted, and the incoming account can come back without the enrollment that made it reachable from the ChatGPT app.
+
+`authswitch` keeps a stash of credentials keyed by account email, captures each account's remote-control enrollments next to its credential, and puts both back together.
+
+## Install
+
+This package is published to the private Verdaccio registry, not to npmjs, so the scope has to be mapped first:
+
+```bash
+pnpm config set @modelprofile.com:registry https://verdaccio.lossless.digital
+```
+
+```bash
+pnpm install -g @modelprofile.com/authswitch
+```
+
+Node.js 24 or newer is required.
+
+## Usage
+
+Run `authswitch`, `authswitch -i`, or `authswitch --interactive` for an interactive guide. Use the arrow keys and
+Enter to switch accounts, save the current login, list accounts and live status, check remote
+control, or remove a saved account. The guide shows the current account and returns
+to the menu after each successful action; choose **Back** in a submenu or **Exit** to finish.
+
+Before showing the actions, the guide checks whether the current credential has a
+matching, readable saved copy. A new or refreshed login gets an offer to save it
+while keeping it active. The switch action checks again before offering targets;
+declining that save cancels the switch. Scripts still preserve the outgoing login
+automatically through the harness adapter.
+
+When saving, choose whether to keep the account active or clear the active login so
+you can run `codex login` for another account. Removing a saved account requires
+confirmation and leaves the active login in place.
+
+The guide requires an interactive terminal. With no arguments, piped output and CI
+runs show help instead; explicitly requesting `-i`, `--interactive`, or `--tui`
+without an interactive terminal fails. Explicit commands remain available for scripts:
+
+```bash
+authswitch                        # interactive guide
+authswitch -i                     # explicitly open the guide
+authswitch codex --interactive    # guide for one harness
+authswitch --tui                  # full-screen account management
+authswitch codex --tui            # start the dashboard on Codex
+authswitch list                   # all known accounts across registered harnesses, with live status
+authswitch list --json            # complete account/status document for scripts
+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 codex preuse <email>   # send the default prompt without activating the account
+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
+authswitch opencode list          # all OpenCode provider logins and saved accounts
+authswitch opencode stash openai --keep
+authswitch opencode use alice@example.com
+authswitch opencode login openai  # device login; save the new account without switching
+authswitch codex login            # save a new Codex account without disturbing the current login
+authswitch claude stash --keep    # save a Claude Code subscriber login
+authswitch claude list --json
+authswitch claude use alice@example.com
+```
+
+### OpenCode and Claude Code
+
+Both adapters support `current`, `stash`, `use`, `drop`, `doctor`, the guide,
+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.
+Unmanaged native processes must still be exited manually: a terminal session
+cannot safely be reconstructed from its PID. Status lookups remain read-only
+and work while harnesses are running. `preuse` remains a Codex capability.
+
+`authswitch codex login` and `authswitch opencode login openai` use the shared
+OpenAI device login flow. They display a verification link and code, then save
+the new account without changing the active native login. Ctrl-C cancels login.
+Select the saved account with `use` when ready to switch. Claude Code and other
+OpenCode providers retain their native login commands.
+
+### Hosted account management
+
+`AuthSwitchService` exposes credential-free account lists, login capabilities,
+login prompts, saved-account identifiers and mutation outcomes for authenticated
+hosts such as AGL. Every request has `protocolVersion: 1`. `list`, `login` and
+`mutate` start bounded background operations; `get` polls the returned operation
+ID and `cancel` cancels a pending login. Operations outlive a disconnected client,
+and completed results remain available for ten minutes. Call `close()` during
+host shutdown. The host must authenticate and authorize every request.
+
+Login requests identify the harness, provider and supported flow explicitly.
+`AuthSwitchLogin` is the backend login owner and accepts additional provider
+adapters. Its credential-bearing completion is for backend storage only.
+When an enclosing registry owns an injected adapter, construct it with
+`{ disposeProviders: false }` as the second argument and dispose that registry
+after closing the login service.
+
+`OpenCodeHarness.importCredential(providerId, credential)` saves an inactive
+login. `activateCredential(providerId, credential)` preserves and verifies the
+outgoing native login before activation; the caller retains ownership of the
+incoming credential's durable storage. Both are backend APIs, never wire payloads.
+
+`AuthSwitchOperations` is shared by the command, guide and TUI. Its optional
+coordinator receives only the harness, operation, account ID, consent to wait,
+and a credential-location fingerprint. AGL owns private-controller discovery;
+authswitch uses `agl authswitch --request <json>` without an AGL package dependency.
+A failed or ambiguous transport never falls through to a second local mutation.
+AGL and the CLI must use matching credential locations and compatible versions.
+
+OpenCode credentials live in `${XDG_DATA_HOME:-~/.local/share}/opencode/auth.json`.
+Several providers can be active at once. Saving or switching `openai` preserves
+every other provider, and `stash openai` without `--keep` clears only OpenAI.
+When several logins are active, the guide asks which to save; scripts must name
+the provider or account. In the TUI, select an active row before pressing `a` or `c`.
+ChatGPT OAuth accounts display their email and use the same direct status APIs as
+Codex. API keys and opaque provider tokens have no reliable email, so their labels
+contain the provider and a SHA-256 fingerprint. Their quota/billing information is
+explicitly unavailable. `OPENCODE_AUTH_CONTENT` overrides the file and blocks file
+management. Provider configuration and environment credentials remain managed by OpenCode.
+
+Claude Code supports subscriber file logins on Linux and Windows. The adapter pairs
+`~/.claude/.credentials.json` with `~/.claude.json`'s `oauthAccount`; with
+`CLAUDE_CONFIG_DIR`, both files are inside that directory. Switching preserves
+unrelated settings and credential entries and clears native account-specific caches.
+A metadata write failure rolls back our writes and keeps the outgoing account saved.
+macOS Keychain switching and environment/API-key/cloud-provider logins are explicitly
+unsupported. A file login shadowed by an environment override cannot be switched.
+User and current-directory project settings are also checked for credential helpers
+and provider environment overrides; helpers are never executed. Authswitch manages
+the local file login, so launch-time flags, managed policies and credentials supplied
+by embedding applications remain under Claude Code's control.
+
+Claude's direct OAuth profile and usage lookups report the plan, weekly and five-hour
+usage, model-specific windows, and available extra-usage budget information.
+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.
+
+OpenCode and Claude saved records are separate owner-only files under
+`~/.authswitch/opencode` and `~/.authswitch/claude`. Emails are accepted as account
+references; ambiguous matches report provider-qualified references and full IDs.
+
+### Preusing an account
+
+`preuse` sends one text prompt through the selected account. Use it after a reset
+to make the first token-consuming request for the next usage window:
+
+```bash
+authswitch codex preuse alice@example.com
+authswitch codex preuse alice@example.com --prompt "Write 2000 words about strawberries."
+authswitch codex preuse alice@example.com --model gpt-5.5 --prompt "Describe a strawberry in one sentence."
+```
+
+The default prompt is `Write 2000 words about strawberries.` Without an account,
+an interactive terminal shows an account picker. Scripts must specify an account
+and, when multiple harnesses are registered, the harness. Active and saved
+accounts are supported, including an active login that has not been stashed.
+
+Codex inference uses the published FlexHarness models/providers packages and the
+selected ChatGPT login's access token and account ID. It selects the account's
+advertised default text model unless `--model` is supplied, preferring a supported
+low reasoning setting when the catalog provides one. API-key logins are rejected
+because they do not have ChatGPT subscription reset windows. Expired credentials
+must be renewed through Codex and saved again.
+
+Each invocation consumes quota and sends at most one inference request. It does
+not watch for resets or schedule future requests. No active login is switched,
+credential refreshed or written, app-server restarted, or earned reset consumed.
+The prompt has no tools, files or conversation history. The generated prose is
+drained without being printed or stored; the command reports provider token
+counts and then reads the account's reset schedule. It does not infer that a
+timer started merely from a zero-percent usage reading or a successful response.
+
+Ctrl-C cancels the request. Codex preuse has a three-minute deadline, with a
+ten-second model-catalog limit. Failed or interrupted requests can have consumed
+tokens and are never retried automatically. A completed prompt exits with 0 even
+if the subsequent reset lookup fails, reporting that uncertainty separately;
+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.
+
+### Management dashboard
+
+`authswitch --tui` opens a resizable account table with subscription, usage and
+reset availability, usage bars, 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.
+
+| Key | Action |
+| --- | --- |
+| Arrows, Home/End, PageUp/PageDown | Select accounts or scroll the focused view |
+| Tab / Shift-Tab | Move focus between harnesses, accounts, tabs and details |
+| Enter | Switch to the selected saved account; activate a harness in its selector |
+| `/`, `s`, `S` | Filter the table, cycle its sort column, reverse sorting |
+| `a` / `c` | Save the current login and keep it active / save and clear it |
+| `d` | Remove the selected saved copy, preserving the active login |
+| `r` / `g` | Refresh status / run harness diagnostics |
+| `q` / Ctrl-C | Close and restore the terminal |
+
+Save, switch and removal actions require confirmation. Confirmations start on
+Cancel; use Left/Right or Tab to select the action, then Enter. Switching first
+checks the current credential and offers to save an unsaved login. A declined,
+failed or unverified save prevents switching. Plain character shortcuts remain
+available as text while editing a table filter; Enter keeps the filter and Escape
+clears it. Closing waits for an in-flight operation to finish its cleanup.
+
+Interactive mode flags accept an optional harness and cannot be combined with
+commands or another mode flag.
+
+### Getting your accounts into the stash
+
+`stash` reads whatever Codex currently has active, files it under the account's email, and empties the active slot so the next login starts clean:
+
+```bash
+authswitch codex stash            # -> stashed alice@example.com
+codex login                       # log in as the second account
+authswitch codex stash            # -> stashed bob@example.com
+```
+
+Use `--keep` to take a checkpoint without logging yourself out.
+
+### Switching
+
+```bash
+authswitch codex use alice@example.com
+```
+
+Or with no argument, to pick from a list:
+
+```bash
+authswitch codex use
+```
+
+The account argument also accepts the directory slug, the local part, or a unique prefix, so `authswitch codex use alice` resolves to `alice@example.com` when that is unambiguous. It is deliberately not a substring match — this argument decides which credential becomes active, and an incidental substring hit should never pick an account you did not name.
+
+## What a switch actually does
+
+`use` runs as one sequence, and steps 1 to 4 stop at the first failure:
+
+1. **Stop the app-server.** It holds the state database open, owns the remote-control websocket, and refreshes tokens on its own schedule. Reading or writing `auth.json` while it runs races that refresh — the copy taken could be a token the daemon has already rotated away, and a credential the daemon wrote afterwards would be destroyed unstashed. `authswitch` stops it through Codex' own `codex app-server daemon stop` rather than signalling the process behind Codex' back, and aborts if it will not stop.
+2. **Check in the outgoing credential.** Only now is the active credential read, stashed under its account email, and read back from the stash to prove it landed. A credential is never overwritten until a copy has been verified on disk. Re-stashing an account that already has a stash refreshes it.
+3. **Write the incoming credential** to `auth.json`, owner-only, through an exclusively-created temp file and a rename.
+4. **Restore the incoming account's remote-control enrollments** into the state database. If the state database or its enrollment table is missing, this fails loudly rather than reporting that it restored nothing.
+5. **Start the app-server again** — but only if it was running to begin with, so the machine's posture is unchanged. This runs even when an earlier step failed: a failed switch must not leave remote control down.
+
+`stash` follows the same quiesce-and-resume discipline, for the same reason.
+
+If the switch completes but something did not finish — most likely the app-server refusing to come back — the command prints what is outstanding and exits non-zero, so it cannot look like a success to a script.
+
+Running `use` for the account that is already active is not a no-op: it restores that account's enrollments, which is the repair path when remote control has stopped working for the current login.
+
+Re-selecting the active account keeps its current tokens, including any refresh
+since it was last saved, and updates the verified stash before restoring pairings.
+
+`doctor` prints where the credential lives, which state database is in use, every
+enrollment row, whether the app-server is up, and any stash directory left incomplete
+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, weekly usage, earned resets and
+the weekly 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 general account window, 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.
+Feature limits such as Spark and code review have a separate table and never
+determine the general summary. The TUI uses the same weekly-first selection.
+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. 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. Stored plans are
+marked 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.
+
+### JSON output
+
+`authswitch list --json`, `authswitch codex list --json`, and the `ls` alias write
+one JSON document to stdout, with no color, tables or progress messages. `--json`
+may appear before or after the command and requires `list` or `ls`. It cannot be
+combined with a mutation or interactive mode. Unknown list arguments exit with 2.
+
+The exported `IAccountList` contract contains:
+
+- `schemaVersion: 2`, `generatedAt` (ISO UTC), and `complete`.
+- `harnesses[]`: `id`, `label`, `loginHint`, `saveUnavailableReason`, `accounts`, and
+  harness-level `problems` (distinguishing failed discovery from an empty list).
+- Each account's opaque `id`, `label`, `isActive`, verified `isStashed`, `savedAt`,
+  `details`, and `status` containing all labelled `facts`, `problems`, and optional
+  typed `summary` fields. Missing fields remain omitted, not replaced by zero.
+
+JSON retains full fact strings and absolute ISO reset/expiry timestamps. It exports
+the credential-free adapter contract, never credentials, raw HTTP responses or
+harness internals. A partial result still produces valid JSON and exits with 1;
+successful and empty results exit with 0. `complete` describes lookup success,
+not whether the provider exposes every possible metric.
+
+Version 2 of this JSON schema allows `usageWindows[].resetAt` to be null and adds
+optional account `slotId` fields. Consumers migrating from authswitch 1.x must
+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
+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
+`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;
+another workspace's default entry cannot supply its billing information.
+Each request uses that account's access token and account ID. For the active
+account it reads the current credential, which may be newer than the stash.
+Listing never switches accounts, starts or stops an app-server, refreshes tokens,
+writes credentials, stores status results, or consumes an earned reset.
+
+These backend contracts come from Codex's source and can change. Missing fields,
+expired logins, denied requests, timeouts, and unsupported responses are shown
+explicitly; they are never reported as zero usage. Other accounts and successful
+sections still appear, and a failed status lookup makes the command exit nonzero.
+An expired saved login must be renewed through Codex and saved again.
+
+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.
+
+The billing request uses a verified Chromium-compatible User-Agent because the
+service challenged the generic authswitch User-Agent in controlled comparisons.
+This is a fixed HTTP request profile and requires no local browser installation. Other
+Codex status endpoints retain the authswitch User-Agent. If the billing endpoint
+still returns a Cloudflare verification challenge, that is reported explicitly as
+unavailable billing and a partial result, without treating it as a rejected login.
+Authswitch does not
+import browser cookies, replay desktop integrity state, refresh credentials or
+switch accounts to bypass the challenge. A plan from the stored login remains
+unverified when the live usage request fails. API-key logins and keyring credentials
+cannot provide these ChatGPT subscription metrics.
+
+## Harness adapters
+
+The CLI operates on `IAuthHarness`, with opaque account IDs scoped to each harness.
+Codex, OpenCode and Claude Code are built-in adapters. Adding an adapter does not require
+changing command routing, save prompts, account pickers or status rendering:
+
+```typescript
+import { AuthSwitchCli, CodexHarness } from '@modelprofile.com/authswitch';
+import { AnotherHarness } from './anotherharness.js'; // your IAuthHarness implementation
+
+const cli = new AuthSwitchCli([new CodexHarness(), new AnotherHarness()]);
+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. `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
+labels, details, facts and outcomes contain plain text; smartconsole owns terminal
+formatting for both the guide and dashboard.
+Credentials, email assumptions and Codex enrollment metadata stay out of the
+shared interface. The existing `CodexSwitcher` API and single-switcher CLI
+constructor remain available.
+
+An account's optional `slotId` identifies the credential it replaces. Accounts in
+different slots may be active simultaneously. `saveCurrent({ keepActive, accountId })`
+must target the selected active account; omitting `accountId` is allowed only when
+the adapter has one unambiguous active login. `usageWindows[].resetAt` may be null
+when the provider explicitly reports no scheduled reset; missing windows stay omitted.
+
+Adapters may implement `preuseAccount(accountId, options)` as an optional
+quota-consuming capability. `IHarnessPreuseOptions` carries the prompt, optional
+model identifier and cancellation signal; `IHarnessPreuseResult` returns the
+selected model and optional input/output/total token counts. The adapter owns
+credential selection and inference and must leave the active login unchanged.
+Unsupported adapters reject the command before account selection. Prompt results
+never contain credentials or raw provider responses.
+
+Adapters can also return an optional `IHarnessAccountStatus.summary` with a
+subscription plan and its live/stored provenance, labelled usage windows with
+duration, used percentage and UTC reset time, and available reset credits with
+optional expiry details. This harness-neutral data supports shared presentation
+without parsing provider-specific fact strings. Missing data stays unknown;
+explicit zeroes remain zero. A successful reset-detail lookup supplies the summary
+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` so those
+quotas remain available in JSON and details without distorting the general
+account summary. Weekly windows are identified by `durationSeconds: 604800`;
+neither window labels nor plan names are parsed to infer limits.
+
+Optional `summary.billing` contains provider-reported `hasActiveSubscription`,
+`autoRenew`, `renewsAt`, `cancelsAt`, and `expiresAt`, independent of the plan name.
+Dates are ISO UTC and omitted
+when unknown. They must come from a live billing source; entitlement expiry alone
+does not establish renewal or cancellation. Codex omits this field if its billing
+lookup fails and supplies a corresponding problem.
+
+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.
+
+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;
+scripts must qualify them. Account references never resolve across harnesses.
+
+## Where things are stored
+
+| What | Where |
+| --- | --- |
+| Stashed credentials | `~/.authswitch/codex/<email>/auth.json` (mode 0600, in a 0700 directory) |
+| Stash metadata and enrollments | `~/.authswitch/codex/<email>/stash.json` |
+| Codex' active credential | `$CODEX_HOME/auth.json`, default `~/.codex/auth.json` |
+| Codex' remote-control enrollments | the `remote_control_enrollments` table in `$CODEX_HOME/state_<n>.sqlite` |
+
+`CODEX_HOME` and `AUTHSWITCH_HOME` both override their defaults, which is also how the test suite runs against a throwaway directory. `AUTHSWITCH_CODEX_BIN` points at a specific `codex` executable when it is not on `PATH`, and `NO_COLOR` turns off colouring (as does piping the output anywhere that is not a terminal).
+
+Account identity comes from the `id_token` inside the credential — the email claim names the stash, the account id ties it to its enrollments. The token is decoded, never verified, and never printed: `authswitch` only ever reports emails, plan names and server names.
+
+## Limits
+
+**Keyring-backed credentials cannot be switched.** Codex can keep credentials in an OS keyring instead of `auth.json`, in which case there is no file to move. `authswitch` detects this and refuses rather than half-working; `doctor` reports it as `keyring (not switchable)`. Switch Codex to file storage via `auth_credentials_store_mode` in `config.toml` and log in again to use this tool.
+
+**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.
+
+**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
+listing and identity checks, and a collision refuses to overwrite either login.
+Account IDs in the shared harness interface do not have this email restriction.
+
+**A stash is a credential.** `~/.authswitch` holds live refresh tokens. It is written owner-only, but it is not encrypted, and it belongs in the same threat model as `~/.codex/auth.json` itself.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
+The test suite builds a fixture `CODEX_HOME` with a real SQLite state database and exercises the full stash/login/restore cycle, including the case where a fresh login has removed an account's enrollment row. It never touches the developer's own Codex installation.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@modelprofile.com/authswitch',
+  version: '2.1.2',
+  description: 'Manage Codex, OpenCode and Claude Code accounts with guided switching and live usage status'
+}

package/ts/accounts.ts

@@ -0,0 +1,78 @@
+import type { IAuthHarness, IHarnessAccount, IHarnessAccountStatus, IHarnessState, IHarnessStatusSummary } from './interfaces.harness.js';
+import { plainText } from './formatting.js';
+
+export interface IAccountRow {
+  harness: IAuthHarness;
+  account: IHarnessAccount;
+  status?: IHarnessAccountStatus;
+}
+export const duration = (secondsArg: number): string => secondsArg % 86400 === 0 ? `${secondsArg / 86400}d` : secondsArg % 3600 === 0 ? `${secondsArg / 3600}h` : `${secondsArg / 60}m`;
+/** A countdown is a snapshot of the provider's deadline, not proof a quota has reset. */
+export const until = (timestampArg: string | null, nowArg: number): string => {
+  if (timestampArg === null) return 'Not scheduled';
+  const remaining = Date.parse(timestampArg) - nowArg;
+  if (!Number.isFinite(remaining)) return 'Unavailable';
+  if (remaining <= 0) return 'due';
+  const minutes = Math.floor(remaining / 60000);
+  if (!minutes) return '<1min';
+  const days = Math.floor(minutes / 1440);
+  const hours = Math.floor(minutes % 1440 / 60);
+  return [days ? `${days}d` : '', hours ? `${hours}h` : '', minutes % 60 ? `${minutes % 60}min` : ''].filter(Boolean).join(' ');
+};
+export const accountPlan = (rowArg: IAccountRow): string => {
+  const subscription = rowArg.status?.summary?.subscription;
+  return subscription ? `${plainText(subscription.plan)}${subscription.source === 'stored' ? ' (stored; unverified)' : ' (live)'}` : rowArg.status ? 'Unavailable' : 'Loading';
+};
+type TUsageWindow = NonNullable<IHarnessStatusSummary['usageWindows']>[number];
+type TAccountStatusRow = Pick<IAccountRow, 'status'>;
+export const usagePeriod = (windowArg: TUsageWindow): string => windowArg.durationSeconds === 604800 ? 'Weekly' : duration(windowArg.durationSeconds);
+/** Order by scope and actual duration: a provider's primary slot need not be five hours. */
+export const orderedUsageWindows = (windowsArg: readonly TUsageWindow[] = []): TUsageWindow[] => [...windowsArg].sort((left, right) =>
+  Number(left.scope === 'feature') - Number(right.scope === 'feature') ||
+  Number(left.durationSeconds !== 604800) - Number(right.durationSeconds !== 604800) || right.durationSeconds - left.durationSeconds);
+export const accountUsageWindows = (rowArg: TAccountStatusRow): TUsageWindow[] | undefined => {
+  const windows = rowArg.status?.summary?.usageWindows;
+  return windows === undefined ? undefined : orderedUsageWindows(windows.filter(window => window.scope !== 'feature'));
+};
+export const accountUsage = (rowArg: TAccountStatusRow): string => {
+  const windows = accountUsageWindows(rowArg);
+  return windows?.length ? `${usagePeriod(windows[0])}: ${windows[0].usedPercent}% used` : windows ? 'None reported' : rowArg.status ? 'Unavailable' : 'Loading';
+};
+export const accountResets = (rowArg: IAccountRow): string => rowArg.status?.summary?.resets === undefined ? rowArg.status ? 'Unavailable' : 'Loading' : String(rowArg.status.summary.resets.available);
+export const accountNextReset = (rowArg: TAccountStatusRow, nowArg = Date.now()): string => {
+  const window = accountUsageWindows(rowArg)?.[0];
+  return window ? until(window.resetAt, nowArg) : 'Unavailable';
+};
+export const accountQuotaSummary = (rowArg: TAccountStatusRow, nowArg: number): string => {
+  const windows = accountUsageWindows(rowArg);
+  return [accountUsage(rowArg), ...(windows?.length ? [
+    `Reset in: ${accountNextReset(rowArg, nowArg)}`,
+    ...windows.slice(1).filter(window => window.usedPercent >= 100).map(window => `${usagePeriod(window)} exhausted\nResets in: ${until(window.resetAt, nowArg)}`),
+  ] : [])].join('\n');
+};
+export const accountState = (rowArg: IAccountRow): string => `${rowArg.account.isActive ? '* active, ' : ''}${rowArg.account.isStashed ? 'saved' : 'not saved'}`;
+export const accountDetails = (rowArg: IAccountRow): string => [
+  plainText(rowArg.account.label), accountState(rowArg),
+  ...(rowArg.account.savedAt ? ['Saved: ' + plainText(rowArg.account.savedAt)] : []),
+  ...rowArg.account.details.map(plainText),
+  ...(rowArg.status?.facts.map(factArg => `${plainText(factArg.label)}: ${plainText(factArg.value)}`) ?? ['Loading account status…']),
+  ...(rowArg.status?.problems.map(problemArg => `Unavailable: ${plainText(problemArg)}`) ?? []),
+].join('\n');
+
+/** Read-only, bounded parallel status lookup. No account is switched to inspect it. */
+export const readAccountRows = async (
+  harnessArg: IAuthHarness,
+  optionsArg: { signal?: AbortSignal; onUpdate?: (rowsArg: IAccountRow[], stateArg: IHarnessState) => void | Promise<void> } = {},
+): Promise<{ rows: IAccountRow[]; state: IHarnessState }> => {
+  const state = await harnessArg.readState();
+  const rows = state.accounts.map(account => ({ harness: harnessArg, account } as IAccountRow));
+  await optionsArg.onUpdate?.(rows, state);
+  for (let index = 0; index < rows.length && !optionsArg.signal?.aborted; index += 4) {
+    await Promise.all(rows.slice(index, index + 4).map(async row => {
+      try { row.status = await harnessArg.readAccountStatus(row.account.id); }
+      catch { row.status = { facts: [], problems: ['Could not read account status.'] }; }
+      if (!optionsArg.signal?.aborted) await optionsArg.onUpdate?.(rows, state);
+    }));
+  }
+  return { rows, state };
+};