@linxiraos/pi-ai 1.1.27 → 1.2.1

package/CHANGELOG.md

@@ -1,30 +1,8 @@
-# Changelog
-
 ## [Unreleased]
 
-## [1.1.27] - 2026-10-07
-
-- 版本线推进至 1.1.27；本版无独立用户可见变化。
-
-### Changed
-
-- Reduced CPU spent on thinking-loop detection while streaming long reasoning ([#14284](https://github.com/can1357/oh-my-pi/pull/14284) by [@abilliontokens](https://github.com/abilliontokens)).
-- Added `recordAffinity: false` to credential resolution options, selecting as the session would without pinning the choice to that session ([#14512](https://github.com/can1357/oh-my-pi/pull/14512) by [@will-bogusz](https://github.com/will-bogusz))
-
-### Fixed
-
-- Fixed replayed Responses and Codex history, including persisted Codex user/developer and assistant items, sending `detail: "original"` images to endpoints whose `supportsImageDetailOriginal` is off ([#13687](https://github.com/can1357/oh-my-pi/pull/13687) by [@alphastorm](https://github.com/alphastorm)).
-- Fixed thinking in turns kept after Anthropic native compaction being rejected or dropped on the next request ([#14251](https://github.com/can1357/oh-my-pi/pull/14251) by [@will-bogusz](https://github.com/will-bogusz))
-- Fixed Claude usage being re-polled every 10 seconds while Anthropic rate-limits the account; a failed refresh now waits a minute before trying again ([#14515](https://github.com/can1357/oh-my-pi/pull/14515) by [@will-bogusz](https://github.com/will-bogusz))
-- Fixed Devin requests skipping the `onPayload` hook, so payload capture now sees each Devin chat request and a returned replacement is what gets sent ([#14506](https://github.com/can1357/oh-my-pi/pull/14506) by [@will-bogusz](https://github.com/will-bogusz))
-- An OpenAI Responses turn whose connection drops mid-stream can now recover the finished answer from the provider (on hosts that store results, such as Muse Code) instead of re-running the whole turn and discarding the reasoning already done. Storage is opt-in: pass `storeResponses: true`, set `PI_MUSE_STORE_RESPONSES=1`, or set a process-wide default with `configureProviderStoreResponses` ([#14293](https://github.com/can1357/oh-my-pi/pull/14293) and [#14534](https://github.com/can1357/oh-my-pi/pull/14534) by [@abilliontokens](https://github.com/abilliontokens)).
-- Fixed the auth broker exiting when a background OAuth refresh sweep cannot read the credential store; the failure is now logged and the next sweep retries ([#14538](https://github.com/can1357/oh-my-pi/issues/14538))
-- Fixed Anthropic OAuth billing headers changing during developer-first sessions and side turns, preserving the prompt-cache prefix ([#14495](https://github.com/can1357/oh-my-pi/issues/14495)).
-- Fixed OpenAI-compatible chat-completions gateways recording completed turns as client-cancelled because the connection closed before their `[DONE]` sentinel arrived ([#14481](https://github.com/can1357/oh-my-pi/issues/14481)).
-
-## [1.1.25] - 2026-10-03
+## [1.2.0] - 2026-10-12
 
-- 版本线推进至 1.1.25；本版无独立用户可见变化。
+- 版本线推进至 1.2.0；本版无独立用户可见变化。
 
 ## [1.1.24] - 2026-10-03
 

package/README.md

@@ -1043,7 +1043,7 @@ The default inference role must hold either `SNOWFLAKE.CORTEX_USER` or the narro
 
 For PAT authentication, set both `SNOWFLAKE_ACCOUNT` and `SNOWFLAKE_PAT`. Prefer a short-lived PAT restricted to a dedicated inference role and the required user-scoped network allowlist; do not disable network-policy enforcement. See [Snowflake PAT setup](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) and [local-application OAuth](https://docs.snowflake.com/en/user-guide/oauth-local-applications).
 
-Claude models use `/api/v2/cortex/v1/messages`; OpenAI models use `/api/v2/cortex/v1/chat/completions`. Both reuse omp's streaming transports and local tool execution. The 15 bundled models are a documented roster, not an account entitlement check: availability still depends on Cortex REST API enablement, role grants, model allowlists, and region. If authentication succeeds but Cortex returns `003001` ("This account is not allowed to access this endpoint"), Snowflake has not enabled Cortex REST for the account. [Self-service trial accounts disable AI features until a credit card is added](https://docs.snowflake.com/en/user-guide/admin-trial-account#label-trial-account-ai-features) (adding one does not end the trial); REST access can remain disabled even after AI SQL functions work, in which case Snowflake support must enable it. Cross-region inference requires an account administrator's explicit decision. `omp models snowflake --json` lists available models only after credentials are configured.
+Claude models use `/api/v2/cortex/v1/messages`; OpenAI models use `/api/v2/cortex/v1/chat/completions`. Both reuse omp's streaming transports and local tool execution. The 15 bundled models are a documented roster, not an account entitlement check: availability still depends on Cortex REST API enablement, role grants, model allowlists, and region. If authentication succeeds but Cortex returns `003001` ("This account is not allowed to access this endpoint"), Snowflake has not enabled Cortex REST for the account. [Self-service trial accounts disable AI features until a credit card is added](https://docs.snowflake.com/en/user-guide/admin-trial-account#label-trial-account-ai-features) (adding one does not end the trial); REST access can remain disabled even after AI SQL functions work, in which case Snowflake support must enable it. Cross-region inference requires an account administrator's explicit decision. `zetacode models snowflake --json` lists available models only after credentials are configured.
 
 This provider uses the [public, account-billed Cortex REST API](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-rest-api). CoCo-subscription coverage is unverified. Catalog prices are per-million-token estimates from [Consumption Table 6(b)](https://www.snowflake.com/legal-files/CreditConsumptionTable.pdf) at [$2 per AI Credit](https://docs.snowflake.com/en/user-guide/snowflake-cortex/pricing) for on-demand global routing, not your contract price. Output is capped at the REST API's documented 16,384-token maximum; context windows are conservative AI_COMPLETE limits, not verified REST maxima. Cortex compatibility rules limit explicit cache retention to five minutes. Paste an account identifier or current Snowsight link; legacy `app.snowflake.com/<region>/<locator>` links are rejected because they don't map uniformly to an account host.
 

package/dist/types/auth/affinity.d.ts

@@ -1,4 +1,4 @@
-import type { AuthCredential, OAuthCredential, SessionsApi } from "./types.js";
+import type { AuthCredential, OAuthCredential, SessionRestrictionLease, SessionsApi } from "./types.js";
 import type { AuthCredentialStore } from "./store.js";
 import type { CredentialPool } from "./pool.js";
 import type { KeyOverrides } from "./cascade.js";
@@ -13,10 +13,31 @@ export type SessionCredential = {
     /** Set only by the public user-facing pin API; automatic warm affinity leaves it absent. */
     explicit?: true;
 };
+/** One installed restriction: the allowed OAuth identity keys and the lease that lifts it. */
+type SessionRestriction = {
+    readonly allowed: ReadonlySet<string>;
+    readonly lease: SessionRestrictionLease;
+};
+/**
+ * Provider → session id → installed restriction. Owned by `AuthStorage` so
+ * restrictions outlive store replacement, which rebuilds every store-bound
+ * module (pins included) around the same identities.
+ */
+export type SessionRestrictions = Map<string, Map<string, SessionRestriction>>;
 /** Session → credential affinity (pins), persisted in the store cache. */
 export declare class SessionAffinity implements SessionsApi {
     #private;
-    constructor(store: AuthCredentialStore, pool: CredentialPool, overrides: KeyOverrides);
+    constructor(store: AuthCredentialStore, pool: CredentialPool, overrides: KeyOverrides, restrictions: SessionRestrictions);
+    restrict(provider: string, sessionId: string, identityKeys: readonly string[]): SessionRestrictionLease;
+    unrestrict(provider: string, sessionId: string, lease: SessionRestrictionLease): void;
+    /** True when {@link restrict} limits `sessionId` for `provider`. */
+    isRestricted(provider: string, sessionId: string | undefined): boolean;
+    /**
+     * True when `credential` may serve `sessionId`: always for an unrestricted
+     * session, otherwise only an OAuth credential whose identity key is allowed.
+     */
+    allows(provider: string, sessionId: string | undefined, credential: AuthCredential): boolean;
+    permits(provider: string, sessionId: string, credentialId: number): boolean;
     /** Drop every pin for a provider, both in memory and in the persisted cache. */
     clearProvider(provider: string): void;
     /** Drop only this in-memory session pin after OAuth selection falls through. */
@@ -33,7 +54,11 @@ export declare class SessionAffinity implements SessionsApi {
      * rewrites were pure database churn.
      */
     record(provider: string, sessionId: string | undefined, type: AuthCredential["type"], index: number, lastUsedAtMs?: number, explicit?: boolean): void;
-    /** Retrieves the last credential used by a session. */
+    /**
+     * Retrieves the last credential used by a session. A restricted session
+     * never sees a pin outside its allowlist — inherited, restored, or recorded
+     * before the restriction — so it re-ranks inside the allowlist instead.
+     */
     get(provider: string, sessionId: string | undefined): SessionCredential | undefined;
     /** Clears the last credential used by a session for a provider. */
     clear(provider: string, sessionId: string | undefined): void;
@@ -55,14 +80,15 @@ export declare class SessionAffinity implements SessionsApi {
         restoredAtMs?: number;
     }): boolean;
     /**
-     * Copy every stored credential affinity from one live session to another.
+     * Copy stored credential affinities from one live session to another.
      *
      * The target receives its own sticky entries, so request resolution, usage
      * blocking, credential rotation, metadata, and persisted pins all continue
      * through the target session id without retaining a live dependency on the
-     * source session.
+     * source session. `include` limits the copy to the providers it accepts,
+     * given whether the source's affinity is an explicit user pin.
      */
-    inherit(sourceSessionId: string, targetSessionId: string): number;
+    inherit(sourceSessionId: string, targetSessionId: string, include?: (provider: string, explicit: boolean) => boolean): number;
     /**
      * Release a session's sticky credential so its next `KeyCascade.get` call
      * re-runs native pool ranking. This never blocks or penalizes the released
@@ -71,3 +97,4 @@ export declare class SessionAffinity implements SessionsApi {
      */
     release(provider: string, sessionId: string): boolean;
 }
+export {};

package/dist/types/auth/cascade.d.ts

@@ -2,12 +2,20 @@ import { type ApiKeyResolver, type ResolvedApiKey } from "../auth-retry.js";
 import type { SessionAffinity } from "./affinity.js";
 import type { CredentialPool } from "./pool.js";
 import type { CredentialSelector } from "./select.js";
-import type { AuthApiKeyOptions, AuthCredential, AuthSource, AuthSourceOptions, KeysApi, LimitsApi, OAuthRequestIdentity } from "./types.js";
+import type { AuthApiKeyOptions, AuthCredential, AuthSource, AuthSourceOptions, KeysApi, LimitsApi } from "./types.js";
 /** Runtime (--api-key) and config (models.yml) key overrides plus the config-value resolver. */
 export declare class KeyOverrides {
     #private;
     constructor(resolver?: (config: string) => Promise<string | undefined>);
     has(provider: string): boolean;
+    /**
+     * Whether an override replaces OAuth for a session. Any override does for an
+     * unrestricted session. A restricted session skips the runtime key, but a
+     * config key still blocks OAuth: it marks the provider's endpoint (often a
+     * proxy) as taking that key, so the session fails closed instead of sending
+     * a pooled OAuth token there (see `KeyCascade.get`).
+     */
+    suppressesOAuth(provider: string, restricted: boolean): boolean;
     runtimeKey(provider: string): string | undefined;
     configKey(provider: string): string | undefined;
     /** Config value consulted only after stored OAuth/login credentials. */
@@ -121,15 +129,29 @@ export declare class KeyCascade implements KeysApi {
      * credential to reach the correct host.
      */
     peek(provider: string): Promise<string | undefined>;
-    /** Resolve a bearer together with the stored row that supplied it. */
+    /**
+     * Resolve a bearer together with the stored row that supplied it, for a request.
+     * Same precedence as {@link KeyCascade.get}, but rejects with
+     * {@link AIError.OAuthRefreshUnavailableError} (transient, retryable) when OAuth
+     * refresh failed with a retryable error and no other permitted source could serve
+     * the request, so request paths retry instead of reporting a missing key.
+     */
     getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
     /**
      * Get API key for a provider.
      * Priority (first match wins): runtime override, config override, OAuth,
      * login API key, environment variable, another stored API key, then the
      * lowest-tier OMP compat mirror.
+     * login API key, environment variable, then another stored API key.
+     * A session restricted by `sessions.restrict` resolves only its allowed
+     * OAuth accounts and throws {@link AIError.MissingApiKeyError} when none
+     * can serve or a config key (a models.yml `apiKey`, often for a proxy
+     * `baseUrl`) owns the provider, rather than using any other credential.
+     * A transient OAuth refresh failure resolves `undefined`, so availability
+     * probes move on to their next candidate; request paths use
+     * {@link KeyCascade.getWithCredential}, which surfaces it.
      */
-    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions, onCredentialId?: (id: number, identity?: OAuthRequestIdentity) => void): Promise<string | undefined>;
+    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
     /**
      * Build an {@link ApiKeyResolver} backed by this storage, implementing the
      * central a/b/c auth-retry policy:

package/dist/types/auth/oauth.d.ts

@@ -37,9 +37,11 @@ export declare class OAuthAccounts implements OAuthApi {
      * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
      * scenarios, prefer API-key resolution.
      *
-     * Returns `undefined` when no OAuth credential is available, the
-     * credential fails to refresh, or runtime/config overrides have replaced
-     * OAuth with an explicit API key.
+     * Returns `undefined` when no usable OAuth credential is available
+     * (none stored, or every one definitively failed to refresh) or
+     * runtime/config overrides have replaced OAuth with an explicit API key.
+     * Rejects with {@link AIError.OAuthRefreshUnavailableError} (transient,
+     * retryable) when a retryable refresh failure left no usable credential.
      */
     access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     /**
@@ -65,9 +67,10 @@ export declare class OAuthAccounts implements OAuthApi {
      * Resolve one stored OAuth credential by its durable storage row id.
      *
      * Unlike the normal session resolver, this method never ranks, rotates, or
-     * falls back to sibling credentials. A forced refresh re-mints only the
-     * requested row, preserving exact-account affinity for operations whose
-     * provenance and policy boundary are tied to one workspace.
+     * falls back to sibling credentials. A generic forced refresh re-mints only the
+     * requested row; with `refreshReason: "auth-recovery"` it may instead reuse a
+     * still-usable recent mint of that row. Either way exact-account affinity holds
+     * for operations whose provenance and policy boundary are tied to one workspace.
      *
      * Returns `undefined` when the row does not exist for `provider` or an
      * explicit runtime/config API-key override suppresses OAuth.

package/dist/types/auth/policy.d.ts

@@ -14,6 +14,7 @@ export declare class AccountPolicies {
      */
     replace(policies: AuthAccountPolicies, defaultReservePct: number | undefined, storedCredentials?: ReadonlyMap<string, readonly AuthCredential[]>): void;
     validateUsageCapability(provider: string, canFetchUsage: boolean): void;
+    /** Throw on ambiguous selectors for `provider`; a selector whose account is absent is inert and warns once. */
     validateFor(provider: string, credentials: readonly AuthCredential[]): void;
     /**
      * Return the configured account policy matching an OAuth identity.

package/dist/types/auth/refresh.d.ts

@@ -1,7 +1,6 @@
 import type { OAuthCredentials } from "../registry/oauth/types.js";
 import type { Provider } from "../types.js";
 import { type CredentialPool } from "./pool.js";
-import type { AccountPolicies } from "./policy.js";
 import { type AuthCredentialStore } from "./store.js";
 import { type AuthCredentialSnapshotEntry, type AuthStorageOptions, type OAuthCredential, type OAuthRefreshByIdOptions, type OAuthRefreshReason, type StoredOAuthRefreshOptions, type StoredOAuthRefreshResult } from "./types.js";
 /**
@@ -30,8 +29,8 @@ export declare function mergeRefreshedCredential<T extends OAuthCredential>(curr
 export interface OAuthRefresherDeps {
     store: AuthCredentialStore;
     pool: CredentialPool;
-    policies: AccountPolicies;
     override?: AuthStorageOptions["refreshOAuthCredential"];
+    overrideMints?: AuthStorageOptions["refreshOAuthCredentialMints"];
 }
 /** Single-flighted, lease-guarded OAuth refresh with compare-and-set persistence. */
 export declare class OAuthRefresher {

package/dist/types/auth/select.d.ts

@@ -8,7 +8,7 @@ import { type CredentialPool } from "./pool.js";
 import { type ApiKeySelection, type OAuthSelection } from "./rank.js";
 import { type OAuthRefresher } from "./refresh.js";
 import type { AuthCredentialStore } from "./store.js";
-import type { ApiKeyCredential, AuthApiKeyOptions, AuthCredential, OAuthCredential } from "./types.js";
+import { type ApiKeyCredential, type AuthApiKeyOptions, type AuthCredential, type OAuthCredential } from "./types.js";
 import type { UsageService } from "./usage.js";
 /** Temporary block after a transient OAuth refresh failure. */
 export declare const OAUTH_REFRESH_FAILURE_BACKOFF_MS: number;
@@ -32,6 +32,8 @@ export type TryOAuthOptions = {
     blockScopes?: readonly string[];
     /** When false, a definitive failure of THIS credential returns undefined instead of falling back to the ranked/round-robin selector (target-only resolution). */
     allowFallback?: boolean;
+    /** Receives a non-definitive refresh failure that left this credential unusable; the caller filters for retryable ones. */
+    onTransientRefreshFailure?: (error: unknown) => void;
 };
 /** Services consulted by CredentialSelector for policy, usage, blocks, refresh, and session affinity. */
 export interface CredentialSelectorDeps {
@@ -69,9 +71,9 @@ export declare class CredentialSelector {
      * 1. strict: unblocked credentials only, usage limits respected, plan
      *    filter enforced (when any account is confirmed eligible);
      * 2. plan-fitting last resort: same plan filter, but blocked/exhausted
-     *    accounts are allowed (blocked candidates rank earliest-unblocking
-     *    first) so the caller gets real usage-limit semantics from the wire
-     *    instead of a missing key;
+     *    accounts are allowed (an explicit session pin first, then blocked
+     *    candidates earliest-unblocking first) so the caller gets real
+     *    usage-limit semantics from the wire instead of a missing key;
      * 3. unfiltered last resort: the plan filter matched nothing usable —
      *    skip it and try every account once; the server is the final arbiter
      *    of model access.

package/dist/types/auth/sqlite-credential-store.d.ts

@@ -7,7 +7,7 @@
 import type { Database } from "bun:sqlite";
 import { isSqliteBusyError, isSqliteCorruptionError } from "@linxiraos/pi-utils";
 import type { AuthCredentialStore, CredentialRefreshLeaseFence } from "./store.js";
-import type { AuthCredential, DisabledCredentialSummary, StoredAuthCredential, StoredCredentialBlock } from "./types.js";
+import type { AuthCredential, DisabledCredentialSummary, OAuthCredential, StoredAuthCredential, StoredCredentialBlock } from "./types.js";
 import type { OAuthCredentials } from "../registry/oauth/types.js";
 import type { ClientUsageReport, ClientUsageSummary, UsageHistoryEntry, UsageHistoryQuery } from "../usage.js";
 export declare const USAGE_REPORT_TTL_MS: number;
@@ -18,7 +18,26 @@ type SerializedCredentialRecord = {
 };
 export { isSqliteBusyError, isSqliteCorruptionError };
 export declare function serializeCredential(provider: string, credential: AuthCredential): SerializedCredentialRecord | null;
+/**
+ * Identity key of a credential: the `identityKey` that broker snapshots carry
+ * and that broker account pools and `sessions.restrict` match, such as
+ * `email:<address>|org:<id>` for org-scoped providers. `null` for an API key or
+ * an OAuth credential without any account, email, project, or org identity.
+ */
 export declare function resolveCredentialIdentityKey(provider: string, credential: AuthCredential): string | null;
+/**
+ * Whether upserting `incoming` replaces the active row holding `existing` (stored
+ * under `existingIdentityKey`) instead of inserting a new row beside it.
+ */
+export declare function matchesReplacementCredential(provider: string, existing: AuthCredential | null, existingIdentityKey: string | null, incoming: AuthCredential): boolean;
+/**
+ * Whether two OAuth credentials belong to the same account of the same organization,
+ * whichever identity key each is stored under. The email decides when both carry one;
+ * otherwise a matching account id does, unless it is the organization's own id (a
+ * ChatGPT workspace id shared by every member). Project ids are shared between users
+ * (every consumer Antigravity login has the same one) and never count.
+ */
+export declare function isSameOAuthAccount(a: OAuthCredential, b: OAuthCredential): boolean;
 /**
  * Default SQLite-backed implementation of {@link AuthCredentialStore}.
  *
@@ -60,6 +79,7 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     deleteCachePrefix(prefix: string): void;
     cleanExpiredCache(): void;
     getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    getCredentialBlockScopes(credentialId: number, providerKey: string): Map<string, number>;
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     upsertCredentialBlock(block: StoredCredentialBlock): void;
     deleteCredentialBlock(credentialId: number, providerKey: string, blockScope: string): void;

package/dist/types/auth/store.d.ts

@@ -71,6 +71,12 @@ export interface CredentialCacheStore {
 export interface CredentialBlockStore {
     /** Non-expired block for one (credential, providerKey, scope) key, or undefined. */
     getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    /**
+     * Non-expired blocks for one credential and providerKey, keyed by block
+     * scope (`""` is unscoped), in one read. Optional: selectors fall back to
+     * {@link CredentialBlockStore.getCredentialBlock} per scope when absent.
+     */
+    getCredentialBlockScopes?(credentialId: number, providerKey: string): ReadonlyMap<string, number>;
     /** Earliest time a shared-store block should be eligible for live-usage reconciliation. */
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     /** Upsert with MAX semantics: keep the later blockedUntilMs on conflict. */
@@ -116,8 +122,8 @@ export interface UsageLedgerStore {
 }
 /** Broker-delegated OAuth refresh and usage-report operations. */
 export interface CredentialUpstream {
-    /** Optional hook to notify the underlying store that usage report cache is stale. */
-    invalidateUsageCache(signal?: AbortSignal): Promise<void>;
+    /** Optional hook to notify the underlying store that usage reports (one provider's, when given) are stale. */
+    invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void>;
     /**
      * Optional store-supplied OAuth refresh. When present, `AuthStorage` uses
      * it before the per-provider local refresh path. `RemoteAuthCredentialStore`

package/dist/types/auth/types.d.ts

@@ -316,6 +316,12 @@ export type AuthStorageOptions = {
      * the actual refresh token never leaves the broker.
      */
     refreshOAuthCredential?: (provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason) => Promise<OAuthCredentials>;
+    /**
+     * Set when {@link refreshOAuthCredential} exchanges the refresh token with the
+     * provider itself instead of delegating (e.g. to a broker), so its tokens count
+     * as this process's mints for auth-recovery reuse.
+     */
+    refreshOAuthCredentialMints?: boolean;
     /**
      * Human-readable description of the credential store backing this
      * AuthStorage instance. Surfaced through {@link AuthStorage.keys.describe}
@@ -409,7 +415,7 @@ export interface ModelUsageHealthOptions {
 export type AuthApiKeyOptions = {
     baseUrl?: string;
     modelId?: string;
-    /** Provider account ids known to serve `modelId` from multi-account discovery; OAuth selection prefers them and tries other accounts only as a last resort. */
+    /** {@link oauthAccountKey}s of accounts known to serve `modelId` from multi-account discovery; OAuth selection prefers them and tries other accounts only as a last resort. */
     accountIds?: readonly string[];
     /**
      * Caller's cancel signal. Threaded into any broker-bound OAuth refresh so
@@ -429,6 +435,19 @@ export type AuthApiKeyOptions = {
     /** When false, select as `sessionId` would without recording the choice as that session's sticky credential. */
     recordAffinity?: boolean;
 };
+/**
+ * Identity that multi-account discovery records in `Model.accountAccess` and
+ * that {@link AuthApiKeyOptions.accountIds} selection matches: the provider
+ * account id (Codex `chatgpt_account_id`), else the login email for providers
+ * whose credentials carry no account id (Antigravity), else the project id for
+ * a login whose email lookup failed. Same precedence as the credential store's
+ * identity key.
+ */
+export declare function oauthAccountKey(identity: {
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+}): string | undefined;
 /** Non-secret identity bound to the OAuth credential selected for one request attempt. */
 export interface OAuthRequestIdentity {
     orgId?: string;
@@ -814,9 +833,20 @@ export interface KeysApi {
      * 6. Stored API key (e.g. a broker-migrated copy) — last resort, so an explicit env var wins
      * 7. OMP compatibility mirror — below every stored credential, so a key the
      *    user saves locally always wins over the upstream fallback
+     *
+     * Resolves `undefined` when no permitted credential can serve, including when
+     * OAuth refresh failed transiently (network, timeout, 5xx), so availability
+     * probes move on to their next candidate. Request paths use
+     * {@link KeysApi.getWithCredential}, which surfaces that failure.
      */
     get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
-    /** Resolve a bearer together with its durable stored credential row id, when known. */
+    /**
+     * Resolve a bearer together with its durable stored credential row id, when known.
+     * Same precedence as {@link KeysApi.get}, but rejects with
+     * `OAuthRefreshUnavailableError` (transient, retryable) when OAuth refresh failed
+     * with a retryable error and no other permitted source could serve the request;
+     * the stored credential is kept.
+     */
     getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
     /**
      * Peek at API key for a provider without refreshing OAuth tokens.
@@ -913,7 +943,7 @@ export interface KeysApi {
         modelId?: string;
     }): ApiKeyResolver;
 }
-/** Controls whether a row-id refresh may reuse a token minted by this refresher. */
+/** Controls whether a row-id refresh may reuse a recently minted token. */
 export interface OAuthRefreshByIdOptions {
     /**
      * Return the stored credential when it still holds a fresh access token this
@@ -921,6 +951,12 @@ export interface OAuthRefreshByIdOptions {
      * refresh tokens repeatedly when a provider rejects every valid bearer.
      */
     reuseRecentMint?: boolean;
+    /**
+     * Provider-401 recovery intent. Forwarded to a delegated refresh (an auth
+     * broker), which may then return a token it minted in the last five minutes.
+     * Local reuse still requires {@link reuseRecentMint}.
+     */
+    reason?: OAuthRefreshReason;
 }
 /** OAuth login, access, account identity, and refresh operations. */
 export interface OAuthApi {
@@ -942,9 +978,11 @@ export interface OAuthApi {
      * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
      * scenarios, prefer {@link AuthStorage.keys.get}.
      *
-     * Returns `undefined` when no OAuth credential is available, the
-     * credential fails to refresh, or runtime/config overrides have replaced
-     * OAuth with an explicit API key.
+     * Returns `undefined` when no usable OAuth credential is available (none
+     * stored, or every one definitively failed to refresh) or runtime/config
+     * overrides have replaced OAuth with an explicit API key. Rejects with
+     * `OAuthRefreshUnavailableError` (transient, retryable) when a retryable
+     * refresh failure left no usable credential.
      */
     access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     /**
@@ -960,9 +998,10 @@ export interface OAuthApi {
      * Resolve one stored OAuth credential by its durable storage row id.
      *
      * Unlike the normal session resolver, this method never ranks, rotates, or
-     * falls back to sibling credentials. A forced refresh re-mints only the
-     * requested row, preserving exact-account affinity for operations whose
-     * provenance and policy boundary are tied to one workspace.
+     * falls back to sibling credentials. A generic forced refresh re-mints only the
+     * requested row; with `refreshReason: "auth-recovery"` it may instead reuse a
+     * still-usable recent mint of that row. Either way exact-account affinity holds
+     * for operations whose provenance and policy boundary are tied to one workspace.
      *
      * Returns `undefined` when the row does not exist for `provider` or an
      * explicit runtime/config API-key override suppresses OAuth.
@@ -996,8 +1035,9 @@ export interface OAuthApi {
      * Refresh the OAuth credential with the given id through a per-credential
      * single-flight. Concurrent callers for the same row await the same upstream
      * refresh attempt, which is required for providers that rotate refresh tokens
-     * on every successful refresh. Mints unconditionally unless
-     * {@link OAuthRefreshByIdOptions.reuseRecentMint} is set.
+     * on every successful refresh. Mints unless {@link OAuthRefreshByIdOptions.reuseRecentMint}
+     * finds a recent local mint, or a delegated refresh given
+     * {@link OAuthRefreshByIdOptions.reason} `"auth-recovery"` returns its recent mint.
      */
     refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
     /**
@@ -1005,6 +1045,11 @@ export interface OAuthApi {
      */
     refreshStored<T extends OAuthCredential = OAuthCredential>(provider: string, options: StoredOAuthRefreshOptions<T>): Promise<StoredOAuthRefreshResult<T>>;
 }
+/**
+ * Handle for one {@link SessionsApi.restrict} call. {@link SessionsApi.unrestrict}
+ * lifts a restriction only with the lease of the call that installed it.
+ */
+export type SessionRestrictionLease = symbol;
 /** Session credential affinity operations. */
 export interface SessionsApi {
     /**
@@ -1024,14 +1069,42 @@ export interface SessionsApi {
         restoredAtMs?: number;
     }): boolean;
     /**
-     * Copy every stored credential affinity from one live session to another.
+     * Copy stored credential affinities from one live session to another.
      *
      * The target receives its own sticky entries, so request resolution, usage
      * blocking, credential rotation, metadata, and persisted pins all continue
      * through the target session id without retaining a live dependency on the
-     * source session.
+     * source session. `include` limits the copy to the providers it accepts,
+     * given whether the source's affinity is an explicit user pin.
+     */
+    inherit(sourceSessionId: string, targetSessionId: string, include?: (provider: string, explicit: boolean) => boolean): number;
+    /**
+     * Restrict one session's credentials for `provider` to the OAuth accounts
+     * whose identity key (`email:<address>|org:<id>` for org-scoped providers;
+     * otherwise `account:`, `email:`, or `project:` — the keys broker account
+     * pools use) is listed. Selection, session pins, inherited affinity,
+     * fallback passes, and rotation never leave the list, and runtime, config,
+     * environment, and stored API keys are not used for that session; when no
+     * listed account can serve, key resolution fails instead of borrowing
+     * another account. An empty list allows no account. Replaces any earlier
+     * restriction for the same provider and session; {@link inherit} does not
+     * copy restrictions. Restrictions are never evicted, because that would
+     * widen a live session; the owner passes the returned lease to
+     * {@link unrestrict} when the session ends.
+     */
+    restrict(provider: string, sessionId: string, identityKeys: readonly string[]): SessionRestrictionLease;
+    /**
+     * Lift the restriction that `lease` installed. Once a later {@link restrict}
+     * call has replaced it for the same provider and session, this does nothing,
+     * so a stale owner never lifts the restriction a newer owner relies on.
+     */
+    unrestrict(provider: string, sessionId: string, lease: SessionRestrictionLease): void;
+    /**
+     * Whether stored credential `credentialId` may serve `sessionId`: always for
+     * an unrestricted session, otherwise only an OAuth account its
+     * {@link restrict} list names.
      */
-    inherit(sourceSessionId: string, targetSessionId: string): number;
+    permits(provider: string, sessionId: string, credentialId: number): boolean;
     /**
      * Release a session's sticky credential so its next {@link getApiKey} call
      * re-runs native pool ranking. This never blocks or penalizes the released

package/dist/types/auth-broker/client.d.ts

@@ -1,8 +1,8 @@
 /**
- * HTTP client for the omp auth-broker server.
+ * HTTP client for the zetacode auth-broker server.
  *
  * Used by {@link RemoteAuthCredentialStore} (snapshot pulls) and by
- * `omp auth-broker status` (liveness checks). All endpoints except
+ * `zetacode auth-broker status` (liveness checks). All endpoints except
  * `/v1/healthz` require a bearer token.
  */
 import type { AuthCredential, DisabledCredentialSummary, OAuthRefreshReason } from "../auth-storage.js";
@@ -85,7 +85,7 @@ export declare class AuthBrokerClient {
     fetchClientUsageSummary(query?: {
         sinceMs?: number;
     }, signal?: AbortSignal): Promise<ClientUsageSummaryResponse>;
-    notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse>;
+    notifyUsageStale(provider?: string, signal?: AbortSignal): Promise<UsageStaleResponse>;
     refreshCredential(id: number, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
     /**

package/dist/types/auth-broker/discover.d.ts

@@ -18,7 +18,7 @@ export interface DiscoverAuthStorageOptions {
     accountPolicies?: AuthAccountPolicies;
     authStorageOptions?: Omit<AuthStorageOptions, "accountPolicies" | "configValueResolver" | "sourceLabel">;
 }
-/** Path to the local bearer token file. Created by `omp auth-broker token`. */
+/** Path to the local bearer token file. Created by `zetacode auth-broker token`. */
 export declare function getAuthBrokerTokenFilePath(): string;
 export interface AuthAccountPolicyConfig {
     accountPolicies: AuthAccountPolicies;

package/dist/types/auth-broker/remote-store.d.ts

@@ -73,6 +73,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     /** Broker-backed disabled tombstones; empty against brokers predating the endpoint. */
     listDisabledCredentials(provider?: string, signal?: AbortSignal): Promise<DisabledCredentialSummary[]>;
     getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    getCredentialBlockScopes(credentialId: number, providerKey: string): Map<string, number>;
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     listCredentialBlocks(credentialIds: readonly number[]): StoredCredentialBlock[];
     upsertCredentialBlock(block: StoredCredentialBlock): void;
@@ -121,7 +122,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     /** Drop all cache rows whose keys start with the supplied prefix. */
     deleteCachePrefix(prefix: string): void;
     cleanExpiredCache(): void;
-    invalidateUsageCache(signal?: AbortSignal): Promise<void>;
+    invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void>;
     /**
      * Store-level hook consumed by `AuthStorage` — routes refresh through the
      * broker so the actual refresh token never leaves the broker host. Returns
@@ -148,9 +149,10 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     ingestUsageReport(provider: Provider, credential: OAuthCredential, report: UsageReport): boolean;
     /**
      * Fold locally observed request usage into the pending report and schedule
-     * a flush. One `POST /v1/usage/observed` at most per flush interval; on
-     * failure the batch is retained and retried with the next flush. A 404
-     * (pre-endpoint broker) disables reporting for the life of this store.
+     * a flush. One `POST /v1/usage/observed` at most per flush interval, plus a
+     * final one when the process exits; on failure the batch is retained and
+     * retried with the next flush. A 404 (pre-endpoint broker) disables
+     * reporting for the life of this store.
      *
      * `client` overrides the reporting identity — the auth-gateway attributes
      * each request to the originating install/app instead of the gateway host.

package/dist/types/auth-broker/server.d.ts

@@ -17,6 +17,8 @@ export interface AuthBrokerServerOptions {
     bind?: string;
     /** Accept any of these bearer tokens. Empty disables auth (loopback only). */
     bearerTokens: string[];
+    /** Honor forwarded peer headers only when the connecting proxy is trusted. Default false. */
+    trustProxyHeaders?: boolean;
     /** Broker version string surfaced on `/v1/healthz`. */
     version?: string;
     /** Refresh credentials expiring within this window. Default 5 min. */

package/dist/types/auth-broker/snapshot-cache.d.ts

@@ -15,3 +15,15 @@ export interface WriteAuthBrokerSnapshotCacheOptions {
 }
 export declare function readAuthBrokerSnapshotCache(opts: ReadAuthBrokerSnapshotCacheOptions): Promise<SnapshotResponse | null>;
 export declare function writeAuthBrokerSnapshotCache(opts: WriteAuthBrokerSnapshotCacheOptions): Promise<void>;
+/**
+ * Fire-and-forget cache write for snapshot callbacks. The first snapshot after
+ * a quiet period is written immediately; later ones within
+ * {@link WRITE_COALESCE_MS} collapse into a single trailing write of the
+ * newest. A snapshot whose generation and credential content match the last
+ * write is skipped (see {@link UNCHANGED_REWRITE_MS}). Pending writes are
+ * flushed on process shutdown and by {@link flushAuthBrokerSnapshotCacheWrites};
+ * failures are logged, never thrown.
+ */
+export declare function scheduleAuthBrokerSnapshotCacheWrite(opts: WriteAuthBrokerSnapshotCacheOptions): void;
+/** Write every pending scheduled snapshot now and wait for in-flight writes to settle. */
+export declare function flushAuthBrokerSnapshotCacheWrites(): Promise<void>;