Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat(credentials): tell a credential that failed apart from one that is absent

Jack Rudenko712728762cca
diff --git a/packages/cli/src/auth/credentials/antigravity-credential.ts b/packages/cli/src/auth/credentials/antigravity-credential.ts
index 9fe94e2c..c620f205 100644
--- a/packages/cli/src/auth/credentials/antigravity-credential.ts
+++ b/packages/cli/src/auth/credentials/antigravity-credential.ts
@@ -31,7 +31,13 @@ import {
getServedAntigravityModels,
setupAntigravityUser,
} from "../antigravity-user.js";
-import type { CredentialProvider, RequestAuth, RequestAuthContext } from "./types.js";
+import type {
+ CredentialProvider,
+ ReadinessResult,
+ RequestAuth,
+ RequestAuthContext,
+} from "./types.js";
+import { readinessDetail } from "./types.js";
/** Generate a short random request ID (matches the Antigravity CLI activity logger). */
function createActivityRequestId(): string {
@@ -42,18 +48,37 @@ export class AntigravityCredentialProvider implements CredentialProvider {
readonly catalogName = "antigravity";
/**
- * Available when a shared Antigravity token exists in the keychain. Never
- * throws (a non-macOS platform or an absent store resolves to false), matching
- * the authority's "readiness never brings down the caller" contract.
+ * Available when a shared Antigravity token exists in the keychain.
+ *
+ * A non-macOS platform or an empty store is `absent` — the normal state for
+ * anyone not signed in to Antigravity. A store read that THREW is `failed`:
+ * nothing was learned, and reporting it as absence is what silently replaces
+ * a subscription with a metered provider.
+ *
+ * KNOWN RESIDUAL, declared rather than papered over: `defaultReadStore` in
+ * `auth/antigravity-token.ts` swallows its own `security` failure into `null`,
+ * so a LOCKED keychain still arrives here as `absent`. Closing that means
+ * changing the shared agy/claudish token path's contract — the same change
+ * `architecture/keychain.md` already parks as deserving its own commit. This
+ * method reports honestly for everything that reaches it; the gap is one
+ * level down, not here.
*/
- async isAvailable(): Promise<boolean> {
+ async describeReadiness(): Promise<ReadinessResult> {
try {
- return readSharedAntigravityToken() !== null;
- } catch {
- return false;
+ return { readiness: readSharedAntigravityToken() !== null ? "present" : "absent" };
+ } catch (err) {
+ return {
+ readiness: "failed",
+ detail: `Antigravity token store could not be read: ${readinessDetail(err) ?? "unknown error"}`,
+ };
}
}
+ /** Unchanged contract: the `=== "present"` projection of the above. */
+ async isAvailable(): Promise<boolean> {
+ return (await this.describeReadiness()).readiness === "present";
+ }
+
async getRequestAuth(ctx: RequestAuthContext): Promise<RequestAuth> {
const token = await getValidAntigravityAccessToken();
const { projectId, tierId } = await setupAntigravityUser(token);
diff --git a/packages/cli/src/auth/credentials/api-key-credential.ts b/packages/cli/src/auth/credentials/api-key-credential.ts
index a0167ad9..261dc84c 100644
--- a/packages/cli/src/auth/credentials/api-key-credential.ts
+++ b/packages/cli/src/auth/credentials/api-key-credential.ts
@@ -19,7 +19,17 @@
* SDK or the keychain. The authority is the ONLY code that pushes keys from
* either vault into process.env.
*
- * `isAvailable()` additionally honors one affordance the legacy oracle granted:
+ * `describeReadiness()` reports `present` / `absent` / `failed`, and
+ * `isAvailable()` is its `=== "present"` projection. Steps 4 and 5 are the two
+ * measured ways a REAL credential resolves to nothing — a locked or declined
+ * keychain, a denied 1Password handshake — and both used to arrive here as a
+ * bare `""`, indistinguishable from "this user has no key". That is what let a
+ * flat-rate subscription be dropped from the routing chain and replaced by a
+ * metered provider with nothing printed. The reason now survives; what routing
+ * DOES with it is unchanged, since `failed` still projects to unavailable.
+ *
+ * `describeReadiness()` additionally honors one affordance the legacy oracle
+ * granted:
* - `oauthFallback`: a `<file>` under ~/.claudish/ — if that OAuth credential
* file exists, the provider is available even without an env/config/op key.
*
@@ -45,7 +55,27 @@ import {
} from "./keychain-source.js";
import { resolveLocalApiKey } from "./local-api-key.js";
import { hasOpSources, resolveOpKeyForEnvVars } from "./op-source.js";
-import type { CredentialProvider, RequestAuth, RequestAuthContext } from "./types.js";
+import type {
+ CredentialProvider,
+ ReadinessResult,
+ RequestAuth,
+ RequestAuthContext,
+} from "./types.js";
+
+/**
+ * The outcome of one async key resolution: the key (possibly ""), plus WHY it
+ * is empty when a credential STORE could not be consulted.
+ *
+ * `failure` is set only for "could not ask" — a keychain that would not answer,
+ * a 1Password handshake that was denied or unavailable. It is deliberately NOT
+ * set for "every source answered and none holds this key", which is an ordinary,
+ * stable `absent` and must stay one: marking that `failed` would make every
+ * provider the user has not configured report an error.
+ */
+interface KeyResolution {
+ key: string;
+ failure?: string;
+}
export interface ApiKeyDescriptor {
catalogName: string;
@@ -113,8 +143,16 @@ export class ApiKeyCredentialProvider implements CredentialProvider {
/** Memoized resolved key ("" = resolved-and-empty). undefined = not yet resolved. */
private cachedKey: string | undefined;
- /** In-flight resolution, so concurrent callers share one op pull. */
- private resolving: Promise<string> | undefined;
+ /**
+ * In-flight resolution, so concurrent callers share one op pull.
+ *
+ * It carries the FAILURE alongside the key rather than leaving the reason in
+ * an instance field: several callers share one resolution (a bare model name
+ * credential-filters a whole chain, and the config TUI resolves ~16 providers
+ * at once), so a field would be read by whichever caller happened to land
+ * after the next resolution had already overwritten it.
+ */
+ private resolving: Promise<KeyResolution> | undefined;
constructor(descriptor: ApiKeyDescriptor) {
this.catalogName = descriptor.catalogName;
@@ -170,19 +208,42 @@ export class ApiKeyCredentialProvider implements CredentialProvider {
* THROUGH to process.env so spawned children inherit it.
*/
private async resolveKey(opts?: { allowOpPrompt?: boolean }): Promise<string> {
- if (this.cachedKey !== undefined) return this.cachedKey;
+ return (await this.resolveKeyDetailed(opts)).key;
+ }
+
+ /**
+ * The same resolution, keeping the REASON an empty result is empty.
+ *
+ * Both vault steps below can come back with nothing for two different
+ * reasons, and the old `Promise<string>` had one slot for both. "The keychain
+ * is locked" and "there is no item for this variable" arrived as the same
+ * `""`, so `isAvailable()` reported a subscriber with a perfectly good key as
+ * uncredentialed, routing dropped the provider, and a metered vendor served
+ * the request. The stores already distinguish the two — `{value?, failed}`
+ * from the keychain, and now `onFailure` from the op source — so this method
+ * carries the distinction up instead of flattening it.
+ *
+ * The failure is reported WITHOUT ever being cached: transience is the whole
+ * point, and the existing "do not memoize a miss that might have been a
+ * failure" rules below are what make the next call retry.
+ */
+ private async resolveKeyDetailed(opts?: { allowOpPrompt?: boolean }): Promise<KeyResolution> {
+ // A cached key is a SETTLED answer — either a real value or a stable,
+ // deliberately-memoized absence. Neither carries a failure, because the
+ // rules below refuse to cache anything that might have been one.
+ if (this.cachedKey !== undefined) return { key: this.cachedKey };
if (this.resolving) return this.resolving;
- this.resolving = (async () => {
+ this.resolving = (async (): Promise<KeyResolution> => {
// Steps 1-3: env / aliases / config — no SDK.
const local = this.resolveFromEnvConfig();
if (local) {
this.cachedKey = local;
- return local;
+ return { key: local };
}
// Step 4: macOS Keychain, only if the backend is on (the sync sniff gates
// the `security` spawn). Local and quiet, so it is tried before 1Password.
- let keychainFailed = false;
+ let keychainFailure: string | undefined;
if (hasKeychainSource()) {
const kc = resolveKeychainKeyForEnvVars([this.envVar, ...this.aliases]);
if (kc.value) {
@@ -191,20 +252,32 @@ export class ApiKeyCredentialProvider implements CredentialProvider {
process.env[this.envVar] = kc.value;
recordKeychainHydratedVar(this.envVar);
this.cachedKey = kc.value;
- return kc.value;
+ return { key: kc.value };
}
// A keychain MISS is stable (the item is genuinely absent) and may be
// cached below. A keychain FAILURE — locked, or a declined ACL — is
// transient and must not be, or one early stumble would mark this
// provider unavailable for the rest of the process.
- keychainFailed = kc.failed;
+ if (kc.failed) {
+ keychainFailure = kc.error
+ ? `macOS Keychain could not be read: ${kc.error}`
+ : "macOS Keychain could not be read";
+ }
}
// Step 5: 1Password, only if a source exists (the sync sniff gates the SDK).
if (hasOpSources()) {
const wanted = new Set<string>([this.envVar, ...this.aliases]);
+ // Capture the first swallowed reason. `onAuthFailure:"skip"` is right —
+ // a credential backend having a bad day must not take down an MCP or
+ // serve process — but skipping the ERROR is not the same as skipping
+ // the exception, and this is where the two were conflated.
+ let opFailure: string | undefined;
const resolved = await resolveOpKeyForEnvVars(wanted, {
onAuthFailure: "skip",
allowPrompt: opts?.allowOpPrompt ?? false,
+ onFailure: (reason) => {
+ opFailure ??= reason;
+ },
});
const value =
resolved[this.envVar] ?? this.aliases.map((a) => resolved[a]).find((v) => !!v);
@@ -212,21 +285,26 @@ export class ApiKeyCredentialProvider implements CredentialProvider {
// Write-through mirror: child processes inherit this, no re-resolve.
process.env[this.envVar] = value;
this.cachedKey = value;
- return value;
+ return { key: value };
}
// op source EXISTS but resolution came back empty — this can be a
// TRANSIENT op-auth failure (onAuthFailure:"skip" swallows it). Do NOT
// cache the miss, or a single early failure would mark the provider
// permanently unavailable. Return "" WITHOUT caching so the next call
// retries (e.g. once the 1Password desktop handshake completes).
- return "";
+ //
+ // The keychain failure is reported only when 1Password did not fail
+ // too: one reason is a remedy the user can act on, two are a list to
+ // triage. 1Password wins because it is the step that actually answered
+ // last for this key.
+ return { key: "", failure: opFailure ?? keychainFailure };
}
// No op source at all → the empty result is stable and safe to cache,
// UNLESS the keychain step above failed rather than simply missing: that
// failure is transient, so leave the result uncached and let the next
// call retry once the keychain is unlocked.
- if (!keychainFailed) this.cachedKey = "";
- return "";
+ if (!keychainFailure) this.cachedKey = "";
+ return { key: "", failure: keychainFailure };
})();
try {
@@ -236,17 +314,35 @@ export class ApiKeyCredentialProvider implements CredentialProvider {
}
}
- async isAvailable(opts?: { allowOpPrompt?: boolean }): Promise<boolean> {
+ /**
+ * Three-valued readiness. `isAvailable()` below is its `=== "present"`
+ * projection, so the two cannot disagree about whether this provider routes.
+ *
+ * The ORDER of the cheap checks is the same as it always was, and it matters
+ * for more than speed: a key already in env/config, or an oauth file on disk,
+ * makes the provider `present` without ever touching a vault — so a broken
+ * keychain or a denied 1Password cannot downgrade a provider that was never
+ * going to ask them.
+ */
+ async describeReadiness(opts?: { allowOpPrompt?: boolean }): Promise<ReadinessResult> {
// A provider that takes no credential is always available. Checked FIRST and
// before any resolution, because there is nothing to resolve: reaching the
// env/config/oauth/1Password chain for it would be pure cost, and on the
// 1Password step a real prompt for a key that does not exist.
- if (this.authScheme === "none") return true;
+ if (this.authScheme === "none") return { readiness: "present" };
// Cheap checks first — avoid the op pull when an oauth file already qualifies.
- if (this.resolveFromEnvConfig()) return true;
- if (this.hasOauthFallbackFile()) return true;
- const key = await this.resolveKey(opts);
- return !!key;
+ if (this.resolveFromEnvConfig()) return { readiness: "present" };
+ if (this.hasOauthFallbackFile()) return { readiness: "present" };
+ const { key, failure } = await this.resolveKeyDetailed(opts);
+ if (key) return { readiness: "present" };
+ // No key AND no failure means every store answered and none holds one —
+ // which is the ordinary state of every provider the user has not set up,
+ // and must stay `absent`.
+ return failure ? { readiness: "failed", detail: failure } : { readiness: "absent" };
+ }
+
+ async isAvailable(opts?: { allowOpPrompt?: boolean }): Promise<boolean> {
+ return (await this.describeReadiness(opts)).readiness === "present";
}
invalidate(): void {
diff --git a/packages/cli/src/auth/credentials/authority.ts b/packages/cli/src/auth/credentials/authority.ts
index 7be921bb..b3391c54 100644
--- a/packages/cli/src/auth/credentials/authority.ts
+++ b/packages/cli/src/auth/credentials/authority.ts
@@ -22,9 +22,24 @@ import { GrokSubscriptionCredentialProvider } from "./grok-credential.js";
import { makeKimiCodingCredential, makeKimiCredential } from "./kimi-credential.js";
import { LocalCredentialProvider } from "./local-credential.js";
import { NativeAnthropicCredentialProvider } from "./native-anthropic-credential.js";
-import type { CredentialProvider, RequestAuth, RequestAuthContext } from "./types.js";
+import type {
+ CredentialProvider,
+ ReadinessResult,
+ RequestAuth,
+ RequestAuthContext,
+} from "./types.js";
+import { readinessDetail } from "./types.js";
import { VertexCredentialProvider } from "./vertex-credential.js";
+/**
+ * Re-exported from `types.js`, which is where the interface that carries them
+ * lives. The authority is the documented home of the readiness vocabulary, so
+ * consumers import it from here and never have to know which of the two files
+ * declares it.
+ */
+export type { CredentialReadiness, ReadinessResult } from "./types.js";
+export { readinessDetail } from "./types.js";
+
/** Built-in local provider names that get a LocalCredentialProvider. */
const LOCAL_PROVIDER_NAMES = ["ollama", "lmstudio", "vllm", "mlx"];
@@ -100,19 +115,67 @@ export class CredentialAuthority {
);
}
+ /**
+ * ASYNC readiness, THREE-VALUED: resolves env → config → oauth-file →
+ * keychain → op:// (both lazy) and reports `present` / `absent` / `failed`.
+ *
+ * This method exists because `isAvailable` had exactly one slot for two facts
+ * and the old `catch { return false }` here put both in it. Every resolution
+ * failure — a denied 1Password handshake and its 15-second machine-wide
+ * suppression, a locked Mac, a keychain ACL the user declined, a `security`
+ * binary that is not there — became indistinguishable from "this user has no
+ * key for this provider". Downstream, `hasCredentialsForProvider`
+ * (routing-rules.ts) drops such a candidate from the routing chain, so a
+ * flat-rate subscription the user DOES hold was silently replaced by a
+ * metered provider and billed per token, with nothing printed.
+ *
+ * Three things make the third value REACHABLE rather than decorative, since
+ * no production source throws:
+ * - a provider may implement `describeReadiness()` itself and report
+ * `failed` from a propagated flag — `ApiKeyCredentialProvider` does this
+ * for the keychain's `{value?, failed}` and for an op resolve whose
+ * failure `onAuthFailure:"skip"` swallowed;
+ * - `CompositeCredentialProvider` forwards a half's `failed` instead of
+ * flattening it to a boolean;
+ * - a source that DOES throw is caught here and reported as `failed`.
+ *
+ * Never throws. An unknown provider is genuinely `absent` — nothing was
+ * consulted, so there is no failure to report.
+ */
+ async describeReadiness(
+ name: string,
+ opts?: { allowOpPrompt?: boolean }
+ ): Promise<ReadinessResult> {
+ const provider = this.registry.get(name);
+ if (!provider) return { readiness: "absent" };
+ try {
+ if (provider.describeReadiness) {
+ // A provider is allowed to be sloppy about its return; a missing verdict
+ // must not become `undefined.readiness` at a call site that reads it.
+ return (await provider.describeReadiness(opts)) ?? { readiness: "absent" };
+ }
+ return { readiness: (await provider.isAvailable(opts)) ? "present" : "absent" };
+ } catch (err) {
+ return { readiness: "failed", detail: readinessDetail(err) };
+ }
+ }
+
/**
* ASYNC readiness: resolves env → config → oauth-file → op:// (lazy SDK) for
* the provider. Never throws — an unknown provider or a 1Password auth failure
* resolves to false. Memoized inside each provider, so the SDK is touched at
* most once. This is THE single readiness oracle (replaces the three old sync
* ones: isProviderAvailable / isApiKeyAvailable / the old isAuthenticated).
+ *
+ * UNCHANGED SIGNATURE, UNCHANGED CONTRACT, and deliberately a pure PROJECTION
+ * of `describeReadiness` rather than a second implementation. `failed` maps to
+ * `false` exactly as it always did — a credential that will not resolve cannot
+ * sign a request either — so every routing decision is byte-identical to the
+ * boolean oracle it replaces. `equivalence.test.ts` is the pin on that claim.
+ * Only the REASON is new, and only for callers that ask for it.
*/
async isAvailable(name: string, opts?: { allowOpPrompt?: boolean }): Promise<boolean> {
- try {
- return (await this.registry.get(name)?.isAvailable(opts)) ?? false;
- } catch {
- return false;
- }
+ return (await this.describeReadiness(name, opts)).readiness === "present";
}
async getRequestAuth(name: string, ctx: RequestAuthContext): Promise<RequestAuth> {
diff --git a/packages/cli/src/auth/credentials/composite-credential.ts b/packages/cli/src/auth/credentials/composite-credential.ts
index 39db4bfa..b4643fbe 100644
--- a/packages/cli/src/auth/credentials/composite-credential.ts
+++ b/packages/cli/src/auth/credentials/composite-credential.ts
@@ -8,7 +8,36 @@
* "OAuth_FALLBACK_TO_API_KEY" when its refresh fails and an API key is present).
*/
-import type { CredentialProvider, RequestAuth, RequestAuthContext } from "./types.js";
+import type {
+ CredentialProvider,
+ ReadinessResult,
+ RequestAuth,
+ RequestAuthContext,
+} from "./types.js";
+
+/**
+ * One half's readiness, whether or not it implements the tri-state.
+ *
+ * A half that does not is not wrong, only less informative: its `false` means
+ * "absent", which is the answer the whole layer gave before.
+ *
+ * A half that THROWS is deliberately NOT caught here. The old `isAvailable` was
+ * `primary || fallback`, so a throwing half aborted the whole composite and the
+ * authority's catch turned it into `false`. Catching it here instead would let
+ * the fallback answer for a primary that blew up — better-looking, and a real
+ * routing change: a provider that reported unavailable would start reporting
+ * available. The throw propagates, the authority reports `failed`, and `failed`
+ * projects to `false` — the same boolean, with the reason now attached.
+ */
+async function readinessOf(
+ provider: CredentialProvider,
+ opts?: { allowOpPrompt?: boolean }
+): Promise<ReadinessResult> {
+ if (provider.describeReadiness) {
+ return (await provider.describeReadiness(opts)) ?? { readiness: "absent" };
+ }
+ return { readiness: (await provider.isAvailable(opts)) ? "present" : "absent" };
+}
export interface CompositeOptions {
/**
@@ -37,8 +66,34 @@ export class CompositeCredentialProvider implements CredentialProvider {
this.opts = opts;
}
+ /**
+ * Readiness for the pair, keeping a half's `failed` instead of flattening it.
+ *
+ * This method is not optional decoration. The fallback half is normally an
+ * `ApiKeyCredentialProvider`, which is the ONLY place the keychain and
+ * 1Password are consulted — so without forwarding, a denied handshake for
+ * `kimi` or `openai-codex` would be reported by this composite as a clean
+ * `absent`, and the tri-state would be dead on arrival for exactly the
+ * subscription providers it exists to protect.
+ *
+ * `present` short-circuits on the primary, matching the old `||` exactly: a
+ * broken fallback store is never consulted, and never downgrades a provider
+ * whose OAuth credential already answered. `failed` beats `absent` because a
+ * store that could not be asked has not established absence.
+ */
+ async describeReadiness(opts?: { allowOpPrompt?: boolean }): Promise<ReadinessResult> {
+ const primary = await readinessOf(this.primary, opts);
+ if (primary.readiness === "present") return primary;
+ const fallback = await readinessOf(this.fallback, opts);
+ if (fallback.readiness === "present") return fallback;
+ if (fallback.readiness === "failed") return fallback;
+ if (primary.readiness === "failed") return primary;
+ return { readiness: "absent" };
+ }
+
+ /** Unchanged contract: the `=== "present"` projection of the above. */
async isAvailable(opts?: { allowOpPrompt?: boolean }): Promise<boolean> {
- return (await this.primary.isAvailable(opts)) || (await this.fallback.isAvailable(opts));
+ return (await this.describeReadiness(opts)).readiness === "present";
}
invalidate(): void {
diff --git a/packages/cli/src/auth/credentials/devin-credential.ts b/packages/cli/src/auth/credentials/devin-credential.ts
index 178fb8f6..cd731204 100644
--- a/packages/cli/src/auth/credentials/devin-credential.ts
+++ b/packages/cli/src/auth/credentials/devin-credential.ts
@@ -25,7 +25,8 @@
*/
import { hasDevinCredentials, readDevinApiKey } from "../../providers/devin/devin-credentials.js";
-import type { CredentialProvider, RequestAuth } from "./types.js";
+import type { CredentialProvider, ReadinessResult, RequestAuth } from "./types.js";
+import { readinessDetail } from "./types.js";
/**
* Build the Devin request headers for a key.
@@ -48,17 +49,32 @@ export class DevinCredentialProvider implements CredentialProvider {
/**
* Available when a Devin credential resolves from env, claudish config, or the
- * Devin CLI's `credentials.toml`. Never throws — an absent Devin CLI is the
- * normal state for every user who does not have one.
+ * Devin CLI's `credentials.toml`.
+ *
+ * `false` used to be the answer to two different questions. An absent Devin
+ * CLI is the normal state for every user who does not have one — that is
+ * `absent`, and it must stay `absent` or every unconfigured provider starts
+ * reporting an error. A resolver that THREW (an unreadable config, a
+ * credentials file that is a directory, a permission error) is not evidence
+ * of absence at all, and reporting it as such is how a credentialed provider
+ * gets dropped from a routing chain in silence.
*/
- async isAvailable(): Promise<boolean> {
+ async describeReadiness(): Promise<ReadinessResult> {
try {
- return hasDevinCredentials();
- } catch {
- return false;
+ return { readiness: hasDevinCredentials() ? "present" : "absent" };
+ } catch (err) {
+ return {
+ readiness: "failed",
+ detail: `Devin credential could not be read: ${readinessDetail(err) ?? "unknown error"}`,
+ };
}
}
+ /** Unchanged contract: the `=== "present"` projection of the above. */
+ async isAvailable(): Promise<boolean> {
+ return (await this.describeReadiness()).readiness === "present";
+ }
+
async getRequestAuth(): Promise<RequestAuth> {
const apiKey = readDevinApiKey();
if (!apiKey) {
diff --git a/packages/cli/src/auth/credentials/grok-credential.ts b/packages/cli/src/auth/credentials/grok-credential.ts
index 3e36a7eb..9d3b24f8 100644
--- a/packages/cli/src/auth/credentials/grok-credential.ts
+++ b/packages/cli/src/auth/credentials/grok-credential.ts
@@ -24,23 +24,37 @@ import {
resolveGrokAccessToken,
resolveGrokClientVersion,
} from "../../providers/grok/grok-credentials.js";
-import type { CredentialProvider, RequestAuth } from "./types.js";
+import type { CredentialProvider, ReadinessResult, RequestAuth } from "./types.js";
+import { readinessDetail } from "./types.js";
export class GrokSubscriptionCredentialProvider implements CredentialProvider {
readonly catalogName = "grok-subscription";
/**
- * Available when `grok login` has written a credential. Never throws — an
- * absent Grok CLI is the normal state for every user who does not have one.
+ * Available when `grok login` has written a credential.
+ *
+ * An absent Grok CLI is the normal state for every user who does not have one
+ * — `absent`, and it stays `absent`. A resolver that THREW is a different
+ * fact: nothing was established about whether the credential exists, and
+ * calling that "no credential" is what quietly drops a flat-rate `gk@`
+ * subscription out of a routing chain in favour of the metered `x-ai`.
*/
- async isAvailable(): Promise<boolean> {
+ async describeReadiness(): Promise<ReadinessResult> {
try {
- return hasGrokCredentials();
- } catch {
- return false;
+ return { readiness: hasGrokCredentials() ? "present" : "absent" };
+ } catch (err) {
+ return {
+ readiness: "failed",
+ detail: `Grok credential could not be read: ${readinessDetail(err) ?? "unknown error"}`,
+ };
}
}
+ /** Unchanged contract: the `=== "present"` projection of the above. */
+ async isAvailable(): Promise<boolean> {
+ return (await this.describeReadiness()).readiness === "present";
+ }
+
/**
* Resolve (refreshing when expired) and sign.
*
diff --git a/packages/cli/src/auth/credentials/keychain-source.test.ts b/packages/cli/src/auth/credentials/keychain-source.test.ts
index d8fe955d..6043d38d 100644
--- a/packages/cli/src/auth/credentials/keychain-source.test.ts
+++ b/packages/cli/src/auth/credentials/keychain-source.test.ts
@@ -215,7 +215,11 @@ describe("resolveKeychainKeyForEnvVars", () => {
try {
const resolved = resolveKeychainKeyForEnvVars([PRIMARY_ENV]);
- expect(resolved).toEqual({ failed: true });
+ // The reason travels with the flag. Without it the caller can say
+ // "unavailable" but not WHICH store was unreachable, which is the
+ // difference between telling a user to unlock their keychain and telling
+ // them they have no subscription.
+ expect(resolved).toEqual({ failed: true, error: UNKNOWN_COMMAND_STDERR });
expect("value" in resolved).toBe(false);
expect(runCalls).toEqual([{ args: ["dump-keychain"], stdin: undefined }]);
} finally {
@@ -233,8 +237,10 @@ describe("resolveKeychainKeyForEnvVars", () => {
try {
const resolved = resolveKeychainKeyForEnvVars([PRIMARY_ENV]);
- expect(resolved).toEqual({ failed: true });
expect(resolved.failed).toBe(true);
+ // A per-item read failure surfaces the engine's KeychainError message,
+ // not the enumeration diagnostic — enumeration succeeded here.
+ expect(resolved.error).toContain(UNKNOWN_COMMAND_STDERR);
expect("value" in resolved).toBe(false);
} finally {
errorSpy.mockRestore();
diff --git a/packages/cli/src/auth/credentials/keychain-source.ts b/packages/cli/src/auth/credentials/keychain-source.ts
index c1b97373..c0dd09e5 100644
--- a/packages/cli/src/auth/credentials/keychain-source.ts
+++ b/packages/cli/src/auth/credentials/keychain-source.ts
@@ -119,6 +119,18 @@ export interface KeychainResolveResult {
value?: string;
/** True when the keychain could not be consulted (NOT when it simply had no item). */
failed: boolean;
+ /**
+ * One-line diagnostic for `failed`, taken from the engine's own
+ * `KeychainEnumeration.error` (`security`'s stderr, or the exit code when it
+ * said nothing). Present only when `failed` is true, and never key material —
+ * enumeration runs `dump-keychain` WITHOUT `-d`, so it never reads item data.
+ *
+ * It exists so the caller can say WHICH store was unreachable rather than
+ * "unavailable". The authority turns this into a `failed` readiness detail,
+ * which is the difference between telling a user to unlock their keychain and
+ * telling them to buy a subscription they already have.
+ */
+ error?: string;
}
/**
@@ -129,11 +141,16 @@ export interface KeychainResolveResult {
* costs no per-variable spawn at all. Only a name that IS present pays the
* ~17ms value lookup.
*
- * NEVER THROWS. A keychain failure degrades this provider to "no credential",
- * which lets the caller fall through to 1Password and lets a proxy or MCP
- * server keep running. The same policy op-source applies under
- * `onAuthFailure: "skip"`, and for the same reason: a credential backend having
- * a bad day must not take down the process.
+ * NEVER THROWS, AND IT NEVER HAD TO. A failure is DATA here — `failed` plus
+ * `error` — not an exception and not a silent `undefined`. That distinction is
+ * the whole point: throwing would force every caller into a try/catch whose
+ * only honest outcome is the same flag, and returning a bare "no value" is what
+ * turned a locked keychain into "this user has no credential" and moved a
+ * flat-rate subscriber onto a metered provider without a word. A keychain
+ * failure still degrades this provider to "no credential" for THIS resolve, so
+ * the caller falls through to 1Password and a proxy or MCP server keeps running
+ * — the same policy op-source applies under `onAuthFailure: "skip"`. What
+ * changes is that the caller can now tell the two apart and say so.
*/
export function resolveKeychainKeyForEnvVars(wanted: Iterable<string>): KeychainResolveResult {
if (!hasKeychainSource()) return { failed: false };
@@ -151,19 +168,41 @@ export function resolveKeychainKeyForEnvVars(wanted: Iterable<string>): Keychain
if (value) return { value, failed: false };
}
} catch (err) {
- warnOnce(
- `[claudish] macOS Keychain lookup skipped: ${err instanceof KeychainError ? err.message : String(err)}`
- );
- return { failed: true };
+ const detail = err instanceof KeychainError ? err.message : String(err);
+ warnOnce(`[claudish] macOS Keychain lookup skipped: ${detail}`);
+ return { failed: true, error: detail };
}
if (failed) {
warnOnce(
"[claudish] macOS Keychain could not be enumerated — treating this provider as unresolved rather than uncredentialed."
);
+ // The engine already recorded WHY, and this read is normally a memo hit: the
+ // same `enumerateKeychainVars()` call `lookupKeychainVar` just made is inside
+ // the 3-second burst window, so asking for its diagnostic costs no extra spawn.
+ // Taking the reason from the engine rather than re-deriving it here keeps
+ // one description of the failure instead of two that can disagree.
+ return { failed: true, error: keychainFailureDetail() };
}
return { failed };
}
+/**
+ * The engine's own reason the keychain could not be enumerated, if it still has
+ * one. Never throws. Called straight after `lookupKeychainVar` enumerated, so it
+ * is a memo hit inside the 3-second burst window; only if that window closed in
+ * between does it re-run the one `dump-keychain` the lookup already made. A
+ * re-read that now succeeds yields `undefined`, and a `failed` readiness without
+ * a detail is still a correct `failed`.
+ */
+function keychainFailureDetail(): string | undefined {
+ try {
+ const listed = enumerateKeychainVars();
+ return listed.failed ? listed.error : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
/**
* Load every stored keychain secret into `process.env`, gap-filling only.
*
diff --git a/packages/cli/src/auth/credentials/op-source.ts b/packages/cli/src/auth/credentials/op-source.ts
index 7120be8d..0b7ce426 100644
--- a/packages/cli/src/auth/credentials/op-source.ts
+++ b/packages/cli/src/auth/credentials/op-source.ts
@@ -29,6 +29,16 @@
* provider resolves as "not available", so the MCP/serve server keeps
* running instead of dying at startup.
*
+ * `"skip"` MUST NOT ERASE THE REASON, and it used to. A swallowed failure and a
+ * clean "1Password does not hold this key" both came back as `{}`, so the
+ * credential authority reported a denied handshake as "the user has no
+ * credential" and routing quietly moved a flat-rate subscription onto a metered
+ * provider. `opts.onFailure` is the seam that keeps the reason: it fires for
+ * every failure this function decides not to throw, per CALL, so a second
+ * provider asking after the same denial still learns about it (the `warnOnce`
+ * line and the `recordOpFailure` entry are both de-duplicated, by design — they
+ * are for the user, not for the caller's control flow).
+ *
* This module replaces the per-entry-point PUSH-into-process.env machinery that
* used to live in index.ts (loadStoredApiKeys / applyCustomEndpointOpKeys /
* getSdkAuth). There is no "resolve everything" pass here — resolution is
@@ -160,6 +170,27 @@ export class OpAuthError extends Error {
/** What to do when SDK auth resolution fails. */
export type OnAuthFailure = "throw" | "skip";
+/** Options accepted by {@link resolveOpKeyForEnvVars}. */
+export interface OpResolveOptions {
+ onAuthFailure?: OnAuthFailure;
+ allowPrompt?: boolean;
+ /**
+ * Called once per SWALLOWED failure, with a one-line reason.
+ *
+ * Only fires under `onAuthFailure: "skip"` semantics — i.e. for the failures
+ * this module deliberately does not throw (a denied or unavailable desktop
+ * handshake, a glob that could not be read, an Environment fetch that failed,
+ * a reference that would not resolve). It is NOT called for a clean resolve
+ * that simply found nothing: "1Password does not hold this key" is an answer,
+ * not a failure, and turning it into one would mark every unconfigured
+ * provider as broken.
+ *
+ * Reasons are already humanized and carry no key material. A throwing sink is
+ * swallowed — diagnostics must never be able to fail a credential resolve.
+ */
+ onFailure?: (reason: string) => void;
+}
+
// ── Lazy SDK-auth resolution (memoized once per process) ────────────────────
let cachedSdkAuth: SdkAuth | undefined;
@@ -334,6 +365,7 @@ async function authForEntry(
// the real resolver and run `op account list` against the developer's actual
// machine — 12 tests did exactly that, at ~2s each, silently depending on real
// 1Password state.
+ if (testSeams?.ambientAuthFailure) throw new OpAuthError(testSeams.ambientAuthFailure);
if (testSeams?.auth) return testSeams.auth;
return getSdkAuth(allowPrompt);
}
@@ -382,6 +414,18 @@ interface OpSourceTestSeams {
sdkFactory?: SdkClientFactory;
/** Skips getSdkAuth() entirely (no account resolution, no prompts). */
auth?: SdkAuth;
+ /**
+ * Make AMBIENT auth resolution FAIL with this message, as a denied or locked
+ * 1Password desktop handshake does.
+ *
+ * The one production path `auth` above cannot express, and the one that
+ * decides `failed` vs `absent` for a whole routing chain. `auth` short-circuits
+ * `getSdkAuth()` with a success; without it a hermetic test reaches the real
+ * resolver and runs `op account list` against the developer's machine. So the
+ * failure needs its own seam, or the denial branch is untestable without
+ * `mock.module()` — which Bun leaks process-wide across sibling files.
+ */
+ ambientAuthFailure?: string;
}
let testSeams: OpSourceTestSeams | undefined;
@@ -786,7 +830,7 @@ export function __resetResolveCacheForTests(): void {
*/
export async function resolveOpKeyForEnvVars(
wanted: Set<string>,
- opts: { onAuthFailure?: OnAuthFailure; allowPrompt?: boolean } = {}
+ opts: OpResolveOptions = {}
): Promise<Record<string, string>> {
if (wanted.size === 0) return {};
@@ -887,10 +931,36 @@ function importAccountLookup(): Map<string, string | undefined> {
return out;
}
+/** What `collectConfigImports` returns, restated to avoid a static SDK import. */
+interface CollectedImports {
+ opRefs: Record<string, string>;
+ globImports: string[];
+ warnings: string[];
+}
+
+/**
+ * The env var names a custom endpoint's `op://` apiKey would resolve INTO.
+ *
+ * Mirrors the derivation in step 2 of the resolve body exactly — a custom
+ * endpoint named `my-vllm` supplies only `CUSTOM_MY_VLLM_KEY`, and nothing else.
+ * Used to decide applicability, so the two must not drift.
+ */
+function customEndpointRefNames(cfg: SniffedConfig): string[] {
+ if (!cfg.customEndpoints || typeof cfg.customEndpoints !== "object") return [];
+ const names: string[] = [];
+ for (const [name, raw] of Object.entries(cfg.customEndpoints)) {
+ if (!raw || typeof raw !== "object") continue;
+ const apiKey = (raw as { apiKey?: unknown }).apiKey;
+ if (typeof apiKey !== "string" || !apiKey.startsWith("op://")) continue;
+ names.push(`CUSTOM_${name.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_KEY`);
+ }
+ return names;
+}
+
/** The actual resolution body (runs inside runOpExclusive). */
async function resolveOpKeyForEnvVarsInner(
wanted: Set<string>,
- opts: { onAuthFailure?: OnAuthFailure; allowPrompt?: boolean } = {},
+ opts: OpResolveOptions = {},
span?: OpSpanCtx
): Promise<Record<string, string>> {
if (wanted.size === 0) return {};
@@ -899,6 +969,86 @@ async function resolveOpKeyForEnvVarsInner(
const onAuthFailure = opts.onAuthFailure ?? "skip";
const allowPrompt = opts.allowPrompt ?? false;
+ // ── APPLICABILITY IS DECIDED BEFORE RESOLUTION ────────────────────────────
+ //
+ // `hasOpSources()` above is a GLOBAL sniff. It answers "does this RUN
+ // configure 1Password at all", never "could 1Password hold THIS provider's
+ // key" — so a locked Mac or a denied handshake used to be reported as a
+ // credential FAILURE to every provider that asked, including providers whose
+ // env var no configured source names.
+ //
+ // Routing reads `failed` as "a real key exists and could not be read", and
+ // tells the user so (routing-rules.ts). So the over-report is not cosmetic:
+ // a metered-only user whose 1Password happens to be locked would be told
+ // that a subscription they never bought could not be read. That is the
+ // mirror image of the bug three-valued readiness fixed — `failed` read as
+ // `absent` — and an `absent` result must stay `absent`.
+ //
+ // So: a failure is attributed to THIS call only when some configured source
+ // could actually carry one of the wanted names —
+ //
+ // EXPLICIT — an `op://` reference whose derived env var is in `wanted`
+ // (an `apiKeys` entry, an `onepassword[]` single ref, a custom
+ // endpoint's key). Its contents ARE known by name, so a ref
+ // naming something else is definitively not about this caller.
+ // BROAD — a glob import or a 1Password Environment. Its contents cannot
+ // be known without reading it, so a read that failed leaves the
+ // question genuinely open: still `failed`.
+ //
+ // Computed HERE, before any handshake, rather than inferred from what the
+ // resolve happened to touch. The failure paths below fire from places that no
+ // longer know which source was in play, and `absent`-vs-`failed` is not a
+ // question to answer from a stack position.
+ const importedOnepassword = await import("../../providers/onepassword.js");
+ const cfg = readConfigRaw();
+ let collected: CollectedImports = { opRefs: {}, globImports: [], warnings: [] };
+ let collectFailed = false;
+ try {
+ collected = importedOnepassword.collectConfigImports(
+ {
+ apiKeys: cfg.apiKeys,
+ // collectConfigImports parses op:// strings; the account lives beside it
+ // in importAccounts, so only the VALUES go in here.
+ onepassword: parseOpSourceEntries(cfg.onepassword ?? [], "ref").map((e) => e.value),
+ },
+ process.env
+ );
+ } catch {
+ // Could not tell WHAT is configured. Keep the previous, broader attribution
+ // rather than silently narrowing it — a fix for over-reporting must not
+ // become a cause of under-reporting.
+ collectFailed = true;
+ }
+ const sourcesCouldHoldWanted =
+ collectFailed ||
+ Object.keys(collected.opRefs).some((name) => wanted.has(name)) ||
+ customEndpointRefNames(cfg).some((name) => wanted.has(name)) ||
+ collected.globImports.length > 0 ||
+ registeredEnvironmentEntries().length > 0;
+
+ /**
+ * Report a failure this function is about to swallow. Per CALL, not
+ * de-duplicated: `warnOnce` and `recordOpFailure` both collapse repeats
+ * because a user does not want the same line four times, but a caller
+ * deciding "absent or failed?" needs the answer every time it asks — that
+ * de-duplication is exactly why a call-site check of `getOpFailures()` would
+ * report the second provider in a chain as cleanly uncredentialed.
+ *
+ * The stderr warning and the run-scoped `recordOpFailure` record are NOT
+ * gated by applicability, deliberately: a broken 1Password is still worth
+ * telling the user about once, and provenance still wants the whole picture.
+ * Only the per-caller "is YOUR credential failed or absent?" answer is.
+ */
+ const noteFailure = (reason: string): void => {
+ if (!opts.onFailure) return;
+ if (!sourcesCouldHoldWanted) return;
+ try {
+ opts.onFailure(reason);
+ } catch {
+ // A diagnostic sink must never be able to fail a credential resolve.
+ }
+ };
+
// AMBIENT auth is resolved LAZILY, not as an upfront gate.
//
// It used to be resolved here and a failure returned immediately. That made
@@ -913,6 +1063,7 @@ async function resolveOpKeyForEnvVarsInner(
// run whose every source is declared never resolves ambient auth at all.
let ambientFailure: OpAuthError | undefined;
const ambientAuth = async (): Promise<SdkAuth | undefined> => {
+ if (testSeams?.ambientAuthFailure) throw new OpAuthError(testSeams.ambientAuthFailure);
if (testSeams?.auth) return testSeams.auth;
if (ambientFailure) throw ambientFailure;
try {
@@ -926,6 +1077,7 @@ async function resolveOpKeyForEnvVarsInner(
/** Report an auth failure the way the old upfront gate did, or rethrow. */
const reportAuthFailure = async (err: unknown): Promise<void> => {
if (!(err instanceof OpAuthError) || onAuthFailure !== "skip") throw err;
+ noteFailure(`1Password auth unavailable: ${err.message}`);
warnOnce(`[claudish] 1Password auth unavailable, skipping op:// keys: ${err.message}`);
// Record before returning: this run's keys may live in 1Password, and the
// missing-key error downstream must not tell the user to `export` a
@@ -962,30 +1114,17 @@ async function resolveOpKeyForEnvVarsInner(
}
}
- const {
- collectConfigImports,
- resolveSecrets,
- recordOpHydratedVars,
- recordOpFailure,
- withSdkRetry,
- humanizeOpError,
- } = await import("../../providers/onepassword.js");
+ const { resolveSecrets, recordOpHydratedVars, recordOpFailure, withSdkRetry, humanizeOpError } =
+ importedOnepassword;
- const cfg = readConfigRaw();
const out: Record<string, string> = {};
try {
- // 1. config single op:// refs + globs (apiKeys + onepassword[]).
+ // 1. config single op:// refs + globs (apiKeys + onepassword[]) — already
+ // collected above, because applicability had to be decided before the
+ // handshake. ONE parse, so the set the applicability check reasoned about
+ // and the set resolution walks cannot drift apart.
const importAccounts = importAccountLookup();
- const collected = collectConfigImports(
- {
- apiKeys: cfg.apiKeys,
- // collectConfigImports parses op:// strings; the account lives beside it
- // in importAccounts, so only the VALUES go in here.
- onepassword: parseOpSourceEntries(cfg.onepassword ?? [], "ref").map((e) => e.value),
- },
- process.env
- );
for (const w of collected.warnings) console.error(w);
// Single refs whose derived env name is wanted.
@@ -1059,6 +1198,7 @@ async function resolveOpKeyForEnvVarsInner(
// RECORD the raw message (wasOpAuthorizationDenied matches on it),
// DISPLAY the humanized one — the SDK's Rust struct dump names no cause.
const m = globErr instanceof Error ? globErr.message : String(globErr);
+ noteFailure(`1Password import failed: ${humanizeOpError(globErr)}`);
warnOnce(`[claudish] 1Password import skipped: ${humanizeOpError(globErr)}`);
recordOpFailure({ kind: "import", source: globPath, message: m });
}
@@ -1116,6 +1256,7 @@ async function resolveOpKeyForEnvVarsInner(
// never lock the user out. The failed resolution was evicted, so the
// next resolve retries it.
const m = envErr instanceof Error ? envErr.message : String(envErr);
+ noteFailure(`1Password environment "${envId}" failed: ${humanizeOpError(envErr)}`);
warnOnce(`[claudish] 1Password environment skipped: ${humanizeOpError(envErr)}`);
recordOpFailure({ kind: "environment", source: envId, message: m });
}
@@ -1123,6 +1264,7 @@ async function resolveOpKeyForEnvVarsInner(
}
} catch (err) {
if (err instanceof OpAuthError && onAuthFailure === "skip") {
+ noteFailure(`1Password resolution skipped: ${err.message}`);
warnOnce(`[claudish] 1Password resolution skipped: ${err.message}`);
recordOpFailure({ kind: "auth", message: err.message });
return out;
@@ -1131,6 +1273,10 @@ async function resolveOpKeyForEnvVarsInner(
warnOnce(`[claudish] 1Password secret resolution failed: ${humanizeOpError(err)}`);
recordOpFailure({ kind: "reference", message });
if (onAuthFailure === "throw") throw err;
+ // Only AFTER the rethrow: the sink reports failures this function swallows.
+ // A caller that asked to have it thrown is getting the error itself and
+ // must not also be told about it through the back channel.
+ noteFailure(`1Password secret resolution failed: ${humanizeOpError(err)}`);
}
// Provenance: record which env vars came from 1Password so the config TUI /
diff --git a/packages/cli/src/auth/credentials/readiness.test.ts b/packages/cli/src/auth/credentials/readiness.test.ts
new file mode 100644
index 00000000..857d5002
--- /dev/null
+++ b/packages/cli/src/auth/credentials/readiness.test.ts
@@ -0,0 +1,810 @@
+/**
+ * Credential readiness — proving that a credential FAILURE is distinguishable
+ * from credential ABSENCE, and that nothing else moved.
+ *
+ * ── What this file exists to catch ───────────────────────────────────────────
+ * `isAvailable()` is a boolean with one slot for two facts. Every resolution
+ * failure collapsed into `false`, which downstream reads as "this user has no
+ * key for this provider": `hasCredentialsForProvider` drops the candidate from
+ * the routing chain and a metered provider serves the request with nothing
+ * printed. A locked Mac, a denied 1Password handshake or a keychain ACL the
+ * user declined therefore moved a flat-rate subscriber onto pay-per-token, in
+ * silence.
+ *
+ * A first attempt at the fix produced `"failed"` ONLY when a source threw — and
+ * no production source throws. The tests below deliberately drive the two
+ * measured failure modes through their real code paths (a `security` that
+ * exits non-zero, a 1Password handshake that fails) rather than by making a
+ * fake provider throw, because a throw-only oracle passes a throw-only test
+ * while the actual bug is untouched.
+ *
+ * ── The two invariants ───────────────────────────────────────────────────────
+ * 1. `failed` ≠ `absent`. The SAME provider, the SAME environment, differing
+ * only in whether the store answered, must produce two different verdicts.
+ * 2. Routing is byte-identical: `isAvailable(name)` is exactly
+ * `describeReadiness(name).readiness === "present"`, so `failed` still
+ * keeps a candidate out of the chain. `equivalence.test.ts` is the pin on
+ * the matrix; this file pins the projection itself, per verdict.
+ *
+ * ── Hermetic strategy ────────────────────────────────────────────────────────
+ * NO `mock.module()` anywhere: Bun's module registry is process-global and a
+ * stub bleeds into sibling files. The keychain is driven entirely through the
+ * production `setKeychainTestDeps()` seam (platform / run / runAsync) against a
+ * temp config file, so NO test here can reach the real login keychain — killing
+ * `security` processes restarts `securityd` and drops the authenticated
+ * keychain session of every app on the machine. 1Password is driven through
+ * `__setOpSourceSeamsForTests` (in-memory config + fake SDK factory + stub
+ * auth), and is otherwise held off with the production `CLAUDISH_DISABLE_OP`
+ * escape hatch.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getConfigFileOverride, setConfigFileOverride } from "../../config-override.js";
+import type { KeychainDeps, KeychainRunResult } from "../../providers/keychain.js";
+import { invalidateKeychainCache, setKeychainTestDeps } from "../../providers/keychain.js";
+import type { SdkAuth, SdkClientFactory, SdkClientLike } from "../../providers/onepassword.js";
+import {
+ resetOpFailures,
+ setAppLockProbe,
+ setLockRetryTiming,
+ setPeerLockProbe,
+ setScreenLockProbe,
+} from "../../providers/onepassword.js";
+import type { AntigravityTokenDeps } from "../antigravity-token.js";
+import { readSharedAntigravityToken } from "../antigravity-token.js";
+import {
+ __resetResolveCacheForTests,
+ __resetSdkAuthForTests,
+ __resetSniffForTests,
+ __resetWarnOnceForTests,
+ __setOpSourceSeamsForTests,
+} from "./op-source.js";
+import type { CredentialProvider, ReadinessResult, RequestAuth } from "./types.js";
+
+// ── Import ORDER matters here, which is why these are dynamic ───────────────
+//
+// `authority.ts` builds its `credentials` singleton at module scope, and that
+// constructor references the provider classes it imports. Those providers sit
+// in an import CYCLE with the authority (antigravity-credential reaches it
+// through the transport/catalog modules). Naming a provider module first in a
+// static import list makes IT the entry point, so the authority's module body
+// runs while the class it is about to construct is still in its temporal dead
+// zone — "Cannot access 'AntigravityCredentialProvider' before initialization",
+// at import time, before a single test runs. Loading the authority FIRST lets
+// it pull every provider in the order it already works in; by the time the
+// lines below run, each module is fully initialised.
+const { CredentialAuthority } = await import("./authority.js");
+const { ApiKeyCredentialProvider } = await import("./api-key-credential.js");
+const { CompositeCredentialProvider } = await import("./composite-credential.js");
+const { AntigravityCredentialProvider } = await import("./antigravity-credential.js");
+const { DevinCredentialProvider } = await import("./devin-credential.js");
+const { GrokSubscriptionCredentialProvider } = await import("./grok-credential.js");
+
+type CredentialAuthorityInstance = InstanceType<typeof CredentialAuthority>;
+type ApiKeyProviderInstance = InstanceType<typeof ApiKeyCredentialProvider>;
+
+// ── Fixtures ────────────────────────────────────────────────────────────────
+
+/**
+ * A real captured `security dump-keychain` block (attributes only — the command
+ * runs without `-d`, so it never reads item DATA). Reused from
+ * keychain-source.test.ts rather than hand-authored.
+ */
+const REAL_DUMP_BLOCK = `keychain: "/Users/jack/Library/Keychains/login.keychain-db"
+version: 512
+class: "genp"
+attributes:
+ 0x00000007 <blob>="claudish: CLAUDISH_READINESS_TEST_API_KEY"
+ "acct"<blob>="CLAUDISH_READINESS_TEST_API_KEY"
+ "cdat"<timedate>=0x32303236303832323132333235385A00
+ "desc"<blob>="application password"
+ "icmt"<blob>="Stored by claudish"
+ "svce"<blob>="claudish"`;
+
+/** The measured stderr of a `security` invocation that could not be answered. */
+const LOCKED_STDERR = "security: SecKeychainSearchCopyNext: User interaction is not allowed.";
+
+const ENV_VAR = "CLAUDISH_READINESS_TEST_API_KEY";
+const OTHER_ENV_VAR = "CLAUDISH_READINESS_TEST_OTHER_API_KEY";
+const TOUCHED_ENV_VARS = [ENV_VAR, OTHER_ENV_VAR] as const;
+
+const OP_ENVIRONMENT_ID = "readiness-test-env";
+const STUB_AUTH: SdkAuth = { kind: "token", token: "ops_test" };
+
+// ── Shared hermetic state ───────────────────────────────────────────────────
+
+let tempDirectory: string;
+let configFile: string;
+let savedConfigOverride: string | null;
+let savedEnv: Map<string, string | undefined>;
+let savedDisableKeychain: string | undefined;
+let savedDisableOp: string | undefined;
+let savedArgv: string[];
+let runCalls: string[][];
+let runImpl: KeychainDeps["run"];
+
+function runResult(code: number, stdout = "", stderr = ""): KeychainRunResult {
+ return { code, stdout, stderr };
+}
+
+function writeConfig(config: Record<string, unknown>): void {
+ writeFileSync(configFile, JSON.stringify(config));
+ // The op sniff reads the config file directly and memoizes; a rewrite must
+ // invalidate it or the next `hasOpSources()` answers about the old file.
+ __resetSniffForTests();
+}
+
+/** Turn the keychain backend ON for this test, through the real config flag. */
+function enableKeychain(): void {
+ writeConfig({ keychain: { enabled: true } });
+ delete process.env.CLAUDISH_DISABLE_KEYCHAIN;
+ // The engine memoizes enumeration for a 3-second burst, INCLUDING failures.
+ // Each case scripts a different `security` answer, so the memo must go.
+ invalidateKeychainCache();
+}
+
+/** A provider whose ONLY possible credential source is the keychain. */
+function keychainOnlyProvider(envVar = ENV_VAR): ApiKeyProviderInstance {
+ return new ApiKeyCredentialProvider({ catalogName: `readiness-${envVar}`, envVar });
+}
+
+beforeEach(() => {
+ savedConfigOverride = getConfigFileOverride();
+ savedDisableKeychain = process.env.CLAUDISH_DISABLE_KEYCHAIN;
+ savedDisableOp = process.env.CLAUDISH_DISABLE_OP;
+ savedArgv = process.argv;
+
+ tempDirectory = mkdtempSync(join(tmpdir(), "claudish-readiness-"));
+ configFile = join(tempDirectory, "config.json");
+ setConfigFileOverride(configFile);
+ writeConfig({});
+
+ savedEnv = new Map(TOUCHED_ENV_VARS.map((name) => [name, process.env[name]]));
+ for (const name of TOUCHED_ENV_VARS) delete process.env[name];
+
+ // Default posture: BOTH vaults off. A test that wants one turns it on
+ // explicitly, so nothing here can reach a real store by omission.
+ process.env.CLAUDISH_DISABLE_KEYCHAIN = "1";
+ process.env.CLAUDISH_DISABLE_OP = "1";
+ process.argv = ["bun", "readiness.test.ts"];
+
+ runCalls = [];
+ runImpl = () => {
+ throw new Error("unexpected keychain call — a test must script `runImpl` first");
+ };
+ setKeychainTestDeps({
+ platform: () => "darwin",
+ run: (args, stdin) => {
+ runCalls.push([...args]);
+ return runImpl(args, stdin);
+ },
+ runAsync: async (args, stdin) => {
+ runCalls.push([...args]);
+ return runImpl(args, stdin);
+ },
+ });
+ invalidateKeychainCache();
+
+ __resetSdkAuthForTests();
+ __resetSniffForTests();
+ __resetWarnOnceForTests();
+ __resetResolveCacheForTests();
+ __setOpSourceSeamsForTests(undefined);
+ resetOpFailures();
+ setLockRetryTiming({ seconds: 0.01, tickMs: 1 });
+ setScreenLockProbe(() => false);
+ setAppLockProbe(() => false);
+ setPeerLockProbe(() => false);
+});
+
+afterEach(() => {
+ for (const [name, value] of savedEnv) {
+ if (value === undefined) delete process.env[name];
+ else process.env[name] = value;
+ }
+ if (savedDisableKeychain === undefined) delete process.env.CLAUDISH_DISABLE_KEYCHAIN;
+ else process.env.CLAUDISH_DISABLE_KEYCHAIN = savedDisableKeychain;
+ if (savedDisableOp === undefined) delete process.env.CLAUDISH_DISABLE_OP;
+ else process.env.CLAUDISH_DISABLE_OP = savedDisableOp;
+ process.argv = savedArgv;
+
+ setKeychainTestDeps(null);
+ invalidateKeychainCache();
+ setConfigFileOverride(savedConfigOverride);
+ rmSync(tempDirectory, { recursive: true, force: true });
+
+ __resetSdkAuthForTests();
+ __resetSniffForTests();
+ __resetWarnOnceForTests();
+ __resetResolveCacheForTests();
+ __setOpSourceSeamsForTests(undefined);
+ resetOpFailures();
+ setLockRetryTiming();
+ setScreenLockProbe(undefined);
+ setAppLockProbe(undefined);
+ setPeerLockProbe(undefined);
+});
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/** A scriptable CredentialProvider with no tri-state of its own. */
+class LegacyProvider implements CredentialProvider {
+ constructor(
+ readonly catalogName: string,
+ private readonly answer: boolean | Error
+ ) {}
+
+ async isAvailable(): Promise<boolean> {
+ if (this.answer instanceof Error) throw this.answer;
+ return this.answer;
+ }
+
+ async getRequestAuth(): Promise<RequestAuth> {
+ return { headers: {} };
+ }
+}
+
+/**
+ * Assert invariant 2 — `isAvailable` is the `=== "present"` projection, per
+ * verdict rather than only across a matrix. A provider that reports `failed`
+ * and `true` would be a routing change hiding behind a richer type.
+ */
+async function expectProjection(
+ authority: CredentialAuthorityInstance,
+ name: string
+): Promise<ReadinessResult> {
+ const described = await authority.describeReadiness(name);
+ expect(await authority.isAvailable(name)).toBe(described.readiness === "present");
+ return described;
+}
+
+/** A fake 1Password whose Environment fetch always fails with `message`. */
+function opEnvironmentThatFails(message: string): SdkClientFactory {
+ const client: SdkClientLike = {
+ secrets: {
+ async resolve(ref: string): Promise<string> {
+ throw new Error(`readiness tests resolve no refs: ${ref}`);
+ },
+ async resolveAll() {
+ return { individualResponses: {} };
+ },
+ },
+ vaults: {
+ async list() {
+ return [];
+ },
+ },
+ items: {
+ async list() {
+ return [];
+ },
+ async get() {
+ throw new Error("readiness tests must not inspect items");
+ },
+ },
+ environments: {
+ async getVariables() {
+ throw new Error(message);
+ },
+ },
+ };
+ return async () => client;
+}
+
+/** A fake 1Password whose Environment answers cleanly, holding `vars`. */
+function opEnvironmentHolding(vars: Record<string, string>): SdkClientFactory {
+ const client: SdkClientLike = {
+ secrets: {
+ async resolve(ref: string): Promise<string> {
+ throw new Error(`readiness tests resolve no refs: ${ref}`);
+ },
+ async resolveAll() {
+ return { individualResponses: {} };
+ },
+ },
+ vaults: {
+ async list() {
+ return [];
+ },
+ },
+ items: {
+ async list() {
+ return [];
+ },
+ async get() {
+ throw new Error("readiness tests must not inspect items");
+ },
+ },
+ environments: {
+ // The SDK's real shape is `{ variables: [{ name, value }] }`. An EMPTY
+ // array is not "holds nothing" — `readEnvironment` throws on it,
+ // deliberately, because an Environment fetch is all-or-nothing and an
+ // empty answer cannot be told apart from a wrong id.
+ async getVariables() {
+ return {
+ variables: Object.entries(vars).map(([name, value]) => ({
+ name,
+ value,
+ masked: false,
+ })),
+ };
+ },
+ },
+ };
+ return async () => client;
+}
+
+/** Install the in-memory 1Password seam and turn the sync sniff back on. */
+function enableOp(factory: SdkClientFactory): void {
+ delete process.env.CLAUDISH_DISABLE_OP;
+ __setOpSourceSeamsForTests({
+ config: { onepassword: [], onepasswordEnvironments: [OP_ENVIRONMENT_ID] },
+ sdkFactory: factory,
+ auth: STUB_AUTH,
+ });
+ __resetSniffForTests();
+}
+
+/**
+ * 1Password configured with exactly `config`, and an AMBIENT handshake that is
+ * denied — the measured failure shape (`Denied authorization for SDK client`),
+ * driven through the production path rather than through a throwing fake.
+ *
+ * `auth` is deliberately NOT set: it stands in for a SUCCESSFUL ambient resolve
+ * and would short-circuit the branch under test. `ambientAuthFailure` is what
+ * keeps this hermetic — without it `getSdkAuth()` runs `op account list` against
+ * the developer's real machine.
+ */
+function enableOpWithAmbientFailure(
+ config: { apiKeys?: Record<string, string>; onepassword?: string[] },
+ message: string
+): void {
+ delete process.env.CLAUDISH_DISABLE_OP;
+ __setOpSourceSeamsForTests({
+ config: { onepassword: [], onepasswordEnvironments: [], ...config },
+ ambientAuthFailure: message,
+ });
+ __resetSniffForTests();
+}
+
+/** Silence the deliberate stderr warnings a failing store emits. */
+async function quietly<T>(body: () => Promise<T>): Promise<T> {
+ const spy = spyOn(console, "error").mockImplementation(() => {});
+ try {
+ return await body();
+ } finally {
+ spy.mockRestore();
+ }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. The authority's tri-state, and the projection that keeps routing still
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("CredentialAuthority.describeReadiness — the three values", () => {
+ it("reports an UNREGISTERED provider as absent, never failed", async () => {
+ const authority = new CredentialAuthority();
+ // Nothing was consulted, so there is no failure to report. This is the one
+ // place `absent` is the honest answer to "we did not ask".
+ expect(await expectProjection(authority, "no-such-provider")).toEqual({ readiness: "absent" });
+ });
+
+ it("reports a provider with no credential as absent", async () => {
+ const authority = new CredentialAuthority();
+ authority.register(new LegacyProvider("legacy-absent", false));
+
+ expect(await expectProjection(authority, "legacy-absent")).toEqual({ readiness: "absent" });
+ });
+
+ it("reports a credentialed provider as present", async () => {
+ const authority = new CredentialAuthority();
+ authority.register(new LegacyProvider("legacy-present", true));
+
+ expect(await expectProjection(authority, "legacy-present")).toEqual({ readiness: "present" });
+ });
+
+ it("reports a THROWING source as failed, with the reason, never as absent", async () => {
+ const authority = new CredentialAuthority();
+ authority.register(
+ new LegacyProvider("legacy-throws", new Error("keychain is locked\nsecond line dropped"))
+ );
+
+ const described = await expectProjection(authority, "legacy-throws");
+ expect(described.readiness).toBe("failed");
+ expect(described.detail).toBe("keychain is locked");
+ });
+
+ it("still keeps a failed provider OUT of the chain — isAvailable is false", async () => {
+ const authority = new CredentialAuthority();
+ authority.register(new LegacyProvider("legacy-throws", new Error("denied")));
+
+ // This is invariant 2 stated as money: `failed` must not become a licence
+ // to route. A credential that will not resolve cannot sign a request.
+ expect(await authority.isAvailable("legacy-throws")).toBe(false);
+ });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. THE HEADLINE — a keychain that could not be READ is not a keychain that
+// is EMPTY. Driven through the real `security` path, not through a throw.
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("macOS Keychain: failure vs absence", () => {
+ it("distinguishes a keychain that could not be read from one holding nothing", async () => {
+ // Case A — the store answered, and it holds nothing for this variable.
+ enableKeychain();
+ runImpl = () => runResult(0, "");
+ const absent = await quietly(() => keychainOnlyProvider().describeReadiness());
+
+ // Case B — the SAME provider, the SAME (empty) environment. The only thing
+ // that differs is that `security` could not answer.
+ enableKeychain();
+ runImpl = () => runResult(1, "", LOCKED_STDERR);
+ const failed = await quietly(() => keychainOnlyProvider().describeReadiness());
+
+ expect(absent.readiness).toBe("absent");
+ expect(failed.readiness).toBe("failed");
+ // The whole point, in one assertion: two different answers to two different
+ // questions. Collapse them and this line is the one that goes red.
+ expect(failed.readiness).not.toBe(absent.readiness);
+ });
+
+ it("names the store in the failure detail, and carries `security`'s own reason", async () => {
+ enableKeychain();
+ runImpl = () => runResult(1, "", LOCKED_STDERR);
+
+ const described = await quietly(() => keychainOnlyProvider().describeReadiness());
+
+ expect(described.readiness).toBe("failed");
+ // "unlock your keychain" and "buy the subscription you already own" are
+ // different remedies; the detail is what lets a caller offer the right one.
+ expect(described.detail).toContain("Keychain");
+ expect(described.detail).toContain("User interaction is not allowed");
+ });
+
+ it("reports an unreadable ITEM as failed, not as an absent item", async () => {
+ // Enumeration succeeds and lists the variable, so the item exists — the
+ // per-item read is what was refused (a declined ACL). Absence is disproven
+ // by the enumeration itself, so this can only be `failed`.
+ //
+ // Exit 1, NOT 44: 44 is `security`'s measured "genuinely absent" signal and
+ // reporting that as a failure would be the over-report this whole change
+ // exists to avoid. Only a read that could not be performed is `failed`.
+ enableKeychain();
+ runImpl = (args) =>
+ args[0] === "dump-keychain" ? runResult(0, REAL_DUMP_BLOCK) : runResult(1, "", LOCKED_STDERR);
+
+ const described = await quietly(() => keychainOnlyProvider().describeReadiness());
+
+ expect(described.readiness).toBe("failed");
+ });
+
+ it("keeps routing unchanged: isAvailable is false for BOTH absent and failed", async () => {
+ enableKeychain();
+ runImpl = () => runResult(0, "");
+ expect(await quietly(() => keychainOnlyProvider().isAvailable())).toBe(false);
+
+ enableKeychain();
+ runImpl = () => runResult(1, "", LOCKED_STDERR);
+ expect(await quietly(() => keychainOnlyProvider().isAvailable())).toBe(false);
+ });
+
+ it("does NOT cache a failure — the next call retries and can succeed", async () => {
+ enableKeychain();
+ const provider = keychainOnlyProvider();
+
+ runImpl = () => runResult(1, "", LOCKED_STDERR);
+ expect((await quietly(() => provider.describeReadiness())).readiness).toBe("failed");
+
+ // The user unlocked the keychain. A cached failure would pin this provider
+ // as credential-less for the life of the process — the compounding bug
+ // architecture/keychain.md records.
+ invalidateKeychainCache();
+ runImpl = (args) =>
+ args[0] === "dump-keychain"
+ ? runResult(0, REAL_DUMP_BLOCK)
+ : runResult(0, "sk-recovered-value\n");
+
+ expect(await provider.describeReadiness()).toEqual({ readiness: "present" });
+ });
+
+ it("does not let a broken keychain downgrade a provider whose key is in env", async () => {
+ // A store that is never consulted cannot make a provider look broken. The
+ // cheap env check runs first, by design.
+ enableKeychain();
+ process.env[ENV_VAR] = "sk-from-the-shell";
+ runImpl = () => runResult(1, "", LOCKED_STDERR);
+
+ expect(await keychainOnlyProvider().describeReadiness()).toEqual({ readiness: "present" });
+ expect(runCalls).toHaveLength(0);
+ });
+
+ it("reports absent — not failed — when the backend is simply not enabled", async () => {
+ // The over-report guard. Every user who has not opted into the keychain
+ // must stay `absent`, or every provider starts reporting errors.
+ expect(await keychainOnlyProvider().describeReadiness()).toEqual({ readiness: "absent" });
+ expect(runCalls).toHaveLength(0);
+ });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 3. 1Password — `onAuthFailure: "skip"` must skip the EXCEPTION, not the REASON
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("1Password: a swallowed failure is still a failure", () => {
+ it("reports a failed handshake as failed, not as absent", async () => {
+ enableOp(opEnvironmentThatFails("1Password desktop bridge unavailable (test)"));
+
+ const described = await quietly(() => keychainOnlyProvider().describeReadiness());
+
+ expect(described.readiness).toBe("failed");
+ expect(described.detail).toContain("1Password");
+ });
+
+ it("reports absent when 1Password answers cleanly and holds nothing", async () => {
+ // The other half of the over-report guard: a working vault that does not
+ // carry this key is an ANSWER. Turning it into `failed` would mark every
+ // unconfigured provider broken for every 1Password user.
+ enableOp(opEnvironmentHolding({ SOMETHING_ELSE_API_KEY: "sk-unrelated" }));
+
+ expect(await keychainOnlyProvider().describeReadiness()).toEqual({ readiness: "absent" });
+ });
+
+ it("reports failed for EVERY provider in a chain, not just the first to ask", async () => {
+ // The trap that makes a call-site `getOpFailures()` check wrong: both the
+ // stderr warning and the run-scoped failure record are de-duplicated on
+ // purpose, so the second provider to hit the same denial sees no new
+ // evidence. A bare model name filters a whole chain of candidates, so
+ // "only the first one learns" means the rest get billed metered silently.
+ enableOp(opEnvironmentThatFails("1Password desktop bridge unavailable (test)"));
+
+ const verdicts = await quietly(async () => [
+ await keychainOnlyProvider(ENV_VAR).describeReadiness(),
+ await keychainOnlyProvider(OTHER_ENV_VAR).describeReadiness(),
+ ]);
+
+ expect(verdicts.map((v) => v.readiness)).toEqual(["failed", "failed"]);
+ });
+
+ it("keeps routing unchanged: a failed 1Password resolve is still unavailable", async () => {
+ enableOp(opEnvironmentThatFails("1Password desktop bridge unavailable (test)"));
+
+ expect(await quietly(() => keychainOnlyProvider().isAvailable())).toBe(false);
+ });
+
+ // ── The OVER-report guard, from the other side (HIGH Issue 2) ─────────────
+ //
+ // Revert control for the pair below: delete the `sourcesCouldHoldWanted` test
+ // inside `noteFailure` in op-source.ts. The first goes red — `failed` for a
+ // provider no configured source names — while the second stays green, which is
+ // the asymmetry that makes this a control rather than a coincidence.
+
+ it("does NOT attribute an ambient handshake failure to a provider no source names", async () => {
+ // A metered-only user with an unrelated explicit `op://` reference for some
+ // OTHER provider, and a 1Password that will not answer. Nothing configured
+ // here could ever hold this provider's key, so the honest verdict is that
+ // the user has none — `absent`.
+ //
+ // This matters as more than tidiness: routing reads `failed` as "a real
+ // subscription key exists and could not be read" and says so on stderr. The
+ // over-report would tell the user that a subscription they never bought
+ // could not be read.
+ enableOpWithAmbientFailure(
+ { apiKeys: { UNRELATED_OTHER_API_KEY: "op://vault/item/UNRELATED_OTHER_API_KEY" } },
+ "Denied authorization for SDK client"
+ );
+
+ expect(await quietly(() => keychainOnlyProvider().describeReadiness())).toEqual({
+ readiness: "absent",
+ });
+ });
+
+ it("DOES report failed when a BROAD source could have held it — a glob is not knowable", async () => {
+ // The other half. A glob's contents cannot be known without reading it, so a
+ // read that failed leaves the question genuinely open, and `failed` is the
+ // honest answer. Narrowing this to explicit refs only would reintroduce the
+ // unanimous CRITICAL for every user who imports by glob.
+ enableOpWithAmbientFailure(
+ { onepassword: ["op://vault/API Keys/*"] },
+ "Denied authorization for SDK client"
+ );
+
+ const described = await quietly(() => keychainOnlyProvider().describeReadiness());
+ expect(described.readiness).toBe("failed");
+ expect(described.detail).toContain("1Password");
+ });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 4. The composite must not flatten a half's `failed` back into a boolean
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("CompositeCredentialProvider readiness", () => {
+ it("forwards a failed fallback instead of reporting absent", async () => {
+ // kimi and openai-codex are composites whose FALLBACK half is the only
+ // thing that ever touches the keychain or 1Password. Flatten here and the
+ // tri-state is dead on arrival for exactly the subscription providers it
+ // exists to protect.
+ enableKeychain();
+ runImpl = () => runResult(1, "", LOCKED_STDERR);
+ const composite = new CompositeCredentialProvider(
+ "composite-test",
+ new LegacyProvider("oauth-half", false),
+ keychainOnlyProvider()
+ );
+
+ const described = await quietly(() => composite.describeReadiness());
+
+ expect(described.readiness).toBe("failed");
+ expect(await quietly(() => composite.isAvailable())).toBe(false);
+ });
+
+ it("short-circuits on a present primary — a broken fallback never downgrades it", async () => {
+ enableKeychain();
+ runImpl = () => runResult(1, "", LOCKED_STDERR);
+ const composite = new CompositeCredentialProvider(
+ "composite-test",
+ new LegacyProvider("oauth-half", true),
+ keychainOnlyProvider()
+ );
+
+ expect(await composite.describeReadiness()).toEqual({ readiness: "present" });
+ expect(runCalls).toHaveLength(0);
+ });
+
+ it("reports absent when both halves are cleanly absent", async () => {
+ const composite = new CompositeCredentialProvider(
+ "composite-test",
+ new LegacyProvider("oauth-half", false),
+ new LegacyProvider("key-half", false)
+ );
+
+ expect(await composite.describeReadiness()).toEqual({ readiness: "absent" });
+ expect(await composite.isAvailable()).toBe(false);
+ });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 5. The blast radius is every provider — the `catch { return false }` sites
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("subscription providers report the tri-state", () => {
+ // ANTIGRAVITY IS DELIBERATELY NOT IN THIS LOOP, and must not be added back.
+ //
+ // The loop calls the REAL provider with no stub. `AntigravityCredentialProvider`
+ // reads its token through `auth/antigravity-token.ts`, whose `defaultReadStore`
+ // spawns `security` — and none of the three existing protections reaches it:
+ //
+ // · `setKeychainTestDeps()` stubs `providers/keychain.ts` only. The two are
+ // separable precisely because antigravity resolves a BARE `"security"`
+ // through `PATH` while keychain.ts uses the absolute `/usr/bin/security`
+ // (architecture/keychain.md).
+ // · `CLAUDISH_DISABLE_KEYCHAIN=1` appears nowhere in `antigravity-token.ts`,
+ // so not even `bun run test:safe` prevents the spawn.
+ // · The injection seam is a DEFAULT PARAMETER, and the provider calls it with
+ // no argument — a test cannot intervene from outside.
+ //
+ // So the loop read the developer's real shared agy token on every run, in a
+ // repository whose own rule is that a safe target must EXIST rather than
+ // relying on care. It stayed green either way, which is what made it invisible.
+ // Antigravity's contract is covered below, through the parameter seam.
+ const providers: [string, CredentialProvider][] = [
+ ["devin", new DevinCredentialProvider()],
+ ["grok-subscription", new GrokSubscriptionCredentialProvider()],
+ ];
+
+ for (const [name, provider] of providers) {
+ it(`${name} implements describeReadiness and projects isAvailable from it`, async () => {
+ // These three swallowed every error into `return false`, so a store that
+ // could not be asked was reported as a user who never subscribed — and
+ // `gk@` / `dv@` / `ag@` fell through to a metered vendor in silence.
+ expect(typeof provider.describeReadiness).toBe("function");
+
+ const described = await provider.describeReadiness?.({});
+ expect(described).toBeDefined();
+ const readiness = described?.readiness ?? "(none returned)";
+ expect(["present", "absent", "failed"]).toContain(readiness);
+ expect(await provider.isAvailable()).toBe(readiness === "present");
+ });
+ }
+
+ it("a provider whose store read throws is failed, via the authority", async () => {
+ // The shared contract behind all three: the authority is the backstop for
+ // any source that still raises rather than reporting.
+ const authority = new CredentialAuthority();
+ authority.register(new LegacyProvider("devin", new Error("credentials.toml is a directory")));
+
+ const described = await expectProjection(authority, "devin");
+ expect(described.readiness).toBe("failed");
+ expect(described.detail).toBe("credentials.toml is a directory");
+ });
+
+ // ── Antigravity, through the parameter seam and NOT through `security` ─────
+
+ it("antigravity implements describeReadiness and projects isAvailable from it", () => {
+ // Shape only. Calling either one here is what spawns `security`; the VALUE
+ // each returns is pinned below, against a stubbed store.
+ const provider = new AntigravityCredentialProvider();
+ expect(typeof provider.describeReadiness).toBe("function");
+ expect(typeof provider.isAvailable).toBe("function");
+ });
+
+ it("antigravity's store read drives present / absent / failed through injected deps", () => {
+ // `AntigravityCredentialProvider.describeReadiness` is exactly:
+ // readSharedAntigravityToken() !== null → present : absent, and a THROW
+ // from the store → failed.
+ // Every one of those three verdicts is decided by the value this seam
+ // returns, so driving the seam covers the tri-state without a subprocess.
+ const stub = (readStore: () => string | null): AntigravityTokenDeps => ({
+ readStore,
+ writeStore: () => {
+ throw new Error("readiness tests never write the shared store");
+ },
+ runAgyRefresh: () => ({ kind: "not-installed" }) as const,
+ now: () => Date.parse("2026-08-04T00:00:00.000Z"),
+ });
+
+ // present — a real go-keyring-base64 record, built the same way
+ // antigravity-token.test.ts builds its fixtures.
+ const record = {
+ token: {
+ access_token: "readiness-access-token",
+ token_type: "Bearer",
+ refresh_token: "readiness-refresh-token",
+ expiry: "2026-08-04T01:00:00.000Z",
+ },
+ id_token: "readiness-id-token",
+ auth_method: "oauth",
+ };
+ const raw = `go-keyring-base64:${Buffer.from(JSON.stringify(record), "utf8").toString("base64")}`;
+ expect(readSharedAntigravityToken(stub(() => raw))?.access_token).toBe(
+ "readiness-access-token"
+ );
+
+ // absent — the store answered, and it holds nothing.
+ expect(readSharedAntigravityToken(stub(() => null))).toBeNull();
+
+ // failed — the store could not be asked. What matters is that the read
+ // PROPAGATES rather than swallowing: the provider's `failed` branch is its
+ // `catch`, so a read that returned null here would make that branch dead
+ // code and collapse "could not ask" back into "not signed in".
+ expect(() =>
+ readSharedAntigravityToken(
+ stub(() => {
+ throw new Error("security: User interaction is not allowed.");
+ })
+ )
+ ).toThrow("User interaction is not allowed");
+ });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 6. The projection invariant, end to end through the authority
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("isAvailable is exactly the `=== present` projection", () => {
+ it("holds for present, absent and failed, through a registered ApiKey provider", async () => {
+ const authority = new CredentialAuthority();
+ authority.register(keychainOnlyProvider());
+ const name = `readiness-${ENV_VAR}`;
+
+ // present — resolved from env.
+ process.env[ENV_VAR] = "sk-present";
+ expect(await expectProjection(authority, name)).toEqual({ readiness: "present" });
+
+ // absent — nothing anywhere, every store consulted and quiet.
+ delete process.env[ENV_VAR];
+ authority.invalidate(name);
+ expect(await expectProjection(authority, name)).toEqual({ readiness: "absent" });
+
+ // failed — the store could not be asked.
+ authority.invalidate(name);
+ enableKeychain();
+ runImpl = () => runResult(1, "", LOCKED_STDERR);
+ const failed = await quietly(() => expectProjection(authority, name));
+ expect(failed.readiness).toBe("failed");
+ });
+});
diff --git a/packages/cli/src/auth/credentials/types.blackbox.test.ts b/packages/cli/src/auth/credentials/types.blackbox.test.ts
new file mode 100644
index 00000000..87de25e9
--- /dev/null
+++ b/packages/cli/src/auth/credentials/types.blackbox.test.ts
@@ -0,0 +1,33 @@
+/**
+ * BLACK-BOX. Written by `gpt-6-astra` from the spec and a body-stripped `.d.ts`,
+ * with no access to this implementation. See
+ * `ai-docs/sessions/dev-feature-alibaba-subscript-20260917/tests/blackbox-results.md`.
+ *
+ * DO NOT edit an assertion to make it pass. Its value is that its author had
+ * never read the code; a repaired assertion is a regression test, not evidence.
+ * Adaptation on integration: import path only (`../contract/types` → `./types.js`).
+ *
+ * Second adaptation, on the port to the current tree: the file-scoped
+ * `useBlackboxEnv()` isolation (`test-helpers/blackbox-env.ts`) is not called
+ * here. T1 and T2 exercise a pure string function that reads no HOME, no
+ * environment and no network, so that harness has nothing to guard in this
+ * file, and the harness itself ships with the black-box suites that need it.
+ */
+import { describe, expect, test } from "bun:test";
+import { readinessDetail } from "./types.js";
+
+describe("credential diagnostics remain usable in the billing explanation", () => {
+ test("T1 a vault exception retains the reason the user can act on", () => {
+ expect(readinessDetail(new Error("1Password handshake denied"))).toContain(
+ "1Password handshake denied"
+ );
+ });
+ test("T2 multiline source errors become one bounded diagnostic line", () => {
+ const message = `Keychain locked\r\n${"SDK diagnostic detail\n".repeat(2_000)}`;
+ const detail = readinessDetail(new Error(message));
+ expect(typeof detail).toBe("string");
+ expect(detail).toContain("Keychain locked");
+ expect(detail).not.toMatch(/[\r\n]/);
+ expect(detail!.length).toBeLessThan(message.length);
+ });
+});
diff --git a/packages/cli/src/auth/credentials/types.ts b/packages/cli/src/auth/credentials/types.ts
index 9410dbda..b48cb4f1 100644
--- a/packages/cli/src/auth/credentials/types.ts
+++ b/packages/cli/src/auth/credentials/types.ts
@@ -17,6 +17,59 @@
* - `invalidate()` — drop any memoized resolution (after a TUI hydrate-on-add).
*/
+/**
+ * Three-valued credential readiness — "I could not ask" is NOT "there is
+ * nothing there".
+ *
+ * `isAvailable()` answers a boolean, and a boolean has exactly one slot for two
+ * different facts. Every resolution failure therefore collapsed into `false`,
+ * which reads downstream as "this user has no credential for this provider":
+ * the candidate is filtered out of the routing chain and a metered provider
+ * serves the request with no line printed. A locked Mac, a denied 1Password
+ * handshake or a keychain ACL the user declined would silently move a
+ * flat-rate subscriber onto pay-per-token.
+ *
+ * - `present` — a credential resolved (or none is required).
+ * - `absent` — every source was consulted and none holds one. A STABLE answer.
+ * - `failed` — a source could not be consulted at all. TRANSIENT, and it says
+ * nothing about whether the credential exists.
+ *
+ * `failed` still keeps a candidate out of the chain — a credential that will
+ * not resolve cannot sign a request either — so routing is unchanged. What is
+ * new is that the REASON survives to the caller. The same line the keychain
+ * engine draws (`{present, failed}` / `{value?, failed}`) and the same line the
+ * op source draws for denied handshakes, carried one layer further up.
+ */
+export type CredentialReadiness = "present" | "absent" | "failed";
+
+/** A readiness verdict, with a one-line diagnostic when it is `failed`. */
+export interface ReadinessResult {
+ readiness: CredentialReadiness;
+ /**
+ * Why the credential could not be resolved. Set only for `failed`, and NEVER
+ * key material — these strings reach stderr and the routing warning.
+ */
+ detail?: string;
+}
+
+/**
+ * A thrown value as ONE bounded line, for {@link ReadinessResult.detail}.
+ *
+ * Lives here, beside the type it serves, so the authority, the composite and
+ * every provider format a failure the same way — a second implementation of
+ * this is a second thing that can disagree. It is bounded because an SDK error
+ * can be a multi-line Rust struct dump, and pasting one into a routing warning
+ * buries the sentence that matters.
+ *
+ * Message text only. A credential source never puts key material in an error
+ * message, and this does not go looking for any.
+ */
+export function readinessDetail(err: unknown): string | undefined {
+ const line = (err instanceof Error ? err.message : String(err ?? "")).split("\n")[0].trim();
+ if (!line) return undefined;
+ return line.length > 200 ? `${line.slice(0, 199)}…` : line;
+}
+
export interface RequestAuthContext {
model: string;
forceRefresh?: boolean;
@@ -68,6 +121,23 @@ export interface CredentialProvider {
* server keeps running. Memoized: the SDK is touched at most once per provider.
*/
isAvailable(opts?: { allowOpPrompt?: boolean }): Promise<boolean>;
+ /**
+ * OPTIONAL three-valued readiness — implement it wherever this provider can
+ * tell "no credential" apart from "could not ask" (see
+ * {@link CredentialReadiness}).
+ *
+ * CONTRACT, and it is load-bearing: the authority projects
+ * `isAvailable(name)` as `describeReadiness(name).readiness === "present"`, so
+ * an implementation MUST agree with its own `isAvailable()` on that boundary
+ * or routing changes. The safe way to hold the contract is to define
+ * `isAvailable()` as the projection of this method rather than writing the
+ * two independently — every implementation here does.
+ *
+ * A provider that does not implement it is not wrong, only less informative:
+ * the authority falls back to `isAvailable()` and maps `false` to `absent`,
+ * which is exactly the behaviour that existed before.
+ */
+ describeReadiness?(opts?: { allowOpPrompt?: boolean }): Promise<ReadinessResult>;
/** ASYNC: the rich artifact for an outgoing request. Refreshes OAuth / pulls op:// internally. */
getRequestAuth(ctx: RequestAuthContext): Promise<RequestAuth>;
/** Drop any memoized resolution so the next read re-resolves (TUI hydrate-on-add). */