@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/oauth/meta-muse-errors.ts

@@ -0,0 +1,41 @@
+/** Closed, account-free diagnostics: never project a provider's raw error text. */
+const messages = {
+  "cancelled": "Muse Code login cancelled.",
+  "pointer-unreadable": "Could not read the Muse Code credential file. Check its permissions or run `muse login` again.",
+  "pointer-invalid": "The Muse Code credential file is not valid JSON or has an invalid shape. Run `muse login` to rewrite it.",
+  "storage-unsupported": "Muse Code stored its credential with an unsupported backend; only the macOS Keychain import is verified. Retry import or paste an existing Muse Code key when prompted.",
+  "keychain-timeout": "The Muse Code Keychain approval timed out after 120s. Unlock the login keychain, approve the prompt and retry, or paste an existing Muse Code key when prompted.",
+  "keychain-denied": "Access to the Muse Code Keychain entry was denied or cancelled. Approve the Keychain prompt and retry, or paste an existing Muse Code key when prompted.",
+  "keychain-locked": "The Muse Code Keychain entry requires user interaction. Unlock the login keychain and retry from an interactive macOS session, or paste an existing Muse Code key when prompted.",
+  "keychain-missing": "The Muse Code Keychain entry was not found. Run `muse login` again, or paste an existing Muse Code key when prompted.",
+  "keychain-unreadable": "Could not read the Muse Code credential from the macOS Keychain. Run `muse login` again, or paste an existing Muse Code key when prompted.",
+  "keychain-invalid": "The Muse Code Keychain entry is not valid JSON or has an invalid shape. Run `muse login` to rewrite it.",
+  "key-missing": "The Muse Code Keychain entry carries no usable API key. Run `muse login` again, or paste an existing Muse Code key when prompted.",
+  "key-format": "The Muse Code credential is not in the expected Meta API key format. Run `muse login` again, or paste an existing Muse Code key when prompted.",
+  "manual-key-missing": "The pasted Muse Code credential carries no usable API key. Copy it again from https://dev.meta.ai.",
+  "manual-key-format": "The pasted Muse Code credential is not in the expected Meta API key format. Copy it again from https://dev.meta.ai.",
+  "validation-network": "Could not reach the Meta Model API to validate the Muse Code credential. Check the proxy host's network and retry.",
+  "validation-timeout": "The Meta Model API credential validation timed out after 10s. Check the proxy host's network and retry.",
+  "validation-http": "The Muse Code credential was rejected by the Meta Model API. Renew it with `muse login` or copy it again from https://dev.meta.ai, then retry.",
+} as const;
+
+export type MuseLoginErrorKind = keyof typeof messages;
+
+export class MuseLoginError extends Error {
+  constructor(readonly kind: MuseLoginErrorKind, readonly status?: number) {
+    super(museLoginErrorMessage(kind, status));
+    this.name = "MuseLoginError";
+  }
+}
+
+export function museLoginErrorMessage(kind: MuseLoginErrorKind, status?: number): string {
+  const message = Object.hasOwn(messages, kind) ? messages[kind] : messages["keychain-unreadable"];
+  return kind === "validation-http" && Number.isInteger(status) && status! >= 100 && status! <= 599
+    ? `${message} (HTTP ${status})`
+    : message;
+}
+
+export function publicMuseLoginErrorMessage(error: unknown): string | undefined {
+  // Reconstruct from the closed kind; even a mutated Error.message cannot leak a key.
+  return error instanceof MuseLoginError ? museLoginErrorMessage(error.kind, error.status) : undefined;
+}

package/src/oauth/meta-muse-keychain.ts

