@byokit/accounts 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.14.0 (2026-10-01)
+
+- Dependency update: pins @byokit/usage 0.4.0.
+
+- SECURITY: Add a Node-only managed CLI account boundary for subscription sign-in: only app-owned folders and explicitly passed absolute binaries, no default login access, no credential-file reads, no token output, and launch environment credential shedding.
+- Add managed CLI account creation, marker-gated sign-in, status, rename, cancellation, history links and removal, with legacy roster and terms compatibility.
+- Share the portable chooser's AccountLike type and accept normalized subscription usage with millisecond reset times.
+- Bound native status deadlines even when a passed CLI ignores termination; stdout is capped and only the owned child is terminated.
+- Offer every subscription catalogue row by default on supported platforms, adding Kimi, Meta, Qwen and MiniMax labels; preserve Claude Pro/Max sign-in and remove terms and visibility gates. API key (billed per use) rows remain opt-in. Simplify the ChatGPT plan-use error words.
+
+## 0.13.0 (2026-10-01)
+
+
+
+- Add portable, choose-once multi-account selection with most-room ordering, unknown room above exhausted, and secret-free candidate explanations. Auto and default fallback use subscription accounts only; an API key (billed per use) must be explicitly selected.
+- Export roomOf and roomWords, shared Auto conformance fixtures, and descriptive multi-account terms data.
+
 ## 0.12.0 (2026-09-30)
 
 

package/README.md

@@ -8,8 +8,8 @@
 </p>
 
 <p align="center"><strong>Sign in with the AI plan you already pay for, inside your own app.</strong><br/>
-ChatGPT and Claude Pro/Max on every platform (Claude needs Web Crypto); OpenRouter on computers when an app offers it (API billing, never by default); Grok and
-GitHub Copilot hidden by default. Anthropic uses an app-passed API key (billed per use), explicitly opted in. Sign-ins go into your app's own store: on a computer (Node, Electron), in a browser
+ChatGPT and Claude Pro/Max on every platform (Claude needs Web Crypto); Grok, GitHub Copilot, Kimi and Meta on computers.
+OpenRouter and Anthropic API keys are billed per use and require explicit app opt-in. Sign-ins go into your app's own store: on a computer (Node, Electron), in a browser
 (a PWA, Electron's renderer) and on a phone (React Native and Expo, iOS and Android). One import; your bundler picks
 the platform's side (`package.json`'s `react-native` and `browser` conditions).</p>
 
@@ -75,16 +75,18 @@ On a computer it uses Pi's [`@earendil-works/pi-ai`](https://www.npmjs.com/packa
 flows, pinned exactly:
 
 ```ts
+import type { SafeStorageLike } from '@byokit/accounts';
 import { isolate } from '@byokit/accounts/isolate'; // first, before any Pi import
 isolate('/path/to/app/engine');                     // scrub inherited Pi settings and provider keys
-const { Accounts, fileStore } = await import('@byokit/accounts');
-const { app, safeStorage } = await import('electron');
-await app.whenReady();
-
-const accounts = new Accounts({ store: (member) => fileStore(`/path/to/app/people/${member}/auth.json`, safeStorage) });
-const shown = await accounts.login(1, 'chatgpt', { via: 'code' }); // { state: 'waiting', code, url }
-// show shown.code and shown.url; the sign-in finishes by itself
-(await accounts.status(1, 'chatgpt')).words;                     // "ChatGPT is connected."
+
+// Your Electron main process waits for app.whenReady(), then passes its safeStorage here.
+export async function connect(safeStorage: SafeStorageLike) {
+  const { Accounts, fileStore } = await import('@byokit/accounts');
+  const accounts = new Accounts({ store: (member) => fileStore(`/path/to/app/people/${member}/auth.json`, safeStorage) });
+  const shown = await accounts.login(1, 'chatgpt', { via: 'code' }); // { state: 'waiting', code, url }
+  // show shown.code and shown.url; the sign-in finishes by itself
+  return { shown, status: await accounts.status(1, 'chatgpt') };
+}
 ```
 
 ### On a phone or in a browser
@@ -119,7 +121,7 @@ and [`examples/pwa`](../../examples/pwa) (browser sign-in).
 | `Accounts` | Sign-in, status, sign-out, asking and limits for each member: `login`, `finished`, `status`, `plan`, `logout`, `respond`, `failed`, `ladder`, `keepFresh` |
 | `portable`, `computer`, `loopback` | The platform `Accounts` runs on: device code with `fetch` alone, or (Node entry only) Pi's flows and the loopback listener |
 | `memoryStore`, `fileStore`, `secureStore`, `browserStore`, `recordStore` | One store per person: in memory, a sealed 0600 file (Node entry only), Keychain/Keystore, IndexedDB, or your own load and save |
-| `offered`, `provider`, `PROVIDERS` | The catalogue: each provider's billing, terms status, reason and source |
+| `offered`, `provider`, `PROVIDERS` | The catalogue: each provider's billing, models and source |
 | `billingWords`, `say`, `WORDS`, `signInError`, `failure`, `clock`, `callbackPage` | The plain sentences every app shows the same way (`words.json`), a time in words, and the page a browser sees after a sign-in |
 | `respond`, `ResponseError`, `IncompleteError`, `sseReader`, `limitResponse`, `isFunctionCall` | Ask ChatGPT's answers endpoint with a sign-in, with tools, pictures, thinking effort and an answer shape; the error with the words to show and the kind acted on |
 | `classifyFailure`, `classify`, `REST_MS` | An error's kind (limit, overload, plan without this use, lapsed sign-in, network) and default rest times |
