@linxiraos/pi-ai 1.1.26 → 1.2.0

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

@@ -0,0 +1,29 @@
+/**
+ * Removal of DeepSeek DSML tool-call markup left in visible assistant text.
+ *
+ * DeepSeek models on OpenAI-compatible hosts sometimes emit their tool calls as
+ * raw `<｜DSML｜…>` markup in `content`. A well-formed envelope is healed into a
+ * structured call by `StreamMarkupHealing`, but a degraded model can drop the
+ * opening `<｜DSML｜tool_calls>` / `<｜DSML｜invoke name="…">` tags (or the host
+ * runs no healer at all). That markup must not stay in history: replaying it
+ * teaches the model to keep writing tool calls as text (issue #10556). Callers
+ * strip it before the message is committed and tell the model its call failed.
+ */
+import type { AssistantMessage, Model } from "../types.js";
+/**
+ * Whether DSML leak recovery applies to `model`: a DeepSeek-class model, or one
+ * explicitly configured with the `dsml` stream healer (e.g. a `models.yml` entry
+ * whose id the classifier cannot place). Other models never write DSML tool
+ * calls, so DSML text from them is prose and is left alone.
+ */
+export declare function isDsmlLeakRecoveryTarget(model: Model): boolean;
+/**
+ * Strip leaked DSML tool-call markup from `text`, leaving quoted code intact.
+ * Returns `undefined` when `text` carries no such markup.
+ */
+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.
+ */
+export declare function removeDsmlToolMarkupLeak(message: AssistantMessage): boolean;

package/dist/types/utils/glyph-codec.d.ts

