@bitkyc08/opencodex 2.82.0 → 2.84.0

package/src/oauth/index.ts

@@ -5,6 +5,7 @@ import { getDefaultConfig, initializePersistedConfigIfMissing, loadConfig, mutat
 import { resolveProviderApiKey } from "../providers/key-store";
 import { projectEmail } from "../lib/privacy";
 import { KiroTokenRefreshError, environmentKiroRoutingMetadata, loginKiro, refreshKiroToken, settleKiroLoginTransaction } from "./kiro";
+import { KiroUserIdentityUnavailableError, kiroReauthIdentityMatches } from "./kiro-account-identity";
 import {
   OAuthMutationBusyError,
   OAuthRefreshIntentIOError,
@@ -86,6 +87,7 @@ import { codexAccountNamespaceProviderCollisionError } from "../codex/account-na
 
 import { REFRESH_SKEW_MS } from "./refresh-policy";
 import { newerClaudeCredentialForInstance, captureAnthropicCredentialOwnerForInstance } from "./anthropic-continuity";
+import { normalizeOAuthPlan, mergeOAuthPlan } from "./plan";
 import { mergeAnthropicIdentity, type AnthropicIdentityResolver } from "./anthropic-identity";
 import { AnthropicCrossInstanceDuplicateError, AnthropicLocalCliImportError, assertAnthropicCredentialSource } from "./store-anthropic-instance";
 export interface OAuthAccessSnapshot {
@@ -360,7 +362,7 @@ export const OAUTH_PROVIDERS: Record<string, OAuthProviderDef> = {
  * Removed provider ids that still name a live successor.
  *
  * `devin-cli` was merged into `devin` (import-first login absorbed the CLI
- * credential import; devlog/_plan/260913_devin_provider_merge). The id can
+ * credential import; devlog/_fin/260913_devin_provider_merge). The id can
  * still arrive here from a saved config row or a stored credential slot that
  * the startup migration has not rekeyed yet, and from a user typing the old
  * name at `ocx login`. It is deliberately NOT an OAUTH_PROVIDERS entry:
@@ -491,6 +493,9 @@ export function publicOAuthAuthenticationErrorMessage(error: unknown): string {
     || error instanceof AnthropicInstanceCollisionError
     || error instanceof AnthropicCrossInstanceDuplicateError
     || error instanceof AnthropicLocalCliImportError
+    // Fixed, account-free text: a Kiro login that could not name its user left the existing
+    // organization account in place, and the user must confirm the signed-in CLI user (#6641).
+    || error instanceof KiroUserIdentityUnavailableError
   ) return error.message;
   return "OAuth authentication failed. Check the OpenCodex account status and retry.";
 }
@@ -749,6 +754,7 @@ function merged(fresh: OAuthCredentials, previous: OAuthCredentials): OAuthCrede
   return {
     ...fresh,
     ...mergeAnthropicIdentity(fresh, previous),
+    plan: mergeOAuthPlan(fresh, previous),
     // Shared: a refresh function returns "local-cli" only when the credential it hands back
     // still is the local CLI's (Devin re-reading the CLI file, Meta Muse echoing its durable
     // CLI key). Relabelling that "oauth" would stop the next forced refresh from re-reading it.
@@ -1617,15 +1623,22 @@ export async function runLogin(
       if (!existing.accountId && !existing.email) {
         throw new OAuthReauthIdentityUnverifiedError();
       }
-      const identityMatches = existing.accountId && cred.accountId
-        ? existing.accountId === cred.accountId
-        : existing.email && cred.email
-          ? existing.email.toLowerCase() === cred.email.toLowerCase()
-          : false;
+      // A Kiro organization profile ARN is shared by its users, so it alone is not the account.
+      const identityMatches = provider === "kiro"
+        ? kiroReauthIdentityMatches(existing, cred, getAccountSet("kiro")?.accounts
+          .filter(account => account.id !== opts.reauthAccountId).map(account => account.credential))
+        : existing.accountId && cred.accountId
+          ? existing.accountId === cred.accountId
+          : existing.email && cred.email
+            ? existing.email.toLowerCase() === cred.email.toLowerCase()
+            : false;
       if (!identityMatches) {
         throw new OAuthReauthIdentityMismatchError();
       }
-      await (deps.saveAccountCredential ?? saveAccountCredential)(provider, opts.reauthAccountId, cred, {
+      // Proven same account: a reauth whose tier read failed keeps the stored label.
+      const reauthPlan = mergeOAuthPlan(cred, existing);
+      const reauthCred = reauthPlan === undefined ? cred : { ...cred, plan: reauthPlan };
+      await (deps.saveAccountCredential ?? saveAccountCredential)(provider, opts.reauthAccountId, reauthCred, {
         assertBeforePersist: deps.assertCurrentOwner,
         rotateLoginId: true,
       });
@@ -1736,10 +1749,9 @@ export interface OAuthAccountSummary {
    * version looked and upstream did not say. Omitting it would make those indistinguishable and
    * invite a consumer to assume a tier.
    *
-   * Every OAuth provider reports `null` today. Anthropic's `/api/oauth/usage` returns quota
-   * buckets only — `five_hour`, `seven_day`, the model-scoped weekly windows and `limits[]` —
-   * and carries no subscription/tier field, and its token response carries none either. See
-   * `fetchAnthropicUsageQuota` in `src/providers/quota.ts`.
+   * Reports the validated upstream tier stored with the credential. Anthropic profile reads
+   * supply the organization tier; Antigravity loadCodeAssist reads prefer paidTier to currentTier.
+   * Missing or invalid labels remain null; quota percentages never establish a subscription.
    */
   plan: string | null;
 }
@@ -1764,11 +1776,8 @@ export function getLoginStatus(provider: string, maskEmails = true): { loggedIn:
     ...(accountNeedsReauthForStatus(provider, a) ? { needsReauth: true } : {}),
     ...(a.needsReauth && a.needsReauthReason === "verify_account" ? { needsReauthReason: a.needsReauthReason } : {}),
     expiresAt: a.credential.expires,
-    // Explicitly null rather than omitted — see OAuthAccountSummary.plan. No OAuth provider
-    // exposes a subscription tier today, so there is nothing truthful to put here; deriving one
-    // from quota percentages is not possible, because they are normalized per account and a
-    // half-consumed small seat is indistinguishable from a half-consumed large one.
-    plan: null,
+    // Explicitly null rather than omitted when upstream tier metadata is unknown.
+    plan: normalizeOAuthPlan(a.credential.plan) ?? null,
   }));
 
   // A stored credential counts as "logged in" when it exists and is not marked for

package/src/oauth/kiro-account-identity.ts

@@ -0,0 +1,106 @@
+/**
+ * Kiro account identity (#6641).
+ *
+ * A Kiro profile ARN names an organization (IAM Identity Center) profile, and every user of
+ * that profile shares it, so it cannot tell two users apart. The user-level identifier OCX can
+ * observe is the email that same-session `kiro-cli whoami --format json` reports. Account
+ * identity is therefore the ARN together with that email; `accountId` keeps the ARN because
+ * request routing, rotated-session recovery and persisted evidence read it as the profile.
+ *
+ * Stored rows are never rewritten to a new key. A legacy row keeps matching the shape it was
+ * saved with, and a row that predates the email is only claimed by a login proven to be the
+ * same CLI session (identical refresh token). A login that cannot name its user keeps the legacy
+ * profile identity, but is refused rather than overwrite an identified user of that profile.
+ */
+import type { OAuthCredentials, ProviderAccount } from "./types";
+
+type KiroIdentityFields = Pick<OAuthCredentials, "accountId" | "email">;
+
+export class KiroUserIdentityUnavailableError extends Error {
+  constructor() {
+    super(
+      "Kiro CLI did not report which user is signed in, so OpenCodex cannot tell this login apart "
+        + "from the identified users of the same Kiro profile. No existing account was replaced. "
+        + "Confirm that `kiro-cli whoami` reports the signed-in user, then retry; to renew one "
+        + "account, use its Reauthenticate action.",
+    );
+    this.name = "KiroUserIdentityUnavailableError";
+  }
+}
+
+export function kiroUserEmail(credential: Pick<OAuthCredentials, "email">): string | undefined {
+  const email = credential.email?.trim().toLowerCase();
+  return email ? email : undefined;
+}
+
+/** ARN + user email when both are known; otherwise whichever one the credential carries. */
+export function kiroIdentityKey(credential: KiroIdentityFields): string | undefined {
+  const email = kiroUserEmail(credential);
+  if (credential.accountId && email) return `${credential.accountId}\n${email}`;
+  return credential.accountId ?? email;
+}
+
+function sameCliSession(account: ProviderAccount, incoming: OAuthCredentials): boolean {
+  return Boolean(incoming.refresh) && account.credential.refresh === incoming.refresh;
+}
+
+/**
+ * Pick the stored row an identity-bearing Kiro login updates, or undefined to append a new row.
+ * Throws KiroUserIdentityUnavailableError instead of guessing between identified users.
+ */
+export function findKiroAccountForLogin(
+  accounts: readonly ProviderAccount[],
+  incoming: OAuthCredentials,
+): ProviderAccount | undefined {
+  const key = kiroIdentityKey(incoming);
+  if (!key) return undefined;
+  const profileArn = incoming.accountId;
+  const sameProfile = profileArn
+    ? accounts.filter(account => account.credential.accountId === profileArn)
+    : [];
+  if (profileArn && !kiroUserEmail(incoming)) {
+    // whoami named no user. Without any identified user the profile ARN stays the identity, as it
+    // always was. Once the profile has an identified user, a profile-only match could be anyone
+    // in the organization: only the same CLI session may update a row; otherwise refuse.
+    if (sameProfile.some(account => kiroUserEmail(account.credential))) {
+      const proven = sameProfile.find(account => sameCliSession(account, incoming));
+      if (proven) return proven;
+      throw new KiroUserIdentityUnavailableError();
+    }
+  }
+  const exact = accounts.find(account => kiroIdentityKey(account.credential) === key);
+  if (exact) return exact;
+  if (profileArn && kiroUserEmail(incoming)) {
+    // A row saved before whoami named its user: only the same CLI session proves it is this user.
+    return sameProfile.find(account => !kiroUserEmail(account.credential) && sameCliSession(account, incoming));
+  }
+  return undefined;
+}
+
+/** A proven same-session update without whoami keeps the user email the row already has. */
+export function withRetainedKiroUser(incoming: OAuthCredentials, existing: OAuthCredentials): OAuthCredentials {
+  if (incoming.email || !existing.email || incoming.accountId !== existing.accountId) return incoming;
+  return { ...incoming, email: existing.email };
+}
+
+/**
+ * Reauth may refresh a slot only with the same profile AND, once known, the same user. A slot
+ * saved before its user was known is renewable only by this explicit reauth, unless the incoming
+ * user already owns another slot of the profile (then it is provably someone else).
+ */
+export function kiroReauthIdentityMatches(
+  existing: KiroIdentityFields,
+  incoming: KiroIdentityFields,
+  otherAccounts: readonly KiroIdentityFields[] = [],
+): boolean {
+  const existingEmail = kiroUserEmail(existing);
+  const incomingEmail = kiroUserEmail(incoming);
+  if (existing.accountId && incoming.accountId) {
+    if (existing.accountId !== incoming.accountId) return false;
+    if (existingEmail !== undefined) return existingEmail === incomingEmail;
+    return incomingEmail === undefined || !otherAccounts.some(other =>
+      other.accountId === incoming.accountId && kiroUserEmail(other) === incomingEmail);
+  }
+  return Boolean(existingEmail && incomingEmail && existingEmail === incomingEmail);
+}
+

package/src/oauth/kiro.ts

@@ -27,8 +27,9 @@ import {
   type KiroImportDiagnostic,
 } from "./kiro-credentials";
 import { homedir } from "node:os";
-import { getAccountSet, saveAccountCredential } from "./store";
+import { bindKiroAccountUserEmail, getAccountSet, saveAccountCredential } from "./store";
 import { KIRO_BUILDER_ID_SERVICE_PROFILE_ARN } from "../adapters/kiro-constants";
+import { kiroUserEmail } from "./kiro-account-identity";
 
 const DEFAULT_REGION = "us-east-1";
 const REFRESH_URL = "https://prod.{region}.auth.desktop.kiro.dev/refreshToken";
@@ -246,8 +247,10 @@ export function environmentKiroRoutingMetadata(): Pick<KiroOAuthMetadata, "profi
 }
 
 /**
- * Before Add-account switches the external CLI identity, bind any matching legacy identity-less
- * OCX row to the current CLI session. Unmatched identity-less rows are left alone here so a
+ * Before Add-account switches the external CLI identity, bind any matching legacy OCX row to the
+ * current CLI session: identity-less rows gain their identity, and rows keyed only by a profile
+ * ARN gain the same-session whoami user, so the user being added next is told apart from them
+ * when both share an organization profile (#6641). Unmatched rows are left alone here so a
  * cancelled browser login cannot destroy the only stored credential; after a successful add they
  * remain selectable but cannot borrow the new CLI identity (and reauth refuses identity-less slots).
  */
@@ -258,7 +261,7 @@ async function bindMatchingLegacyIdentitylessKiroAccounts(
   const set = getAccountSet("kiro");
   if (!set) return;
   const legacyAccounts = set.accounts.filter(
-    account => account.credential.accountId === undefined && account.credential.email === undefined,
+    account => account.credential.email === undefined,
   );
   if (legacyAccounts.length === 0) return;
 
@@ -275,7 +278,14 @@ async function bindMatchingLegacyIdentitylessKiroAccounts(
     if (!refresh || imported.refresh !== refresh) continue;
     const bound = await oauthCredentialFromImported(imported, runner, signal);
     if (!bound.accountId && !bound.email) continue;
-    await saveAccountCredential("kiro", account.id, bound);
+    const storedArn = account.credential.accountId;
+    if (storedArn === undefined) {
+      await saveAccountCredential("kiro", account.id, bound);
+      continue;
+    }
+    // An ARN-keyed row only gains its user; tokens, routing, plan and health stay as stored.
+    if (bound.accountId !== storedArn || !bound.email) continue;
+    await bindKiroAccountUserEmail(account.id, { profileArn: storedArn, refresh, email: bound.email });
   }
 }
 
@@ -659,10 +669,40 @@ function metadataForRotatedKiroCliCredential(
   };
 }
 
+/**
+ * Users of one organization share its profile ARN (#6641). A row that names its user adopts the
+ * local CLI session only when same-session whoami reports that user and the CLI still holds the
+ * matched session. A row without a user keeps the profile match only while no other stored Kiro
+ * row shares the profile. Cancellation propagates as cancellation, never as the refresh refusal.
+ */
+async function localKiroCliSessionBelongsToUser(
+  credential: OAuthCredentials,
+  local: ImportedKiroCredential,
+  runner: KiroCliRunner,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  const email = kiroUserEmail(credential);
+  if (!email) {
+    return !(getAccountSet("kiro")?.accounts ?? []).some(account =>
+      account.credential.refresh !== credential.refresh && account.credential.accountId === local.profileArn);
+  }
+  const identity = await readKiroCliIdentity(runner, signal);
+  signal?.throwIfAborted();
+  if (identity.email !== email) return false;
+  let current: ImportedKiroCredential | null;
+  try {
+    current = readKiroCliSqliteCredential();
+  } catch {
+    return false;
+  }
+  return current !== null && (current.refresh || current.access) === (local.refresh || local.access);
+}
+
 export async function refreshKiroToken(
   refresh: string,
   signal?: AbortSignal,
   credential?: OAuthCredentials,
+  options: { cliRunner?: KiroCliRunner } = {},
 ): Promise<OAuthCredentials> {
   if (!refresh) throw new Error("Kiro: no refresh token available (re-run `kiro-cli login`).");
   try {
@@ -672,6 +712,9 @@ export async function refreshKiroToken(
     if (!credential) throw error;
     const local = matchingRotatedKiroCliCredential(refresh, credential);
     if (!local) throw error;
+    if (!await localKiroCliSessionBelongsToUser(credential, local, options.cliRunner ?? defaultKiroCliRunner, signal)) {
+      throw error;
+    }
     const retryMetadata = metadataForRotatedKiroCliCredential(credential, local);
     try {
       const fresh = await refreshAwsSsoOidcToken(local.refresh, signal, {

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

@@ -6,7 +6,7 @@
  * resulting account token into the `LLM|` Model API key our request path sends as a
  * bearer.
  *
- * Protocol source: devlog/_plan/260912_muse_device_oauth/001_reference_measurements.md.
+ * Protocol source: devlog/_fin/260912_muse_device_oauth/001_reference_measurements.md.
  * It is second-party, not vendor documentation, so every response is parsed defensively
  * and every failure names a kind instead of throwing a bare string.
  *

package/src/oauth/plan.ts

@@ -0,0 +1,29 @@
+import type { OAuthCredentials } from "./types";
+
+/** Display-only upstream tier; never infer a plan from normalized quota percentages. */
+export function normalizeOAuthPlan(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const plan = value.trim();
+  return plan.length <= 64 && /^[a-z0-9_.-]+$/.test(plan) ? plan : undefined;
+}
+
+/**
+ * Same account by the strongest identifier both credentials carry, compared kind for kind
+ * (Anthropic UUID, then accountId, then case-insensitive email); undefined when none overlap.
+ */
+function sameAccount(a: OAuthCredentials, b: OAuthCredentials): boolean | undefined {
+  const pairs: Array<[string | undefined, string | undefined]> = [
+    [a.anthropicIdentity?.accountUuid, b.anthropicIdentity?.accountUuid],
+    [a.accountId, b.accountId],
+    [a.email?.toLowerCase(), b.email?.toLowerCase()],
+  ];
+  for (const [left, right] of pairs) if (left !== undefined && right !== undefined) return left === right;
+  return undefined;
+}
+
+/** An observed unknown clears old metadata; an account replacement cannot inherit a plan. */
+export function mergeOAuthPlan(fresh: OAuthCredentials, previous: OAuthCredentials): string | null | undefined {
+  if (fresh.plan !== undefined) return normalizeOAuthPlan(fresh.plan) ?? null;
+  if (sameAccount(fresh, previous) === false) return undefined;
+  return previous.plan === null ? null : normalizeOAuthPlan(previous.plan);
+}

package/src/oauth/store.ts

@@ -19,7 +19,9 @@
  *   distinct one. Kimi extracts JWT `user_id`/`sub` as accountId; Cursor extracts JWT `sub` —
  *   both append distinct identified accounts under multiauth.
  */
+import { normalizeOAuthPlan, mergeOAuthPlan } from "./plan";
 import { normalizeAnthropicIdentity, matchesAnthropicImport, mergeAnthropicIdentity } from "./anthropic-identity";
+import { findKiroAccountForLogin, withRetainedKiroUser } from "./kiro-account-identity";
 import { isAnthropicInstanceId, type AnthropicInstanceId } from "../providers/anthropic-instance-id";
 import { assertNoCrossAnthropicRegistration, assertAnthropicCredentialSource, assertAnthropicInstanceLoginConfig } from "./store-anthropic-instance";
 import { createHash, randomUUID } from "node:crypto";
@@ -537,6 +539,7 @@ function normalizeCredential(cred: unknown): OAuthCredentials | null {
   if (typeof candidate.accountId === "string" && candidate.accountId.length > 0) normalized.accountId = candidate.accountId;
   const identity = normalizeAnthropicIdentity(candidate.anthropicIdentity, candidate.access);
   if (identity) normalized.anthropicIdentity = identity;
+  if (candidate.plan !== undefined) normalized.plan = normalizeOAuthPlan(candidate.plan) ?? null;
   if (isCredentialSource(candidate.source)) normalized.source = candidate.source;
   if (typeof candidate.projectId === "string" && candidate.projectId.length > 0) normalized.projectId = candidate.projectId;
   if (typeof candidate.apiBaseUrl === "string" && candidate.apiBaseUrl.length > 0) {
@@ -905,6 +908,7 @@ export async function saveCredentialWithReceipt(
       const existing = set.accounts.find(a => matchesAnthropicImport(a.credential, safe));
       if (existing) {
         existing.credential = { ...safe, ...mergeAnthropicIdentity(safe, existing.credential),
+          plan: mergeOAuthPlan(safe, existing.credential),
           accountId: safe.accountId ?? existing.credential.accountId, email: safe.email ?? existing.credential.email };
         set.selectionRevision = previousSelectionRevision;
         delete existing.needsReauth;
@@ -918,9 +922,17 @@ export async function saveCredentialWithReceipt(
         accountId = id;
       }
     } else if (identity) {
-      const existing = set.accounts.find(a => (a.credential.accountId ?? a.credential.email) === identity);
+      // Kiro: a shared organization profile ARN is not a user, so its identity also carries the
+      // same-session whoami email (#6641); the helper never guesses between identified users.
+      const existing = provider === "kiro"
+        ? findKiroAccountForLogin(set.accounts, safe)
+        : set.accounts.find(a => (a.credential.accountId ?? a.credential.email) === identity);
       if (existing) {
-        existing.credential = safe;
+        const incoming = provider === "kiro" ? withRetainedKiroUser(safe, existing.credential) : safe;
+        // Same identity: a login whose tier read failed keeps the stored label (plan absent),
+        // while an observed unknown (plan null) still clears it.
+        const plan = mergeOAuthPlan(incoming, existing.credential);
+        existing.credential = plan === undefined ? incoming : { ...incoming, plan };
         delete existing.needsReauth;
         delete existing.needsReauthReason;
         delete existing.refreshAttentionGeneration;
@@ -932,7 +944,13 @@ export async function saveCredentialWithReceipt(
         // active identity-less row in place prevents a stale duplicate that stays selectable
         // and would re-refresh into a second row with the same identity.
         const active = set.accounts.find(a => a.id === set.activeAccountId);
-        if (!opts.preserveIdentityless && active && active.credential.accountId === undefined && active.credential.email === undefined) {
+        // Kiro rows of one organization differ only by user: while another row shares the profile,
+        // an unmatched Kiro login claims an identity-less slot only as the same CLI session (#6641).
+        const legacyUpgrade = active !== undefined && active.credential.accountId === undefined
+          && active.credential.email === undefined
+          && (provider !== "kiro" || (Boolean(safe.refresh) && active.credential.refresh === safe.refresh)
+            || !set.accounts.some(a => safe.accountId !== undefined && a.credential.accountId === safe.accountId));
+        if (!opts.preserveIdentityless && active && legacyUpgrade) {
           active.credential = safe;
           delete active.needsReauth;
           delete active.needsReauthReason;
@@ -1014,6 +1032,25 @@ export async function saveCredential(
   await saveCredentialWithReceipt(provider, cred, opts);
 }
 
+/**
+ * Record the same-session whoami user on a Kiro row saved before whoami named it (#6641).
+ * Applies only while the row still holds the proven session's refresh token and profile ARN
+ * and has no user yet; tokens, routing, plan and health are left exactly as stored.
+ */
+export async function bindKiroAccountUserEmail(
+  accountId: string,
+  proof: { profileArn: string; refresh: string; email: string },
+): Promise<boolean> {
+  return await mutateStore(store => {
+    const account = store.kiro?.accounts.find(candidate => candidate.id === accountId);
+    const credential = account?.credential;
+    if (!credential || credential.email !== undefined) return false;
+    if (credential.accountId !== proof.profileArn || credential.refresh !== proof.refresh) return false;
+    credential.email = proof.email;
+    return true;
+  }, [accountId, proof]);
+}
+
 /** Native device approval always gets a new slot; no unverified identity can replace one. */
 export async function appendKiroAccountFromDeviceLogin(
   cred: OAuthCredentials,

package/src/oauth/types.ts

@@ -30,7 +30,7 @@ export interface KiroOAuthMetadata {
  *
  * The Model API is authenticated by the `LLM|` key in `access`; this token authenticates
  * the Meta ACCOUNT and exists only to mint that key and to read subscription usage
- * (devlog/_plan/260912_muse_device_oauth/002 A). Keeping it out of `access` is what lets
+ * (devlog/_fin/260912_muse_device_oauth/002 A). Keeping it out of `access` is what lets
  * every request path stay unchanged.
  *
  * It must never be added to `OAuthAccountSummary` (src/oauth/index.ts:1803) or to
@@ -62,6 +62,8 @@ export type OAuthCredentials = {
   email?: string;
   accountId?: string;
   source?: OAuthCredentialSource;
+  /** Validated upstream subscription label; null is an observed unknown, absent is not read. */
+  plan?: string | null;
   /** Private authenticated account proof; never projected into account summaries. */
   anthropicIdentity?: { v: 1; accountUuid: string; bearerSha256: string };
   /** Google Antigravity (Cloud Code Assist) discovered project id; injected into the CCA envelope. */

package/src/plugins/loader.ts

@@ -121,8 +121,19 @@ export function macAclProbeTrustError(probe: () => MacAclProbeResult): string |
   }
 }
 
+let pluginAclInspectorForTests: ((path: string) => string | null) | undefined;
+
+/**
+ * Shipped mutable seam, test-only by intent: no config or env path reaches it.
+ * Passing undefined restores the real ACL inspector.
+ */
+export function setPluginAclInspectorForTests(inspector?: (path: string) => string | null): void {
+  pluginAclInspectorForTests = inspector;
+}
+
 /** Refuse extended ACLs: mode bits alone cannot prove who can rewrite a plugin path. */
 function aclTrustError(path: string): string | null {
+  if (pluginAclInspectorForTests) return pluginAclInspectorForTests(path);
   if (process.platform !== "darwin" && process.platform !== "linux") return null;
   const mac = process.platform === "darwin";
   // CI and operator PATHs may put GNU coreutils ahead of the macOS tool.

package/src/providers/anthropic-billing-ownership.ts

@@ -0,0 +1,74 @@
+import type { OcxProviderConfig } from "../types";
+import { resolveAnthropicMessagesUrl } from "../adapters/anthropic";
+import { providerApiKeySelectionIsCurrent } from "./api-key-selection";
+import { hasKeyPoolFailover } from "./key-failover";
+import type { OcxConfig } from "../types";
+import { registerProviderResponseProvenance } from "./request-pacing";
+import { isEgressTransparentExecutor, markEgressTransparentExecutor } from "../lib/provider-egress";
+
+interface BillingSendOwnership {
+  readonly providerName: string;
+  readonly provider: OcxProviderConfig;
+  readonly target: string;
+}
+const responseOwners = new WeakMap<Response, BillingSendOwnership | null>();
+registerProviderResponseProvenance(responseOwners);
+
+/** Runs inside connection policy, after plugin/header rewrites, at the physical fetch. */
+export function anthropicBillingPhysicalFetch(
+  physicalFetch: typeof globalThis.fetch,
+  providerName: string,
+  provider: OcxProviderConfig,
+): typeof globalThis.fetch {
+  const wrapped = (async (input, init) => {
+    const target = input instanceof Request ? input.url : String(input);
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    const selection = provider._apiKeyAttempt;
+    const ownsCredential = provider.apiKeyTransport === "bearer"
+      ? headers.get("authorization") === `Bearer ${provider.apiKey}` && !headers.has("x-api-key")
+      : headers.get("x-api-key") === provider.apiKey && !headers.has("authorization");
+    const ownsKey = provider.adapter === "anthropic" && (provider.authMode === undefined || provider.authMode === "key")
+      && hasKeyPoolFailover(provider) && selection !== undefined && provider.apiKey !== undefined
+      && ownsCredential
+      && target === resolveAnthropicMessagesUrl(provider);
+    const owner: BillingSendOwnership | null = ownsKey ? Object.freeze({
+      providerName, target,
+      provider: Object.freeze({ ...provider,
+        _apiKeyAttempt: Object.freeze({ ...selection }),
+        headers: Object.freeze({ ...provider.headers }),
+        apiKeyPool: provider.apiKeyPool?.map(entry => Object.freeze({ ...entry })),
+      }),
+    }) : null;
+    // No await between capturing the selected credential and invoking the actual send.
+    const response = await physicalFetch(input, init);
+    // An executor reusing a Response across physical sends cannot assign it two owners.
+    responseOwners.set(response, responseOwners.has(response) ? null : owner);
+    return response;
+  }) as typeof globalThis.fetch;
+  return isEgressTransparentExecutor(physicalFetch) ? markEgressTransparentExecutor(wrapped) : wrapped;
+}
+
+/** Immutable response ownership, matched to the attempted route and still-current selection. */
+export function anthropicBillingResponseOwner(
+  response: Response, config: OcxConfig, providerName: string, attemptedProvider: OcxProviderConfig,
+): OcxProviderConfig | null {
+  const owner = responseOwners.get(response);
+  if (!owner || owner.providerName !== providerName || owner.target !== resolveAnthropicMessagesUrl(attemptedProvider)) return null;
+  const sent = owner.provider;
+  const current = config.providers[providerName];
+  if (!current || current.adapter !== sent.adapter || current.adapter !== "anthropic"
+    || (current.authMode !== undefined && current.authMode !== "key") || !hasKeyPoolFailover(current)) return null;
+  const sentTransport = sent.apiKeyTransport ?? "x-api-key";
+  if ((current.apiKeyTransport ?? "x-api-key") !== sentTransport
+    || (attemptedProvider.apiKeyTransport ?? "x-api-key") !== sentTransport) return null;
+  // Configured headers can change billing/account ownership independently of key selection.
+  const headerShape = (provider: OcxProviderConfig) => JSON.stringify(Object.entries(provider.headers ?? {}).sort(([a], [b]) => a.localeCompare(b)));
+  if (headerShape(current) !== headerShape(sent)) return null;
+  const attempted = attemptedProvider._apiKeyAttempt;
+  if (!attempted || attemptedProvider.apiKey !== sent.apiKey || attemptedProvider.baseUrl !== sent.baseUrl
+    || attemptedProvider.authMode !== sent.authMode || attemptedProvider.adapter !== sent.adapter
+    || attempted.entryId !== sent._apiKeyAttempt?.entryId || attempted.reference !== sent._apiKeyAttempt?.reference
+    || attempted.revision !== sent._apiKeyAttempt?.revision
+    || !providerApiKeySelectionIsCurrent(config, providerName, sent)) return null;
+  return sent;
+}

package/src/providers/anthropic-billing-recovery.ts

@@ -0,0 +1,31 @@
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { isNonReplayableResponse } from "../lib/upstream-retry";
+import { anthropicBillingResponseOwner } from "./anthropic-billing-ownership";
+import { readAnthropicBillingRefusal } from "./anthropic-billing-refusal";
+import { hasKeyPoolFailover, rotateProviderTransportOnAnthropicBilling } from "./key-failover";
+import type { OcxProviderTransport } from "./xai-transport";
+
+/**
+ * Whether a provider can recover a credit-balance refusal by key rotation. This is an
+ * eligibility predicate for send accounting, not a recovery site: the one billing recovery
+ * loop in adapter-dispatch.ts keeps its own `hasKeyPoolFailover` guard.
+ */
+export function isAnthropicBillingKeyPool(provider: OcxProviderConfig): boolean {
+  return provider.adapter === "anthropic" && hasKeyPoolFailover(provider);
+}
+
+/** Pre-output billing recovery cools the refused key for the credit-balance window. */
+export async function rotateAnthropicBillingKeyOnResponse(
+  response: Response, config: OcxConfig, providerName: string, attemptedProvider: OcxProviderConfig,
+  options: { signal?: AbortSignal; promptCacheKey?: string } = {},
+): Promise<OcxProviderTransport | null> {
+  if (options.signal?.aborted || isNonReplayableResponse(response)
+    || !anthropicBillingResponseOwner(response, config, providerName, attemptedProvider)) return null;
+  if (!await readAnthropicBillingRefusal(response, options.signal) || options.signal?.aborted) return null;
+  // Reading is asynchronous: fence a late refusal against manual selection or key replacement.
+  const owner = anthropicBillingResponseOwner(response, config, providerName, attemptedProvider);
+  if (!owner) return null;
+  return rotateProviderTransportOnAnthropicBilling(config, providerName, owner, {
+    attemptedKey: owner.apiKey, attemptedSelection: owner._apiKeyAttempt, promptCacheKey: options.promptCacheKey,
+  });
+}

package/src/providers/anthropic-billing-refusal.ts

@@ -0,0 +1,55 @@
+/** Pure credit-balance evidence, independent of OAuth account routing. */
+import { readBoundedResponseBody } from "../lib/bounded-body";
+const MAX_BILLING_REFUSAL_BYTES = 8 * 1024;
+const BILLING_REFUSAL_DEADLINE_MS = 250;
+// Keep the whole-message credit-balance pattern used by anthropic-account-refusal.
+const CREDIT_BALANCE_REFUSAL = /^Your credit balance is too low to access the Anthropic API\.(?: Please go to Plans & Billing to upgrade or purchase credits\.)?$/i;
+const BILLING_ERROR_TYPES = new Set(["invalid_request_error", "billing_error", "permission_error"]);
+const ACCOUNT_REFUSAL_CODES = new Set(["subscription_required", "insufficient_quota", "permission_denied"]);
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Only an Anthropic error envelope with exact billing wording is evidence. */
+export function isAnthropicBillingRefusal(status: number, payload: unknown): boolean {
+  if (status !== 400 && status !== 402) return false;
+  if (!record(payload) || payload.type !== "error" || !record(payload.error)) return false;
+  const error = payload.error;
+  if (typeof error.type !== "string" || !BILLING_ERROR_TYPES.has(error.type)
+    || typeof error.message !== "string" || Buffer.byteLength(error.message, "utf8") > MAX_BILLING_REFUSAL_BYTES) return false;
+  if (error.code != null && (typeof error.code !== "string" || !ACCOUNT_REFUSAL_CODES.has(error.code))) return false;
+  return CREDIT_BALANCE_REFUSAL.test(error.message.trim());
+}
+
+/** Bounded combo evidence after existing HTTP error formatting, before any output. */
+export function isAnthropicBillingFailure(status: number, message: string, code?: string | null): boolean {
+  if (status !== 400 && status !== 402 || Buffer.byteLength(message, "utf8") > MAX_BILLING_REFUSAL_BYTES) return false;
+  if (code != null && !BILLING_ERROR_TYPES.has(code) && !ACCOUNT_REFUSAL_CODES.has(code)) return false;
+  let text = message.trim();
+  const prefix = `Provider error ${status}: `;
+  if (text.startsWith(prefix)) text = text.slice(prefix.length);
+  try { return isAnthropicBillingRefusal(status, JSON.parse(text)); } catch { /* Exact prose needs a structured type. */ }
+  return typeof code === "string" && BILLING_ERROR_TYPES.has(code)
+    && isAnthropicBillingRefusal(status, { type: "error", error: { type: code, message: text } });
+}
+
+/** Inspect a clone, never the terminal body; the shared reader owns interruption/cleanup. */
+export async function readAnthropicBillingRefusal(response: Response, signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted || (response.status !== 400 && response.status !== 402)) return false;
+  const contentType = response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
+  if (!contentType || !/^application\/(?:json|[a-z0-9.+-]+\+json)$/.test(contentType)) return false;
+  try {
+    const deadline = AbortSignal.timeout(BILLING_REFUSAL_DEADLINE_MS);
+    const body = await readBoundedResponseBody(response.clone(), {
+      signal: signal ? AbortSignal.any([signal, deadline]) : deadline,
+      maxBytes: MAX_BILLING_REFUSAL_BYTES, fatalUtf8: true,
+      totalTimeoutMs: BILLING_REFUSAL_DEADLINE_MS,
+    });
+    if (signal?.aborted || !body.displaySafe || body.truncated || body.timedOut || body.oversized) return false;
+    return isAnthropicBillingRefusal(response.status, JSON.parse(body.text));
+  } catch {
+    // Untrusted malformed, unreadable and invalid UTF-8 bodies confer no authority.
+    return false;
+  }
+}

package/src/providers/anthropic-fast.ts

@@ -12,7 +12,7 @@
  * account rate limit and must keep flowing into the existing wait/rotation handling, so only an
  * error message that names fast mode or the speed parameter, or a fast-pool header reporting
  * zero remaining, counts. Live probe strings (2026-09-23,
- * devlog/_plan/260923_anthropic_fast_speed/020_probe-evidence.md):
+ * devlog/_fin/260923_anthropic_fast_speed/020_probe-evidence.md):
  *   429 "Usage credits are required for fast mode."
  *   400 "Fast mode is not enabled for your organization. ..."
  *   400 "'<model>' does not support the `speed` parameter. ..."