@@ -138,7 +140,7 @@ and [`examples/pwa`](../../examples/pwa) (browser sign-in).
 | Claude Pro/Max (subscription) | Provider page, paste its code back | Same PKCE flow; token endpoint CORS required | Same PKCE flow; app supplies Web Crypto |
 | Anthropic (API key, billed per use) | App passes its own key, explicitly | Same fetch-only Messages provider | Same fetch-only Messages provider |
 | OpenRouter (API billing) | Its own page, back to this computer (Pi's flow), when an app offers it (never by default) | Not yet | Not yet |
-| Grok, Copilot (hidden) | Pi's flows | No | No |
+| Grok, Copilot, Kimi, Meta | Pi's flows | No | No |
 | Where sign-ins are kept | `fileStore(path, safeStorage)`, sealing required | `browserStore(name)` (IndexedDB) | `secureStore(SecureStore, name)` (Keychain, Keystore) |
 
 Device code works everywhere: OpenAI's sign-in endpoints answer any web page. The page-straight-back sign-in needs a
@@ -148,13 +150,16 @@ doesn't answer other web pages), so a PWA's model calls go through the app's own
 
 ## Catalogue and billing
 
-`catalogue.json` holds each provider with its billing (`subscription`, `api`) and terms status (`allowed`, `grey`,
-`partner`), a one-line reason and a source. The kit labels; your app decides what to offer
-(`new Accounts({ offer: ['chatgpt'] })`). Without an explicit `offer`, only subscription sign-ins supported on this
-platform are shown: OpenRouter is API-billed and never offered by default. An explicit list is not platform-filtered,
-so choose from the table above. Show `billingWords(p)` next to every provider you list.
+`catalogue.json` holds each provider's billing (`subscription`, `api`), models and source.
+All subscription rows are offered by default on platforms that support their sign-in. API-billed rows
+are offered only when the app names them. An explicit `offer` list is not platform-filtered.
+The `Provider` shape no longer has `terms`, `hidden` or `why`, and `Terms` is no longer exported.
+Qwen and MiniMax have subscription catalogue rows; their paste and portal sign-in flows follow in later work packages.
+Each provider's own terms apply to how you use your plan.
+Anthropic Messages uses an app-passed API key (billed per use); authentication is separate from the Messages request.
 
-Anthropic Messages uses an app-passed API key (billed per use), with explicit opt-in; its authentication is separate from the Messages request.
+Native Claude CLI sign-in uses the managed-folder entry.
+Approved exception: the `./cli` entry reads and runs only app-managed per-account folders under `stateDir` and the absolute CLI binaries the app passes; it never touches the person's default login; tokens never leave the device and are never logged.
 
 ```ts
 import { Accounts, billingWords, offered } from '@byokit/accounts';
@@ -164,7 +169,7 @@ for (const p of offered(['chatgpt', 'openrouter'])) console.log(`${p.name}: ${bi
 ```
 
 ```text
-[ 'chatgpt', 'claude' ]
+[ 'chatgpt', 'grok', 'copilot', 'claude', 'kimi', 'meta', 'qwen', 'minimax' ]
 ChatGPT: Uses your ChatGPT plan.
 OpenRouter: Charged per use to your OpenRouter account, not a plan.
 ```
@@ -438,8 +443,6 @@ fetch such as Expo's. `betas` explicitly opts into native beta headers.
 
 ## Claude Pro/Max subscription
 
-Anthropic's [developer guidance](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) prohibits third-party Claude.ai login without approval; BYOKit has no approval, and this route may stop working or lead to account restrictions (the separately billed API-key route is the documented alternative).
-
 Claude is available by default. Open its page, then paste the returned `code#state` into the app:
 
 ```ts
@@ -489,3 +492,100 @@ The common route follows Hermes's platform token host, three scopes and `axios/1
 with inference `claude-code/2.1.74 (external, cli)`, `x-app: cli`, bearer authorization, Messages version
 `2023-06-01` and betas `claude-code-20250219,oauth-2025-04-20`. The implementation is independent;
 [NOTICE](NOTICE) records the MIT protocol references.
+
+## Choosing between accounts
+
+The portable entry exports `chooseAccount`, `resolveSelection`, `roomOf`, `roomWords` and the structural
+`AccountLike`, `AccountPick`, `Room`, `Considered`, `RunSelection` and `Defaults` types. The host supplies its own
+account records and readings; these functions never read credentials, sign in, refresh, start a run or switch a
+running conversation. Resolve once before starting and keep the selected account for the whole run.
+
+```ts
+import { resolveSelection, roomOf, type AccountLike, type Defaults } from '@byokit/accounts';
+
+// Host-provided account, model and measurement accessors:
+declare const accounts: readonly AccountLike[];
+declare const defaults: Defaults;
+declare function windowsFor(account: AccountLike, demand: readonly string[]):
+  { usedPercent: number; kind: string; resetsAt?: number }[];
+declare function measuredAt(account: AccountLike): number | undefined;
+declare function modelsFor(account: AccountLike): { id: string; available: boolean }[];
+declare function startRunWith(account: AccountLike, model: string): void;
+
+const pick = resolveSelection(accounts, defaults, { account: 'auto', needs: ['provider/model'] },
+  (account, demand) => roomOf(windowsFor(account, demand), measuredAt(account), 'milliseconds'), Date.now(),
+  (account) => modelsFor(account));
+if (pick.ok) startRunWith(pick.account, pick.model);
+```
+
+Auto uses ready subscription accounts (including a rest whose deadline has elapsed). It ranks usable readings
+by most room, earlier refill, then list order; unknown readings follow; exhausted accounts refill first. A reading
+older than 24 hours counts as unknown. A numeric reading without a measurement time retains its room tier,
+with unknown age/confidence. Explicit account ids bypass state and billing filtering: the host must verify the
+selected account is ready before starting, and a failed explicit selection never falls back to another account.
+API key accounts (billed per use) are used only when explicitly selected by id or a ready default.
+
+`sel.model` and deduplicated `sel.needs` form the demand passed to the room reader. Supply `models` to verify
+every demanded model is available. Without it, the host owns model eligibility; `model` is the explicit or default
+model, or an empty string when neither is provided. With a model list, no available model returns `not_included`.
+Without a demand, selection stays within the default account's provider, or the first provider in list order.
+
+Each pick includes every account's `considered` row in list order. It holds only ids, exclusion/ranking codes,
+room figures, measurement age and confidence (`known`, `stale`, `unknown`); no names, emails, credential fields
+or engine messages are copied. The winning row's `reason` is the pick's `why`; other candidate reasons describe
+the deterministic comparison to the Auto winner. Excluded rows carry their first exclusion code. Account ids
+and model ids supplied by the host must themselves be secret-free. The generic returned `account` is the original
+host record: keep credentials outside that record before exposing the whole pick to UI or logs.
+
+`AccountLike.until`, `nowMs`, `Room.at`, `Room.resetsAt` and `Considered.age` use **milliseconds**.
+`roomOf(windows, at, resetUnit?)` accepts structural windows. Legacy reset **epoch seconds** are the default,
+converted by 1000 exactly once. For normalized `@byokit/usage` 0.2.0+ windows, pass `'milliseconds'` as the
+third argument; reset times then stay unchanged. A normalized usage `Room` also passes directly to the chooser.
+The optional `at` is always the original measurement time in epoch milliseconds.
+The current structural input contains `usedPercent`, `kind`, and optional `resetsAt`; hard-limit/model-scope and
+poll-health ingestion is a follow-up to the pending usage extension. Hosts must supply demand-filtered windows
+and authoritative eligibility rather than interpreting an unavailable quota reading as a fresh successful read.
+
+`Provider.multiAccount` gives a terms assessment, reason and source for multiple accounts of that service.
+A grey assessment records missing explicit documentation; it does not gate selection. `auto.terms`, `auto.*`,
+`room.*` and `pick.*` words are exported in `WORDS`.
+
+Identity and re-authentication stay with the host's canonical device store or engine. A provider account id
+scoped by member/provider proves identity; names and emails do not. The TypeScript identity fixture records
+wrong-account, duplicate identity, changed-email, absent-identity, removal/refresh and extension-field boundaries
+for runtime integration; the chooser consumes host-validated state and never adopts credentials itself.
+
+## Managed CLI accounts (Node only)
+
+`@byokit/accounts/cli` exports `cliAccounts`, `CliAccountError`, `CliProvider`, `CliAccount`, `CliOptions` and `SignInCommand`. Accounts use subscription billing. The portable entries and the `Accounts` class retain their existing sign-in flows.
+
+`CliAccount` extends the portable chooser's `AccountLike`. Pass normalized usage through `@byokit/usage`'s `roomOf(reading, nowMs)` when selecting an account, preserving millisecond reset times and the original measurement time.
+
+```ts
+import { cliAccounts } from '@byokit/accounts/cli';
+const accounts = cliAccounts({
+  stateDir: '/app/state/plans',
+  bins: { claude: '/app/bin/claude', codex: '/app/bin/codex' },
+  env: { HOME: '/app/home', PATH: '/app/bin:/usr/bin:/bin' },
+  historyFrom: { claude: '/app/history/projects', codex: '/app/history/sessions' },
+  prepare: async (folder, provider) => { /* app-owned setup, such as installing hooks */ },
+});
+const { account, signIn } = await accounts.add('claude');
+// Run signIn.shell in the app's sign-in tab, or run signIn.argv with signIn.env
+// and create signIn.completion privately only after that command succeeds.
+const current = await accounts.status(account.id);
+const { set, unset } = accounts.launchEnv(account.id);
+// Apply unset to the launch environment, then apply set, before starting the agent.
+```
+
+`stateDir` must be an absolute app-owned directory with an existing parent. The kit creates it at 0700 and creates private `<provider>/<hex>` account folders below it. `bins` are absolute paths; PATH is never used to find the CLI. Status and login use an environment built from nothing plus the app's `env`, after removing provider credential overrides and adding the managed-folder variable. Pass proxy or temporary-directory settings explicitly if needed. `launchEnv` returns the folder variable in `set` and the provider overrides in `unset`; hosts must apply both so a stray API key (billed per use) cannot override the chosen subscription.
+
+`add` returns a `signing` account and the native login command. `status` stays `signing` until the completion marker exists, including after a host restart, and does not run a second native client during pending sign-in. The shell uses a private per-folder lock and marks completion only after successful login. Stop the app's sign-in tab before `cancel` or `remove`; the kit does not supervise that tab. `signInAgain` reuses a pending command or starts a new completion cycle; if an account operation is already in flight it throws `prepare-failed`, so await that operation before retrying. Native CLIs own their refresh transactions; the kit neither copies credentials nor refreshes grants. A crashed sign-in shell can leave its lock; the host should stop that process and remove only that managed lock before retrying.
+
+`list` probes managed folders concurrently; `status`, `rename`, `remove` and `cancel` serialize operations per account. Only signed-in state (`ready` or `signed_out`), email and plan come from native status output; no credential file is opened and raw CLI errors and output are discarded. `rename` accepts a trimmed name of 1–64 characters. `cancel` removes only folders added by this instance; for existing accounts it ends the pending completion cycle without deleting the account. `remove` deletes only a validated managed folder. `historyFrom` creates a history symlink inside that folder; it never creates or writes the target, even when it is missing. A throwing `prepare` rolls back the new folder.
+
+Native status reads resolve within 15 seconds. Claude stdout is capped at 256 KB and identity JSON at 64 KB; the shared Codex client caps stdout at 64 KB. Timeout or excess output terminates only that owned child, with SIGTERM followed by SIGKILL after one second if it is still alive.
+
+The existing `accounts-v1.json` `{version:1,accounts:[{id,provider,name,folder,found}]}` and `auto-terms-v1.json` `{acknowledged:true}` encodings remain unchanged, with 0600 files and atomic replacement. The kit preserves but excludes `found-*` and `found:true` rows, which belong to the host's default-login adapter. Legacy managed rows without kit completion sidecars retain their native signed-in status; new or re-signing rows require the completion marker. Symlinked account folders and records outside the provider/hex layout are refused.
+
+`usageSource(id)` returns a Codex Source for `@byokit/usage`; Claude returns `undefined`, and its usage Source is `{provider:'claude', folder:set.CLAUDE_CONFIG_DIR, headers}` in a usage reader whose `stateDir` is the same managed root. `kinds` serves only the matching native agent (`claude` or `codex`); Pi is excluded until its folder mapping is verified. `resumeArgs` accepts an `id` conversation reference for these kinds. `termsAcknowledged` and `acknowledgeTerms` keep the host's existing terms bit; they do not gate sign-in. `suggestName` uses the first part of an email, falling back to the provider's name.

package/SECURITY.md

@@ -66,7 +66,7 @@ Deleting local files alone does not revoke tokens, and deletion cannot erase old
 
 Tests use fake providers, temporary homes, filesystem canaries and Node permissions;
 `npm test` blocks outbound networking and checks the owner's existing setup byte for byte.
-The kit never invokes the owner's installed tools or borrows environment API keys.
+The kit never borrows environment API keys. Its Node-only `./cli` exception invokes only app-passed absolute CLI binaries against app-managed folders; it never opens credential files or the person's default login. Native CLI credentials remain on the device under the CLI's own storage policy; they do not pass through `fileStore` sealing.
 
 ## Review record
 

package/dist/accounts.d.ts

@@ -55,7 +55,7 @@ export type AnthropicAccountAsk = AnthropicAsk & {
     key: string;
 };
 export type AccountsOptions<M extends Member = Member> = {
-    /** The accounts this app offers, in order. Default: supported subscription providers not hidden. */
+    /** The accounts this app offers, in order. Default: every subscription provider supported on this platform. */
     offer?: readonly string[];
     /** Each member's own store. Default: in memory. */
     store?: (member: M) => CredentialStore;
@@ -112,7 +112,7 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
     onExpired?: (member: M, key: string) => void;
     onSignOutError?: (member: M, key: string, error: Error) => void;
     private platform;
-    /** Offered: the providers named in `offer`, else every provider not hidden that this platform can sign in to. */
+    /** Offered: the providers named in `offer`, else every subscription provider that this platform can sign in to. */
     constructor(opts?: AccountsOptions<M>, platform?: Platform);
     /** A member's own store. */
     protected store(member: M): EndingStore;

package/dist/accounts.js

@@ -51,7 +51,7 @@ export class Accounts {
     onExpired;
     onSignOutError;
     platform;
-    /** Offered: the providers named in `offer`, else every provider not hidden that this platform can sign in to. */
+    /** Offered: the providers named in `offer`, else every subscription provider that this platform can sign in to. */
     constructor(opts = {}, platform = portable) {
         this.opts = opts;
         this.platform = platform;

package/dist/catalogue.d.ts

@@ -1,6 +1,11 @@
-export type Terms = 'allowed' | 'grey' | 'partner' | 'forbidden';
 /** How the person pays: their plan (`subscription`), or per-use charges to their account (`api`, never offered by default). */
 export type Billing = 'subscription' | 'api';
+/** Terms assessment for choosing between several accounts; descriptive, never an eligibility gate. */
+export type MultiAccountTerms = {
+    terms: 'allowed' | 'grey' | 'partner' | 'forbidden';
+    why: string;
+    source: string;
+};
 /** `callbackPort`: where the provider sends the browser back after its own sign-in page, fixed for the client Pi signs in as.
  *  `revoke`: where signing out ends the sign-in on the provider's side too, for the client `clientId`. */
 export type Provider = {
@@ -19,13 +24,11 @@ export type Provider = {
     auth?: 'api-key' | 'oauth';
     label?: string;
     offer?: boolean;
-    terms: Terms;
-    hidden: boolean;
-    why: string;
     source: string;
+    multiAccount: MultiAccountTerms;
 };
 export declare const PROVIDERS: Record<string, Provider>;
 export declare function provider(key: string): Provider;
-/** What an app offers: the keys it names, in its order, or every subscription provider not hidden by default.
+/** What an app offers: the keys it names, in its order, or every subscription provider by default.
  *  API-billed rows are never in the default: an app offers them only by naming them. */
 export declare const offered: (keys?: readonly string[]) => Provider[];

package/dist/catalogue.js

@@ -1,7 +1,3 @@
-// The AI accounts a person can bring, by the name they know, with each provider's billing and terms status as data
-// (catalogue.json, readable from Kotlin too). The kit labels; the app decides what to offer. API-billed rows are never
-// offered by default; an app names them explicitly. Anthropic here is the app-passed API-key route; authentication
-// is separate from Messages, allowing additional opt-in auth routes to be implemented independently.
 import CATALOGUE from './catalogue.json' with { type: 'json' };
 export const PROVIDERS = Object.fromEntries(Object.entries(CATALOGUE).map(([key, p]) => [key, { key, ...p }]));
 export function provider(key) {
@@ -10,6 +6,6 @@ export function provider(key) {
         throw Object.assign(new Error('no such AI account'), { status: 404 });
     return p;
 }
-/** What an app offers: the keys it names, in its order, or every subscription provider not hidden by default.
+/** What an app offers: the keys it names, in its order, or every subscription provider by default.
  *  API-billed rows are never in the default: an app offers them only by naming them. */
-export const offered = (keys) => keys ? keys.map(provider) : Object.values(PROVIDERS).filter((p) => !p.hidden && p.offer !== false && p.billing === 'subscription');
+export const offered = (keys) => keys ? keys.map(provider) : Object.values(PROVIDERS).filter((p) => p.billing === 'subscription');

package/dist/catalogue.json

@@ -11,10 +11,12 @@
         "clientId": "app_EMoamEEZ73f0CkXaXp7hrann",
         "revoke": "https://auth.openai.com/oauth/revoke",
         "billing": "subscription",
-        "terms": "grey",
-        "hidden": false,
-        "why": "Signs in through Codex's own sign-in. OpenAI documents it for Codex, not for other apps, and has endorsed one other app using it.",
-        "source": "https://developers.openai.com/codex/auth"
+        "source": "https://developers.openai.com/codex/auth",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://developers.openai.com/codex/auth"
+        }
     },
     "openrouter": {
         "pi": "openrouter",
@@ -24,10 +26,12 @@
             "strong": "moonshotai/kimi-k2.6"
         },
         "billing": "api",
-        "terms": "allowed",
-        "hidden": false,
-        "why": "Documented sign-in for any app, no registration. Pay-as-you-go credits, not a subscription.",
-        "source": "https://openrouter.ai/docs/guides/overview/auth/oauth"
+        "source": "https://openrouter.ai/docs/guides/overview/auth/oauth",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://openrouter.ai/docs/guides/overview/auth/oauth"
+        }
     },
     "grok": {
         "pi": "xai",
@@ -37,10 +41,12 @@
             "strong": "grok-4.7"
         },
         "billing": "subscription",
-        "terms": "partner",
-        "hidden": true,
-        "why": "xAI allows plan sign-in only in apps it has partnered with.",
-        "source": "https://x.ai/news/grok-opencode"
+        "source": "https://x.ai/news/grok-opencode",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://x.ai/news/grok-opencode"
+        }
     },
     "copilot": {
         "pi": "github-copilot",
@@ -50,10 +56,12 @@
             "strong": "gpt-5.4"
         },
         "billing": "subscription",
-        "terms": "partner",
-        "hidden": true,
-        "why": "GitHub allows Copilot sign-in only in apps it has partnered with; this uses VS Code's client.",
-        "source": "https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode"
+        "source": "https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode"
+        }
     },
     "anthropic": {
         "pi": "anthropic",
@@ -63,13 +71,15 @@
             "strong": "claude-opus-5-5"
         },
         "billing": "api",
