@modelprofile.com/authswitch 5.1.0 → 6.0.0

package/readme.md

@@ -193,14 +193,36 @@ concerns the instances running on it. The command line, the dashboard and a host
 such as AGL all read this one rule; `remove` and a save that keeps the login
 active leave the loaded login in place.
 
+That rule, `assertAuthSwitchMutation` and the `TAuthSwitchMutation` command are also
+published on their own at `@modelprofile.com/authswitch/mutation`, which is the one
+import of this package a browser can bundle:
+
+```ts
+import { authSwitchMutationReplacesLogin, type TAuthSwitchMutation } from '@modelprofile.com/authswitch/mutation';
+```
+
+That module imports nothing at all -- no Node built-in, no package, no other module of
+this one -- so a web client decides what a mutation means to the instances it shows
+without pulling a credential store into the bundle. The package root stays Node-only:
+it reaches the stash, and with it `node:fs`, `node:child_process` and `node:crypto`.
+Both entry points export the same three names from the same source, so a Node caller
+can keep importing them from the package root.
+
 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
+Codex. An `anthropic` OAuth login holds the same Claude subscriber grant Claude Code
+stores, so it reports Claude's own plan, organization and usage windows through the
+account endpoints described under **Claude Code**; OpenCode keeps no scopes and no
+account identity with that entry, so both are left to the service. Renewing that token
+stays OpenCode's -- the renewal rotates the refresh token a running OpenCode holds in
+memory, which authswitch cannot write into an instance it does not manage -- so an access
+token inside Claude Code's five-minute margin is reported as expired instead, with the
+two ways to renew it. 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.
 
@@ -239,19 +261,27 @@ authswitch does not infer them from account creation or token expiry dates. The
 Claude Code adapter declares that, so `limits` explains it once for the provider
 instead of per account.
 
-Nothing but Claude Code refreshes a Claude login, so a saved one stops being readable
-a few hours after it was saved. Reading a **saved, inactive** account's status therefore
+Nothing but Claude Code refreshes a Claude login, so a saved one stops being readable a
+few hours after it was saved. Reading a **saved, inactive** account's status therefore
 refreshes it first, exactly as Claude Code would: when its access token expires within
 five minutes, authswitch exchanges the stored refresh token at Claude's token endpoint,
 keeps every other field of the login, and writes the result only while the saved record
-still holds the refresh token it sent. The refresh holds the account store's lock, so a
-switch started at the same time waits for it and then activates the refreshed login. The
-**active** login is never refreshed -- Claude Code owns it, and two parties refreshing one
-login can invalidate the grant. A refusal is reported, never worked around -- a rejected
-grant says so and says what fixes it (below), and a service failure, an unreachable service
-or an unsupported response leave the saved login untouched. Requests carry `User-Agent:
-authswitch/<version>`, and HTTP 429 is reported as rate limiting with the service's retry
-time -- never as an exhausted or expired account.
+still holds the refresh token it sent. The request is the one Claude Code sends, down to
+the scopes: a login of Claude Code's own OAuth client is renewed with Claude Code's
+current scope set plus the project scopes the login carries -- not with the set the
+login happens to be stored under, which can be an older or wider one the service no
+longer accepts -- and a set the service refuses as `invalid_scope` is sent once more
+with the stored scopes. A login that names its own OAuth client keeps its stored scopes,
+because only that client's grant knows them. A login that is neither one of Claude
+Code's subscriber logins nor stored with a plan is not sent at all. The refresh holds
+the account store's lock, so a switch started at the same time waits for it and then
+activates the refreshed login. The **active** login is never refreshed -- Claude Code
+owns it, and two parties refreshing one login can invalidate the grant. A refusal is
+reported, never worked around -- a rejected grant says so and says what fixes it
+(below), and a service failure, an unreachable service or an unsupported response leave
+the saved login untouched. Requests carry `User-Agent: authswitch/<version>`, and HTTP
+429 is reported as rate limiting with the service's retry time -- never as an exhausted
+or expired account.
 
 Claude Code also rotates the refresh token of the login it **is** running on, so reading the
 accounts (`list`, `limits`, `active`, `current`, `watch`, the dashboard) mirrors that login
@@ -264,14 +294,55 @@ saved implicitly; `stash` is what saves a login. An installation whose native lo
 authswitch cannot read mirrors nothing, and a read waits at most a second for a lock a
 switch or Claude Code holds before leaving the saved copy to the next read.
 