@@ -0,0 +1,52 @@
+import { MuseLoginError } from "./meta-muse-errors";
+
+// Approval includes typing a password. Five seconds kills security while the user types.
+export const MUSE_KEYCHAIN_TIMEOUT_MS = 120_000;
+export interface MuseKeychainProcess {
+  stdout: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+  kill(): void;
+}
+interface KeychainDeps {
+  spawn?: (argv: string[]) => MuseKeychainProcess;
+  timeoutMs?: number;
+}
+
+export async function readMuseKeychain(signal?: AbortSignal, deps: KeychainDeps = {}): Promise<string> {
+  if (signal?.aborted) throw new MuseLoginError("cancelled");
+  const timeout = AbortSignal.timeout(deps.timeoutMs ?? MUSE_KEYCHAIN_TIMEOUT_MS);
+  const deadline = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  let child: MuseKeychainProcess | undefined;
+  let exited = false;
+  let onAbort: (() => void) | undefined;
+  try {
+    child = (deps.spawn ?? (argv => Bun.spawn(argv, { stdin: "ignore", stdout: "pipe", stderr: "ignore" })))(
+      ["/usr/bin/security", "find-generic-password", "-s", "ai.meta.dev.credentials", "-a", "meta", "-w"],
+    );
+    const finished = Promise.all([new Response(child.stdout).text(), child.exited.then(code => { exited = true; return code; })]);
+    const aborted = new Promise<never>((_, reject) => {
+      onAbort = () => reject(new MuseLoginError(signal?.aborted ? "cancelled" : "keychain-timeout"));
+      if (deadline.aborted) onAbort();
+      else deadline.addEventListener("abort", onAbort, { once: true });
+    });
+    const [out, code] = await Promise.race([finished, aborted]);
+    if (signal?.aborted) throw new MuseLoginError("cancelled");
+    if (code !== 0) {
+      // security returns OSStatus truncated to an 8-bit process exit code (SecBase.h).
+      // Unknown failures stay unknown; no stderr or credential output is retained.
+      if (code === 44) throw new MuseLoginError("keychain-missing"); // errSecItemNotFound -25300
+      if (code === 36) throw new MuseLoginError("keychain-locked"); // errSecInteractionNotAllowed -25308
+      if (code === 51 || code === 128) throw new MuseLoginError("keychain-denied"); // -25293 / -128
+      throw new MuseLoginError("keychain-unreadable");
+    }
+    if (!out.trim()) throw new MuseLoginError("keychain-unreadable");
+    return out.trim();
+  } catch (error) {
+    if (signal?.aborted) throw new MuseLoginError("cancelled");
+    if (error instanceof MuseLoginError) throw error;
+    throw new MuseLoginError("keychain-unreadable");
+  } finally {
+    if (onAbort) deadline.removeEventListener("abort", onAbort);
+    if (child && !exited) { try { child.kill(); } catch { /* already exited */ } }
+  }
+}

package/src/oauth/meta-muse.ts

@@ -26,14 +26,13 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { sanitizeApiKeyValue } from "../providers/api-keys";
 import { MuseDeviceLoginError, loginMetaMuseDevice } from "./meta-muse-device";
+import { MuseLoginError, publicMuseLoginErrorMessage } from "./meta-muse-errors";
+import { readMuseKeychain } from "./meta-muse-keychain";
 import type { OAuthController, OAuthCredentials } from "./types";
 
 const MUSE_POINTER_PATH = join(homedir(), ".config", "muse", "auth.json");
-const KEYCHAIN_SERVICE = "ai.meta.dev.credentials";
-const KEYCHAIN_ACCOUNT = "meta";
 const MODELS_URL = "https://api.meta.ai/v1/models";
 const VALIDATE_TIMEOUT_MS = 10_000;