-        "terms": "allowed",
-        "hidden": false,
         "auth": "api-key",
         "label": "API key (billed per use)",
         "offer": false,
-        "why": "The app passes an Anthropic API key explicitly. API key (billed per use), never a default or subscription fallback.",
-        "source": "https://platform.claude.com/docs/en/api/overview"
+        "source": "https://platform.claude.com/docs/en/api/overview",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://platform.claude.com/docs/en/api/overview"
+        }
     },
     "claude": {
         "pi": "byokit-claude-plan",
@@ -82,9 +92,73 @@
         "clientId": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
         "billing": "subscription",
         "auth": "oauth",
-        "terms": "grey",
-        "hidden": false,
-        "why": "Anthropic prohibits third-party Claude.ai sign-in without approval; this route may stop working or lead to account restrictions.",
-        "source": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
+        "source": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
+        }
+    },
+    "kimi": {
+        "pi": "kimi-coding",
+        "name": "Kimi",
+        "company": "Moonshot AI",
+        "models": {
+            "strong": "k3",
+            "fast": "kimi-for-coding-highspeed"
+        },
+        "billing": "subscription",
+        "source": "https://www.kimi.com",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://www.kimi.com"
+        }
+    },
+    "meta": {
+        "pi": "meta",
+        "name": "Meta",
+        "company": "Meta",
+        "models": {
+            "strong": "muse-spark-1.3"
+        },
+        "billing": "subscription",
+        "source": "https://www.meta.ai",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://www.meta.ai"
+        }
+    },
+    "qwen": {
+        "pi": "qwen-portal",
+        "name": "Qwen",
+        "company": "Alibaba",
+        "models": {
+            "strong": "qwen3-coder-plus"
+        },
+        "billing": "subscription",
+        "source": "https://chat.qwen.ai",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://chat.qwen.ai"
+        }
+    },
+    "minimax": {
+        "pi": "minimax",
+        "name": "MiniMax",
+        "company": "MiniMax",
+        "models": {
+            "strong": "MiniMax-M3",
+            "fast": "MiniMax-M2.7-highspeed"
+        },
+        "billing": "subscription",
+        "source": "https://www.minimax.io",
+        "multiAccount": {
+            "terms": "grey",
+            "why": "This source does not explicitly document choosing between several accounts of this service in another app.",
+            "source": "https://www.minimax.io"
+        }
     }
 }