-A grant the sign-in service refused is remembered in the saved record itself, as a hash of
-the refresh token -- never the token -- so a new authswitch run, a restarted watch or a
-second dashboard does not replay a dead login. Saving that login again clears it, as does
-any refresh that replaces the saved credential. Such a login reports `Login expired or was
-rejected. Log in again with Claude Code and save it. Claude Code rotates a login's refresh
-token as it uses it, and the service can refuse the older one a saved copy still holds once
-that login has been replaced outside authswitch; authswitch claude stash --keep saves the
-new one.`
+An account the service has put **on hold** is not a dead login: the hold refuses the grant
+while it lasts and the same login works again once it is lifted, so such an account keeps
+its stored plan, says that it is on hold and where to appeal, and is asked again on the
+next read.
+
+A grant the sign-in service refused is remembered in the saved record itself, as a hash
+of the request that was refused -- the refresh token, the client and the scopes, never
+the token itself -- so a new authswitch run, a restarted watch or a second dashboard
+does not replay a dead login. Because the hash covers the request and not only the
+token, a release that changes how authswitch asks gives every such login one honest
+attempt under the new derivation, while a refusal of the request authswitch still sends
+stays remembered. Saving that login again clears it, as does any refresh that replaces
+the saved credential. Such a login reports `Login expired or was rejected. Log in again
+with Claude Code and save it. Claude Code rotates a login's refresh token as it uses it,
+and the service can refuse the older one a saved copy still holds once that login has
+been replaced outside authswitch; authswitch claude stash --keep saves the new one.`
+
+Each `n/a` in a Claude row has a reason in the footnote under the table, and each
+reason names what to do:
+
+- `Login refresh: Login expired or was rejected.` -- the sign-in service refused the
+  saved refresh token itself. Log in again in Claude Code for that account and run
+  `authswitch claude stash --keep`; nothing else fixes it.
+- `Login refresh: This Claude account is on hold and cannot sign in.` -- the account,
+  not the login. Appeal at the address in the message; the saved login is kept and is
+  asked again on the next read.
+- `Login refresh: This saved login has no refresh token, and no subscriber scope or
+  plan to refresh with.` -- the saved record is missing what a refresh is made of.
+  Save the login again.
+- `Login refresh: this saved login's access token has expired and cannot be renewed
+  for this installation.` -- authswitch cannot read Claude Code's own files here (the
+  macOS Keychain, or an incomplete native login), so it cannot prove this login is not
+  the active one, and never refreshes a login that might be.
+- `Login refresh: The Claude sign-in service returned HTTP ...`, `... could not be
+  reached.`, `... timed out.`, `... is rate limiting requests (HTTP 429)` -- the
+  service, not the login. The saved login is untouched; read again later.
+- `Profile: ...` or `Usage: ...` -- the account endpoints, asked with a token the
+  refresh had just accepted. `Profile: Login expired or was rejected.` means the access
+  token itself was refused; the other wordings are the service, as above.
+- `Claude returned a different account or organization` -- the answer was about another
+  account and was discarded whole, rather than shown under this account's name.
+- `Claude profile response is unsupported` or `Claude usage response is unsupported` --
+  the service answered in a shape authswitch does not read. Nothing is guessed from a
+  response it does not understand.
+
+An OpenCode `anthropic` row reads the same endpoints and so shows the same reasons,
+plus two of its own: `This Anthropic login's access token has expired.`, which OpenCode
+renews by running or by `opencode auth login`, and `This Anthropic login holds no usable
+access token`, which needs a new `opencode auth login`.
 
 OpenCode and Claude saved records are separate owner-only files under
 `~/.authswitch/opencode` and `~/.authswitch/claude`. Emails are accepted as account

package/ts/00_commitinfo_data.ts

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

package/ts/classes.claudecodeharness.ts

@@ -2,9 +2,9 @@ import * as plugins from './plugins.js';
 import { FileHarness, type IFileAccount, type IFileHarnessSnapshot } from './classes.fileharness.js';
 import { CredentialStore, credentialHash, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw, type IStoredCredential } from './classes.credentialstore.js';
 import { HarnessProcesses } from './classes.harnessprocesses.js';
-import { ClaudeAccountStatus } from './classes.claudestatus.js';
+import { ClaudeAccountStatus, type IClaudeLogin } from './classes.claudestatus.js';
 import { ClaudeCodeLocks } from './classes.claudecodelocks.js';
-import { ClaudeTokenRefresh, type IClaudeTokens } from './classes.claudetokenrefresh.js';
+import { claudeGrant, ClaudeTokenRefresh, grantScope, type IClaudeTokens } from './classes.claudetokenrefresh.js';
 import { CLAUDE_LOGIN_REJECTED, ClaudeLoginRejectedError, ClaudeRateLimitError } from './claudehttp.js';
 import { writeSecretFileAtomically } from './helpers.js';
 import type { IHarnessAccountStatus, IHarnessProcessControl, IHarnessState, IHarnessStatusOptions } from './interfaces.harness.js';
@@ -160,8 +160,33 @@ export class ClaudeCodeHarness extends FileHarness {
       throw new Error('Claude Code switch failed while updating account metadata and was rolled back. The outgoing login remains saved; check authswitch claude doctor.');
     }
   }
