@oh-my-pi/pi-ai 18.8.0 → 18.8.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [18.8.1] - 2026-10-07
+
+### Added
+
+- Added session restrictions for OAuth account pools via `AuthStorage.sessions.restrict`, limiting selection, fallback, rotation, and authentication to specified accounts until the returned lease is released with `sessions.unrestrict`. API keys and other accounts are not used when a session is restricted.
+- Exported `resolveCredentialIdentityKey` for determining the identity key used to match credentials with broker account pools and session restrictions.
+
+### Fixed
+
+- Fixed Codex Fast (`priority`) and Ultrafast usage being recorded, billed, and reported as Standard when the backend echoed a default service tier; the requested tier is now preserved in usage and performance records.
+
 ## [18.8.0] - 2026-10-07
 
 ### Breaking Changes

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,30 @@ 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;
     /** 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 +53,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;
@@ -71,3 +95,4 @@ export declare class SessionAffinity implements SessionsApi {
      */
     release(provider: string, sessionId: string): boolean;
 }
+export {};

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

@@ -8,6 +8,14 @@ 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. */
@@ -115,6 +123,10 @@ export declare class KeyCascade implements KeysApi {
      * Get API key for a provider.
      * Priority (first match wins): runtime override, config override, OAuth,
      * 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.
      */
     get(provider: string, sessionId?: string, options?: AuthApiKeyOptions, onCredentialId?: (id: number, identity?: OAuthRequestIdentity) => void): Promise<string | undefined>;
     /**

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

@@ -18,6 +18,12 @@ 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;
 /**
  * Default SQLite-backed implementation of {@link AuthCredentialStore}.

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

@@ -998,6 +998,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 {
     /**
@@ -1025,6 +1030,27 @@ export interface SessionsApi {
      * source session.
      */
     inherit(sourceSessionId: string, targetSessionId: string): 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;
     /**
      * 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-storage.d.ts

@@ -1,6 +1,6 @@
 import type { AuthCredentialStore } from "./auth/store.js";
 import type { AuthAccountPolicies, AuthApiKeyOptions, AuthStorageOptions, BlocksApi, CredentialsApi, HealthApi, KeysApi, LimitsApi, OAuthApi, ResetsApi, SessionsApi, UsageApi } from "./auth/types.js";
-export { isSqliteBusyError, isSqliteCorruptionError, SqliteAuthCredentialStore } from "./auth/sqlite-credential-store.js";
+export { isSqliteBusyError, isSqliteCorruptionError, resolveCredentialIdentityKey, SqliteAuthCredentialStore, } from "./auth/sqlite-credential-store.js";
 export * from "./auth/store.js";
 export * from "./auth/types.js";
 /**
@@ -46,9 +46,9 @@ export declare class AuthStorage {
      * Swap the backing credential store in place (live `auth.broker.url` change).
      * Loads `store` into fresh store-bound state — pins, blocks, and usage caches are
      * keyed by the old store's row ids — then closes the previous store. Runtime key
-     * overrides, account policies, usage-provider overrides, and credential event
-     * subscribers carry over. On a load failure `store` is closed and the current
-     * store stays active.
+     * overrides, account policies, session account restrictions, usage-provider
+     * overrides, and credential event subscribers carry over. On a load failure
+     * `store` is closed and the current store stays active.
      */
     replaceStore(store: AuthCredentialStore, options?: {
         sourceLabel?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.8.0",
+	"version": "18.8.2",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -155,11 +155,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.8.0",
-		"@oh-my-pi/pi-catalog": "18.8.0",
-		"@oh-my-pi/pi-natives": "18.8.0",
-		"@oh-my-pi/pi-utils": "18.8.0",
-		"@oh-my-pi/pi-wire": "18.8.0"
+		"@oh-my-pi/omptype": "18.8.2",
+		"@oh-my-pi/pi-catalog": "18.8.2",
+		"@oh-my-pi/pi-natives": "18.8.2",
+		"@oh-my-pi/pi-utils": "18.8.2",
+		"@oh-my-pi/pi-wire": "18.8.2"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth/affinity.ts

@@ -1,10 +1,11 @@
 import { logger } from "@oh-my-pi/pi-utils";
 import { LRUCache } from "@oh-my-pi/pi-utils/lru";
 import { getEnvApiKey } from "../env-api-key";
-import type { AuthCredential, OAuthCredential, SessionsApi } from "./types";
+import type { AuthCredential, OAuthCredential, SessionRestrictionLease, SessionsApi } from "./types";
 import type { AuthCredentialStore } from "./store";
 import type { CredentialPool } from "./pool";
 import type { KeyOverrides } from "./cascade";
+import { resolveCredentialIdentityKey } from "./sqlite-credential-store";
 
 /** Prefix for persisted session-to-credential affinity. */
 export const SESSION_STICKY_CACHE_PREFIX = "session:sticky:";
@@ -39,6 +40,16 @@ export type SessionCredential = {
 	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 class SessionAffinity implements SessionsApi {
 	/** Tracks the last used credential per provider for a session (used for rate-limit switching). */
@@ -48,11 +59,58 @@ export class SessionAffinity implements SessionsApi {
 	#store: AuthCredentialStore;
 	#pool: CredentialPool;
 	#overrides: KeyOverrides;
+	#restrictions: SessionRestrictions;
 
-	constructor(store: AuthCredentialStore, pool: CredentialPool, overrides: KeyOverrides) {
+	constructor(
+		store: AuthCredentialStore,
+		pool: CredentialPool,
+		overrides: KeyOverrides,
+		restrictions: SessionRestrictions,
+	) {
 		this.#store = store;
 		this.#pool = pool;
 		this.#overrides = overrides;
+		this.#restrictions = restrictions;
+	}
+
+	restrict(provider: string, sessionId: string, identityKeys: readonly string[]): SessionRestrictionLease {
+		if (!provider || !sessionId) throw new Error("sessions.restrict requires a provider and a session id");
+		const lease = Symbol("sessions.restrict");
+		const sessions = this.#restrictions.get(provider) ?? new Map<string, SessionRestriction>();
+		sessions.set(sessionId, { allowed: new Set(identityKeys), lease });
+		this.#restrictions.set(provider, sessions);
+		return lease;
+	}
+
+	unrestrict(provider: string, sessionId: string, lease: SessionRestrictionLease): void {
+		const sessions = this.#restrictions.get(provider);
+		if (sessions?.get(sessionId)?.lease !== lease) return;
+		sessions.delete(sessionId);
+		if (sessions.size === 0) this.#restrictions.delete(provider);
+	}
+
+	/** True when {@link restrict} limits `sessionId` for `provider`. */
+	isRestricted(provider: string, sessionId: string | undefined): boolean {
+		return sessionId !== undefined && this.#restrictions.get(provider)?.has(sessionId) === true;
+	}
+
+	/**
+	 * 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 {
+		const allowed = sessionId === undefined ? undefined : this.#restrictions.get(provider)?.get(sessionId)?.allowed;
+		if (allowed === undefined) return true;
+		if (credential.type !== "oauth") return false;
+		const identityKey = resolveCredentialIdentityKey(provider, credential);
+		return identityKey !== null && allowed.has(identityKey);
+	}
+
+	/** Whether the stored row at `index` may serve `sessionId` (see {@link allows}). */
+	#permits(provider: string, sessionId: string, index: number): boolean {
+		if (!this.isRestricted(provider, sessionId)) return true;
+		const credential = this.#pool.credentials(provider)[index];
+		return credential !== undefined && this.allows(provider, sessionId, credential);
 	}
 
 	/** Bounded per-provider session map, created on first use. */
@@ -101,7 +159,7 @@ export class SessionAffinity implements SessionsApi {
 		lastUsedAtMs?: number,
 		explicit = false,
 	): void {
-		if (!sessionId) return;
+		if (!sessionId || !this.#permits(provider, sessionId, index)) return;
 		const nowMs = lastUsedAtMs ?? Date.now();
 		const credentialId = this.#pool.entries(provider)[index]?.id;
 		const sessionMap = SessionAffinity.#sessionsFor(this.#sessionLastCredential, provider);
@@ -147,9 +205,18 @@ export class SessionAffinity implements SessionsApi {
 		}
 	}
 
-	/** 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 {
 		if (!sessionId) return undefined;
+		const credential = this.#lookup(provider, sessionId);
+		return credential && this.#permits(provider, sessionId, credential.index) ? credential : undefined;
+	}
+
+	#lookup(provider: string, sessionId: string): SessionCredential | undefined {
 		const live = this.#sessionLastCredential.get(provider)?.get(sessionId);
 		if (live) {
 			// Another process can add or drop rows mid-session and the pool is an
@@ -233,12 +300,17 @@ export class SessionAffinity implements SessionsApi {
 
 	activeOAuth(provider: string, sessionId?: string): OAuthCredential | undefined {
 		const allCredentials = this.#pool.credentials(provider);
-		const oauthCredentials = allCredentials.filter((c): c is OAuthCredential => c.type === "oauth");
+		const oauthCredentials = allCredentials.filter(
+			(c): c is OAuthCredential => c.type === "oauth" && this.allows(provider, sessionId, c),
+		);
 		if (oauthCredentials.length === 0) return undefined;
 
 		// Runtime / config overrides bypass OAuth account_uuid attribution — the
 		// caller is authenticating with an explicit key, not the broker's OAuth.
-		if (this.#overrides.has(provider)) return undefined;
+		// A restricted session skips a runtime key, and a config key fails it
+		// closed (see `KeyCascade.get`).
+		const restricted = this.isRestricted(provider, sessionId);
+		if (this.#overrides.suppressesOAuth(provider, restricted)) return undefined;
 
 		// Prefer the session-sticky credential when available.
 		const sessionPref = this.get(provider, sessionId);
@@ -251,7 +323,7 @@ export class SessionAffinity implements SessionsApi {
 		// would misattribute traffic. Only apply this guard when sessionPref is absent; a
 		// recorded OAuth sticky (sessionPref.type === "oauth") must NOT be blocked even if an
 		// env key also happens to exist.
-		if (!sessionPref && getEnvApiKey(provider)) return undefined;
+		if (!restricted && !sessionPref && getEnvApiKey(provider)) return undefined;
 		// Resolve the sticky index against the full credential list — the index is
 		// recorded against the unfiltered provider array (by record /
 		// CredentialSelector.tryOAuth), not the OAuth-only subset, so dereferencing it into the
@@ -275,13 +347,13 @@ export class SessionAffinity implements SessionsApi {
 	 * account, a stale resume re-ranks.
 	 */
 	pin(provider: string, sessionId: string, credentialId: number, options?: { restoredAtMs?: number }): boolean {
-		if (!sessionId || this.#overrides.has(provider)) {
+		if (!sessionId || this.#overrides.suppressesOAuth(provider, this.isRestricted(provider, sessionId))) {
 			return false;
 		}
 		const stored = this.#pool.entries(provider);
 		const index = stored.findIndex(entry => entry.id === credentialId);
 		const target = stored[index];
-		if (target?.credential.type !== "oauth") return false;
+		if (target?.credential.type !== "oauth" || !this.allows(provider, sessionId, target.credential)) return false;
 		const restoredAtMs = options?.restoredAtMs;
 		this.record(provider, sessionId, "oauth", index, restoredAtMs, restoredAtMs === undefined);
 		return true;
@@ -300,7 +372,7 @@ export class SessionAffinity implements SessionsApi {
 		let inherited = 0;
 		for (const provider of this.#pool.providers()) {
 			const credential = this.get(provider, sourceSessionId);
-			if (!credential) continue;
+			if (!credential || !this.#permits(provider, targetSessionId, credential.index)) continue;
 			this.record(
 				provider,
 				targetSessionId,

package/src/auth/cascade.ts

@@ -42,6 +42,17 @@ export class KeyOverrides {
 		return this.#runtimeOverrides.has(provider) || this.#configOverrides.has(provider);
 	}
 
+	/**
+	 * 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 {
+		return restricted ? this.#configOverrides.has(provider) : this.has(provider);
+	}
+
 	runtimeKey(provider: string): string | undefined {
 		return this.#runtimeOverrides.get(provider);
 	}
@@ -316,6 +327,10 @@ export class KeyCascade implements KeysApi {
 	 * Get API key for a provider.
 	 * Priority (first match wins): runtime override, config override, OAuth,
 	 * 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.
 	 */
 	async get(
 		provider: string,
@@ -323,8 +338,9 @@ export class KeyCascade implements KeysApi {
 		options?: AuthApiKeyOptions,
 		onCredentialId?: (id: number, identity?: OAuthRequestIdentity) => void,
 	): Promise<string | undefined> {
+		const restricted = this.#deps.affinity.isRestricted(provider, sessionId);
 		// Runtime override takes highest priority
-		const runtimeKey = this.#deps.overrides.runtimeKey(provider);
+		const runtimeKey = restricted ? undefined : this.#deps.overrides.runtimeKey(provider);
 		if (runtimeKey) {
 			return runtimeKey;
 		}
@@ -334,7 +350,13 @@ export class KeyCascade implements KeysApi {
 		// (e.g. an auth-gateway) and supplied the bearer for that endpoint —
 		// honor it instead of forwarding an upstream OAuth token that the proxy
 		// won't accept.
-		const configKey = this.#deps.overrides.configKey(provider);
+		if (restricted && this.#deps.overrides.configKey(provider) !== undefined) {
+			throw new AIError.MissingApiKeyError(
+				provider,
+				`No API key for provider: ${provider} (session ${sessionId} is restricted to its OAuth account pool, but models.yml configures an apiKey for this provider, and pooled OAuth tokens are never sent past it)`,
+			);
+		}
+		const configKey = restricted ? undefined : this.#deps.overrides.configKey(provider);
 		if (configKey !== undefined) {
 			return this.#deps.overrides.resolve(configKey);
 		}
@@ -349,6 +371,12 @@ export class KeyCascade implements KeysApi {
 			}
 			return oauthResolved.apiKey;
 		}
+		if (restricted) {
+			throw new AIError.MissingApiKeyError(
+				provider,
+				`No API key for provider: ${provider} (session ${sessionId} is restricted to its OAuth account pool and none of those accounts is available)`,
+			);
+		}
 		const loginApiKeySelection = await this.#deps.selector.selectApiKey(
 			provider,
 			sessionId,

package/src/auth/oauth.ts

@@ -134,8 +134,9 @@ export class OAuthAccounts implements OAuthApi {
 	async access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined> {
 		// Runtime / config overrides intentionally short-circuit OAuth: when the
 		// user has pinned an API key, they expect the OAuth identity to be
-		// suppressed (same contract as account identity lookup).
-		if (this.#deps.overrides.has(provider)) {
+		// suppressed (same contract as account identity lookup). A session
+		// restricted to an account pool never uses a runtime key.
+		if (this.#deps.overrides.suppressesOAuth(provider, this.#deps.affinity.isRestricted(provider, sessionId))) {
 			return undefined;
 		}
 		const resolved = await this.#deps.selector.resolveOAuth(provider, sessionId, options);
@@ -236,7 +237,7 @@ export class OAuthAccounts implements OAuthApi {
 	 * credential.
 	 */
 	accounts(provider: string, sessionId?: string): OAuthAccountSummary[] {
-		if (this.#deps.overrides.has(provider)) {
+		if (this.#deps.overrides.suppressesOAuth(provider, this.#deps.affinity.isRestricted(provider, sessionId))) {
 			return [];
 		}
 		const sessionCredential = this.#deps.affinity.get(provider, sessionId);

package/src/auth/rotation.ts

@@ -141,6 +141,7 @@ export class RateLimits implements LimitsApi {
 	}
 	#blockCredentialForRotation(
 		provider: string,
+		sessionId: string | undefined,
 		credentialType: AuthCredential["type"],
 		targetIndex: number,
 		blockedUntil: number,
@@ -188,7 +189,9 @@ export class RateLimits implements LimitsApi {
 			.map((credential, index) => ({ credential, index }))
 			.filter(
 				(entry): entry is { credential: AuthCredential; index: number } =>
-					entry.credential.type === credentialType && entry.index !== targetIndex,
+					entry.credential.type === credentialType &&
+					entry.index !== targetIndex &&
+					this.#deps.affinity.allows(provider, sessionId, entry.credential),
 			);
 
 		let retryAtMs: number | undefined;
@@ -292,6 +295,7 @@ export class RateLimits implements LimitsApi {
 			.findIndex(entry => entry.id === targetCredentialId && entry.credential.type === credentialType);
 		const rotation = this.#blockCredentialForRotation(
 			provider,
+			sessionId,
 			credentialType,
 			targetIndex,
 			blockedUntil,
@@ -456,6 +460,7 @@ export class RateLimits implements LimitsApi {
 			}
 			const mark = this.#blockCredentialForRotation(
 				provider,
+				sessionId,
 				sessionCredential.type,
 				sessionCredential.index,
 				Date.now() + DEFAULT_BLOCK_MS,
@@ -474,7 +479,8 @@ export class RateLimits implements LimitsApi {
 				(credential, index) =>
 					credential.type === sessionCredential.type &&
 					index !== sessionCredential.index &&
-					!this.#deps.blocks.isBlocked(provider, providerKey, index),
+					!this.#deps.blocks.isBlocked(provider, providerKey, index) &&
+					this.#deps.affinity.allows(provider, sessionId, credential),
 			);
 		const target = this.#deps.pool.entries(provider)[sessionCredential.index];
 		const sticky = this.#deps.affinity.get(provider, sessionId);

package/src/auth/select.ts

@@ -516,14 +516,17 @@ export class CredentialSelector {
 		options?: AuthApiKeyOptions,
 	): Promise<OAuthResolutionResult | undefined> {
 		await this.#deps.pool.adoptExternalChanges();
-		const credentials = this.#deps.pool
+		const stored = this.#deps.pool
 			.credentials(provider)
 			.map((credential, index) => ({ credential, index }))
 			.filter((entry): entry is { credential: OAuthCredential; index: number } => entry.credential.type === "oauth");
 		this.#deps.policies.validateFor(
 			provider,
-			credentials.map(entry => entry.credential),
+			stored.map(entry => entry.credential),
 		);
+		// A session restriction drops every other account before ranking, pins,
+		// and the fallback passes below, so none of them can route back to it.
+		const credentials = stored.filter(entry => this.#deps.affinity.allows(provider, sessionId, entry.credential));
 
 		if (credentials.length === 0) return undefined;
 		this.#deps.policies.validateUsageCapability(provider, this.#deps.usage.canFetchOAuthUsage(provider));

package/src/auth/sqlite-credential-store.ts

@@ -217,6 +217,12 @@ function resolveProviderCredentialIdentityKey(provider: string, identifiers: str
 	return 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 function resolveCredentialIdentityKey(provider: string, credential: AuthCredential): string | null {
 	if (credential.type === "api_key") return null;
 	return resolveProviderCredentialIdentityKey(provider, extractOAuthCredentialIdentifiers(credential));

package/src/auth/types.ts

@@ -1088,6 +1088,12 @@ export interface OAuthApi {
 	): 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 {
 	/**
@@ -1113,6 +1119,27 @@ export interface SessionsApi {
 	 * source session.
 	 */
 	inherit(sourceSessionId: string, targetSessionId: string): 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;
 	/**
 	 * 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/src/auth-storage.ts

@@ -19,7 +19,7 @@
  * const apiKey = await auth.keys.get("anthropic", sessionId, { modelId });
  */
 import { logger } from "@oh-my-pi/pi-utils";
-import { SessionAffinity } from "./auth/affinity";
+import { SessionAffinity, type SessionRestrictions } from "./auth/affinity";
 import { BlockStoreHealth, CredentialBlocks } from "./auth/blocks";
 import { KeyCascade, KeyOverrides } from "./auth/cascade";
 import { CredentialHealth } from "./auth/health";
@@ -52,7 +52,12 @@ import { DEFAULT_USAGE_REQUEST_TIMEOUT_MS, UsageCache } from "./auth/usage-cache
 import type { UsageLogger } from "./usage";
 import { defaultRankingStrategy, defaultUsageProvider } from "./usage/registry";
 
-export { isSqliteBusyError, isSqliteCorruptionError, SqliteAuthCredentialStore } from "./auth/sqlite-credential-store";
+export {
+	isSqliteBusyError,
+	isSqliteCorruptionError,
+	resolveCredentialIdentityKey,
+	SqliteAuthCredentialStore,
+} from "./auth/sqlite-credential-store";
 export * from "./auth/store";
 export * from "./auth/types";
 
@@ -81,6 +86,7 @@ export class AuthStorage {
 	readonly #options: AuthStorageOptions;
 	readonly #overrides: KeyOverrides;
 	readonly #policies: AccountPolicies;
+	readonly #restrictions: SessionRestrictions = new Map();
 	#modules: AuthStorageModules;
 
 	constructor(store: AuthCredentialStore, options: AuthStorageOptions = {}) {
@@ -145,9 +151,9 @@ export class AuthStorage {
 	 * Swap the backing credential store in place (live `auth.broker.url` change).
 	 * Loads `store` into fresh store-bound state — pins, blocks, and usage caches are
 	 * keyed by the old store's row ids — then closes the previous store. Runtime key
-	 * overrides, account policies, usage-provider overrides, and credential event
-	 * subscribers carry over. On a load failure `store` is closed and the current
-	 * store stays active.
+	 * overrides, account policies, session account restrictions, usage-provider
+	 * overrides, and credential event subscribers carry over. On a load failure
+	 * `store` is closed and the current store stays active.
 	 */
 	async replaceStore(store: AuthCredentialStore, options: { sourceLabel?: string } = {}): Promise<void> {
 		const next = this.#compose(store, options.sourceLabel ?? this.#options.sourceLabel);
@@ -185,7 +191,7 @@ export class AuthStorage {
 		// override's `cacheVersion` separates its rows from other processes sharing the store.
 		const usageCache = new UsageCache(store, pool, provider => usage.providerFor(provider));
 		const blocks = new CredentialBlocks({ store, pool, health: blockHealth, usageCache, strategies });
-		const affinity = new SessionAffinity(store, pool, overrides);
+		const affinity = new SessionAffinity(store, pool, overrides, this.#restrictions);
 		const usage = new UsageService({
 			store,
 			pool,

package/src/providers/openai-codex-responses.ts

@@ -1348,14 +1348,19 @@ function getCodexServiceTierCostMultiplier(
 }
 
 /**
- * The tier a Codex response was billed at. The response echo is authoritative
- * whenever it reports a tier (the backend may serve a requested priority/flex
- * turn as `default`); the requested tier is used only when the echo is absent.
- * The tier's identity is preserved even when it has no pricing entry (`scale`),
- * because the recorded tier also drives premium-request and speed accounting.
+ * The tier a Codex turn was served at. The Codex backend echoes
+ * `service_tier: "default"` on turns it serves at the sent tier (a `priority`
+ * turn decodes at Fast speed yet reports `default`), so a `default` or `auto`
+ * echo carries no information and, like an absent one, resolves to the sent
+ * tier, or `default` when none was sent. Any other echo (`flex`, `priority`,
+ * `ultrafast`, `scale`) is authoritative. The tier's identity is preserved even
+ * when it has no pricing entry (`scale`), because the recorded tier also drives
+ * premium-request and speed accounting. The echo cannot reveal a genuine
+ * downgrade, so a downgraded turn is recorded at the sent tier.
  */
 function resolveCodexCostServiceTier(res: ServiceTier | undefined, req?: unknown): ServiceTier {
-	return res ?? parseServiceTier(req) ?? "default";
+	if (res !== undefined && res !== "default" && res !== "auto") return res;
+	return parseServiceTier(req) ?? "default";
 }
 
 function applyCodexServiceTierPricing(
@@ -1921,14 +1926,20 @@ async function openCodexWebSocketTransport(
 	}
 	recordCodexTurnRequestDiagnostics(websocketState, websocketRequest, "websocket", canAppendBeforeRequest);
 	const requestBodyForState = cloneJsonTree(requestContext.transformedBody);
-	// `onPayload` may rewrite the outgoing frame (e.g. drop `stream_options`);
-	// recorded state must reflect what was actually sent — the sequential-cutoff
-	// summary decoder keys off it.
+	// `onPayload` may rewrite the outgoing frame (e.g. drop `stream_options` or
+	// change `service_tier`); recorded state must reflect what was actually
+	// sent — the sequential-cutoff summary decoder and the served-tier
+	// fallback key off it.
 	if (websocketRequest.stream_options === undefined) {
 		delete requestBodyForState.stream_options;
 	} else {
 		requestBodyForState.stream_options = websocketRequest.stream_options;
 	}
+	if (websocketRequest.service_tier === undefined) {
+		delete requestBodyForState.service_tier;
+	} else {
+		requestBodyForState.service_tier = websocketRequest.service_tier;
+	}
 	requestContext.rawRequestDump.body = websocketRequest;
 	CODEX_DEBUG &&
 		logger.debug("[codex] codex websocket request", {

package/src/providers/openai-shared.ts

@@ -362,7 +362,7 @@ export function applyOpenAIServiceTier(
  * Standard OpenAI Responses service-tier cost multipliers. The non-Codex
  * Responses path bills the tier it was served (or requested): Flex processing is
  * half price; Priority (Fast mode) is a 2x premium. Codex bills the same tiers
- * with its own table (Priority is 2.5x on gpt-5.5) and applies that separately.
+ * with its own table (Fast is 2.5x on every model) and applies that separately.
  * `ultrafast` has no API-generic default — only models with a published
  * ultrafast price carry a `serviceTierCost.ultrafast` entry (Astra, 6x) and
  * everything else stays at 1x rather than an invented multiplier.