package/dist/chatgpt-plan.js

@@ -12,7 +12,7 @@ export function chatgptPlan(o) {
             const session = await o.session(signal);
             if (!session || !Array.isArray(session.scopes) || !session.scopes.includes('chatgpt.tokens.use.direct') ||
                 !session.scopes.includes('resource.invoke') || typeof session.accessToken !== 'string' || !session.accessToken.trim()) {
-                throw new UnsupportedAccountError('ChatGPT plan usage needs a consented token-sharing session.');
+                throw new UnsupportedAccountError('This needs a ChatGPT sign-in that allows plan use.');
             }
             return session.accessToken;
         },

package/dist/cli.d.ts

@@ -0,0 +1,65 @@
+import type { AccountLike } from './multi.ts';
+export type CliProvider = 'claude' | 'codex';
+/** Shared selection surface; the CLI entry remains Node-only. */
+export type CliAccount = AccountLike & {
+    provider: CliProvider;
+    billing: 'subscription';
+    email?: string;
+    plan?: string;
+};
+export type CliOptions = {
+    stateDir: string;
+    bins: Partial<Record<CliProvider, string>>;
+    env: {
+        PATH: string;
+        HOME: string;
+    } & Record<string, string>;
+    historyFrom?: Partial<Record<CliProvider, string>>;
+    prepare?: (folder: string, provider: CliProvider) => Promise<void>;
+};
+export type SignInCommand = {
+    argv: string[];
+    env: Record<string, string>;
+    completion: string;
+    shell: string;
+};
+export declare class CliAccountError extends Error {
+    name: string;
+    readonly code: 'unknown-account' | 'invalid-name' | 'kind-mismatch' | 'prepare-failed' | 'bad-option';
+    constructor(code: CliAccountError['code']);
+}
+/** Only app-managed folders and explicitly supplied absolute CLI binaries. */
+export declare function cliAccounts(options: CliOptions): {
+    list: () => Promise<CliAccount[]>;
+    add(provider: CliProvider): Promise<{
+        account: CliAccount;
+        signIn: SignInCommand;
+    }>;
+    signInAgain: (id: string) => SignInCommand;
+    status: (id: string) => Promise<CliAccount>;
+    cancel(id: string): Promise<{
+        removed: boolean;
+    }>;
+    rename(id: string, name: string): Promise<CliAccount>;
+    remove: (id: string) => Promise<void>;
+    launchEnv: (id: string) => {
+        set: {
+            [x: string]: string;
+        };
+        unset: string[];
+    };
+    kinds: (provider: CliProvider) => string[];
+    resumeArgs(kind: string, ref: {
+        kind: "id" | "path";
+        value: string;
+    }): string[];
+    usageSource(id: string): {
+        provider: "codex";
+        bin: string;
+        home: string;
+        env: Record<string, string>;
+    } | undefined;
+    termsAcknowledged: () => boolean;
+    acknowledgeTerms: () => void;
+    suggestName: (email: string | undefined, provider: CliProvider) => string;
+};

package/dist/cli.js