@@ -4,7 +4,7 @@ import { AssistantMessageEventStream } from "./event-stream.js";
 export interface GlyphCodec {
     /** Context with model-bound glyphs encoded and one conditional convention notice. */
     context: Context;
-    /** Decodes glyph tokens in the stream's terminal assistant message. */
+    /** Decodes glyph tokens live: text and tool-call deltas, partial snapshots, completed tool calls, and the terminal message. */
     wrap(inner: AssistantMessageEventStream): AssistantMessageEventStream;
     /** Decodes Cursor Pi calls and encodes their provider-bound results. */
     wrapCursorExecHandlers(handlers: CursorExecHandlers): CursorExecHandlers;

package/dist/types/utils/idle-iterator.d.ts

@@ -138,6 +138,12 @@ export interface TerminalGraceIteratorOptions {
      * the transport until that pending read settles.
      */
     onGraceEnd?: () => void;
+    /**
+     * Wait for the bounded drain when the consumer returns early. Capped
+     * requests must not release their in-flight permit while the transport
+     * still owns a live connection.
+     */
+    awaitDrainOnReturn?: boolean;
 }
 /**
  * Yields items from an async iterable until the consumer marks the stream
@@ -148,5 +154,10 @@ export interface TerminalGraceIteratorOptions {
  * hangs on `iterator.next()` until the idle watchdog converts an
  * already-successful turn into a timeout error. Grace expiry is a clean end
  * of iteration, never an error.
+ *
+ * A consumer that stops early (`break`) after `finishedAtMs()` is set leaves
+ * the source draining until `[DONE]`/EOF or the same grace deadline. Without
+ * `awaitDrainOnReturn`, the consumer is not held up; capped requests await
+ * the drain before completing and releasing their in-flight permit.
  */
 export declare function iterateWithTerminalGrace<T>(iterable: AsyncIterable<T>, options: TerminalGraceIteratorOptions): AsyncGenerator<T>;

package/dist/types/utils/leaked-thinking-stream.d.ts

@@ -23,7 +23,7 @@
  * fences, so wrapping a provider that already heals (or wrapping twice) is a
  * harmless pass-through. Signatures are load-bearing for Google/Gemini/Vertex
  * thought round-tripping, so text sub-blocks carry the source `textSignature`,
- * forwarded thinking blocks their `thinkingSignature`, and forwarded tool calls
+ * forwarded thinking blocks their `thinkingSignature` and `summary` state, and forwarded tool calls
  * their `thoughtSignature`.
  *
  * Modeled on {@link wrapInbandToolStream} / `InbandStreamProjector` in

package/dist/types/utils/resolve-peer.d.ts

@@ -0,0 +1,2 @@
+/** Use the socket peer unless the server explicitly trusts its reverse proxy. */
+export declare function resolvePeer(req: Request, socketAddress: string, trustProxyHeaders?: boolean): string;

package/dist/types/utils/retry-wait.d.ts

@@ -0,0 +1,9 @@
+/** Injected retry sleep: `StreamOptions.providerRetryWait` / `UsageFetchContext.retryWait`. */
+export type RetryWaitHook = (delayMs: number, signal?: AbortSignal) => Promise<void>;
+/**
+ * Waits `delayMs` between retry attempts. Honors the caller's retry-wait hook
+ * when one is set (tests and custom transports inject it to avoid real sleeps)
+ * and otherwise sleeps on `signal`, so an abort rejects instead of the retry
+ * proceeding.
+ */
+export declare function waitForRetry(retryWait: RetryWaitHook | undefined, delayMs: number, signal?: AbortSignal): Promise<void>;

package/dist/types/utils/schema/normalize.d.ts

@@ -10,7 +10,11 @@ export interface NormalizeSchemaOptions {
     unsupportedFields: (key: string) => boolean;
     normalizeFieldNames: boolean;
     collapseNullFields: boolean;
-    normalizeTypeArrayToNullable: boolean;
+    /**
+     * Target takes a scalar `type` only: `["T", "null"]` becomes `T` (+ `nullable`)
+     * and a multi-type array becomes one `anyOf` branch per type.
+     */
+    scalarizeTypeArrays: boolean;
     stripNullableKeyword: boolean;
     autoPropertyOrdering: boolean;
     ensureObjectProperties: boolean;
@@ -66,8 +70,9 @@ export declare function normalizeSchemaForMCP(value: unknown): unknown;
  *    rejected; collapse to `enum` with an inferred scalar `type`.
  *  - `oneOf` is not an MFJS combinator (only `anyOf` is); residual `oneOf` is
  *    folded into `anyOf`.
- *  - `type` must be a scalar string; `type: [...]` arrays are reduced to a
- *    single scalar (the `null` branch is dropped — `nullable` is unsupported).
+ *  - `type` must be a scalar string; `["T", "null"]` reduces to `T` (the
+ *    `null` member is dropped — `nullable` is unsupported) and a multi-type
+ *    array becomes one typed `anyOf` branch per type.
  *  - Enum-bearing nodes get an inferred `type` (the idiomatic MFJS form; a bare
  *    `enum` is valid too) so `anyOf` branches always carry a `type`.
  *  - Validation/decorative keywords (`minItems`, `maxItems`, `maxLength`,

package/dist/types/utils/stream-markup-healing.d.ts

@@ -63,10 +63,10 @@ export declare class StreamMarkupHealing {
     /** Drain accumulated tool calls from calls to {@link feed}. */
     drainCompleted(): HealedToolCall[];
     /**
-     * Flush held-back stream-end fragments as ordered events. Partial tool-call
-     * sections/envelopes are dropped by the delegated scanners; unterminated
-     * thinking blocks are emitted as thinking, matching the previous MiniMax parser
-     * behavior.
+     * Flush held-back stream-end fragments as ordered events. Partial tool calls
+     * are dropped by the delegated scanners; a DSML wrapper without an invoke
+     * remains visible for agent-layer leak recovery. Unterminated thinking blocks
+     * are emitted as thinking.
      */
     flushEvents(): StreamMarkupHealingEvent[];
     /** Flush held-back text only. Reconstructed calls are retained for {@link drainCompleted}. */

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

@@ -1,6 +1,14 @@
 import type { ToolCall } from "../types.js";
 /** Final arguments must not reuse the streaming parser's auto-closed preview. */
 export declare function parseToolCallArguments(json: string | undefined): ToolCall["arguments"];
+/**
+ * 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).
+ * 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;
 /** Longest raw argument text kept in the parse-error diagnostic. */
 export declare const INVALID_ARGUMENTS_RAW_LIMIT = 512;
 /** Bound raw argument text for a diagnostic. Text this function already bounded is returned unchanged. */

package/dist/types/utils.d.ts

@@ -34,6 +34,12 @@ export declare function stripOpenAIResponsesOutputOnlyStatusesForReplay<TItem ex
     type?: unknown;
     status?: unknown;
 }>(items: TItem[]): TItem[];
+/** Clamp replayed images without changing item identities or other native replay fields. */
+export declare function clampOpenAIResponsesImageDetailForReplay<TItem extends {
+    type?: unknown;
+    detail?: unknown;
+    content?: unknown;
+}>(items: TItem[], supportsImageDetailOriginal: boolean): TItem[];
 export declare function sanitizeOpenAIResponsesHistoryItemsForReplay(items: Array<Record<string, unknown>>, options?: OpenAIResponsesReplaySanitizeOptions): ResponseInput;
 /** Strip reasoning IDs whose only linked native output is a computer call that will be demoted. */
 export declare function stripOpenAIResponsesComputerLinkedReasoningIdsForReplay(items: ResponseInput): ResponseInput;

package/package.json

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

package/src/auth/affinity.ts

@@ -1,9 +1,11 @@
 import { logger } from "@linxiraos/pi-utils";
-import { getEnvApiKey } from "../stream";
-import type { AuthCredential, OAuthCredential, SessionsApi } from "./types";
+import { LRUCache } from "@linxiraos/pi-utils/lru";
+import { getEnvApiKey } from "../env-api-key";
+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:";
@@ -14,6 +16,11 @@ const SESSION_STICKY_TTL_SEC = 30 * 24 * 60 * 60;
  * in-memory sticky stays exact; only the copy other processes resume from lags.
  */
 const SESSION_STICKY_PERSIST_INTERVAL_MS = 60_000;
+/**
+ * In-memory pins kept per provider. Long-lived gateways mint a session id per
+ * conversation; evicted sessions resume from their persisted sticky row.
+ */
+const SESSION_AFFINITY_MAX_SESSIONS_PER_PROVIDER = 256;
 
 /** What this process last wrote (or read) for one persisted sticky row. */
 type PersistedSticky = {
@@ -33,29 +40,100 @@ 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). */
-	#sessionLastCredential: Map<string, Map<string, SessionCredential>> = new Map();
-	/** Persisted sticky rows keyed by cache key, so unchanged re-records skip the write. */
-	#persistedSticky: Map<string, PersistedSticky> = new Map();
+	#sessionLastCredential: Map<string, LRUCache<string, SessionCredential>> = new Map();
+	/** Persisted sticky rows per provider, keyed by session id, so unchanged re-records skip the write. */
+	#persistedSticky: Map<string, LRUCache<string, PersistedSticky>> = new Map();
 	#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);
+	}
+
+	permits(provider: string, sessionId: string, credentialId: number): boolean {
+		if (!this.isRestricted(provider, sessionId)) return true;
+		const entry = this.#pool.entries(provider).find(candidate => candidate.id === credentialId);
+		return entry !== undefined && this.allows(provider, sessionId, entry.credential);
+	}
+
+	/** Bounded per-provider session map, created on first use. */
+	static #sessionsFor<V>(maps: Map<string, LRUCache<string, V>>, provider: string): LRUCache<string, V> {
+		let sessions = maps.get(provider);
+		if (!sessions) {
+			sessions = new LRUCache<string, V>({ max: SESSION_AFFINITY_MAX_SESSIONS_PER_PROVIDER });
+			maps.set(provider, sessions);
+		}
+		return sessions;
 	}
 
 	/** Drop every pin for a provider, both in memory and in the persisted cache. */
 	clearProvider(provider: string): void {
 		this.#sessionLastCredential.delete(provider);
+		this.#persistedSticky.delete(provider);
 		const prefix = `${SESSION_STICKY_CACHE_PREFIX}${provider}:`;
-		for (const cacheKey of this.#persistedSticky.keys()) {
-			if (cacheKey.startsWith(prefix)) this.#persistedSticky.delete(cacheKey);
-		}
 		try {
 			this.#store.deleteCachePrefix?.(prefix);
 		} catch (err) {
@@ -87,10 +165,10 @@ 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 = this.#sessionLastCredential.get(provider) ?? new Map();
+		const sessionMap = SessionAffinity.#sessionsFor(this.#sessionLastCredential, provider);
 		const previous = sessionMap.get(sessionId);
 		const sameCredential =
 			previous?.type === type &&
@@ -104,12 +182,12 @@ export class SessionAffinity implements SessionsApi {
 			...(isExplicit ? { explicit: true as const } : {}),
 		};
 		sessionMap.set(sessionId, sessionCredential);
-		this.#sessionLastCredential.set(provider, sessionMap);
 
 		if (credentialId === undefined) return;
 		const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
 		const expiresAtSec = Math.floor(nowMs / 1000) + SESSION_STICKY_TTL_SEC;
-		const persisted = this.#persistedSticky.get(cacheKey);
+		const persistedSessions = SessionAffinity.#sessionsFor(this.#persistedSticky, provider);
+		const persisted = persistedSessions.get(sessionId);
 		if (
 			persisted &&
 			persisted.type === type &&
@@ -121,23 +199,31 @@ export class SessionAffinity implements SessionsApi {
 		}
 		try {
 			this.#store.setCache(cacheKey, JSON.stringify(sessionCredential), expiresAtSec);
-			this.#persistedSticky.set(cacheKey, {
+			persistedSessions.set(sessionId, {
 				type,
 				credentialId,
 				explicit: isExplicit,
 				lastUsedAtMs: nowMs,
 			});
 		} catch (err) {
-			this.#persistedSticky.delete(cacheKey);
+			persistedSessions.delete(sessionId);
 			logger.debug("Failed to write session sticky credential to persistent store cache", { err });
 		}
 	}
 
-	/** 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;
-		let sessionMap = this.#sessionLastCredential.get(provider);
-		const live = sessionMap?.get(sessionId);
+		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
 			// index-ordered snapshot, so re-resolve the pin through its durable row
@@ -147,7 +233,7 @@ export class SessionAffinity implements SessionsApi {
 			const stored = this.#pool.entries(provider);
 			const actualIndex = stored.findIndex(entry => entry.id === live.credentialId);
 			if (actualIndex === -1 || stored[actualIndex]?.credential.type !== live.type) {
-				sessionMap?.delete(sessionId);
+				this.#sessionLastCredential.get(provider)?.delete(sessionId);
 				return undefined;
 			}
 			live.index = actualIndex;
@@ -163,22 +249,18 @@ export class SessionAffinity implements SessionsApi {
 					const stored = this.#pool.entries(provider);
 					const actualIndex = stored.findIndex(entry => entry.id === val.credentialId);
 					if (actualIndex === -1 || stored[actualIndex]?.credential.type !== val.type) {
-						this.#persistedSticky.delete(cacheKey);
+						this.#persistedSticky.get(provider)?.delete(sessionId);
 						this.#store.setCache(cacheKey, "", 0);
 						return undefined;
 					}
 					val.index = actualIndex;
 				} else {
 					// Fallback: drop unsafe index-only cache rows to prevent wrong-account routing
-					this.#persistedSticky.delete(cacheKey);
+					this.#persistedSticky.get(provider)?.delete(sessionId);
 					this.#store.setCache(cacheKey, "", 0);
 					return undefined;
 				}
 
-				if (!sessionMap) {
-					sessionMap = new Map();
-					this.#sessionLastCredential.set(provider, sessionMap);
-				}
 				const sessionVal: SessionCredential = {
 					type: val.type,
 					index: val.index,
@@ -187,14 +269,14 @@ export class SessionAffinity implements SessionsApi {
 					...(val.explicit === true ? { explicit: true } : {}),
 				};
 				if (typeof val.lastUsedAtMs === "number") {
-					this.#persistedSticky.set(cacheKey, {
+					SessionAffinity.#sessionsFor(this.#persistedSticky, provider).set(sessionId, {
 						type: val.type,
 						credentialId: val.credentialId,
 						explicit: val.explicit === true,
 						lastUsedAtMs: val.lastUsedAtMs,
 					});
 				}
-				sessionMap.set(sessionId, sessionVal);
+				SessionAffinity.#sessionsFor(this.#sessionLastCredential, provider).set(sessionId, sessionVal);
 				return sessionVal;
 			}
 		} catch (err) {
@@ -214,7 +296,7 @@ export class SessionAffinity implements SessionsApi {
 			}
 		}
 		const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
-		this.#persistedSticky.delete(cacheKey);
+		this.#persistedSticky.get(provider)?.delete(sessionId);
 		try {
 			this.#store.setCache(cacheKey, "", 0);
 		} catch (err) {
@@ -224,12 +306,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);
@@ -242,7 +329,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
@@ -266,32 +353,38 @@ 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;
 	}
 
 	/**
-	 * 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 {
 		if (!sourceSessionId || !targetSessionId || sourceSessionId === targetSessionId) return 0;
 		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;
+			if (include && !include(provider, credential.explicit === true)) continue;
 			this.record(
 				provider,
 				targetSessionId,