@linxiraos/pi-ai 1.2.1 → 1.3.0

package/dist/types/providers/systemone-server.d.ts

@@ -1,7 +1,9 @@
 import type { JudgmentRequest, JudgmentResult } from "../judgment/types.js";
+import type { JudgmentImageAssets } from "../judgment/wire.js";
 export interface SystemOneParsedRequest {
     modelId: string;
     request: JudgmentRequest;
+    imageAssets?: JudgmentImageAssets;
 }
 /** `POST /v1/systemone` response body; `cost` (USD) appears only when the route billed one. */
 export interface SystemOneResponseBody {
@@ -14,10 +16,12 @@ export interface SystemOneResponseBody {
     };
 }
 /**
- * Validate the routing-relevant parts of a System One request body.
+ * Validate the routing-relevant parts of a System One request body, including
+ * top-level embedded images and inline TypeSafe image assets.
  *
- * @throws {AIError.ValidationError} naming the offending field when `model`,
- * `state`, or `questions` is missing or malformed.
+ * @throws {AIError.ValidationError} when required routing fields are missing
+ * or malformed, supplied image data is invalid, or an asset uses multipart
+ * `part`, which this JSON ingress cannot read.
  */
 export declare function parseRequest(body: unknown): SystemOneParsedRequest;
 /** Re-encode a judgment result in TypeSafe's response shape. */

package/dist/types/providers/transform-messages.d.ts

@@ -9,6 +9,10 @@ import type { Api, AssistantMessage, Message, Model } from "../types.js";
  * MUST not push a normalized id past this bound.
  */
 export declare const MAX_TOOL_CALL_ID_LENGTH = 64;
+/** Replace unsupported tool-call ID characters and cap the result for strict replay providers. */
+export declare function normalizeToolCallId(id: string, maxLength?: number): string;
+/** Whether `id` already satisfies the strict 1–64 `[a-zA-Z0-9_-]` tool-call ID contract. */
+export declare function isValidToolCallId(id: string): boolean;
 /**
  * OpenAI Responses-family APIs mint composite tool ids (`call_id|item_id`);
  * opaque Chat Completions ids do not (openai-completions preserves same-model
@@ -25,12 +29,29 @@ export declare function isResponsesFamilyApi(api: Api | undefined): boolean;
 export declare function responsesCallComponent(id: string): string;
 export declare function appendDuplicateSuffix(originalId: string, suffix: string, maxLength: number): string;
 /**
- * Whether a tool-call name cannot belong to any declared tool: missing, empty,
- * longer than OpenAI's 128-character replay limit, or containing whitespace or
- * control characters (tool schemas never allow them; their presence means the
- * name slot carries invocation text).
+ * Whether a tool-call name cannot be replayed to the target: missing, empty,
+ * longer than its declaration limit, or containing a character outside its
+ * declaration charset. Models emit such names when the name slot carries
+ * invocation text (whitespace, NULs) or an invented internal URL (`proc://*`).
+ *
+ * Without a target, use the OpenAI Responses native-history constraints.
+ */
+export declare function isMalformedToolCallName(name: unknown, allowedName?: RegExp, maxLength?: number): boolean;
+/**
+ * Whether {@link transformMessages} drops `msg` from every replay: a turn cut
+ * off by `length` / `error` / `aborted` that carries no text and no tool call.
+ */
+export declare function shouldDropTruncatedThinkingOnlyAssistant(msg: AssistantMessage): boolean;
+/**
+ * Whether `msg` reaches a replay as an assistant turn, so it can be the latest
+ * surviving one: {@link sanitizeMalformedToolCalls} drops its malformed tool
+ * calls, then {@link shouldDropTruncatedThinkingOnlyAssistant} a truncated
+ * turn left with no text and no tool call. On an already sanitized list this
+ * is `!shouldDropTruncatedThinkingOnlyAssistant(msg)`. Pass the target `model`
+ * to apply its tool-name limits; without one, any provider-declarable name survives.
  */