-const KEYCHAIN_TIMEOUT_MS = 5_000;
 
 /**
  * Shown BEFORE any credential is read.
@@ -82,44 +81,9 @@ export interface MuseLoginOptions {
 async function defaultReadPointer(): Promise<string | null> {
   try {
     return await Bun.file(MUSE_POINTER_PATH).text();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * `security` can block indefinitely — the Keychain may raise an interactive approval
- * prompt, and on a headless or locked machine nobody answers it. Without a deadline the
- * login would hang before the validation timeout below is even created, so the bound
- * lives here rather than only around the fetch.
- */
-async function defaultReadKeychain(signal?: AbortSignal): Promise<string | null> {
-  const deadline = signal
-    ? AbortSignal.any([signal, AbortSignal.timeout(KEYCHAIN_TIMEOUT_MS)])
-    : AbortSignal.timeout(KEYCHAIN_TIMEOUT_MS);
-  let proc: Bun.Subprocess<"ignore", "pipe", "pipe"> | undefined;
-  try {
-    proc = Bun.spawn(
-      ["security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", KEYCHAIN_ACCOUNT, "-w"],
-      { stdout: "pipe", stderr: "pipe" },
-    );
-    const child = proc;
-    const finished = Promise.all([new Response(child.stdout).text(), child.exited]);
-    const timedOut = new Promise<null>((resolve) => {
-      if (deadline.aborted) { resolve(null); return; }
-      deadline.addEventListener("abort", () => resolve(null), { once: true });
-    });
-    const settled = await Promise.race([finished, timedOut]);
-    if (settled === null) return null;
-    const [out, code] = settled;
-    if (code !== 0) return null;
-    const trimmed = out.trim();
-    return trimmed.length > 0 ? trimmed : null;
-  } catch {
-    return null;
-  } finally {
-    // A prompt still on screen keeps the child alive after the race resolves.
-    if (proc && proc.exitCode === null) { try { proc.kill(); } catch { /* already gone */ } }
+  } catch (error) {
+    if ((error as { code?: string })?.code === "ENOENT") return null;
+    throw new MuseLoginError("pointer-unreadable");
   }
 }
 