-  /** The hash that identifies a saved login's refresh token, so a rejected grant is remembered without keeping it. */
-  private grantKey(oauthArg: Record<string, unknown>): string { return credentialHash(credentialText(oauthArg.refreshToken) ?? ''); }
+  /**
+   * The hash that identifies a refused sign-in, so it is remembered without keeping anything of the login.
+   *
+   * A refusal is about one request: the refresh token it carried, and the client and scopes authswitch derived for
+   * it. Binding all three means a login keeps its refusal for as long as authswitch would send the same request
+   * again, and that a release which changes the derivation -- adopting a scope set Claude Code changed, say -- gives
+   * every such login one honest attempt under the new one instead of repeating a verdict its request no longer earns.
+   */
+  private grantKey(oauthArg: Record<string, unknown>): string {
+    const grant = claudeGrant(oauthArg);
+    return credentialHash(JSON.stringify([credentialText(oauthArg.refreshToken) ?? '', grant?.clientId ?? '', grant === null ? '' : grantScope(grant.scopes)]));
+  }
+
+  /** The login a status lookup asks with: its token, and what this store knows about it. */
+  private login(accountArg: IFileAccount): IClaudeLogin {
+    const oauth = credentialRecord(accountArg.credential.claudeAiOauth);
+    const account = credentialRecord(accountArg.credential.oauthAccount);
+    const accountUuid = credentialText(account.accountUuid);
+    const organizationUuid = credentialText(account.organizationUuid);
+    const plan = credentialText(oauth.subscriptionType);
+    return {
+      accessToken: credentialText(oauth.accessToken) ?? '',
+      scopes: Array.isArray(oauth.scopes) ? oauth.scopes.filter((scope): scope is string => typeof scope === 'string') : [],
+      ...(accountUuid !== undefined && organizationUuid !== undefined ? { identity: { accountUuid, organizationUuid } } : {}),
+      ...(plan === undefined ? {} : { plan }),
+    };
+  }
 
   /**
    * The harness's accounts, with the saved copy of the active login brought up to date first.
@@ -226,28 +251,28 @@ export class ClaudeCodeHarness extends FileHarness {
    * is due is refreshed first; when that fails, the status says why and keeps the stored plan, and the saved login is
    * left exactly as it was.
    *
-   * A refresh is only ever sent for a login the native files prove is not the active one (`nativeView`), and a grant
-   * the service already rejected is not sent again while the saved record still holds it.
+   * A refresh is only ever sent for a login the native files prove is not the active one (`nativeView`), and a request
+   * the service already refused is not sent again while the saved record would produce the same one (`grantKey`).
    */
   public async readAccountStatus(id: string, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
-    const read = (accountArg: IFileAccount) =>
-      this.status.read(credentialRecord(accountArg.credential.claudeAiOauth), credentialRecord(accountArg.credential.oauthAccount), optionsArg);
+    const read = (accountArg: IFileAccount) => this.status.read(this.login(accountArg), optionsArg);
     const view = this.nativeView(id);
     if (view.active) return read(view.active);
     const saved = this.savedCredential(id);
+    const login = this.login(saved);
     const oauth = credentialRecord(saved.credential.claudeAiOauth);
     if (!this.tokens.due(oauth)) return read(saved);
     if (view.unavailable !== null) {
-      return this.status.unavailable(oauth, `Login refresh: this saved login's access token has expired and cannot be renewed for this installation. ${view.unavailable}`);
+      return this.status.unavailable(login, `Login refresh: this saved login's access token has expired and cannot be renewed for this installation. ${view.unavailable}`);
     }
-    if (this.store.read(id).rejectedGrant === this.grantKey(oauth)) return this.status.unavailable(oauth, `Login refresh: ${SAVED_LOGIN_REJECTED}`);
+    if (this.store.read(id).rejectedGrant === this.grantKey(oauth)) return this.status.unavailable(login, `Login refresh: ${SAVED_LOGIN_REJECTED}`);
     let refreshed: IFileAccount;
     try { refreshed = await this.refreshSaved(id, optionsArg.signal); }
     catch (error) {
       if (optionsArg.signal?.aborted) throw error;
       const problem = error instanceof ClaudeLoginRejectedError ? SAVED_LOGIN_REJECTED
         : error instanceof Error ? error.message : 'the saved login could not be refreshed.';
-      return this.status.unavailable(oauth, `Login refresh: ${problem}`,
+      return this.status.unavailable(login, `Login refresh: ${problem}`,
         error instanceof ClaudeRateLimitError ? { retryAt: error.retryAt } : undefined);
     }
     return read(refreshed);
@@ -260,7 +285,7 @@ export class ClaudeCodeHarness extends FileHarness {
    * became active meanwhile belongs to Claude Code and is returned as it is, one in an installation that can no
    * longer be read is returned unrefreshed, and one another refresh already renewed is not refreshed twice. The new
    * tokens replace the saved ones only while the record still holds the refresh token that was sent, the
-   * compare-and-swap Claude Code 2.1.273 applies to its own store (`$fn`, @15410824).
+   * compare-and-swap Claude Code 2.1.273 applies to its own store (`$fn`, @191212749).
    */
   private refreshSaved(id: string, signal?: AbortSignal): Promise<IFileAccount> {
     return this.store.locked(async () => {

package/ts/classes.claudestatus.ts

@@ -110,6 +110,21 @@ type TClaudeProfile =
   | { kind: 'mismatch' }
   | { kind: 'unavailable'; problem: string };
 
+/**
+ * One Claude OAuth login as a status lookup needs it: the token to ask with, and what the store that keeps it knows
+ * about it. Claude Code's own store keeps the scopes and the account the login belongs to; another harness holding
+ * the same kind of grant (OpenCode's `anthropic` provider entry) keeps neither, and leaves both to the service.
+ */
+export interface IClaudeLogin {
+  accessToken: string;
+  /** The scopes the login is stored with. An empty list means the store keeps none, not that the login has none. */
+  scopes: readonly string[];
+  /** The account the login must belong to; an answer about another account is refused. Omitted where no store keeps it. */
+  identity?: { accountUuid: string; organizationUuid: string };
+  /** The plan the login was saved with, the only one known while the service cannot be asked. */
+  plan?: string;
+}
+
 /**
  * How long a session reuses an account's profile. The watch polls every few minutes, and the profile (plan,
  * organization, billing type) changes far more rarely, so it is read at most hourly there.
@@ -119,9 +134,12 @@ const REQUEST_TIMEOUT_MS = 10_000;
 const MISMATCH = 'Claude returned a different account or organization; no account data was displayed.';
 
 /**
- * Claude Code's read-only OAuth account endpoints: the profile and usage of one login, with the access token it
- * carries. It never refreshes that token; `ClaudeCodeHarness` refreshes a saved login first, and leaves the active
- * login's tokens to Claude Code. No inference or browser session is used.
+ * Claude Code's read-only OAuth account endpoints: the profile and usage of one Claude OAuth login, asked with the
+ * access token that login carries and with the headers Claude Code 2.1.273 sends (`_ke`, bundle offset @191153494,
+ * and the `anthropic-beta` value `Vu`, @188533107). Any harness holding such a grant is served, not only Claude Code's own store.
+ *
+ * It never refreshes that token; `ClaudeCodeHarness` refreshes a saved login first, and leaves the active login's
+ * tokens to Claude Code. No inference or browser session is used.
  */
 export class ClaudeAccountStatus {
   constructor(private readonly fetcher: typeof fetch = globalThis.fetch, private readonly now: () => number = Date.now) {}
@@ -139,15 +157,15 @@ export class ClaudeAccountStatus {
   }
 
   /** The profile, from the session while it is younger than an hour; the session key is a hash of the token, never the token. */
-  private profile(token: string, account: Record<string, unknown>, optionsArg: IHarnessStatusOptions): Promise<TClaudeProfile> {
-    const lookup = () => this.lookupProfile(token, account, optionsArg.signal);
-    return optionsArg.session ? optionsArg.session.reuse(`claude:profile:${credentialHash(token)}`, PROFILE_REUSE_MS, lookup) : lookup();
+  private profile(loginArg: IClaudeLogin, optionsArg: IHarnessStatusOptions): Promise<TClaudeProfile> {
+    const lookup = () => this.lookupProfile(loginArg, optionsArg.signal);
+    return optionsArg.session ? optionsArg.session.reuse(`claude:profile:${credentialHash(loginArg.accessToken)}`, PROFILE_REUSE_MS, lookup) : lookup();
   }
 
   /** A rejected login and an unsupported or foreign profile are answers; a rate limit or a failed request is thrown. */
-  private async lookupProfile(token: string, account: Record<string, unknown>, signal?: AbortSignal): Promise<TClaudeProfile> {
+  private async lookupProfile(loginArg: IClaudeLogin, signal?: AbortSignal): Promise<TClaudeProfile> {
     let body: Record<string, unknown>;
-    try { body = await this.get('profile', token, signal); }
+    try { body = await this.get('profile', loginArg.accessToken, signal); }
     catch (error) {
       if (error instanceof ClaudeLoginRejectedError) return { kind: 'unavailable', problem: `Profile: ${error.message}` };
       throw error;
@@ -155,7 +173,9 @@ export class ClaudeAccountStatus {
     try {
       const user = credentialRecord(body.account);
       const organization = credentialRecord(body.organization);
-      if (user.uuid !== account.accountUuid || organization.uuid !== account.organizationUuid) return { kind: 'mismatch' };
+      // A store that keeps no account identity has none to compare; the service's answer is about the token that was sent.
+      const identity = loginArg.identity;
+      if (identity !== undefined && (user.uuid !== identity.accountUuid || organization.uuid !== identity.organizationUuid)) return { kind: 'mismatch' };
       const facts: IHarnessStatusFact[] = [];
       for (const [label, value] of [['Email', user.email], ['Organization', organization.name], ['Billing type', organization.billing_type], ['Seat tier', organization.seat_tier]]) {
         if (credentialText(value)) facts.push({ section: 'Account', label: String(label), value: String(value) });
@@ -165,25 +185,25 @@ export class ClaudeAccountStatus {
   }
 
   /** The plan the login was saved with, the only one known while the service cannot be asked. */
-  private storedSummary(oauth: Record<string, unknown>): Pick<IHarnessAccountStatus, 'summary'> {
-    const plan = credentialText(oauth.subscriptionType);
-    return plan ? { summary: { subscription: { plan, source: 'stored' } } } : {};
+  private storedSummary(loginArg: Pick<IClaudeLogin, 'plan'>): Pick<IHarnessAccountStatus, 'summary'> {
+    return loginArg.plan ? { summary: { subscription: { plan: loginArg.plan, source: 'stored' } } } : {};
   }
 
   /** A login that could not be made usable for a lookup: its stored plan and why, with the service's retry time for a rate limit. */
-  public unavailable(oauth: Record<string, unknown>, problem: string, rateLimit?: IHarnessAccountStatus['rateLimit']): IHarnessAccountStatus {
-    return { facts: [], problems: [problem], ...this.storedSummary(oauth), ...(rateLimit ? { rateLimit } : {}) };
+  public unavailable(loginArg: Pick<IClaudeLogin, 'plan'>, problem: string, rateLimit?: IHarnessAccountStatus['rateLimit']): IHarnessAccountStatus {
+    return { facts: [], problems: [problem], ...this.storedSummary(loginArg), ...(rateLimit ? { rateLimit } : {}) };
   }
 
-  public async read(oauth: Record<string, unknown>, account: Record<string, unknown>, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
-    const result: IHarnessAccountStatus = { facts: [], problems: [], ...this.storedSummary(oauth) };
-    if (!Array.isArray(oauth.scopes) || !oauth.scopes.includes('user:profile')) {
+  public async read(loginArg: IClaudeLogin, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
+    const result: IHarnessAccountStatus = { facts: [], problems: [], ...this.storedSummary(loginArg) };
+    // Only a store that keeps the login's scopes can tell beforehand that the service will not answer about the account.
+    if (loginArg.scopes.length && !loginArg.scopes.includes('user:profile')) {
       result.facts.push({ section: 'Availability', label: 'Live account status', value: 'This login lacks the user:profile scope. Log in through Claude Code to obtain subscriber status.' });
       return result;
     }
-    const token = credentialText(oauth.accessToken);
+    const token = credentialText(loginArg.accessToken);
     if (!token) return { facts: [], problems: ['No usable Claude Code access token is available.'] };
-    const [profile, usage] = await Promise.allSettled([this.profile(token, account, optionsArg), this.get('usage', token, optionsArg.signal)]);
+    const [profile, usage] = await Promise.allSettled([this.profile(loginArg, optionsArg), this.get('usage', token, optionsArg.signal)]);
     const failure = (reason: unknown): string => reason instanceof ClaudeRequestError ? reason.message : 'Lookup failed.';
     if (profile.status === 'fulfilled') {
       const found = profile.value;

package/ts/classes.claudetokenrefresh.ts

@@ -1,18 +1,31 @@
 import { credentialText } from './classes.credentialstore.js';
-import { claudeRequest, ClaudeLoginRejectedError, ClaudeRequestError } from './claudehttp.js';
+import { claudeRequest, ClaudeAccountOnHoldError, ClaudeLoginRejectedError, ClaudeRequestError, oauthErrorCode } from './claudehttp.js';
 
-/** Claude Code 2.1.273's token endpoint (`TOKEN_URL`, bundle offset @12733057; see hints.md). */
+/** Claude Code 2.1.273's token endpoint (`TOKEN_URL`, bundle offset @188533776). */
 const TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
-/** Claude Code 2.1.273's public OAuth client (`CLIENT_ID`, @12733057), used when a login does not name its own. */
+/** Claude Code 2.1.273's public OAuth client (`CLIENT_ID`, @188534240), used when a login does not name its own. */
 export const CLAUDE_CODE_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
-/** Claude Code 2.1.273 refreshes an access token that expires within five minutes (`cF`, @15359182). */
-const REFRESH_MARGIN_MS = 300_000;
+/** Claude Code 2.1.273 refreshes an access token that expires within five minutes (`cF`, @191161107). */
+export const CLAUDE_REFRESH_MARGIN_MS = 300_000;
 /**
  * Claude Code 2.1.273 allows a refresh 30 seconds. A refresh is never cut shorter than that, nor cancelled once sent:
  * the service may already have replaced the refresh token the request carries.
  */
 const REFRESH_TIMEOUT_MS = 30_000;
 
+/**
+ * The scopes Claude Code 2.1.273 asks for when it refreshes a login of its own OAuth client (`bFe`, @188533214,
+ * with the plugins scope its production build registers). It sends this set whatever the login was stored with,
+ * so a login saved under an older or wider set is renewed exactly as Claude Code renews it.
+ */
+export const CLAUDE_CODE_SCOPES: readonly string[] = [
+  'user:profile', 'user:inference', 'user:sessions:claude_code', 'user:mcp_servers', 'user:file_upload', 'user:plugins',
+];
+/** The only stored scopes Claude Code carries into that set (`Dyn`, @188533421). */
+const CARRIED_SCOPES: readonly string[] = ['user:projects:read', 'user:projects:write'];
+/** The scope that marks a login as one of Claude Code's own subscriber logins (`NS`/`YWt`, @188532967). */
+const INFERENCE_SCOPE = 'user:inference';
+
 /** The token fields a refresh replaces in a stored `claudeAiOauth`; every other field is kept. */
 export interface IClaudeTokens {
   accessToken: string;
@@ -23,11 +36,64 @@ export interface IClaudeTokens {
   scopes?: string[];
 }
 
+/** How Claude Code 2.1.273 builds one refresh request for a stored login. */
+export interface IClaudeGrant {
+  /** The login's own OAuth client, or Claude Code's public one. */
+  clientId: string;
+  /** The scopes the request asks for. */
+  scopes: readonly string[];
+  /**
+   * The stored scopes the request falls back to once the service refuses the set above as `invalid_scope`
+   * (`hg`, @191228494); null where Claude Code sends no second request.
+   */
+  fallbackScopes: readonly string[] | null;
+}
+
+/** The scopes a stored login carries, or none when it carries nothing a scope list can be read from. */
+const storedScopes = (oauthArg: Record<string, unknown>): string[] =>
+  Array.isArray(oauthArg.scopes) && oauthArg.scopes.every(scope => typeof scope === 'string') ? [...oauthArg.scopes as string[]] : [];
+
+/**
+ * How Claude Code 2.1.273 would renew this login, or null where it would not send a refresh at all: a login without
+ * a refresh token, and one that is neither a subscriber login (`user:inference`) nor stored with a plan, which
+ * Claude Code reports as `not_refreshable` (`hg`, @191228494).
+ *
+ * A login of Claude Code's own client is renewed with Claude Code's current scope set plus the project scopes it
+ * carries (`DQn`, @188533511) -- not with the set it was stored under. A login that names its own OAuth client is
+ * renewed with exactly the scopes it was stored with, because only that client's grant knows them.
+ */
+export const claudeGrant = (oauthArg: Record<string, unknown>): IClaudeGrant | null => {
+  if (!credentialText(oauthArg.refreshToken)) return null;
+  const stored = storedScopes(oauthArg);
+  const isSubscriberLogin = stored.includes(INFERENCE_SCOPE);
+  if (!isSubscriberLogin && !credentialText(oauthArg.subscriptionType)) return null;
+  const clientId = credentialText(oauthArg.clientId);
+  if (clientId !== undefined) return { clientId, scopes: stored, fallbackScopes: null };
+  return {
+    clientId: CLAUDE_CODE_CLIENT_ID,
+    scopes: [...new Set([...CLAUDE_CODE_SCOPES, ...stored.filter(scope => CARRIED_SCOPES.includes(scope))])],
+    fallbackScopes: isSubscriberLogin ? stored : null,
+  };
+};
+
+/** The `scope` value one request carries: Claude Code sends its own set for an empty scope list (`RQ`, @191156785). */
+export const grantScope = (scopesArg: readonly string[]): string => (scopesArg.length ? scopesArg : CLAUDE_CODE_SCOPES).join(' ');
+
 const seconds = (valueArg: unknown): number | undefined =>
   typeof valueArg === 'number' && Number.isFinite(valueArg) && valueArg >= 0 ? valueArg : undefined;
 
 /**
- * Refreshes a saved Claude Code login with the refresh-token grant Claude Code 2.1.273 uses (`RQ`, @15355055).
+ * Whether the service refused this grant because the account is on hold (`Pfn`, @191165493, over `fgt`, @190071426):
+ * an `invalid_grant` or `access_denied` whose description is the service's `account_on_hold` marker. Claude Code keeps
+ * such a login and retries it later; only a refusal without that marker means the grant itself is dead.
+ */
+const accountOnHold = (statusArg: number, bodyArg: Record<string, unknown> | null): boolean =>
+  (statusArg === 400 || statusArg === 401 || statusArg === 403)
+  && (oauthErrorCode(bodyArg) === 'invalid_grant' || oauthErrorCode(bodyArg) === 'access_denied')
+  && bodyArg?.error_description === 'account_on_hold';
+
+/**
+ * Refreshes a saved Claude Code login with the refresh-token grant Claude Code 2.1.273 uses (`RQ`, @191156785).
  *
  * It only talks to the token endpoint; which login is refreshed, and how the result is stored, belongs to the harness.
  */
@@ -41,29 +107,39 @@ export class ClaudeTokenRefresh {
   public due(oauthArg: Record<string, unknown>): boolean {
     const expiresAt = oauthArg.expiresAt;
     return typeof expiresAt === 'number' && Number.isFinite(expiresAt) && credentialText(oauthArg.refreshToken) !== undefined
-      && this.now() + REFRESH_MARGIN_MS >= expiresAt;
+      && this.now() + CLAUDE_REFRESH_MARGIN_MS >= expiresAt;
+  }
+
+  /** One refresh request, as Claude Code sends it: a JSON body, the login's client, and the scopes of this attempt. */
+  private attempt(refreshTokenArg: string, grantArg: IClaudeGrant, scopesArg: readonly string[]) {
+    return claudeRequest(this.fetcher, {
+      url: TOKEN_URL, method: 'POST', headers: { 'Content-Type': 'application/json' }, subject: 'Claude sign-in',
+      body: JSON.stringify({
+        grant_type: 'refresh_token', refresh_token: refreshTokenArg, client_id: grantArg.clientId, scope: grantScope(scopesArg),
+      }),
+      timeoutMs: REFRESH_TIMEOUT_MS, readErrorBody: true, now: this.now,
+    });
   }
 
   /**
    * New tokens for the login. A response without a refresh token keeps the one sent, and one without a scope keeps the
    * stored scopes, as Claude Code merges them. Throws `ClaudeRequestError` with a fixed diagnostic; a grant the service
-   * rejects is `ClaudeLoginRejectedError`, and a rate limit is `ClaudeRateLimitError`.
+   * rejects is `ClaudeLoginRejectedError`, an account the service put on hold is `ClaudeAccountOnHoldError`, and a rate
+   * limit is `ClaudeRateLimitError`.
    */
   public async refresh(oauthArg: Record<string, unknown>): Promise<IClaudeTokens> {
     const refreshToken = credentialText(oauthArg.refreshToken);
-    const scopes = oauthArg.scopes;
-    if (!refreshToken || !Array.isArray(scopes) || !scopes.every(scope => typeof scope === 'string')) {
-      throw new ClaudeRequestError('This saved login has no refresh token or scopes to refresh with. Log in again with Claude Code and save it.');
+    const grant = claudeGrant(oauthArg);
+    if (!refreshToken || !grant) {
+      throw new ClaudeRequestError('This saved login has no refresh token, and no subscriber scope or plan to refresh with. Log in again with Claude Code and save it.');
     }
-    const { status, body } = await claudeRequest(this.fetcher, {
-      url: TOKEN_URL, method: 'POST', headers: { 'Content-Type': 'application/json' }, subject: 'Claude sign-in',
-      body: JSON.stringify({
-        grant_type: 'refresh_token', refresh_token: refreshToken,
-        client_id: credentialText(oauthArg.clientId) ?? CLAUDE_CODE_CLIENT_ID, scope: scopes.join(' '),
-      }),
-      timeoutMs: REFRESH_TIMEOUT_MS, readErrorBody: true, now: this.now,
-    });
-    if ((status === 400 || status === 401) && body?.error === 'invalid_grant') throw new ClaudeLoginRejectedError();
+    let { status, body } = await this.attempt(refreshToken, grant, grant.scopes);
+    // The service refusing Claude Code's current scope set is the one failure it sends a second request for.
+    if (status === 400 && oauthErrorCode(body) === 'invalid_scope' && grant.fallbackScopes !== null) {
+      ({ status, body } = await this.attempt(refreshToken, grant, grant.fallbackScopes));
+    }
+    if (accountOnHold(status, body)) throw new ClaudeAccountOnHoldError();
+    if ((status === 400 || status === 401) && oauthErrorCode(body) === 'invalid_grant') throw new ClaudeLoginRejectedError();
     if (status < 200 || status > 299) throw new ClaudeRequestError(`The Claude sign-in service returned HTTP ${status}.`);
     const receivedAt = this.now();
     const accessToken = credentialText(body?.access_token);

package/ts/classes.opencodeharness.ts

@@ -2,6 +2,8 @@ import * as plugins from './plugins.js';
 import { FileHarness, type IFileAccount, type IFileHarnessSnapshot } from './classes.fileharness.js';
 import { CredentialStore, credentialHash, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw } from './classes.credentialstore.js';
 import { HarnessProcesses } from './classes.harnessprocesses.js';
+import { ClaudeAccountStatus } from './classes.claudestatus.js';
+import { CLAUDE_REFRESH_MARGIN_MS } from './classes.claudetokenrefresh.js';
 import { CodexAccountStatus } from './classes.codexstatus.js';
 import { writeSecretFileAtomically } from './helpers.js';
 import type { IHarnessAccountStatus, IHarnessLoginOptions, IHarnessLoginProvider, IHarnessProcessControl, IHarnessStatusOptions } from './interfaces.harness.js';
@@ -15,6 +17,8 @@ export interface IOpenCodeHarnessOptions {
   fetch?: typeof fetch;
   /** Running-instance inspection, injectable for isolated installations and tests. */
   processes?: IHarnessProcessControl;
+  /** The clock that decides whether a provider's stored access token is still usable; `Date.now` by default. */
+  now?: () => number;
 }
 
 /** OpenCode owns one login per provider. Replacing a slot never replaces the whole provider set. */
@@ -31,8 +35,10 @@ export class OpenCodeHarness extends FileHarness {
   private readonly file: string;
   private readonly env: NodeJS.ProcessEnv;
   private readonly status: CodexAccountStatus;
+  private readonly claudeStatus: ClaudeAccountStatus;
   public readonly processes: IHarnessProcessControl;
   private readonly fetcher?: typeof fetch;
+  private readonly now: () => number;
 
   constructor(options: IOpenCodeHarnessOptions = {}) {
     super();
@@ -40,7 +46,9 @@ export class OpenCodeHarness extends FileHarness {
     this.file = plugins.path.join(options.dataHome ?? (this.env.XDG_DATA_HOME || plugins.path.join(plugins.os.homedir(), '.local', 'share')), 'opencode', 'auth.json');
     this.store = new CredentialStore(this.id, options.stashRoot);
     this.status = new CodexAccountStatus(options.fetch);
+    this.claudeStatus = new ClaudeAccountStatus(options.fetch, options.now);
     this.fetcher = options.fetch;
+    this.now = options.now ?? Date.now;
     this.processes = options.processes ?? new HarnessProcesses('opencode');
   }
   /** Every provider entry lives in one file, so its bytes are the whole stability proof. */
@@ -104,6 +112,27 @@ export class OpenCodeHarness extends FileHarness {
     writeSecretFileAtomically(this.file, raw);
     if (readCredentialDocument(this.file).raw !== raw) throw new Error('Active login verification failed. The outgoing login remains saved.');
   }
+  /**
+   * The subscription and usage of an OpenCode `anthropic` OAuth login.
+   *
+   * That entry holds the same Claude subscriber grant Claude Code stores, so Claude's own account endpoints answer
+   * for it and the account reports real windows instead of no quota API at all. OpenCode keeps no scopes and no
+   * account identity with it, so the service decides both; the token is used exactly as stored. Renewing it is
+   * OpenCode's, because the renewal rotates the refresh token a running OpenCode holds in memory, and authswitch
+   * cannot write that rotation into an instance it does not manage.
+   */
+  private anthropicStatus(credentialArg: Record<string, unknown>, optionsArg?: IHarnessStatusOptions): Promise<IHarnessAccountStatus> {
+    const accessToken = credentialText(credentialArg.access);
+    const expires = credentialArg.expires;
+    if (accessToken === undefined || typeof expires !== 'number') {
+      return Promise.resolve(this.claudeStatus.unavailable({}, 'This Anthropic login holds no usable access token; log in again with opencode auth login.'));
+    }
+    if (this.now() + CLAUDE_REFRESH_MARGIN_MS >= expires) {
+      return Promise.resolve(this.claudeStatus.unavailable({}, 'This Anthropic login\'s access token has expired. OpenCode renews it while it runs; authswitch does not, because the renewal rotates the refresh token a running OpenCode keeps in memory. Start OpenCode, or log in again with opencode auth login.'));
+    }
+    return this.claudeStatus.read({ accessToken, scopes: [] }, optionsArg);
+  }
+
   public async readAccountStatus(id: string, optionsArg?: IHarnessStatusOptions): Promise<IHarnessAccountStatus> {
     const account = this.readCredential(id);
     if (account.slotId === 'openai' && account.credential.type === 'oauth') {
@@ -111,6 +140,7 @@ export class OpenCodeHarness extends FileHarness {
       if (!info.accountId) return { facts: [], problems: ['The OpenAI login has no account ID for a status lookup.'] };
       return this.status.readCredential(credentialText(account.credential.access)!, info.accountId, info.plan, optionsArg);
     }
+    if (account.slotId === 'anthropic' && account.credential.type === 'oauth') return this.anthropicStatus(account.credential, optionsArg);
     return { facts: [
       { section: 'Authentication', label: 'Provider', value: account.slotId },
       { section: 'Authentication', label: 'Login type', value: String(account.credential.type) },