-export declare function isMalformedToolCallName(name: unknown): boolean;
+export declare function isSurvivingAssistant(msg: AssistantMessage, model?: Model): boolean;
+export declare function isAnthropicMessagesModel(model: Model): model is Model<"anthropic-messages">;
 /**
  * Normalize tool call ID for cross-provider compatibility.
  * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.

package/dist/types/registry/oauth/google-antigravity.d.ts

@@ -1,5 +1,5 @@
 /**
- * Antigravity OAuth flow (Gemini 3, Claude, GPT-OSS via Google Cloud)
+ * Google Antigravity OAuth flow (Gemini, Claude, GPT-OSS via Google Cloud)
  * Uses different OAuth credentials than google-gemini-cli for access to additional models.
  */
 import type { AfterExchangeHook } from "../hooks/types.js";

package/dist/types/stream.d.ts

@@ -5,8 +5,6 @@ import type { GoogleGeminiCliOptions } from "./providers/google-gemini-cli.js";
 import type { GoogleVertexOptions } from "./providers/google-vertex.js";
 import type { Api, AssistantMessage, Context, Model, OptionsForApi, SimpleStreamOptions, ToolChoice } from "./types.js";
 import { AssistantMessageEventStream } from "./utils/event-stream.js";
-/** Strict official-Codex endpoint check; exact origin or a path boundary after {@link CODEX_BASE_URL}. */
-export declare function isOfficialCodexApiUrl(baseUrl: string | undefined): boolean;
 export declare function configureProviderMaxInFlightRequests(limits: Record<string, number> | undefined): void;
 export declare const __providerInFlightForTesting: {
     setRoot(root: string | undefined): void;

package/dist/types/types.d.ts

@@ -9,7 +9,7 @@ import type { ApiKey } from "./auth-retry.js";
 import type { OAuthRequestIdentity } from "./auth/types.js";
 import type { BedrockOptions } from "./providers/amazon-bedrock.js";
 import type { AnthropicOptions } from "./providers/anthropic.js";
-import type { FallbackParam, StopDetails } from "./providers/anthropic-wire.js";
+import type { FallbackParam, MessageCreateParamsStreaming, StopDetails } from "./providers/anthropic-wire.js";
 import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses.js";
 import type { CursorOptions } from "./providers/cursor.js";
 import type { AppleFoundationModelsOptions } from "./providers/apple-foundation-models.js";
@@ -267,6 +267,11 @@ export interface StreamOptions {
     frequencyPenalty?: number;
     maxTokens?: number;
     signal?: AbortSignal;
+    /**
+     * OpenAI chat-completions HTTP attempt budget. When set, transient provider
+     * errors are not replayed above the transport, so retries share this limit.
+     */
+    maxHttpAttempts?: number;
     apiKey?: string;
     /** @internal Stored credential row serving this request, when known. */
     credentialId?: number;
@@ -398,8 +403,6 @@ export interface StreamOptions {
     liveSteering?: LiveSteering;
     /** Canonical Codex compaction classification; ignored by other providers. */
     codexCompaction?: CodexCompactionRequestContext;
-    /** Codex Code Mode tool exposure snapshot emitted as `tool_namespaces_info` turn metadata; ignored by other providers. */
-    toolNamespacesInfo?: unknown;
     /**
      * Optional per-provider concurrent request cap for LLM stream calls. Keys are
      * provider ids (`model.provider`); positive numeric values cap in-flight
@@ -645,6 +648,13 @@ export interface ThinkingContent {
      * replay natively on another host.
      */
     summary?: boolean;
+    /**
+     * `true`: the block is narration — prose the model addressed to the user
+     * between tool calls, which the provider returned as a signed thinking block
+     * (Anthropic connector-text summarization). It stays a thinking block for
+     * replay; user-facing surfaces present it as answer text.
+     */
+    narration?: boolean;
 }
 export interface RedactedThinkingContent {
     type: "redactedThinking";
@@ -652,11 +662,12 @@ export interface RedactedThinkingContent {
 }
 /**
  * Anthropic server-side-fallback boundary marker persisted on assistant
- * turns whose provider request opted into
- * `AnthropicOptions.fallbacks`. Consumers other than the Anthropic
- * provider MUST ignore it — `transformMessages` strips the block on any
- * cross-provider hop and on non-official Anthropic replays, so downstream
- * converters never see it.
+ * turns whose response switched models mid-stream, whether the request
+ * opted into `AnthropicOptions.fallbacks` or a gateway opted in on its
+ * behalf. Consumers other than the Anthropic provider MUST ignore it —
+ * `transformMessages` strips the block on any non-Anthropic hop, and
+ * `convertAnthropicMessages` only puts it on the wire for an opted-in
+ * request to the official endpoint.
  */
 export interface AnthropicFallbackContent {
     type: "fallback";
@@ -983,6 +994,12 @@ export type AssistantRetryRecovery = {
 export interface ContextSnapshot {
     promptTokens: number;
     nonMessageTokens: number;
+    /**
+     * Estimated tool-schema tokens included in `nonMessageTokens` (0 when the
+     * model defers schemas server-side). Lets a later model whose schema policy
+     * differs rebase the provider anchor instead of inheriting its schemas.
+     */
+    toolSchemaTokens?: number;
     /** Estimated prompt tokens removed by local history rewrites after this provider snapshot was recorded. */
     historyRewriteTokensRemoved?: number;
     /**
@@ -1031,6 +1048,12 @@ export interface AssistantMessage {
      */
     serviceTier?: ServiceTier;
     usage: Usage;
+    /**
+     * Visible output tokens a history rewrite (shake) has since removed from
+     * `content`. `usage.output` still counts them, so a replay estimate subtracts
+     * them to keep the turn's reasoning without recharging the removed text.
+     */
+    elidedOutputTokens?: number;
     stopReason: StopReason;
     stopDetails?: StopDetails | null;
     errorMessage?: string;
@@ -1418,7 +1441,8 @@ export type AssistantMessageEvent = {
 export interface AnthropicFallbackCreditHandle {
     token: string;
     prefillClaim?: boolean | null;
-    params: unknown;
+    /** The refused request's body, replayed with the credit token on the fallback model. */
+    params: MessageCreateParamsStreaming;
     betas?: readonly string[];
     betaHeader?: string;
     expiresAt: number;

package/dist/types/utils/dsml-leak.d.ts

@@ -23,7 +23,9 @@ export declare function isDsmlLeakRecoveryTarget(model: Model): boolean;
  */
 export declare function stripDsmlToolMarkup(text: string): string | undefined;
 /**
- * Remove leaked DSML tool-call markup from `message`'s text blocks in place,
- * dropping blocks left empty. Returns true when anything was removed.
+ * Remove leaked DSML tool-call markup from an assistant message before commit,
+ * including reasoning blocks and turns with valid structured calls. Rewritten
+ * thinking with an opaque signature is discarded; OpenAI-compatible reasoning
+ * field names are replay markers, not signatures, and survive cleanup.
  */
 export declare function removeDsmlToolMarkupLeak(message: AssistantMessage): boolean;

package/dist/types/utils/narration.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantMessage } from "../types.js";
+/**
+ * The message as a user-facing surface should present it: every narration
+ * thinking block (see `ThinkingContent.narration`) becomes a text block, so it
+ * renders as part of the answer instead of folding into reasoning. Returns the
+ * input unchanged when it holds no narration. Display-only: replay must keep
+ * the original thinking blocks and their signatures.
+ */
+export declare function presentNarrationAsAnswer(message: AssistantMessage): AssistantMessage;

package/dist/types/utils/openai-http.d.ts

@@ -26,6 +26,8 @@ export interface OpenAIStreamRequestInit {
     body: unknown;
     signal: AbortSignal;
     fetch?: FetchImpl;
+    /** Override the default transport attempt budget for this request. */
+    maxAttempts?: number;
     /** Optional caller-specific gate composed with shared transport retry exclusions. */
     shouldRetryResponse?: (response: Response, bodyText: string) => boolean | Promise<boolean>;
     /**

package/dist/types/utils/request-body.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bytes of a request body as the server reads them: the `gzip`/`zstd`
+ * `Content-Encoding` applied by request compression is undone, any other
+ * encoding is returned untouched.
+ */
+export declare function decodeRequestBodyBytes(bytes: Uint8Array, contentEncoding: string | null): Uint8Array;
+/**
+ * Text of a string or byte request body after undoing its content encoding;
+ * `undefined` when the request has no such body (none, stream, form data).
+ */
+export declare function requestBodyText(init: RequestInit | undefined): string | undefined;

package/dist/types/utils/request-compression.d.ts

@@ -0,0 +1,21 @@
+import type { FetchImpl, Model } from "../types.js";
+/**
+ * Compresses request bodies from {@link model} to its provider's own endpoint
+ * when its catalog rules declare encodings the endpoint decodes
+ * (`request-encodings` / `endpoint-hosts` KDL axes). Long sessions resend
+ * multi-MB transcripts every turn, so upload time dominates time-to-first-token
+ * on ordinary uplinks.
+ *
+ * Install it beneath any body rewriter or signer (e.g. the cch attestation
+ * patch): those must see the uncompressed bytes. Other hosts, small bodies,
+ * bodies that already carry `Content-Encoding`, and `PI_REQUEST_COMPRESSION=0`
+ * pass through untouched. A possible rejection — the host's decode error, or a
+ * non-JSON 400/403/415 from a proxy in front of it — is resent uncompressed
+ * once; only when that resend succeeds is the encoding latched off for the
+ * host, so a genuine 400 never disables compression. When a non-JSON refusal
+ * recurs uncompressed with the same status and a non-JSON body, that status
+ * stops being re-checked for the host.
+ */
+export declare function wrapFetchForRequestCompression(base: FetchImpl, model: Model): FetchImpl;
+/** Test hook: clears every per-host latch. */
+export declare function resetRequestCompressionForTesting(): void;

package/dist/types/utils/tool-call-arguments.d.ts

@@ -5,7 +5,8 @@ export declare function parseToolCallArguments(json: string | undefined): ToolCa
  * Native Responses `function_call.arguments` to persist for replay.
  *
  * {@link parseToolCallArguments} repairs some invalid JSON (e.g. `"name": ,`) and the tool runs with the
- * repaired value; replay drops a call whose stored arguments do not parse, orphaning its output (#14155).
+ * repaired value; replay must carry what was executed (#14155), not the {@link invalidToolCallArguments}
+ * diagnostic it substitutes for stored arguments that do not parse (#15568).
  * Returns `raw` when it already parses or the arguments were unrepairable, else the executed arguments.
  */
 export declare function replayableToolCallArguments(raw: string, executed: ToolCall["arguments"]): string;

package/dist/types/utils/transport-fetch.d.ts

@@ -12,6 +12,14 @@ import type { Api, FetchImpl, Model } from "../types.js";
  * layer (three PI_REQ_DEBUG dumps for one request).
  */
 export declare function transportFetch(model: Model<Api>, fetchImpl: FetchImpl | undefined): FetchImpl;
+/**
+ * Origin of the last inference request {@link model} actually sent, after
+ * every dispatch-time rewrite (credential endpoints, env overrides, regional
+ * hosts); `undefined` before its first request.
+ */
+export declare function lastDispatchOrigin(model: Model<Api>): string | undefined;
+/** Test hook: forgets every recorded dispatch origin. */
+export declare function resetDispatchOriginsForTesting(): void;
 /** Options-bag form of {@link transportFetch}; returns `options` untouched when its fetch is already built. */
 export declare function withTransportFetch<T extends {
     fetch?: FetchImpl;

package/dist/types/utils.d.ts

@@ -1,4 +1,5 @@
 import type { ResponseInput } from "./providers/openai-responses-wire.js";
+export { normalizeToolCallId } from "./providers/transform-messages.js";
 import type { CacheRetention, OpenAIResponsesHistoryPayload, ProviderPayload } from "./types.js";
 export { isRecord } from "@linxiraos/pi-utils";
 /**
@@ -9,7 +10,6 @@ export { isRecord } from "@linxiraos/pi-utils";
  */
 export declare function getHeaderCaseInsensitive(headers: Record<string, string> | undefined, headerName: string): string | undefined;
 export declare function normalizeSystemPrompts(systemPrompt: readonly string[] | string | undefined | null): string[];
-export declare function normalizeToolCallId(id: string): string;
 type ResponsesToolItemIdPrefix = "fc" | "ctc";
 /** Preserve opaque call IDs for Responses replay while normalizing or generating the separate item ID. */
 export declare function normalizeResponsesToolCallId(id: string, itemPrefix?: ResponsesToolItemIdPrefix): {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-ai",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -145,18 +145,18 @@
 	},
 	"scripts": {
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "tsc -p tsconfig.json --noEmit",
 		"lint": "oxlint .",
 		"test": "bun test --parallel",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-omptype": "1.2.1",
-		"@linxiraos/pi-catalog": "1.2.1",
-		"@linxiraos/pi-natives": "1.2.1",
-		"@linxiraos/pi-utils": "1.2.1",
-		"@linxiraos/pi-wire": "1.2.1"
+		"@linxiraos/pi-omptype": "1.3.0",
+		"@linxiraos/pi-catalog": "1.3.0",
+		"@linxiraos/pi-natives": "1.3.0",
+		"@linxiraos/pi-utils": "1.3.0",
+		"@linxiraos/pi-wire": "1.3.0"
 	},
 	"devDependencies": {
 		"@types/bun": "1.4.3"

package/src/auth/cascade.ts

@@ -10,6 +10,7 @@ import type { CredentialPool } from "./pool";
 import type { CredentialSelector, OAuthResolutionResult } from "./select";
 import type {
 	AuthApiKeyOptions,
+	AuthPeekOptions,
 	AuthCredential,
 	AuthSource,
 	AuthSourceOptions,
@@ -275,9 +276,11 @@ export class KeyCascade implements KeysApi {
 	 * Used for model discovery where we only need to know if credentials exist
 	 * and get a best-effort token. GitHub Copilot's peek must preserve
 	 * enterprise routing metadata because discovery needs a structured
-	 * credential to reach the correct host.
+	 * credential to reach the correct host. With several stored accounts every
+	 * peek returns the same one, so credential-scoped discovery caches stay on
+	 * one namespace.
 	 */
-	async peek(provider: string): Promise<string | undefined> {
+	async peek(provider: string, options?: AuthPeekOptions): Promise<string | undefined> {
 		const runtimeKey = this.#deps.overrides.runtimeKey(provider);
 		if (runtimeKey) {
 			return runtimeKey;
@@ -292,19 +295,26 @@ export class KeyCascade implements KeysApi {
 
 		// Precedence: a deliberate OAuth/login credential wins, then an explicit env var,
 		// then a stored static api_key (which may be a stale broker-migrated copy) as a last resort.
-		const oauthSelection = this.#deps.selector.selectByType(provider, "oauth");
+		// Peek never refreshes, so only an unexpired OAuth access token is usable
+		// unless the caller only needs the account it names.
+		const now = Date.now();
+		const oauthSelection =
+			this.#deps.selector.selectByType(
+				provider,
+				"oauth",
+				undefined,
+				credential =>
+					credential.type === "oauth" && Number.isFinite(credential.expires) && credential.expires > now,
+			) ?? (options?.includeExpired ? this.#deps.selector.selectByType(provider, "oauth") : undefined);
 		if (oauthSelection) {
-			const expiresAt = oauthSelection.credential.expires;
-			if (Number.isFinite(expiresAt) && expiresAt > Date.now()) {
-				if (provider === "github-copilot") {
-					return JSON.stringify({
-						token: oauthSelection.credential.access,
-						enterpriseUrl: oauthSelection.credential.enterpriseUrl,
-						apiEndpoint: oauthSelection.credential.apiEndpoint,
-					});
-				}
-				return oauthSelection.credential.access;
+			if (provider === "github-copilot") {
+				return JSON.stringify({
+					token: oauthSelection.credential.access,
+					enterpriseUrl: oauthSelection.credential.enterpriseUrl,
+					apiEndpoint: oauthSelection.credential.apiEndpoint,
+				});
 			}
+			return oauthSelection.credential.access;
 		}
 
 		const loginApiKeySelection = this.#deps.selector.selectByType(

package/src/auth/pool.ts

@@ -182,7 +182,7 @@ export class CredentialPool implements CredentialsApi {
 	 * The store is shared across every zeta process, but the pool is an
 	 * in-process cache refreshed only by this process's own writes. Without
 	 * this a long-running session ranks a stale pool for its whole lifetime:
-	 * `zeta-c auth` in another terminal is invisible, rotation reports no usable
+	 * `zetacode auth` in another terminal is invisible, rotation reports no usable
 	 * sibling while a freshly added account sits unblocked in SQLite, and the
 	 * turn degrades to the fallback chain. The auth-broker path already polls;
 	 * direct-store sessions had no equivalent.
@@ -719,7 +719,7 @@ export class CredentialPool implements CredentialsApi {
 	}
 
 	/**
-	 * Disabled credential tombstones for display surfaces (`zeta-c usage`,
+	 * Disabled credential tombstones for display surfaces (`zetacode usage`,
 	 * broker `GET /v1/credentials/disabled`). Empty when the backing store
 	 * keeps no tombstones or the remote broker predates the endpoint.
 	 */
@@ -732,7 +732,7 @@ export class CredentialPool implements CredentialsApi {
 	 * Force the backing store to revalidate its credential snapshot, then
 	 * reload. Remote broker stores re-fetch the snapshot; local stores are
 	 * always current, so only the reload runs. Callers that pair live
-	 * per-credential data with stored identities (`zeta-c usage`) use this so a
+	 * per-credential data with stored identities (`zetacode usage`) use this so a
 	 * disk-cached snapshot cannot misattribute fresh reports.
 	 */
 	async revalidate(): Promise<void> {

package/src/auth/refresh.ts

@@ -1,4 +1,4 @@
-import { logger } from "@linxiraos/pi-utils";
+import { logger, postmortem } from "@linxiraos/pi-utils";
 import * as AIError from "../error";
 import { getOAuthProvider, normalizeOAuthCredentialExpiry, refreshOAuthToken } from "../registry/oauth";
 import type { OAuthCredentials, OAuthProvider } from "../registry/oauth/types";
@@ -101,6 +101,9 @@ export class OAuthRefresher {
 	#oauthCredentialRefreshInFlight: Map<number, Promise<OAuthCredentials>> = new Map();
 	/** Access token this process last minted per credential id. */
 	#recentMints = new Map<number, { provider: string; access: string; at: number }>();
+	#pendingRefreshes = new Set<Promise<unknown>>();
+	#cancelRefreshCleanup?: () => void;
+	#shuttingDown = false;
 
 	constructor(deps: OAuthRefresherDeps) {
 		this.#deps = deps;
@@ -148,7 +151,33 @@ export class OAuthRefresher {
 	/**
 	 * Refresh one stored OAuth credential under durable row ownership.
 	 */
-	async refreshStored<T extends OAuthCredential = OAuthCredential>(
+	refreshStored<T extends OAuthCredential = OAuthCredential>(
+		provider: string,
+		options: StoredOAuthRefreshOptions<T>,
+	): Promise<StoredOAuthRefreshResult<T>> {
+		if (this.#shuttingDown) return Promise.reject(new AIError.AbortError("OAuth refresh stopped during shutdown"));
+		this.#cancelRefreshCleanup ??= postmortem.register("oauth-refresh", () => this.#drainRefreshes(), {
+			exitOnly: true,
+		});
+		const pending = this.#refreshStored(provider, options);
+		this.#pendingRefreshes.add(pending);
+		const settled = () => {
+			this.#pendingRefreshes.delete(pending);
+			if (this.#pendingRefreshes.size === 0 && !this.#shuttingDown) {
+				this.#cancelRefreshCleanup?.();
+				this.#cancelRefreshCleanup = undefined;
+			}
+		};
+		void pending.then(settled, settled);
+		return pending;
+	}
+
+	async #drainRefreshes(): Promise<void> {
+		this.#shuttingDown = true;
+		await Promise.allSettled(this.#pendingRefreshes);
+	}
+
+	async #refreshStored<T extends OAuthCredential = OAuthCredential>(
 		provider: string,
 		options: StoredOAuthRefreshOptions<T>,
 	): Promise<StoredOAuthRefreshResult<T>> {
@@ -158,6 +187,7 @@ export class OAuthRefresher {
 		let leasedCredentialId: number | undefined;
 
 		while (leaseStore) {
+			if (this.#shuttingDown) throw new AIError.AbortError("OAuth refresh stopped during shutdown");
 			if (options.signal?.aborted) throw new AIError.AbortError("OAuth refresh ownership aborted by caller");
 			const rows = this.#deps.store.listAuthCredentials(provider);
 			this.#deps.pool.replace(
@@ -240,6 +270,9 @@ export class OAuthRefresher {
 			if (options.canRefresh && !options.canRefresh(current)) {
 				return { credential: current, refreshed: false, removed: false };
 			}
+			if (this.#shuttingDown || options.signal?.aborted) {
+				throw new AIError.AbortError("OAuth refresh stopped before token exchange");
+			}
 			const serialized = serializeCredential(provider, current);
 			if (!serialized) return { credential: current, refreshed: false, removed: false };
 
@@ -495,13 +528,7 @@ export class OAuthRefresher {
 				forceRefresh,
 				signal,
 				refresh: (current, refreshSignal) =>
-					this.#requestOAuthCredentialRefresh(
-						provider,
-						current,
-						credentialId,
-						signal && refreshSignal ? AbortSignal.any([signal, refreshSignal]) : (signal ?? refreshSignal),
-						reason,
-					),
+					this.#requestOAuthCredentialRefresh(provider, current, credentialId, refreshSignal, reason),
 				isDefinitiveFailure: error => AIError.isDefinitiveOAuthFailure(String(error)),
 				disabledCause: error => `oauth refresh failed: ${String(error)}`,
 			});
@@ -564,9 +591,9 @@ export class OAuthRefresher {
 				refreshPromise = refreshOAuthToken(provider as OAuthProvider, credential, signal);
 			}
 		}
-		// Bound the refresh so a slow/hanging token endpoint cannot stall credential selection.
-		// Caller-driven abort jumps the gun on the timeout — the agent's ESC must
-		// take priority over the floor timeout.
+		// The caller may stop awaiting a refresh, but the leased token exchange
+		// must finish and persist any rotated token. Only the operation timeout
+		// aborts the exchange itself.
 		const cancellation = Promise.withResolvers<never>();
 		let onAbort: (() => void) | undefined;
 		const timeout = setTimeout(

package/src/auth/select.ts

@@ -144,7 +144,11 @@ export class CredentialSelector {
 	/**
 	 * Selects a credential of the specified type for a provider.
 	 * Returns both the credential and its index in the original array (for updates/removal).
-	 * Uses deterministic hashing for session stickiness and skips blocked credentials when possible.
+	 * With `sessionId` the scan starts at the session's hashed index; without one it starts at the
+	 * first stored credential and never advances round-robin. Model discovery peeks through this,
+	 * and credential-scoped catalogs (e.g. GitHub Copilot) key their cache rows on the credential
+	 * picked, so a rotating pick would read another account's cache namespace on every pass.
+	 * Blocked credentials are skipped when possible.
 	 */
 	selectByType<T extends AuthCredential["type"]>(
 		provider: string,
@@ -171,7 +175,9 @@ export class CredentialSelector {
 		if (credentials.length === 1) return credentials[0];
 
 		const providerKey = providerTypeKey(provider, type);
-		const order = this.#getCredentialOrder(providerKey, sessionId, credentials.length);
+		const order = sessionId
+			? this.#getCredentialOrder(providerKey, sessionId, credentials.length)
+			: credentials.map((_, index) => index);
 		const fallback = credentials[order[0]];
 
 		for (const idx of order) {

package/src/auth/types.ts

@@ -112,7 +112,7 @@ export interface StoredCredentialBlock {
 /**
  * Identity slice of a disabled (soft-deleted) credential tombstone — cause and
  * account identity only, never token material. Surfaced so auto-disabled
- * accounts (e.g. an expired Anthropic OAuth grant) stay visible in `zeta-c usage`
+ * accounts (e.g. an expired Anthropic OAuth grant) stay visible in `zetacode usage`
  * instead of silently vanishing until the user notices missing quota.
  */
 export interface DisabledCredentialSummary {
@@ -707,6 +707,16 @@ export interface AuthSourceOptions {
 	env?: "dedicated" | "aliases" | "none";
 }
 
+/** Options for {@link KeysApi.peek}. */
+export interface AuthPeekOptions {
+	/**
+	 * Fall back to an expired OAuth access token when no stored account holds an
+	 * unexpired one. Only for reads that never send the token, e.g. keying an
+	 * offline model-cache lookup on the account it names.
+	 */
+	includeExpired?: boolean;
+}
+
 /** Where a provider's auth comes from ({@link CredentialOrigin}) plus whether any leg holds a concrete key. */
 export interface AuthSource extends CredentialOrigin {
 	/** False when the only auth is an ambient AUTHENTICATED_SENTINEL source (AWS profile, ADC). */
@@ -830,7 +840,7 @@ export interface CredentialsApi {
 	 * Force the backing store to revalidate its credential snapshot, then
 	 * reload. Remote broker stores re-fetch the snapshot; local stores are
 	 * always current, so only the reload runs. Callers that pair live
-	 * per-credential data with stored identities (`zeta-c usage`) use this so a
+	 * per-credential data with stored identities (`zetacode usage`) use this so a
 	 * disk-cached snapshot cannot misattribute fresh reports.
 	 */
 	revalidate(): Promise<void>;
@@ -889,7 +899,7 @@ export interface CredentialsApi {
 	 */
 	disable(id: number, disabledCause: string): Promise<boolean>;
 	/**
-	 * Disabled credential tombstones for display surfaces (`zeta-c usage`,
+	 * Disabled credential tombstones for display surfaces (`zetacode usage`,
 	 * broker `GET /v1/credentials/disabled`). Empty when the backing store
 	 * keeps no tombstones or the remote broker predates the endpoint.
 	 */
@@ -941,9 +951,10 @@ export interface KeysApi {
 	 * Peek at API key for a provider without refreshing OAuth tokens.
 	 * Used for model discovery where we only need to know if credentials exist
 	 * and get a best-effort token. For GitHub Copilot we preserve enterprise
-	 * routing metadata so discovery can hit the correct host.
+	 * routing metadata so discovery can hit the correct host. Repeated peeks
+	 * return the same stored credential; they never rotate accounts.
 	 */
-	peek(provider: string): Promise<string | undefined>;
+	peek(provider: string, options?: AuthPeekOptions): Promise<string | undefined>;
 	/** Resolve the first active auth source by precedence without refreshing credentials. */
 	source(provider: string, options?: AuthSourceOptions): AuthSource | undefined;
 	/**