@@ -160,6 +124,10 @@ async function manualKeyCredential(
   return pasted.length > 0 ? pasted : null;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function normalizedEmail(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim().toLowerCase();
@@ -179,6 +147,7 @@ export async function loginMetaMuse(
   // Before ANY read: the CLI has no other warning surface.
   ctrl.onProgress?.(CONSENT_WARNING);
 
+  if (ctrl.signal?.aborted) throw new MuseLoginError("cancelled");
   const platform = deps.platform ?? process.platform;
 
   // Import first on darwin, and only for a plain login. A user who already ran `muse
@@ -187,8 +156,19 @@ export async function loginMetaMuse(
   // a request to arrive at the same key. `forceLogin` maps to "off" upstream because
   // reimporting is how an add-account silently re-adds the account the user already has.
   if (platform === "darwin" && options.importLocal !== "off") {
-    const imported = await importFromKeychain(ctrl, deps);
-    if (imported) return imported;
+    try {
+      const imported = await importFromKeychain(ctrl, deps);
+      if (imported) return imported;
+    } catch (error) {
+      if (isCancellation(error, ctrl)) throw error;
+      const reason = publicMuseLoginErrorMessage(error);
+      // Recovery requires an explicit paste, never an automatic grant or key mint.
+      if (!reason || !ctrl.onManualCodeInput) throw error;
+      const pasted = await manualKeyCredential(ctrl, reason);
+      if (ctrl.signal?.aborted) throw new MuseLoginError("cancelled");
+      if (pasted === null) throw error;
+      return await validatedMetaMuseCredential(pasted, ctrl, deps, undefined, "manual");
+    }
   }
 
   // fetchImpl/sleep/now are FORWARDED. Without this the device module would carry its own
@@ -221,46 +201,46 @@ export async function loginMetaMuse(
  * caller can offer a device grant instead of a dead end. Everything else still throws: a
  * corrupt file, an unmeasured storage backend, a Keychain read that times out, and a
  * Keychain entry that is unreadable or carries no usable key are all cases where a
- * credential probably EXISTS, and silently starting a browser grant would create a second
- * login to work around a permissions dialog.
+ * credential probably EXISTS. The caller can offer explicit key paste recovery, but never
+ * silently starts a second login to work around a permissions dialog.
  */
 async function importFromKeychain(
   ctrl: OAuthController,
   deps: MuseImportDeps,
 ): Promise<OAuthCredentials | null> {
   const pointerRaw = await (deps.readPointer ?? defaultReadPointer)();
+  if (ctrl.signal?.aborted) throw new MuseLoginError("cancelled");
   if (pointerRaw === null) return null;
 
   let pointer: MusePointer;
   try {
     pointer = JSON.parse(pointerRaw) as MusePointer;
+    if (!isRecord(pointer) || (pointer.providers !== undefined && !isRecord(pointer.providers))
+      || (pointer.providers?.meta !== undefined && !isRecord(pointer.providers.meta))) throw new Error();
   } catch {
-    throw new Error(`Muse Code credential file at ${MUSE_POINTER_PATH} is not valid JSON. Run \`muse login\` to rewrite it.`);
+    throw new MuseLoginError("pointer-invalid");
   }
 
   const meta = pointer.providers?.meta;
   if (!meta || meta.mechanism !== "oauth") return null;
   // A different storage backend is a shape we have not measured; refuse rather than guess.
   if (meta.storage !== "keychain") {
-    throw new Error(
-      `Muse Code stored its credential with an unsupported backend (${String(meta.storage)}); only the macOS Keychain is verified.`,
-    );
+    throw new MuseLoginError("storage-unsupported");
   }
 
-  // ctrl.signal is handed to the reader, not dropped: the caller can cancel a Keychain
-  // prompt nobody is going to answer.
-  const secretRaw = await (deps.readKeychain ?? defaultReadKeychain)(ctrl.signal);
-  if (secretRaw === null) {
-    throw new Error(
-      "Could not read the Muse Code credential from the macOS Keychain within 5s. Approve the Keychain prompt, or run `muse login` again, or add the account again to sign in with a browser code instead.",
-    );
-  }
+  if (ctrl.signal?.aborted) throw new MuseLoginError("cancelled");
+  // Publish a hint before the OS dialog so the dashboard can poll and cancel it.
+  ctrl.onAuth?.({ url: "", instructions: "Approve the Muse Code Keychain prompt on the proxy host. Waiting up to 120 seconds." });
+  const secretRaw = await (deps.readKeychain ?? readMuseKeychain)(ctrl.signal);
+  if (ctrl.signal?.aborted) throw new MuseLoginError("cancelled");
+  if (secretRaw === null) throw new MuseLoginError("keychain-unreadable");
 
   let secret: MuseKeychainSecret;
   try {
     secret = JSON.parse(secretRaw) as MuseKeychainSecret;
+    if (!isRecord(secret)) throw new Error();
   } catch {
-    throw new Error("The Muse Code Keychain entry is not valid JSON. Run `muse login` to rewrite it.");
+    throw new MuseLoginError("keychain-invalid");
   }
 
   // access_token is present but 401s against the Model API (003 §B) — never fall back to it.
@@ -287,7 +267,7 @@ function deviceFailureReason(error: unknown): string {
       case "subscription-inactive":
         return "This Meta account has no active Muse Code subscription.";
       case "entitlement-required":
-        return error.message;
+        return "Complete the Muse Code subscription setup at https://dev.meta.ai, then retry.";
       case "mint-rate-limited":
         return "Meta rate-limited the Muse Code key request.";
       case "device-denied":
@@ -314,7 +294,7 @@ function noPasteSurfaceError(platform: string, reason: string): Error {
   const platformClause = platform === "darwin"
     ? ""
     : platform === "win32"
-      ? " Meta ships no native Windows Muse Code CLI, so there is no credential to import."
+      ? " The Windows Muse Code credential store has not been verified, so there is no credential to import through this reader."
       : " The Muse Code CLI runs here, but where it stores its credential has not been measured, "
         + "so importing one is refused rather than guessed.";
   return new Error(
@@ -338,22 +318,10 @@ async function validatedMetaMuseCredential(
   email: string | undefined,
   source: "local-cli" | "manual",
 ): Promise<OAuthCredentials> {
-  const retry = source === "manual"
-    ? `Copy it again from ${MANUAL_KEY_URL}.`
-    : "Run `muse login` again.";
+  if (ctrl.signal?.aborted) throw new MuseLoginError("cancelled");
   const apiKey = sanitizeApiKeyValue(candidate);
-  if (!apiKey) {
-    // The macOS wording is preserved verbatim. Extraction is a refactor, and a refactor
-    // that quietly rewrites a user-facing error is a behavior change in disguise.
-    throw new Error(source === "manual"
-      ? `The pasted Muse Code credential carries no usable API key. ${retry}`
-      : "The Muse Code Keychain entry carries no usable API key. Run `muse login` again.");
-  }
-  if (!/^LLM\|\d+\|[A-Za-z0-9_-]{10,}$/.test(apiKey)) {
-    throw new Error(source === "manual"
-      ? `The pasted Muse Code credential is not in the expected Meta API key format. ${retry}`
-      : "The Muse Code credential is not in the expected Meta API key format. Run `muse login` again.");
-  }
+  if (!apiKey) throw new MuseLoginError(source === "manual" ? "manual-key-missing" : "key-missing");
+  if (!/^LLM\|\d+\|[A-Za-z0-9_-]{10,}$/.test(apiKey)) throw new MuseLoginError(source === "manual" ? "manual-key-format" : "key-format");
   ctrl.onProgress?.(source === "manual"
     ? "Validating the pasted Meta credential..."
     : "Validating the imported Meta credential...");
@@ -366,18 +334,17 @@ async function validatedMetaMuseCredential(
   let response: Response;
   try {
     response = await fetchImpl(MODELS_URL, {
-      headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json", "x-api-version": "1.0.0" },
+      redirect: "error",
       signal,
     });
-  } catch (error) {
-    if (ctrl.signal?.aborted) throw ctrl.signal.reason ?? new DOMException("Meta Muse login aborted", "AbortError");
-    throw new Error(`Could not reach the Meta Model API to validate the credential: ${(error as Error).message}`);
-  }
-  if (!response.ok) {
-    throw new Error(
-      `The Muse Code credential was rejected by the Meta Model API (HTTP ${response.status}). ${retry}`,
-    );
+  } catch {
+    if (ctrl.signal?.aborted) throw new MuseLoginError("cancelled");
+    throw new MuseLoginError(signal.aborted ? "validation-timeout" : "validation-network");
   }
+  if (ctrl.signal?.aborted) throw new MuseLoginError("cancelled");
+  void response.body?.cancel().catch(() => {});
+  if (!response.ok) throw new MuseLoginError("validation-http", response.status);
 
   return {
     access: apiKey,

package/src/oauth/model-discovery-auth.ts

@@ -5,6 +5,9 @@ import { resolveProviderTransport } from "../providers/xai-transport";
 
 /** Discovery owns its configured row (a frozen capture for catalog gathers), not live config. */
 export function mayResolveModelsOAuth(name: string, provider: OcxProviderConfig | undefined): boolean {
+  // The DSH account token is pinned to its own adapter and fixed DeepSeek hosts. Its catalog is
+  // static, so no discovery path may resolve it, whatever adapter or baseUrl the row was edited to.
+  if (name === "dsh-account") return false;
   return name !== "anthropic2" || (provider !== undefined && provider.disabled !== true
     && isBuiltinAnthropicInstanceRow(name, provider));
 }

package/src/oauth/pool-settings-capability.ts

@@ -22,7 +22,7 @@ import { readAnthropicModelRoutes } from "./anthropic-model-routes";
  */
 export type PoolSettingsKind = "codex" | "anthropic" | "generic";
 
-export const GENERIC_POOL_STRATEGIES = ["quota", "round-robin", "fill-first", "least-loaded"] as const;
+export const GENERIC_POOL_STRATEGIES = ["quota", "round-robin", "fill-first", "reset-first", "least-loaded"] as const;
 export type GenericPoolStrategy = typeof GENERIC_POOL_STRATEGIES[number];
 
 export function poolSettingsCapability(name: string, provider: OcxProviderConfig | undefined): PoolSettingsKind | null {
@@ -33,7 +33,9 @@ export function poolSettingsCapability(name: string, provider: OcxProviderConfig
 }
 
 export function parseGenericPoolStrategy(value: unknown, providerName?: string): GenericPoolStrategy | null {
-  // Keep the common three names in the shared parser; the fourth is Kiro-specific.
+  // reset-first is shared with the Codex pool, so it is named here rather than added to the
+  // three-name shared parser that the Anthropic kind also uses. least-loaded is Kiro-specific.
+  if (value === "reset-first") return value;
   if (value === "least-loaded") return providerName === "kiro" ? value : null;
   return parseAccountPoolStrategy(value);
 }

package/src/oauth/refresh-flight-retirement.ts

@@ -0,0 +1,48 @@
+import { createAdmissionGate } from "../lib/admission";
+import { isAnthropicOAuthInstance } from "../providers/anthropic-instance";
+import { clearObservedAnthropicRefreshIntent } from "./anthropic-oauth-definitions";
+import { logOAuthEvent } from "./log";
+import { markOAuthRefreshIntentStaleOwner, readOAuthRefreshIntent } from "./store";
+
+/** Independent of client lifetime; a cancelled caller can still be awaiting a shared refresh. */
+export const MAX_OAUTH_TOKEN_REFRESH_WAITERS = 256;
+export const tokenRefreshWaiters = createAdmissionGate("oauth_token_refresh_waiters", MAX_OAUTH_TOKEN_REFRESH_WAITERS);
+
+export interface OAuthRefreshFlightEvidence { flightId: string; dispatched: boolean }
+
+export interface RetirableOAuthRefreshFlight extends OAuthRefreshFlightEvidence {
+  settled?: boolean;
+  retirementDeferredLogged?: boolean;
+}
+
+// Retire only after the old attempt has finished its definitive-result cleanup. A provider
+// may ignore abort; marking its intent sooner would poison a late, safely retryable rejection.
+// Failed durable retirement retains the same bounded registry slot for a later retry.
+export function retireSettledOAuthRefreshFlight<F extends RetirableOAuthRefreshFlight>(
+  tokenRefreshes: Map<string, F>, key: string, flight: F,
+): boolean {
+  if (!flight.settled) return false;
+  const [provider, accountId] = key.split("\0");
+  const defer = (reason: "uncertain_intent" | "intent_changed" | "storage_failure"): false => {
+    if (!flight.retirementDeferredLogged) {
+      flight.retirementDeferredLogged = true;
+      logOAuthEvent("OAuth refresh flight retirement deferred", { provider: provider ?? "unknown", reason });
+    }
+    return false;
+  };
+  try {
+    if (provider && accountId && isAnthropicOAuthInstance(provider)) {
+      const intent = readOAuthRefreshIntent(provider, accountId);
+      if (intent?.uncertain) return defer("uncertain_intent");
+      if (intent?.flightId === flight.flightId && !intent.staleOwner && !intent.cleanupPending) {
+        const retired = flight.dispatched
+          ? markOAuthRefreshIntentStaleOwner(provider, accountId, intent.generation, flight.flightId)
+          : clearObservedAnthropicRefreshIntent(provider, accountId, intent);
+        if (!retired) return defer("intent_changed");
+      }
+    }
+  } catch { return defer("storage_failure"); }
+  if (tokenRefreshes.get(key) === flight) tokenRefreshes.delete(key);
+  return true;
+}
+

package/src/oauth/session-affinity-key.ts

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+
+/** Shared conversation identity precedence; Desktop cohort cache keys never bind sessions. */
+export function oauthSessionKeyFromParts(input: {
+  sessionIdHeader?: string | null;
+  threadIdHeader?: string | null;
+  promptCacheKey?: string | null;
+  clientThreadId?: string | null;
+  /** When true, prompt_cache_key is a shared Desktop cohort — ignore it for affinity. */
+  promptCacheKeyIsSharedCohort?: boolean;
+}): string | null {
+  const preferred = input.clientThreadId?.trim()
+    || input.sessionIdHeader?.trim()
+    || input.threadIdHeader?.trim()
+    || "";
+  if (preferred) {
+    return preferred.length <= 128 ? preferred : createHash("sha256").update(preferred).digest("hex");
+  }
+  if (input.promptCacheKeyIsSharedCohort) return null;
+  const cacheKey = input.promptCacheKey?.trim() ?? "";
+  if (!cacheKey) return null;
+  return cacheKey.length <= 128 ? cacheKey : createHash("sha256").update(cacheKey).digest("hex");
+}

package/src/oauth/store-anthropic-instance.ts

@@ -32,6 +32,13 @@ export class AnthropicInstanceCollisionError extends Error {
   }
 }
 
+export class AnthropicInstanceConfigReadError extends Error {
+  constructor() {
+    super("Cannot verify Anthropic Pool 2 ownership in the existing config file.");
+    this.name = "AnthropicInstanceConfigReadError";
+  }
+}
+
 export function assertAnthropicInstanceLoginConfig(config: Pick<OcxConfig, "providers">, provider: string, credentialWritten = false): void {
   if (provider !== "anthropic2") return;
   const row = config.providers.anthropic2;
@@ -44,11 +51,11 @@ export function assertAnthropicInstanceLoginConfig(config: Pick<OcxConfig, "prov
   try { raw = readFileSync(getConfigPath(), "utf8"); }
   catch (error) {
     if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return;
-    throw new Error("Cannot verify Anthropic Pool 2 ownership in the existing config file.");
+    throw new AnthropicInstanceConfigReadError();
   }
   let parsed: unknown;
   try { parsed = JSON.parse(raw.replace(/^\uFEFF/, "")); }
-  catch { throw new Error("Cannot verify Anthropic Pool 2 ownership in the existing config file."); }
+  catch { throw new AnthropicInstanceConfigReadError(); }
   const providers = parsed && typeof parsed === "object" && "providers" in parsed ? parsed.providers : undefined;
   if (providers && typeof providers === "object" && Object.hasOwn(providers, provider)) {
     const persisted = (providers as Record<string, unknown>)[provider];

package/src/oauth/store.ts

@@ -1028,8 +1028,8 @@ export async function saveCredential(
   provider: string,
   cred: OAuthCredentials,
   opts: { preserveIdentityless?: boolean; assertBeforePersist?: () => void } = {},
-): Promise<void> {
-  await saveCredentialWithReceipt(provider, cred, opts);
+): Promise<OAuthCredentialWriteReceipt | null> {
+  return await saveCredentialWithReceipt(provider, cred, opts);
 }
 
 /**
@@ -1234,23 +1234,29 @@ export function getAccountCredentialWithStatus(
   };
 }
 
-/** Persist an explicit login/reauth credential for one account; runtime rotations use mergeAccountCredential. */
+/**
+ * Persist an explicit login/reauth credential for one account; runtime rotations use
+ * mergeAccountCredential. Resolves false when nothing was written (the account is gone).
+ */
 export async function saveAccountCredential(
   provider: string,
   accountId: string,
   cred: OAuthCredentials,
   opts: { assertBeforePersist?: () => void; rotateLoginId?: boolean } = {},
-): Promise<void> {
+): Promise<boolean> {
   if (isAnthropicInstanceId(provider)) assertAnthropicCredentialSource(provider, cred);
   const safe = normalizeCredential(cred);
-  if (!safe) return;
+  if (!safe) return false;
+  let written = false;
   await mutateStore(store => {
+    written = false;
     if (provider === "anthropic2") assertAnthropicInstanceLoginConfig(loadConfig(), provider);
     if (isAnthropicInstanceId(provider)) assertNoCrossAnthropicRegistration(store, provider, safe);
     const set = store[provider];
     const account = set?.accounts.find(a => a.id === accountId);
     if (!set || !account) return;
     account.credential = safe;
+    written = true;
     if (opts.rotateLoginId) account.loginId = randomUUID();
     delete account.needsReauth;
     delete account.needsReauthReason;
@@ -1263,6 +1269,7 @@ export async function saveAccountCredential(
       set.selectionRevision = randomUUID();
     }
   }, [provider, accountId, safe], { assertBeforePersist: registrationPersistGuard(provider, opts.assertBeforePersist) });
+  return written;
 }
 
 function accountSelection(set: ProviderAccountSet): OAuthAccountSelection {