@modelprofile.com/authswitch 3.3.0 → 5.0.0

package/ts/classes.claudecodeharness.ts

@@ -1,10 +1,13 @@
 import * as plugins from './plugins.js';
 import { FileHarness, type IFileAccount, type IFileHarnessSnapshot } from './classes.fileharness.js';
-import { CredentialStore, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw } from './classes.credentialstore.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 { ClaudeCodeLocks } from './classes.claudecodelocks.js';
+import { ClaudeTokenRefresh, type IClaudeTokens } from './classes.claudetokenrefresh.js';
+import { CLAUDE_LOGIN_REJECTED, ClaudeLoginRejectedError, ClaudeRateLimitError } from './claudehttp.js';
 import { writeSecretFileAtomically } from './helpers.js';
-import type { IHarnessAccountStatus, IHarnessProcessControl, IHarnessStatusOptions } from './interfaces.harness.js';
+import type { IHarnessAccountStatus, IHarnessProcessControl, IHarnessState, IHarnessStatusOptions } from './interfaces.harness.js';
 
 export interface IClaudeCodeHarnessOptions {
   configDir?: string;
@@ -17,15 +20,51 @@ export interface IClaudeCodeHarnessOptions {
   processes?: IHarnessProcessControl;
   /** Local settings sources to inspect for credential overrides, in increasing precedence. */
   settingsFiles?: string[];
+  /** How long a credential change waits for a lock Claude Code holds; 15 seconds by default. */
+  lockTimeoutMs?: number;
+  /** The clock that decides when a saved login's access token is due for a refresh; `Date.now` by default. */
+  now?: () => number;
 }
 
+/**
+ * How long a read waits for the store and for Claude Code's locks before leaving the saved copy as it found it.
+ *
+ * Reading accounts must stay as quick as it is while a switch, a refresh or a Claude Code session holds a lock. The
+ * saved copy has nothing to finish: whatever the operation holding the lock writes is what the next read mirrors.
+ */
+const MIRROR_WAIT_MS = 1_000;
+
+/**
+ * A saved login the sign-in service refuses, in terms the user can act on.
+ *
+ * Claude Code rotates the refresh token of the login it is running on (hints.md), and a saved copy keeps the token
+ * it was stashed with. Once such a login has been replaced outside authswitch -- a `claude /login`, a new device
+ * login -- nothing writes the rotation back, and the service was observed refusing the older token the saved copy
+ * still holds (2026-09-18, two saved logins). No retry, no other account and no switch changes that answer; logging
+ * in again and saving that login does, so the message says so.
+ */
+const SAVED_LOGIN_REJECTED = `${CLAUDE_LOGIN_REJECTED} 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.`;
+
 const accountCaches = ['additionalModelOptionsCache', 'additionalModelOptionsAnsweredAt', 'additionalModelCostsCache', 'modelAccessCache', 'orgModelDefaultCache', 'lastSeenOrgDefaultUpdatedAt', 'clientDataCache', 'clientDataCacheSlots', 'autoCompactWindowsCache', 'cachedUsageUtilization'];
 
-/** File-backed Claude Code subscriber login and its matching global oauthAccount metadata. */
+/**
+ * File-backed Claude Code subscriber login and its matching global oauthAccount metadata.
+ *
+ * A running Claude Code (verified against 2.1.273) re-reads its credential file whenever the file's mtime changes,
+ * before every request, and watches `.claude.json`, so a swap is picked up live without a restart. Every native read
+ * and write therefore runs under Claude Code's own locks instead of asking for it to be stopped.
+ *
+ * Nothing else refreshes a saved login, so its access token expires a few hours after it was saved. Reading such a
+ * login's status refreshes it first, the way Claude Code would; the active login's tokens belong to Claude Code, and
+ * reading the accounts mirrors that login into its own saved copy, so the stash keeps what Claude Code last wrote.
+ */
 export class ClaudeCodeHarness extends FileHarness {
   public readonly id = 'claude';
   public readonly label = 'Claude Code';
   public readonly loginHint = 'Log in using claude auth login, then authswitch claude stash --keep; Claude Code may stay running.';
+  public readonly liveSwap = true;
+  public readonly autoSwitch = true;
+  public readonly renewalUnavailableReason = "renewal dates are not exposed by Claude's account API.";
   protected readonly store: CredentialStore;
   private readonly file: string;
   private readonly configFile: string;
@@ -34,6 +73,8 @@ export class ClaudeCodeHarness extends FileHarness {
   private readonly status: ClaudeAccountStatus;
   public readonly processes: IHarnessProcessControl;
   private readonly settingsFiles: string[];
+  private readonly locks: ClaudeCodeLocks;
+  private readonly tokens: ClaudeTokenRefresh;
 
   constructor(options: IClaudeCodeHarnessOptions = {}) {
     super();
@@ -44,10 +85,16 @@ export class ClaudeCodeHarness extends FileHarness {
     this.configFile = options.globalConfigFile ?? plugins.path.join(custom || plugins.os.homedir(), '.claude.json');
     this.store = new CredentialStore(this.id, options.stashRoot);
     this.platform = options.platform ?? process.platform;
-    this.status = new ClaudeAccountStatus(options.fetch);
+    this.status = new ClaudeAccountStatus(options.fetch, options.now);
+    this.tokens = new ClaudeTokenRefresh(options.fetch, options.now);
     this.processes = options.processes ?? new HarnessProcesses('claude', { platform: this.platform });
     this.settingsFiles = options.settingsFiles ?? [plugins.path.join(dir, 'settings.json'),
       plugins.path.join(process.cwd(), '.claude/settings.json'), plugins.path.join(process.cwd(), '.claude/settings.local.json')];
+    this.locks = new ClaudeCodeLocks(dir, this.configFile, { timeoutMs: options.lockTimeoutMs });
+  }
+  /** A login this adapter cannot manage has no Claude Code file to lock; the action itself reports why. */
+  protected nativeTransaction(actionArg: () => string[]): Promise<string[]> {
+    return this.unavailableReason() === null ? this.locks.hold(actionArg) : super.nativeTransaction(actionArg);
   }
   /** One record holds the credential and its matching metadata, so both files must be proven stable. */
   protected nativeSources(): (string | null)[] { return [readCredentialRaw(this.file), readCredentialRaw(this.configFile)]; }
@@ -59,8 +106,9 @@ export class ClaudeCodeHarness extends FileHarness {
       || !credentialText(account.accountUuid) || !credentialText(account.organizationUuid) || !credentialText(account.emailAddress)) throw new Error('Claude Code login or its matching account metadata is incomplete. Log in again with Claude Code before saving.');
     return { slotId, identity: JSON.stringify([account.accountUuid, account.organizationUuid]), label: String(account.emailAddress).toLowerCase(), credential };
   }
-  protected snapshot(): IFileHarnessSnapshot {
-    if (this.platform === 'darwin') return { accounts: [], unavailable: 'Claude Code uses the macOS Keychain. This adapter supports file credentials on Linux and Windows; Keychain switching is unavailable.' };
+  /** Why this installation's login is not a subscriber file login this adapter can manage; null when it is. */
+  private unavailableReason(): string | null {
+    if (this.platform === 'darwin') return 'Claude Code uses the macOS Keychain. This adapter supports file credentials on Linux and Windows; Keychain switching is unavailable.';
     const overrides = ['CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_PROFILE', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'ANTHROPIC_BASE_URL'];
     const settings: Record<string, unknown> = {};
     const environment: Record<string, unknown> = { ...this.env };
@@ -69,7 +117,12 @@ export class ClaudeCodeHarness extends FileHarness {
       Object.assign(settings, data);
       if (data.env != null) Object.assign(environment, credentialRecord(data.env));
     }
-    if (overrides.some(key => environment[key]) || credentialText(settings.apiKeyHelper)) return { accounts: [], unavailable: 'Claude Code has a settings or environment credential/provider override. Remove it before managing subscriber file logins.' };
+    return overrides.some(key => environment[key]) || credentialText(settings.apiKeyHelper)
+      ? 'Claude Code has a settings or environment credential/provider override. Remove it before managing subscriber file logins.' : null;
+  }
+  protected snapshot(): IFileHarnessSnapshot {
+    const unavailable = this.unavailableReason();
+    if (unavailable !== null) return { accounts: [], unavailable };
     const data = readCredentialDocument(this.file).data;
     if (data.claudeAiOauth == null) return { accounts: [], unavailable: null };
     const config = readCredentialDocument(this.configFile).data;
@@ -90,7 +143,7 @@ export class ClaudeCodeHarness extends FileHarness {
     for (const key of accountCaches) delete nextConfig[key];
     const raw = JSON.stringify(next, null, 2) + '\n';
     const configRaw = JSON.stringify(nextConfig, null, 2) + '\n';
-    if (readCredentialDocument(this.file).raw !== original.raw || readCredentialDocument(this.configFile).raw !== config.raw) throw new Error('Claude Code files changed during the operation; try again after Claude Code exits.');
+    if (readCredentialDocument(this.file).raw !== original.raw || readCredentialDocument(this.configFile).raw !== config.raw) throw new Error('Claude Code files changed during the operation; no credential was replaced. Try again.');
     plugins.fs.mkdirSync(plugins.path.dirname(this.file), { recursive: true, mode: 0o700 });
     plugins.fs.mkdirSync(plugins.path.dirname(this.configFile), { recursive: true, mode: 0o700 });
     try {
@@ -103,12 +156,145 @@ export class ClaudeCodeHarness extends FileHarness {
       try {
         if (readCredentialDocument(this.file).raw === raw) writeSecretFileAtomically(this.file, original.raw ?? '{}\n');
         if (readCredentialDocument(this.configFile).raw === configRaw) writeSecretFileAtomically(this.configFile, config.raw ?? '{}\n');
-      } catch { throw new Error('Claude Code switch and rollback were incomplete. Keep Claude Code stopped and restore a verified saved account.'); }
-      throw new Error('Claude Code switch failed while updating account metadata. The outgoing login remains saved; check doctor before restarting.');
+      } catch { throw new Error('Claude Code switch and rollback were incomplete, so its login and account metadata may not match. Activate a verified saved account with authswitch claude use, then check authswitch claude active.'); }
+      throw new Error('Claude Code switch failed while updating account metadata and was rolled back. The outgoing login remains saved; check authswitch claude doctor.');
     }
   }
-  public async readAccountStatus(id: string, optionsArg?: IHarnessStatusOptions): Promise<IHarnessAccountStatus> {
-    const account = this.readCredential(id);
-    return this.status.read(credentialRecord(account.credential.claudeAiOauth), credentialRecord(account.credential.oauthAccount), optionsArg);
+  /** 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 harness's accounts, with the saved copy of the active login brought up to date first.
+   *
+   * Claude Code rotates the refresh token of the login it is running on, and until now only a switch or a save wrote
+   * that back into the stash. A login replaced outside authswitch between two switches therefore left a saved copy
+   * holding the token from before the rotation, which the service was observed refusing -- a saved copy that only
+   * turns out to be unusable when that account's status is next read. Every read of the native login now mirrors it
+   * into its own saved record, so the stash keeps the credential Claude Code last wrote for an account that has one.
+   */
+  public async readState(): Promise<IHarnessState> {
+    await this.mirrorActiveLogin();
+    return super.readState();
+  }
+
+  /**
+   * Writes the active login into its own saved record when the two differ.
+   *
+   * This is the only write a read makes, and it is advisory: a store another operation holds, a lock Claude Code
+   * holds and files that keep changing under it all leave the saved copy as it is, because the next read mirrors
+   * whatever they wrote. The native files are only ever read, and a login without a saved record of its own is
+   * never saved implicitly -- that is what `stash` is for.
+   */
+  private async mirrorActiveLogin(): Promise<void> {
+    try {
+      if (this.staleSavedCopy(this.snapshot()) === null) return;
+      await this.store.locked(() => this.locks.hold(() => {
+        // Under both locks the decision is taken again, from a snapshot proven not to have been read across a write.
+        const stale = this.staleSavedCopy(this.stableSnapshot());
+        if (stale !== null) this.store.replaceCredential(stale.id, stale.credential);
+        return [];
+      }, { timeoutMs: MIRROR_WAIT_MS }), { signal: AbortSignal.timeout(MIRROR_WAIT_MS) });
+    } catch { /* A saved copy that could not be brought up to date is no reason to fail a read of the accounts. */ }
+  }
+
+  /** The active login's saved record when it no longer holds what Claude Code wrote, with the credential to write. */
+  private staleSavedCopy(snapshotArg: IFileHarnessSnapshot): { id: string; credential: Record<string, unknown> } | null {
+    // Claude Code runs one login, and an installation this adapter cannot read reports none at all.
+    const [active] = snapshotArg.accounts;
+    if (!active) return null;
+    const id = this.store.id(active.slotId, active.identity);
+    let saved: IStoredCredential;
+    try { saved = this.store.read(id); } catch { return null; }
+    return credentialHash(JSON.stringify(saved.credential)) === credentialHash(JSON.stringify(active.credential))
+      ? null : { id, credential: active.credential };
+  }
+
+  /**
+   * What the native files say about this account: its active login, and why they could not be read at all.
+   *
+   * Both answers come from one snapshot, because only their combination proves that a login is *not* the active one.
+   * An installation this adapter cannot read reports no accounts, so the login Claude Code is actually running on
+   * reads as inactive there; anything that would renew a saved login has to refuse instead.
+   */
+  private nativeView(idArg: string): { active: IFileAccount | null; unavailable: string | null } {
+    const snapshot = this.snapshot();
+    return { active: snapshot.accounts.find(account => this.store.id(account.slotId, account.identity) === idArg) ?? null, unavailable: snapshot.unavailable };
+  }
+
+  /**
+   * The account's status. The active login is read as it is: Claude Code refreshes it. A saved login whose access token
+   * 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.
+   */
+  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 view = this.nativeView(id);
+    if (view.active) return read(view.active);
+    const saved = this.savedCredential(id);
+    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}`);
+    }
+    if (this.store.read(id).rejectedGrant === this.grantKey(oauth)) return this.status.unavailable(oauth, `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}`,
+        error instanceof ClaudeRateLimitError ? { retryAt: error.retryAt } : undefined);
+    }
+    return read(refreshed);
+  }
+
+  /**
+   * A saved login with fresh tokens, refreshed as the only operation on the store: a switch, a save or another refresh
+   * waits for it, so none of them can read or activate a refresh token the service is replacing. Under the lock the
+   * native files are read again, so the decision that this is not the active login is taken where it holds: one that
+   * 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).
+   */
+  private refreshSaved(id: string, signal?: AbortSignal): Promise<IFileAccount> {
+    return this.store.locked(async () => {
+      const view = this.nativeView(id);
+      if (view.active) return view.active;
+      const saved = this.savedCredential(id);
+      const oauth = credentialRecord(saved.credential.claudeAiOauth);
+      if (view.unavailable !== null || !this.tokens.due(oauth)) return saved;
+      signal?.throwIfAborted();
+      let tokens: IClaudeTokens;
+      try { tokens = await this.tokens.refresh(oauth); }
+      catch (error) {
+        // Only this token was rejected; a login saved again replaces it and is tried like any other.
+        if (error instanceof ClaudeLoginRejectedError) this.recordRejectedGrant(id, oauth);
+        throw error;
+      }
+      const latest = this.savedCredential(id);
+      const latestOauth = credentialRecord(latest.credential.claudeAiOauth);
+      if (latestOauth.refreshToken !== oauth.refreshToken) return latest;
+      this.store.replaceCredential(id, { ...latest.credential, claudeAiOauth: { ...latestOauth, ...tokens } });
+      return this.savedCredential(id);
+    }, { signal });
+  }
+
+  /**
+   * Remembers a rejected grant in the saved record, so the next process does not send it again either -- a watch
+   * would otherwise replay a dead login every tick, and every new CLI run once more. It is written only while the
+   * record still holds the token that was sent, and a record that could not be written changes nothing but that:
+   * the refusal the caller reports is the answer, and the grant is simply tried once more.
+   */
+  private recordRejectedGrant(id: string, oauthArg: Record<string, unknown>): void {
+    try {
+      const latest = credentialRecord(this.savedCredential(id).credential.claudeAiOauth);
+      if (latest.refreshToken === oauthArg.refreshToken) this.store.rememberRejectedGrant(id, this.grantKey(oauthArg));
+    } catch { /* Recording is advisory; the rejection is reported either way. */ }
   }
 }

package/ts/classes.claudecodelocks.ts

@@ -0,0 +1,133 @@
+import * as plugins from './plugins.js';
+import { errorCode } from './helpers.js';
+
+/** One lock Claude Code takes, with the options it takes it with. */
+interface IClaudeCodeLock {
+  /** The path proper-lockfile keys the lock by. */
+  file: string;
+  /** The lock directory. */
+  lockfilePath: string;
+  stale: number;
+  /** Omitted where Claude Code leaves it to proper-lockfile's default of half the stale time. */
+  update?: number;
+  /** Claude Code proceeds without this lock when it fails for any reason other than being held. */
+  bestEffort: boolean;
+}
+
+interface IHeldLock {
+  lockfilePath: string;
+  release: () => Promise<void>;
+}
+
+export interface IClaudeCodeLocksOptions {
+  /** How long an operation waits for a lock that Claude Code holds. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const RETRY_MS = 250;
+
+/**
+ * Claude Code's own locks around its login and global config, taken with its own library and options.
+ *
+ * A running Claude Code picks a swapped credential up on its next request, so a switch no longer waits for it to
+ * stop. What it must not do is interleave with that session's own writes: a token refresh that is in flight when
+ * the credential is swapped leaves the outgoing account's saved copy with a refresh token the server may already
+ * have replaced, and a config save that read `.claude.json` before the swap writes the previous account's
+ * metadata back. Claude Code 2.1.273 serialises those writers with proper-lockfile (see hints.md); this class
+ * takes the same locks, in the order a refresh nests them, waits a bounded time for a held one, and releases them
+ * in reverse order on every path. A lock left behind by a Claude Code that died is stale after its own threshold
+ * and is taken over, exactly as Claude Code itself would.
+ */
+export class ClaudeCodeLocks {
+  private readonly timeoutMs: number;
+
+  constructor(private readonly configDir: string, private readonly configFile: string, optionsArg: IClaudeCodeLocksOptions = {}) {
+    this.timeoutMs = optionsArg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  /** The locks of Claude Code 2.1.273, in acquisition order. */
+  private async locks(): Promise<IClaudeCodeLock[]> {
+    // The OAuth refresh lock's legacy twin is keyed by the resolved directory; Claude Code falls back to the path as given.
+    const resolved = await plugins.fs.promises.realpath(this.configDir).catch(() => this.configDir);
+    const storageWrite = plugins.path.join(this.configDir, '.storage-write');
+    return [
+      { file: this.configDir, lockfilePath: plugins.path.join(this.configDir, '.oauth_refresh.lock'), stale: 60_000, update: 5_000, bestEffort: false },
+      { file: `${resolved}.lock`, lockfilePath: `${resolved}.lock`, stale: 60_000, update: 5_000, bestEffort: true },
+      { file: storageWrite, lockfilePath: `${storageWrite}.lock`, stale: 15_000, bestEffort: false },
+      { file: this.configFile, lockfilePath: `${this.configFile}.lock`, stale: 10_000, bestEffort: false },
+    ];
+  }
+
+  /**
+   * Runs a synchronous read-and-write of the native login while every lock is held.
+   *
+   * A held lock never makes authswitch sit on the others: like Claude Code, it releases what it holds, waits and
+   * starts again, so a live session is never blocked by a switch that is still waiting. A lock that could not be
+   * released afterwards is reported as an outcome line, because the write it guarded has completed and the lock
+   * expires on its own. `timeoutMs` shortens the wait for a caller that must not make a user wait for it -- a read
+   * bringing a saved copy up to date has nothing to finish and can leave it to the next read.
+   */
+  public async hold(actionArg: () => string[], optionsArg: { timeoutMs?: number } = {}): Promise<string[]> {
+    const lockfile = await plugins.loadProperLockfile();
+    const deadline = Date.now() + (optionsArg.timeoutMs ?? this.timeoutMs);
+    const held: IHeldLock[] = [];
+    const unreleased: string[] = [];
+    const releaseAll = async (): Promise<void> => {
+      for (const lock of held.splice(0).reverse()) {
+        // A compromised lock is no longer ours to release; the operation already failed for it.
+        try { await lock.release(); } catch (error) { if (errorCode(error) !== 'ERELEASED') unreleased.push(lock.lockfilePath); }
+      }
+    };
+    let outcome: { lines: string[] } | { error: unknown };
+    try {
+      for (const directory of new Set([this.configDir, plugins.path.dirname(this.configFile)])) {
+        plugins.fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+      }
+      const locks = await this.locks();
+      for (;;) {
+        // Each attempt owns its flag, so a late report about a lock released in an earlier attempt changes nothing.
+        const attempt = { compromised: false };
+        const busy = await this.acquireAll(lockfile, locks, held, () => { attempt.compromised = true; });
+        if (busy === null) {
+          if (attempt.compromised) throw new Error('A Claude Code lock was taken over while authswitch took the others; nothing was changed. Try again.');
+          break;
+        }
+        await releaseAll();
+        if (Date.now() >= deadline) {
+          throw new Error(`Claude Code is refreshing or saving its login (${busy.lockfilePath} is held); nothing was changed. Try again in a moment.`);
+        }
+        await new Promise<void>(resolve => { setTimeout(resolve, Math.min(RETRY_MS, Math.max(1, deadline - Date.now()))); });
+      }
+      outcome = { lines: actionArg() };
+    } catch (error) { outcome = { error }; }
+    await releaseAll();
+    const note = unreleased.length ? `Claude Code's lock ${unreleased.join(', ')} could not be released; it expires on its own within a minute.` : null;
+    if ('error' in outcome) {
+      if (note === null) throw outcome.error;
+      throw new Error(`${outcome.error instanceof Error ? outcome.error.message : 'Credential operation failed.'} ${note}`);
+    }
+    return note === null ? outcome.lines : [...outcome.lines, note];
+  }
+
+  /** Takes the locks in order into `heldArg` and returns the first one another process holds, or null once all are held. */
+  private async acquireAll(
+    lockfileArg: plugins.TProperLockfile,
+    locksArg: readonly IClaudeCodeLock[],
+    heldArg: IHeldLock[],
+    onCompromisedArg: (errorArg: Error) => void,
+  ): Promise<IClaudeCodeLock | null> {
+    for (const lock of locksArg) {
+      try {
+        const release = await lockfileArg.lock(lock.file, {
+          lockfilePath: lock.lockfilePath, realpath: false, stale: lock.stale, update: lock.update, onCompromised: onCompromisedArg,
+        });
+        heldArg.push({ lockfilePath: lock.lockfilePath, release });
+      } catch (error) {
+        if (errorCode(error) === 'ELOCKED') return lock;
+        if (!lock.bestEffort) throw new Error(`Claude Code's lock ${lock.lockfilePath} could not be taken (${errorCode(error) ?? 'unknown error'}); nothing was changed.`);
+      }
+    }
+    return null;
+  }
+}