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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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>): Keychainif (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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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). */