@@ -0,0 +1,337 @@
+import { spawn } from 'node:child_process';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { identity } from '@byokit/usage';
+import { say } from "./words.js";
+export class CliAccountError extends Error {
+    name = 'CliAccountError';
+    code;
+    constructor(code) {
+        super(say({ 'unknown-account': 'cli.unknownAccount', 'invalid-name': 'cli.invalidName', 'kind-mismatch': 'cli.kindMismatch', 'prepare-failed': 'cli.prepareFailed', 'bad-option': 'cli.badOption' }[code]));
+        this.code = code;
+    }
+}
+const record = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v) => typeof v === 'string' && !v.includes('\0');
+const providers = ['claude', 'codex'];
+const shed = {
+    claude: ['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'CLAUDE_CODE_USE_ANTHROPIC_AWS', 'CLAUDE_CODE_USE_MANTLE', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_PROFILE', 'ANTHROPIC_FEDERATION_RULE_ID'],
+    codex: ['OPENAI_API_KEY', 'CODEX_API_KEY'],
+};
+const folderVar = (p) => p === 'claude' ? 'CLAUDE_CONFIG_DIR' : 'CODEX_HOME';
+const quote = (v) => `'${v.replaceAll("'", "'\\''")}'`;
+const complete = (r) => join(r.folder, '.byokit-signin-complete');
+const pending = (r) => join(r.folder, '.byokit-signin-pending');
+function marker(file) {
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new CliAccountError('bad-option');
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function json(file) {
+    let fd;
+    try {
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > 256 * 1024)
+            return undefined;
+        const data = Buffer.alloc(256 * 1024 + 1);
+        let n = 0;
+        while (n < data.length) {
+            const count = readSync(fd, data, n, data.length - n, null);
+            if (!count)
+                break;
+            n += count;
+        }
+        return n < data.length ? JSON.parse(data.subarray(0, n).toString('utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function directory(path, create = false) {
+    try {
+        const s = lstatSync(path);
+        return s.isDirectory() && !s.isSymbolicLink();
+    }
+    catch (error) {
+        if (create && error.code === 'ENOENT') {
+            mkdirSync(path, { mode: 0o700 });
+            return true;
+        }
+        return false;
+    }
+}
+/** Only app-managed folders and explicitly supplied absolute CLI binaries. */
+export function cliAccounts(options) {
+    if (!record(options) || !text(options.stateDir) || !isAbsolute(options.stateDir) || !record(options.bins) || !record(options.env) || !text(options.env.PATH) || !text(options.env.HOME) || !isAbsolute(options.env.HOME))
+        throw new CliAccountError('bad-option');
+    if (Object.entries(options.env).some(([k, v]) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(k) || !text(v)))
+        throw new CliAccountError('bad-option');
+    if (Object.entries(options.bins).some(([p, bin]) => !providers.includes(p) || !text(bin) || !isAbsolute(bin)))
+        throw new CliAccountError('bad-option');
+    if (options.historyFrom && (!record(options.historyFrom) || Object.entries(options.historyFrom).some(([p, path]) => !providers.includes(p) || !text(path) || !isAbsolute(path))))
+        throw new CliAccountError('bad-option');
+    const stateDir = resolve(options.stateDir);
+    const env = { ...options.env };
+    const bins = { ...options.bins };
+    const history = { ...options.historyFrom };
+    for (const path of ['.claude', '.codex', '.pi']) {
+        const own = join(resolve(env.HOME), path);
+        if (stateDir === own || stateDir.startsWith(own + '/'))
+            throw new CliAccountError('bad-option');
+    }
+    // Parents must already be app-owned. Never follow a state/provider/folder symlink.
+    try {
+        if (realpathSync(dirname(stateDir)) !== dirname(stateDir))
+            throw new CliAccountError('bad-option');
+    }
+    catch {
+        throw new CliAccountError('bad-option');
+    }
+    if (!directory(stateDir, true))
+        throw new CliAccountError('bad-option');
+    chmodSync(stateDir, 0o700);
+    const file = join(stateDir, 'accounts-v1.json');
+    const created = new Set();
+    const operations = new Map();
+    function safe(r) {
+        const parent = join(stateDir, r.provider);
+        return resolve(r.folder) === r.folder && r.folder.startsWith(parent + '/') && /^[a-f0-9]+$/.test(r.folder.slice(parent.length + 1)) && directory(stateDir) && realpathSync(stateDir) === stateDir && directory(parent) && directory(r.folder);
+    }
+    function load() {
+        if (!directory(stateDir) || realpathSync(stateDir) !== stateDir)
+            throw new CliAccountError('bad-option');
+        const saved = json(file);
+        if (!record(saved) || !Array.isArray(saved.accounts))
+            return [];
+        const seen = new Set();
+        const rows = [];
+        for (const candidate of saved.accounts) {
+            if (!record(candidate) || !text(candidate.id) || !candidate.id || candidate.id.length > 128 || seen.has(candidate.id) || !providers.includes(candidate.provider) || !text(candidate.name) || candidate.name.length > 64 || !text(candidate.folder) || typeof candidate.found !== 'boolean')
+                continue;
+            const r = { id: candidate.id, provider: candidate.provider, name: candidate.name, folder: candidate.folder, found: candidate.found };
+            // Host-owned rows remain byte-compatible in the roster, without touching their folder.
+            if (!r.found && !r.id.startsWith('found-') && !safe(r))
+                continue;
+            seen.add(r.id);
+            rows.push(r);
+        }
+        return rows;
+    }
+    function atomic(path, value) {
+        if (!directory(stateDir) || realpathSync(stateDir) !== stateDir)
+            throw new CliAccountError('bad-option');
+        const tmp = `${path}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(tmp, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+            renameSync(tmp, path);
+        }
+        catch {
+            throw new CliAccountError('prepare-failed');
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+    }
+    const save = (rows) => atomic(file, { version: 1, accounts: rows });
+    function row(id) {
+        const r = load().find((r) => r.id === id && !r.found && !r.id.startsWith('found-'));
+        if (!r)
+            throw new CliAccountError('unknown-account');
+        return r;
+    }
+    function binary(p) { const bin = bins[p]; if (!bin)
+        throw new CliAccountError('bad-option'); return bin; }
+    function launch(r) { return { set: { [folderVar(r.provider)]: r.folder }, unset: [...shed[r.provider]] }; }
+    function spawnEnv(r) {
+        const out = { ...env };
+        for (const key of shed[r.provider])
+            delete out[key];
+        delete out.CLAUDE_CONFIG_DIR;
+        delete out.CODEX_HOME;
+        return { ...out, ...launch(r).set };
+    }
+    function command(r) {
+        const argv = r.provider === 'claude' ? [binary(r.provider), 'auth', 'login', '--claudeai'] : [binary(r.provider), 'login', '--device-auth'];
+        const passed = spawnEnv(r);
+        const completion = complete(r);
+        const lock = join(r.folder, '.byokit-signin-lock');
+        const login = ['/usr/bin/env', '-i', ...Object.entries(passed).map(([k, v]) => `${k}=${v}`), ...argv].map(quote).join(' ');
+        // Cross-process guard: a native CLI owns any refresh transaction; the kit never copies or refreshes its grants.
+        const shell = `(umask 077; /bin/mkdir ${quote(lock)} || exit 1; trap ${quote(`/bin/rmdir ${quote(lock)}`)} EXIT; ${login} && (set -C; printf complete > ${quote(completion)}))`;
+        return { argv, env: passed, completion, shell };
+    }
+    function begin(r) {
+        const result = command(r);
+        // Refuse overlapping sign-in starts; reuse the pending command until completion or cancel.
+        if (!marker(pending(r)) || marker(complete(r))) {
+            rmSync(complete(r), { force: true });
+            if (!marker(pending(r)))
+                writeFileSync(pending(r), '', { mode: 0o600, flag: 'wx' });
+        }
+        return result;
+    }
+    function serial(id, action) {
+        const task = (operations.get(id) ?? Promise.resolve()).then(action, action);
+        operations.set(id, task);
+        return task.finally(() => { if (operations.get(id) === task)
+            operations.delete(id); });
+    }
+    async function readIdentity(r) {
+        if (r.provider === 'codex')
+            return identity({ provider: 'codex', bin: binary('codex'), home: r.folder, env: spawnEnv(r) });
+        return new Promise((accept) => {
+            const child = spawn(binary('claude'), ['auth', 'status'], { env: spawnEnv(r), stdio: ['ignore', 'pipe', 'ignore'] });
+            let stdout = '';
+            let bytes = 0;
+            let settled = false;
+            let escalation;
+            const finish = (answer) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (child.exitCode === null && child.signalCode === null) {
+                    child.kill('SIGTERM');
+                    escalation = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                        child.kill('SIGKILL'); }, 1000);
+                }
+                accept(answer);
+            };
+            const timer = setTimeout(() => finish({ signedIn: false }), 15_000);
+            child.once('error', () => finish({ signedIn: false }));
+            child.stdout.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => {
+                if (settled)
+                    return;
+                bytes += Buffer.byteLength(chunk);
+                if (bytes > 256 * 1024) {
+                    finish({ signedIn: false });
+                    return;
+                }
+                stdout += chunk;
+            });
+            child.once('close', () => {
+                clearTimeout(escalation);
+                if (settled)
+                    return;
+                if (bytes > 64 * 1024) {
+                    finish({ signedIn: false });
+                    return;
+                }
+                let raw;
+                try {
+                    raw = JSON.parse(stdout);
+                }
+                catch {
+                    finish({ signedIn: false });
+                    return;
+                }
+                if (!record(raw) || raw.loggedIn !== true) {
+                    finish({ signedIn: false });
+                    return;
+                }
+                const email = typeof raw.email === 'string' && raw.email.length <= 320 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw.email) ? raw.email : undefined;
+                const plan = [raw.subscriptionType, raw.plan, raw.planName, raw.tier].find((v) => typeof v === 'string' && /^[a-zA-Z][a-zA-Z0-9 _+-]{0,63}$/.test(v));
+                finish({ signedIn: true, ...(email ? { email } : {}), ...(typeof plan === 'string' ? { plan } : {}) });
+            });
+        });
+    }
+    function suggestName(email, provider) {
+        const first = email?.split('@')[0]?.split(/[._-]+/).find(Boolean);
+        return first ? (first[0].toUpperCase() + first.slice(1).toLowerCase()).slice(0, 64) : provider === 'claude' ? 'Claude' : 'Codex';
+    }
+    async function status(id) {
+        return serial(id, async () => {
+            const r = row(id);
+            const signing = marker(pending(r)) && !marker(complete(r));
+            if (signing)
+                return { id: r.id, provider: r.provider, name: r.name.trim() || suggestName(undefined, r.provider), billing: 'subscription', state: 'signing' };
+            const info = await readIdentity(r);
+            if (marker(pending(r)))
+                rmSync(pending(r), { force: true });
+            // Pre-existing roster rows have no kit marker; their native status remains authoritative.
+            return { id: r.id, provider: r.provider, name: r.name.trim() || suggestName(info.email, r.provider), billing: 'subscription', state: info.signedIn ? 'ready' : 'signed_out', ...(info.email ? { email: info.email } : {}), ...(info.plan ? { plan: info.plan } : {}) };
+        });
+    }
+    async function remove(id) {
+        return serial(id, async () => { const r = row(id); rmSync(r.folder, { recursive: true, force: true }); save(load().filter((v) => v.id !== id)); created.delete(id); });
+    }
+    return {
+        list: async () => Promise.all(load().filter((r) => !r.found && !r.id.startsWith('found-')).map((r) => status(r.id))),
+        async add(provider) {
+            if (!providers.includes(provider))
+                throw new CliAccountError('bad-option');
+            binary(provider);
+            const parent = join(stateDir, provider);
+            if (!directory(stateDir) || !directory(parent, true))
+                throw new CliAccountError('bad-option');
+            chmodSync(parent, 0o700);
+            const r = { id: `pa_${randomBytes(9).toString('hex')}`, provider, name: '', folder: join(parent, randomBytes(8).toString('hex')), found: false };
+            mkdirSync(r.folder, { mode: 0o700 });
+            try {
+                if (history[provider])
+                    symlinkSync(history[provider], join(r.folder, provider === 'claude' ? 'projects' : 'sessions'), 'dir');
+                const signIn = begin(r);
+                await options.prepare?.(r.folder, provider);
+                if (!safe(r))
+                    throw new CliAccountError('prepare-failed');
+                save([...load(), r]);
+                created.add(r.id);
+                return { account: { id: r.id, provider, name: suggestName(undefined, provider), billing: 'subscription', state: 'signing' }, signIn };
+            }
+            catch {
+                rmSync(r.folder, { recursive: true, force: true });
+                throw new CliAccountError('prepare-failed');
+            }
+        },
+        signInAgain: (id) => {
+            if (operations.has(id))
+                throw new CliAccountError('prepare-failed');
+            return begin(row(id));
+        },
+        status,
+        async cancel(id) {
+            if (created.has(id)) {
+                await remove(id);
+                return { removed: true };
+            }
+            return serial(id, async () => { const r = row(id); rmSync(pending(r), { force: true }); return { removed: false }; });
+        },
+        async rename(id, name) {
+            if (!text(name) || !name.trim() || name.trim().length > 64 || /[\x00-\x1f\x7f]/.test(name))
+                throw new CliAccountError('invalid-name');
+            await serial(id, async () => { row(id); const rows = load(); rows.find((r) => r.id === id).name = name.trim(); save(rows); });
+            return status(id);
+        },
+        remove,
+        launchEnv: (id) => launch(row(id)),
+        kinds: (provider) => providers.includes(provider) ? [provider] : [],
+        resumeArgs(kind, ref) {
+            if (!text(ref.value) || !ref.value || (kind !== 'claude' && kind !== 'codex') || (kind === 'claude' && ref.kind !== 'id') || (kind === 'codex' && ref.kind !== 'id'))
+                throw new CliAccountError('kind-mismatch');
+            return kind === 'claude' ? ['--resume', ref.value] : ['resume', ref.value];
+        },
+        usageSource(id) {
+            const r = row(id);
+            return r.provider === 'codex' ? { provider: 'codex', bin: binary('codex'), home: r.folder, env: spawnEnv(r) } : undefined;
+        },
+        termsAcknowledged: () => { if (!directory(stateDir))
+            throw new CliAccountError('bad-option'); const saved = json(join(stateDir, 'auto-terms-v1.json')); return record(saved) && saved.acknowledged === true; },
+        acknowledgeTerms: () => atomic(join(stateDir, 'auto-terms-v1.json'), { acknowledged: true }),
+        suggestName,
+    };
+}

package/dist/multi.d.ts

@@ -0,0 +1,77 @@
+export type SignInState = 'ready' | 'signing' | 'resting' | 'signed_out' | 'needs_again' | 'not_included';
+export type AccountLike = {
+    id: string;
+    provider: string;
+    name: string;
+    state: SignInState;
+    billing: 'subscription' | 'api';
+    until?: number;
+};
+export type RoomSpan = 'session' | 'week' | 'month' | 'tightest';
+/** Every time here is epoch milliseconds; `at` is the source measurement time, never its receipt time. */
+export type Room = {
+    left: number;
+    span: RoomSpan;
+    resetsAt?: number;
+    at?: number;
+} | {
+    left: 'unknown';
+    at?: number;
+};
+export type RunSelection = {
+    account: string | 'default' | 'auto';
+    model?: string;
+    needs?: string[];
+};
+export type Defaults = {
+    account?: string;
+    model?: string;
+    auto?: boolean;
+};
+export type PickWhy = 'chosen' | 'default' | 'first_ready' | 'only' | 'most_room' | 'earlier_reset' | 'list_order' | 'no_reading' | 'refills_first';
+export type Considered = {
+    id: string;
+    out?: 'state' | 'resting' | 'billing' | 'model' | 'provider';
+    until?: number;
+    missing?: string;
+    tier?: 'room' | 'unknown' | 'exhausted';
+    left: number | 'unknown';
+    span?: RoomSpan;
+    resetsAt?: number;
+    age: number | 'unknown';
+    confidence: 'known' | 'stale' | 'unknown';
+    reason: PickWhy | 'state' | 'resting' | 'billing' | 'model' | 'provider';
+};
+export type AccountPick<A extends AccountLike = AccountLike> = {
+    ok: true;
+    account: A;
+    model: string;
+    how: 'chosen' | 'default' | 'auto';
+    why: PickWhy;
+    reason: string;
+    considered: Considered[];
+} | {
+    ok: false;
+    code: 'none' | 'not_included' | 'unknown_account';
+    reason: string;
+    considered: Considered[];
+};
+type Models<A> = (a: A) => readonly {
+    id: string;
+    available: boolean;
+}[];
+/** Structural windows: legacy reset seconds by default; usage 0.2.0+ must pass milliseconds explicitly. */
+export declare function roomOf(windows: readonly {
+    usedPercent: number;
+    kind: string;
+    resetsAt?: number;
+}[], at?: number, resetUnit?: 'seconds' | 'milliseconds'): Room;
+export declare function roomWords(room: Room): string;
+/** Auto's winner only. Pure and portable; no timers, reads, refreshes or mid-run switching. */
+export declare function chooseAccount<A extends AccountLike>(accounts: readonly A[], room: (a: A) => Room, nowMs: number): {
+    account: A;
+    why: PickWhy;
+} | undefined;
+/** Resolve once before starting. Without `models`, membership is host-validated and a missing model is ''. */
+export declare function resolveSelection<A extends AccountLike>(accounts: readonly A[], defaults: Defaults, sel: RunSelection, room: (a: A, demand: readonly string[]) => Room, nowMs: number, models?: Models<A>): AccountPick<A>;
+export {};

package/dist/multi.js

@@ -0,0 +1,134 @@
+// Pure start-of-run selection. Callers own identities and credentials and keep the returned account for the run.
+import { clock, say } from "./words.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+const reset = (r) => r.resetsAt ?? Infinity;
+/** Structural windows: legacy reset seconds by default; usage 0.2.0+ must pass milliseconds explicitly. */
+export function roomOf(windows, at, resetUnit = 'seconds') {
+    const known = windows.filter((w) => finite(w.usedPercent));
+    if (!known.length)
+        return { left: 'unknown', ...(finite(at) ? { at } : {}) };
+    const w = known.reduce((a, b) => b.usedPercent > a.usedPercent ? b : a);
+    const span = w.kind === 'session' ? 'session' : w.kind === 'weekly' ? 'week' : w.kind === 'monthly' ? 'month' : 'tightest';
+    return { left: Math.max(0, Math.min(100, 100 - w.usedPercent)), span,
+        ...(finite(w.resetsAt) ? { resetsAt: w.resetsAt * (resetUnit === 'seconds' ? 1000 : 1) } : {}), ...(finite(at) ? { at } : {}) };
+}
+export function roomWords(room) {
+    return room.left === 'unknown' ? say('room.unknown') : say(`room.${room.span}`, { left: `${Math.round(room.left)}%` });
+}
+// One shared eligibility predicate for direct picks, Auto and all explanation rows. Room is read once per row.
+function consider(accounts, room, nowMs, demand = [], models, provider, named) {
+    return accounts.map((account) => {
+        const r = room(account);
+        const age = finite(r.at) ? Math.max(0, nowMs - r.at) : 'unknown';
+        const stale = typeof age === 'number' && age > DAY_MS;
+        const left = r.left === 'unknown' || !finite(r.left) || stale ? 'unknown' : Math.max(0, Math.min(100, r.left));
+        const row = { id: account.id, left, age,
+            confidence: stale ? 'stale' : left === 'unknown' || age === 'unknown' ? 'unknown' : 'known', reason: 'no_reading' };
+        if (r.left !== 'unknown') {
+            row.span = r.span;
+            if (finite(r.resetsAt))
+                row.resetsAt = r.resetsAt;
+        }
+        // Explicit ids bypass state and billing: the host verifies readiness before starting, never falls back.
+        if (account.id !== named) {
+            if (account.state === 'resting' && finite(account.until) && account.until > nowMs) {
+                row.out = 'resting';
+                row.until = account.until;
+            }
+            else if (account.state !== 'ready' && !(account.state === 'resting' && finite(account.until) && account.until <= nowMs))
+                row.out = 'state';
+            else if (account.billing !== 'subscription')
+                row.out = 'billing';
+        }
+        if (!row.out && demand.length && models) {
+            const available = models(account);
+            const missing = demand.find((id) => !available.some((m) => m.id === id && m.available));
+            if (missing !== undefined) {
+                row.out = 'model';
+                row.missing = missing;
+            }
+        }
+        if (!row.out && !demand.length && provider !== undefined && account.provider !== provider && account.id !== named)
+            row.out = 'provider';
+        if (row.out)
+            row.reason = row.out;
+        else
+            row.tier = left === 'unknown' ? 'unknown' : left > 0 || reset(row) <= nowMs ? 'room' : 'exhausted';
+        return { account, row };
+    });
+}
+const tierOrder = { room: 0, unknown: 1, exhausted: 2 };
+function compare(a, b) {
+    const tier = tierOrder[a.row.tier] - tierOrder[b.row.tier];
+    if (tier)
+        return tier;
+    if (a.row.tier === 'unknown')
+        return 0;
+    if (a.row.tier === 'room' && a.row.left !== b.row.left)
+        return Number(b.row.left) - Number(a.row.left);
+    // Avoid Infinity - Infinity (NaN); stable sort preserves list order for ties.
+    return reset(a.row) === reset(b.row) ? 0 : reset(a.row) < reset(b.row) ? -1 : 1;
+}
+function rankingReason(winner, next) {
+    if (winner.row.tier === 'unknown')
+        return 'no_reading';
+    if (winner.row.tier === 'exhausted')
+        return 'refills_first';
+    if (!next || next.row.tier !== 'room' || winner.row.left !== next.row.left)
+        return 'most_room';
+    return reset(winner.row) < reset(next.row) ? 'earlier_reset' : 'list_order';
+}
+function rank(rows) {
+    const ranked = rows.filter((c) => !c.row.out).sort(compare);
+    const winner = ranked[0];
+    if (!winner)
+        return undefined;
+    const why = ranked.length === 1 ? 'only' : rankingReason(winner, ranked[1]);
+    for (const c of ranked)
+        c.row.reason = c === winner ? why : rankingReason(winner, c);
+    return { account: winner.account, why, row: winner.row };
+}
+/** Auto's winner only. Pure and portable; no timers, reads, refreshes or mid-run switching. */
+export function chooseAccount(accounts, room, nowMs) {
+    const pick = rank(consider(accounts, room, nowMs));
+    return pick && { account: pick.account, why: pick.why };
+}
+/** Resolve once before starting. Without `models`, membership is host-validated and a missing model is ''. */
+export function resolveSelection(accounts, defaults, sel, room, nowMs, models) {
+    const demand = [...new Set([...(sel.model ? [sel.model] : []), ...(sel.needs ?? [])])];
+    const defaultAccount = accounts.find((a) => a.id === defaults.account);
+    const named = sel.account === 'default' ? defaultAccount?.state === 'ready' ? defaultAccount.id : undefined : sel.account === 'auto' ? undefined : sel.account;
+    const provider = defaultAccount?.provider ?? accounts[0]?.provider;
+    const rows = consider(accounts, (a) => room(a, demand), nowMs, demand, models, provider, named);
+    const considered = rows.map((c) => c.row);
+    const auto = rank(rows); // also fills explanations for every eligible row, even on explicit selection
+    if (named !== undefined) {
+        const chosen = rows.find((c) => c.account.id === named);
+        if (!chosen)
+            return { ok: false, code: 'unknown_account', reason: say('pick.unknownAccount'), considered };
+        if (chosen.row.out)
+            return { ok: false, code: 'not_included', reason: say('pick.out.model', { model: chosen.row.missing ?? '' }), considered };
+        return finish(chosen.account, chosen.row, sel.account === 'default' ? 'default' : 'chosen', sel.account === 'default' ? 'default' : 'chosen');
+    }
+    if (sel.account === 'default' && defaults.auto === false) {
+        const first = rows.find((c) => !c.row.out);
+        if (first)
+            return finish(first.account, first.row, 'default', 'first_ready');
+    }
+    else if (auto)
+        return finish(auto.account, auto.row, 'auto', auto.why);
+    return { ok: false, code: 'none', reason: say('auto.none', { provider: provider ?? '' }), considered };
+    function finish(account, row, how, why) {
+        const available = models?.(account).filter((m) => m.available);
+        const model = sel.model ?? (defaults.model && (!available || available.some((m) => m.id === defaults.model)) ? defaults.model : available?.[0]?.id) ?? '';
+        if (models && !model)
+            return { ok: false, code: 'not_included', reason: say('pick.noModel'), considered };
+        row.reason = why;
+        const slots = { name: account.name, provider: account.provider };
+        const reason = how !== 'auto' ? say(`pick.why.${why}`, slots) : row.tier === 'unknown' ? say('auto.unknown', slots) : row.tier === 'exhausted' ?
+            say(finite(row.resetsAt) ? 'auto.refills' : 'auto.refillsNoTime', { ...slots, time: finite(row.resetsAt) ? clock(row.resetsAt) : '' }) :
+            say('auto.room', { ...slots, room: roomWords({ left: Number(row.left), span: row.span ?? 'tightest' }) });
+        return { ok: true, account, model, how, why, reason, considered };
+    }
+}

package/dist/portable.d.ts

@@ -1,5 +1,5 @@
 export { Accounts, planOf, portable, type AccountsOptions, type ClaudePlanAsk, type AnthropicAccountAsk, type AuthHost, type Loopback, type Member, type Platform, type SignIn, type Status } from './accounts.ts';
-export { PROVIDERS, offered, provider, type Billing, type Provider, type Terms } from './catalogue.ts';
+export { PROVIDERS, offered, provider, type Billing, type MultiAccountTerms, type Provider } from './catalogue.ts';
 export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine, type EngineOptions, type Poll } from './engine.ts';
 export { REST_MS, classify, classifyFailure, type Failure, type Kind } from './limits.ts';
 export { IncompleteError, ResponseError, isFunctionCall, limitResponse, respond, sseReader, type Ask, type ResponseFunctionCall, type ResponseInputItem, type ResponseOutputItem, type ResponseOutputMessage, type ResponseReasoning, type ResponseResult, type ResponseStreamEvent, type ResponseText, type ResponseTextFormat, type ResponseTool, type ResponseToolChoice } from './responses.ts';
@@ -8,3 +8,4 @@ export { WORDS, billingWords, callbackPage, clock, failure, say, signInError, ty
 export { chatgptPlan, UnsupportedAccountError, type ChatGPTPlanAccount, type ChatGPTPlanSession } from './chatgpt-plan.ts';
 export { anthropic, anthropicSseReader, AnthropicIncompleteError, type AnthropicAsk, type AnthropicCacheControl, type AnthropicContent, type AnthropicImage, type AnthropicMessage, type AnthropicOptions, type AnthropicRequest, type AnthropicResponse, type AnthropicResult, type AnthropicStreamEvent, type AnthropicText, type AnthropicThinking, type AnthropicTool, type AnthropicToolChoice, type AnthropicToolUse, type AnthropicUsage } from './anthropic.ts';
 export { ClaudePlanExpiredError, ClaudePlanPlatformError, claudeAuthorization, claudeCode, type ClaudePlanOptions } from './claude-plan.ts';
+export { chooseAccount, resolveSelection, roomOf, roomWords, type AccountLike, type AccountPick, type Considered, type Defaults, type PickWhy, type Room, type RoomSpan, type RunSelection, type SignInState } from './multi.ts';

package/dist/portable.js

@@ -10,3 +10,4 @@ export { WORDS, billingWords, callbackPage, clock, failure, say, signInError } f
 export { chatgptPlan, UnsupportedAccountError } from "./chatgpt-plan.js";
 export { anthropic, anthropicSseReader, AnthropicIncompleteError } from "./anthropic.js";
 export { ClaudePlanExpiredError, ClaudePlanPlatformError, claudeAuthorization, claudeCode } from "./claude-plan.js";
+export { chooseAccount, resolveSelection, roomOf, roomWords } from "./multi.js";

package/dist/words.json

@@ -1,5 +1,5 @@
 {
-    "signIn.opening": "Opening {name}…",
+    "signIn.opening": "Opening {name}\u2026",
     "signIn.waitingUrl": "Sign in on the {name} page that just opened.",
     "signIn.waitingCode": "On the {name} page, type this code: {code}",
     "signIn.pasteHint": "Having trouble? Copy the address from the browser and paste it here.",
@@ -12,7 +12,7 @@
     "signIn.busy": "Something else on this computer is signing in to {name}. Try again in a minute.",
     "signIn.failed": "{name} didn't finish the sign-in. Tap Sign in with {name} to try again.",
     "status.ready": "{name} is connected.",
-    "status.signing": "Signing in to {name}…",
+    "status.signing": "Signing in to {name}\u2026",
     "status.resting": "{name} is resting until {until}.",
     "status.busy": "{name} is busy right now.",
     "status.signedOut": "{name} isn't signed in yet.",
@@ -25,5 +25,42 @@
     "callback.declined": "No problem. Nothing was changed. You can go back to {app}.",
     "callback.failed": "{error} Go back to {app}.",
     "callback.nearly": "Nearly there. Go back to {app} to finish.",
-    "callback.outOfDate": "This sign-in page is out of date. Go back to {app} and tap Sign in with {name} again."
+    "callback.outOfDate": "This sign-in page is out of date. Go back to {app} and tap Sign in with {name} again.",
+    "auto.terms": "Auto may use either of a provider's accounts.",
+    "auto.room": "Right now that's {name}: {room}",
+    "auto.unknown": "Right now that's {name} (no recent reading)",
+    "auto.refills": "All {provider} accounts are out of room until {time}. {name} refills first.",
+    "auto.refillsNoTime": "All {provider} accounts are out of room. {name} refills first.",
+    "auto.none": "No signed-in {provider} account.",
+    "room.unknown": "Room left unknown",
+    "room.session": "{left} left this session",
+    "room.week": "{left} left this week",
+    "room.month": "{left} left this month",
+    "room.tightest": "{left} left for now",
+    "pick.out.state": "Not signed in right now",
+    "pick.out.resting": "Taking a break until {time}",
+    "pick.out.billing": "Billed per use, so used only when you choose it",
+    "pick.out.model": "Doesn't include {model}",
+    "pick.out.provider": "A different service",
+    "pick.out.bound": "This conversation uses another account",
+    "pick.unknownAccount": "That account is no longer in your list.",
+    "pick.noModel": "That account doesn't include a model for this run.",
+    "pick.why.chosen": "You chose {name}.",
+    "pick.why.default": "{name} is your default.",
+    "pick.why.first_ready": "Your default isn't ready, so {name}, the first ready account.",
+    "pick.why.only": "{name} is the only account that can take this.",
+    "pick.why.most_room": "{name} has the most room left.",
+    "pick.why.earlier_reset": "{name} has as much room left and refills sooner.",
+    "pick.why.list_order": "{name} is tied for room and comes first in your list.",
+    "pick.why.no_reading": "No account has a recent reading, so {name}, first in your list.",
+    "pick.why.refills_first": "All accounts are out of room; {name} refills first.",
+    "pick.age": "Read {ago} ago",
+    "pick.ageUnknown": "Reading time unknown",
+    "ago.minutes": "{n} minutes",
+    "ago.hours": "{n} hours",
+    "cli.unknownAccount": "Choose an account from the list.",
+    "cli.invalidName": "Give the account a name up to 64 characters.",
+    "cli.kindMismatch": "That agent cannot use this account.",
+    "cli.prepareFailed": "Could not prepare the account. Try again.",
+    "cli.badOption": "The app supplied invalid account options."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Sign in with the AI plan you already pay for, into your app's own store.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,6 +29,10 @@
       "types": "./dist/isolate.d.ts",
       "default": "./dist/isolate.js"
     },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
@@ -48,6 +52,7 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
+    "@byokit/usage": "0.4.0",
     "@earendil-works/pi-ai": "0.87.1"
   },
   "publishConfig": {