@herbertgao/pi-extensions 2026.9.20 → 2026.10.0

package/node_modules/pi-multi-account/index.ts

@@ -28,6 +28,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { createPayloadStream } from "./provider-payload-stream.ts";
 import { mutateProxyAuth } from "./auth-file-transaction.ts";
 import { mergeStateDeltas, mutateStateFile } from "./state-file-transaction.ts";
+import { normalizeModelPins, persistModelPin, validModelPinScope } from "./model-pins.ts";
+import { mutateConfigFile } from "./config-file-transaction.ts";
 import { createHash } from "node:crypto";
 import {
 	accessSync,
@@ -46,7 +48,8 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { homedir } from "node:os";
 import { Readable } from "node:stream";
 import { dirname, join } from "node:path";
-import { createRequire } from "node:module";
+import { getModel as getHostModel } from "@earendil-works/pi-ai/compat";
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
@@ -120,33 +123,15 @@ import {
 } from "./context-guard.ts";
 
 // ---------------------------------------------------------------------------
-// pi-ai OAuth bridge (version-agnostic)
+// Host-bound pi-ai OAuth bridge
 // ---------------------------------------------------------------------------
-//
-// This is the single most fragile boundary in the extension, and it has now broken
-// twice in the field:
-//
-//   * pi-coding-agent's extension loader aliases `@earendil-works/pi-ai/oauth` to an
-//     empty stub in its own node_modules, so a plain static import yields undefined —
-//     the `undefined is not an object (evaluating
-//     '_oauth.openaiCodexOAuthProvider.usesCallbackServer')` crash at startup.
-//   * pi-ai 0.80 REMOVED the runtime OAuth surface: `dist/oauth.js` is now literally
-//     `export {}` (types only), `getModel` moved to `dist/compat.js`, and the OAuth
-//     implementations live behind provider factories
-//     (`anthropicProvider().auth.oauth`) with a new `login(interaction)` /
-//     `refresh(credential)` shape.
-//
-// So we resolve pi-ai on disk ourselves and normalize BOTH eras behind one internal
-// surface. Everything here is best-effort: a pi-ai we cannot adapt degrades to
-// "subscription logins unavailable" and the extension still loads, so API-key
-// accounts keep rotating instead of the whole extension dying at load time.
-//
-// The 0.80+ adaptation follows the approach contributed by @lfoscari in PR #4.
-
+// Pi's extension loader binds these public imports to the running host SDK.
+// Never probe a private SDK copy: its provider catalog/auth may differ from Pi's.
+// Supported Pi versions use provider factories; legacy callbacks are adapted below.
 /** Normalized OAuth surface — identical for every supported pi-ai version. */
 type PiAiOauthBridge = {
 	/** pi-ai release line this was adapted from, for the debug log. */
-	era: "legacy-oauth-entry" | "provider-factories";
+	era: "provider-factories";
 	anthropic: {
 		login: (callbacks: any) => Promise<any>;
 		refresh: (credentials: any, signal: AbortSignal) => Promise<any>;
@@ -174,57 +159,6 @@ type PiAiOauthBridge = {
 
 let piAiOauthBridge: PiAiOauthBridge | undefined;
 let piAiOauthLoadError: string | undefined;
-let piAiPackageRoot: string | undefined | null; // null = searched, not found
-
-/**
- * Locate the `@earendil-works/pi-ai` package directory, nearest-first.
- *
- * A git checkout keeps pi-ai in the extension's OWN node_modules, but `npm i` /
- * `pi install` HOIST it next to the package instead
- * (`~/.pi/agent/npm/node_modules/pi-multi-account` +
- * `~/.pi/agent/npm/node_modules/@earendil-works/pi-ai`), and pnpm hides it behind a
- * symlinked store. Probing only the nested path made the extension fail to load on
- * every hoisted install, so walk ancestors the way Node's own resolver does and fall
- * back to require.resolve().
- */
-export function piAiRootCandidates(
-	fromFile: string,
-	resolver?: (specifier: string) => string,
-): string[] {
-	const candidates: string[] = [];
-	let dir = dirname(fromFile);
-	for (let depth = 0; depth < 16; depth++) {
-		candidates.push(join(dir, "node_modules", "@earendil-works", "pi-ai"));
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	if (resolver) {
-		try {
-			// Resolves through "exports"/symlinks even when no ancestor path matched.
-			candidates.push(dirname(resolver("@earendil-works/pi-ai/package.json")));
-		} catch {
-			// Not resolvable from here — the ancestor paths above may still hit.
-		}
-	}
-	return [...new Set(candidates)];
-}
-
-function findPiAiRoot(): string | undefined {
-	if (piAiPackageRoot !== undefined) return piAiPackageRoot ?? undefined;
-	const here = fileURLToPath(import.meta.url);
-	const localRequire = createRequire(import.meta.url);
-	for (const candidate of piAiRootCandidates(here, (specifier) =>
-		localRequire.resolve(specifier),
-	)) {
-		if (existsSync(join(candidate, "package.json"))) {
-			piAiPackageRoot = candidate;
-			return candidate;
-		}
-	}
-	piAiPackageRoot = null;
-	return undefined;
-}
 
 /**
  * Bridge Pi's legacy extension OAuth callbacks (`onAuth`/`onDeviceCode`/`onPrompt`/
@@ -272,48 +206,15 @@ function toAuthInteraction(callbacks: any) {
 	};
 }
 
-/** pi-ai <= 0.79: runtime OAuth helpers exported straight from `dist/oauth.js`. */
-function adaptLegacyOauthEntry(mod: any): PiAiOauthBridge | undefined {
-	const codex = mod?.openaiCodexOAuthProvider;
-	if (
-		typeof mod?.loginAnthropic !== "function" ||
-		typeof mod?.refreshAnthropicToken !== "function" ||
-		typeof codex?.login !== "function" ||
-		typeof codex?.refreshToken !== "function"
-	) {
-		return undefined;
-	}
-	return {
-		era: "legacy-oauth-entry",
-		anthropic: {
-			login: (callbacks) => mod.loginAnthropic(callbacks),
-			// This era exchanges the bare refresh token, not the whole credential.
-			refresh: (credentials, signal) =>
-				mod.refreshAnthropicToken(credentials.refresh, signal),
-		},
-		codex: {
-			usesCallbackServer: codex.usesCallbackServer ?? true,
-			login: (callbacks) => codex.login(callbacks),
-			refresh: (credentials, signal) => codex.refreshToken(credentials, signal),
-			getApiKey: (credentials) =>
-				typeof codex.getApiKey === "function"
-					? codex.getApiKey(credentials)
-					: credentials.access,
-		},
-	};
-}
 
 /** pi-ai >= 0.80: OAuth lives behind provider factories, with an AuthInteraction API. */
-function adaptProviderFactories(
-	anthropicMod: any,
-	codexMod: any,
-	kimiMod?: any,
-	xaiMod?: any,
-): PiAiOauthBridge | undefined {
-	const anthropicOauth = anthropicMod?.anthropicProvider?.()?.auth?.oauth;
-	const codexOauth = codexMod?.openaiCodexProvider?.()?.auth?.oauth;
-	const kimiOauth = kimiMod?.kimiCodingProvider?.()?.auth?.oauth;
-	const xaiOauth = xaiMod?.xaiProvider?.()?.auth?.oauth;
+function adaptProviderFactories(): PiAiOauthBridge | undefined {
+	const providers = builtinProviders();
+	const oauth = (id: string): any => providers.find((provider) => provider.id === id)?.auth?.oauth;
+	const anthropicOauth = oauth("anthropic");
+	const codexOauth = oauth("openai-codex");
+	const kimiOauth = oauth("kimi-coding");
+	const xaiOauth = oauth("xai");
 	if (
 		typeof anthropicOauth?.login !== "function" ||
 		typeof anthropicOauth?.refresh !== "function" ||
@@ -355,58 +256,18 @@ function adaptProviderFactories(
 	};
 }
 
-/**
- * Best-effort load + normalization of pi-ai's OAuth surface. NEVER throws.
- *
- * Uses a synchronous require() (Node >= 22 supports require() of ESM without
- * top-level await, and pi-ai qualifies) because providers are registered
- * synchronously — `usesCallbackServer` is read while Pi merely LISTS providers.
- */
+/** Adapt the running host's public factories without loading another SDK instance. */
 function tryLoadPiAiOauth(): PiAiOauthBridge | undefined {
 	if (piAiOauthBridge) return piAiOauthBridge;
-	const root = findPiAiRoot();
-	if (!root) {
-		piAiOauthLoadError = `@earendil-works/pi-ai was not found near ${fileURLToPath(import.meta.url)}. Install @earendil-works/pi-ai alongside pi-multi-account.`;
-		return undefined;
-	}
-	const localRequire = createRequire(import.meta.url);
-	const load = (relative: string): any => {
-		const file = join(root, "dist", relative);
-		if (!existsSync(file)) return undefined;
-		try {
-			return localRequire(file);
-		} catch (error) {
-			tried.push(
-				`${relative}: ${error instanceof Error ? error.message : String(error)}`,
-			);
-			return undefined;
-		}
-	};
-	const tried: string[] = [];
-
-	const legacy = adaptLegacyOauthEntry(load("oauth.js"));
-	if (legacy) {
-		piAiOauthBridge = legacy;
-		piAiOauthLoadError = undefined;
-		return legacy;
-	}
-	tried.push("dist/oauth.js exports no runtime OAuth helpers (pi-ai >= 0.80)");
-
-	const modern = adaptProviderFactories(
-		load(join("providers", "anthropic.js")),
-		load(join("providers", "openai-codex.js")),
-		load(join("providers", "kimi-coding.js")),
-		load(join("providers", "xai.js")),
-	);
-	if (modern) {
-		piAiOauthBridge = modern;
-		piAiOauthLoadError = undefined;
-		return modern;
+	try {
+		piAiOauthBridge = adaptProviderFactories();
+		piAiOauthLoadError = piAiOauthBridge
+			? undefined
+			: "the running Pi host exposes no usable pi-ai OAuth provider factories";
+	} catch (error) {
+		piAiOauthLoadError = error instanceof Error ? error.message : String(error);
 	}
-	tried.push("dist/providers/{anthropic,openai-codex}.js exposed no auth.oauth");
-
-	piAiOauthLoadError = `the @earendil-works/pi-ai at ${root} exposes no OAuth surface this extension can use. ${tried.join("; ")}`;
-	return undefined;
+	return piAiOauthBridge;
 }
 
 /** Load reason, or undefined when OAuth is available. */
@@ -425,36 +286,10 @@ function requirePiAiOauth(): PiAiOauthBridge {
 	return bridge;
 }
 
-/**
- * pi-ai's static model catalog lookup. It lived on the package root until 0.79 and
- * moved to `dist/compat.js` in 0.80, so resolve it lazily from whichever is present
- * — and treat "absent" as "no canonical metadata", never as a load failure.
- */
-let piAiGetModelFn: ((provider: string, id: string) => any) | null | undefined;
-
+/** Canonical chat metadata comes from the same SDK catalog as the running host. */
 function piAiGetModel(provider: string, id: string): any {
-	if (piAiGetModelFn === undefined) {
-		piAiGetModelFn = null;
-		const root = findPiAiRoot();
-		if (root) {
-			const localRequire = createRequire(import.meta.url);
-			for (const relative of ["compat.js", "index.js"]) {
-				const file = join(root, "dist", relative);
-				if (!existsSync(file)) continue;
-				try {
-					const candidate = localRequire(file)?.getModel;
-					if (typeof candidate === "function") {
-						piAiGetModelFn = candidate;
-						break;
-					}
-				} catch {
-					// Try the next entry point.
-				}
-			}
-		}
-	}
 	try {
-		return piAiGetModelFn?.(provider, id);
+		return getHostModel(provider as any, id as any);
 	} catch {
 		return undefined;
 	}
@@ -653,6 +488,9 @@ type ProviderFailoverConfig = {
 	// { "openai-codex": ["gpt-5.6", "gpt-5.5"], "anthropic": ["claude-opus-4-9"] }.
 	// Keys: anthropic | openai-codex | cursor | qwen | ollama.
 	preferredModels?: Record<string, string[]>;
+	// Explicit per-account-group model preference. It never selects a foreground model,
+	// bypasses a cooldown, or authorizes an automatic quality-tier change.
+	pinnedModels?: Record<string, string>;
 	// Forward-progress watchdog tunables (see constants above). 0/absent ⇒ built-in default.
 	resumeIdleTimeoutMs?: number;
 	stuckWatchdogMs?: number;
@@ -702,6 +540,7 @@ type RuntimeConfig = Required<
 		| "preferLatestModel"
 		| "reasoningLevel"
 		| "preferredModels"
+		| "pinnedModels"
 		| "resumeIdleTimeoutMs"
 		| "stuckWatchdogMs"
 		| "compactionWatchdogMs"
@@ -830,6 +669,7 @@ function configuredModelIds(provider: string): string[] {
 		const models = parsed?.providers?.[provider]?.models;
 		if (Array.isArray(models)) {
 			return models
+				.filter((model: any) => !model?.type || model.type === "chat")
 				.map((model: any) => (typeof model === "string" ? model : model?.id))
 				.filter((id: unknown): id is string => typeof id === "string" && id.length > 0);
 		}
@@ -840,6 +680,21 @@ function configuredModelIds(provider: string): string[] {
 	}
 }
 
+// Pi 0.99's provider composer replaces a supplied models array in full. Preserve
+// non-chat definitions verbatim; they must never become account chat aliases.
+function configuredOperationModels(provider: string): any[] {
+	try {
+		const parsed = JSON.parse(readFileSync(MODELS_CONFIG_PATH, "utf8"));
+		const models = parsed?.providers?.[provider]?.models;
+		return Array.isArray(models)
+			? models.filter((model: any) => model && typeof model === "object" &&
+				(model.type === "image" || model.type === "classifier"))
+			: [];
+	} catch {
+		return [];
+	}
+}
+
 function readHostDefaultModel(): { provider: string; id: string } | undefined {
 	try {
 		const parsed = JSON.parse(readFileSync(SETTINGS_PATH, "utf8"));
@@ -1195,7 +1050,7 @@ const ANTI_PINGPONG_MS = 60 * 1000; // don't switch straight back to the account
 // Bumped on every release. Printed at startup and in `/multi-account status` so you can verify
 // which version Pi actually loaded (a running Pi keeps the version it started with — /login and
 // /reload do NOT reload extension code; only a full restart does).
-const VERSION = "1.23.2";
+const VERSION = "1.24.0";
 function sourceFingerprint(): string {
 	try {
 		const root = dirname(fileURLToPath(import.meta.url));
@@ -1816,6 +1671,7 @@ const DEFAULT_CONFIG: ProviderFailoverConfig = {
 	preferLatestModel: true,
 	reasoningLevel: "auto",
 	preferredModels: {},
+	pinnedModels: {},
 	resumeIdleTimeoutMs: RESUME_IDLE_TIMEOUT_MS,
 	stuckWatchdogMs: STUCK_WATCHDOG_MS,
 	compactionWatchdogMs: COMPACTION_WATCHDOG_MS,
@@ -1828,11 +1684,12 @@ const DEFAULT_CONFIG: ProviderFailoverConfig = {
 function ensureDefaultConfig() {
 	if (existsSync(CONFIG_PATH)) return;
 	mkdirSync(dirname(CONFIG_PATH), { recursive: true, mode: 0o700 });
-	writeFileSync(
-		CONFIG_PATH,
-		`${JSON.stringify(DEFAULT_CONFIG, null, "\t")}\n`,
-		{ encoding: "utf8", mode: 0o600 },
-	);
+	try {
+		writeFileSync(CONFIG_PATH, `${JSON.stringify(DEFAULT_CONFIG, null, "\t")}\n`,
+			{ encoding: "utf8", mode: 0o600, flag: "wx" });
+	} catch (error: any) {
+		if (error?.code !== "EEXIST") throw error; // Another root initialized it first.
+	}
 }
 
 function positiveOr(value: unknown, fallback: number) {
@@ -2036,6 +1893,7 @@ function normalizeConfig(raw: ProviderFailoverConfig): RuntimeConfig {
 							.filter(([, v]) => v.length > 0),
 					)
 				: {},
+		pinnedModels: normalizeModelPins(raw.pinnedModels),
 		resumeIdleTimeoutMs: positiveOr(
 			raw.resumeIdleTimeoutMs,
 			RESUME_IDLE_TIMEOUT_MS,
@@ -2287,6 +2145,20 @@ export async function persistRefreshedCredentials(
 		write?: (data: Record<string, any>) => void;
 	},
 ): Promise<boolean> {
+	// Even legacy/set-only hosts must never unhide a numbered slot while saving a refresh.
+	if (!io && isChildFacingPlaceholderForSlot(readAuthFileRaw()[provider], provider)) {
+		try {
+			let persisted = false;
+			mutateProxyAuth(AUTH_PATH, PROXY_OAUTH_PATH, (auth, sidecar) => {
+				if (!isChildFacingPlaceholderForSlot(auth[provider], provider) || sidecar[provider]?.type !== "oauth") {
+					return { auth, sidecar, changed: false };
+				}
+				persisted = true;
+				return { auth, sidecar: { ...sidecar, [provider]: credential }, changed: true };
+			}, "shadow");
+			return persisted;
+		} catch { return false; }
+	}
 	if (typeof authStorage?.modify === "function") {
 		try {
 			await authStorage.modify(provider, () => credential);
@@ -2371,6 +2243,17 @@ function jwtExpMs(token: string): number | undefined {
 		: undefined;
 }
 
+/**
+ * When an OAuth access token expires. Anthropic's `sk-ant-oat…` tokens are opaque, so the JWT
+ * `exp` is absent and the stored `expires` (seconds or milliseconds) is the only signal.
+ */
+function oauthExpiryMs(entry: AuthEntry): number | undefined {
+	const fromJwt = typeof entry.access === "string" ? jwtExpMs(entry.access) : undefined;
+	if (fromJwt !== undefined) return fromJwt;
+	if (typeof entry.expires !== "number" || !Number.isFinite(entry.expires)) return undefined;
+	return entry.expires < 10_000_000_000 ? entry.expires * 1000 : entry.expires;
+}
+
 function getCursorSubFromAccessToken(token: string): string | undefined {
 	const sub = decodeJwtPayload(token)?.sub;
 	return typeof sub === "string" && sub.length > 0 ? sub : undefined;
@@ -2501,13 +2384,7 @@ function isEntryUsable(entry: AuthEntry | undefined): boolean {
 	if (typeof entry.access !== "string" || entry.access.length === 0)
 		return false;
 	// Expired access token with no refresh token → unrecoverable.
-	const storedExpiry =
-		typeof entry.expires === "number" && Number.isFinite(entry.expires)
-			? entry.expires < 10_000_000_000
-				? entry.expires * 1000
-				: entry.expires
-			: undefined;
-	const expMs = jwtExpMs(entry.access) ?? storedExpiry;
+	const expMs = oauthExpiryMs(entry);
 	if (
 		expMs !== undefined &&
 		expMs <= Date.now() &&
@@ -3072,7 +2949,7 @@ function registerCodexCatalog(
 		baseUrl,
 		api: "openai-codex-responses" as any,
 		oauth: codexOAuthOverride(id, name),
-		models: models as any,
+		models: [...models, ...configuredOperationModels(id)] as any,
 	});
 }
 
@@ -3548,7 +3425,7 @@ const MINIMAL_ANTHROPIC_OAUTH_PROMPT = [
 ].join("\n");
 const CLAUDE_CODE_IDENTITY_PREFIX =
 	"You are Claude Code, Anthropic's official CLI";
-const CLAUDE_CODE_VERSION = "2.1.280";
+const CLAUDE_CODE_VERSION = "2.1.288";
 const BILLING_HEADER_SALT = "59cf53e54c78";
 const BILLING_HEADER_POSITIONS = [4, 7, 20] as const;
 const CLAUDE_CODE_ENTRYPOINT = "sdk-cli";
@@ -3925,10 +3802,8 @@ interface HostCompletionRouterAPI {
 export default function piMultiAccount(pi: ExtensionAPI) {
 	// Warm up the OAuth helpers before any provider registration: providers are
 	// registered synchronously below and their `usesCallbackServer`/`getApiKey`
-	// read from the cached module. Deliberately NON-fatal — if pi-ai's oauth entry
-	// cannot be resolved (hoisted npm layout, incompatible pi-ai), the extension
-	// still loads and every non-OAuth account keeps working; only subscription
-	// logins are unavailable, and the user is told once at session start.
+	// use the cached host adapter. An unusable OAuth factory remains non-fatal:
+	// API-key accounts keep working and session start reports unavailable OAuth.
 	const oauthUnavailable = piAiOauthUnavailableReason();
 	let subagentChild = isSubagentChildProcess();
 	let hostOwnsSessionModel = false;
@@ -4881,11 +4756,19 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			let refreshed: AuthEntry | undefined;
 			let persistedUnderLock = false;
 			if (family === "anthropic") {
-				refreshed = await refreshAnthropicCredentials(
-					entry,
-					undefined,
-					provider,
-				);
+				const refreshAnthropic = (current: AuthEntry) => refreshAnthropicCredentials(current, undefined, provider);
+				if (typeof authStorage?.modify === "function") {
+					refreshed = await refreshAndPersistWithStorageLock({
+						provider, credentials: entry, authStorage,
+						readLatest: () => readAuthFile()[provider],
+						refresh: refreshAnthropic,
+						isShadowed: stored => isChildFacingPlaceholderForSlot(stored, provider),
+						persistShadowed: credential => writeProxyOAuthSidecar({ ...readProxyOAuthSidecar(), [provider]: credential }),
+					});
+					persistedUnderLock = true;
+				} else {
+					refreshed = await refreshAnthropic(entry);
+				}
 			} else if (family === "openai-codex") {
 				const refreshCodex = async (current: AuthEntry) => {
 					const next = mergeRefreshedCredentials(
@@ -5281,6 +5164,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			return; // keep the previous (or empty) discovered set; configured ids still serve
 		}
 		const models = ollamaRotationModelIds().map((m) => ollamaModelDef(m, OLLAMA_BASE));
+		models.push(...configuredOperationModels(OLLAMA_BASE));
 		pi.registerProvider(OLLAMA_BASE, {
 			name: "Ollama",
 			baseUrl: OLLAMA_CLOUD_BASE_URL,
@@ -6682,16 +6566,37 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		return [last, ...defaults.filter((id) => id !== last)];
 	}
 
-	// Rank of a model within its family's newest-first preferred order (0 = newest).
-	// Unknown models sort last. Used to keep the latest model across accounts, not
-	// just within one account, during fallback ranking.
+	function pinnedModelForProvider(provider: string): string | undefined {
+		const scope = accountGroup(provider, config.qwenProvider);
+		return Object.hasOwn(config.pinnedModels, scope) ? config.pinnedModels[scope] : undefined;
+	}
+
+	function pinQualityCompatible(model: any, source: any): boolean {
+		const pin = pinnedModelForProvider(model.provider);
+		const sourceBand = modelQualityBand(source?.id, source?.provider);
+		return !pin || !sameModelIdentity(model.id, pin) || !sourceBand || modelQualityBand(model.id, model.provider) === sourceBand;
+	}
+
+	function preferredModelsForProvider(provider: string): string[] {
+		const order = familyPreferredModels(classifyProvider(provider, config.qwenProvider));
+		const pin = pinnedModelForProvider(provider);
+		return pin ? [pin, ...order.filter(id => !sameModelIdentity(id, pin))] : order;
+	}
+
+	// Rank includes an explicit pin, but a pin is not evidence of a quality upgrade.
+	// Unknown models sort last; identity/liveness/quality constraints still apply first.
 	function modelRecencyRank(model: any): number {
-		const family = classifyProvider(model?.provider, config.qwenProvider);
-		const order = familyPreferredModels(family);
+		const order = preferredModelsForProvider(String(model?.provider ?? ""));
 		const idx = order.findIndex((id) => sameModelIdentity(id, model?.id));
 		return idx < 0 ? Number.MAX_SAFE_INTEGER : idx;
 	}
 
+	// Virtual and non-chat operations belong to Pi, not account chat rotation.
+	function isAccountChatModel(model: any): boolean {
+		return !!model && model.api !== "pi-virtual" &&
+			(!model.type || model.type === "chat");
+	}
+
 	function resolveTargets(
 		ctx: any,
 		target: string,
@@ -6702,7 +6607,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		if (!parsed) return [];
 		if (parsed.modelId) {
 			const model = findModelIncludingHidden(ctx, parsed.provider, parsed.modelId);
-			return model ? [model] : [];
+			return isAccountChatModel(model) ? [model] : [];
 		}
 
 		const family = classifyProvider(parsed.provider, config.qwenProvider);
@@ -6710,15 +6615,15 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			? classifyProvider(currentModel.provider, config.qwenProvider)
 			: undefined;
 		const sameFamily = !!family && !!currentFamily && family === currentFamily;
-		// A per-family config override (preferredModels) wins, so a new flagship model can be
-		// pinned without a code change. Order is newest-first either way.
-		const preferred = familyPreferredModels(family);
+		// A pin leads this account's model order without synthesizing a model or losing the
+		// underlying preferredModels/catalog order when that pin is missing or ineligible.
+		const preferred = preferredModelsForProvider(parsed.provider);
 		const keepCurrent = sameFamily && currentModel?.id ? [currentModel.id] : [];
 		// `preferredOnly` means "take this family's flagship, not an arbitrary model". A provider
 		// outside the managed families has no flagship list at all, so honouring it literally
 		// yields no candidate and the switch fails — which is what made an unmanaged account
 		// unreachable by name. Fall back to what Pi knows for it.
-		const usePreferredOnly = preferredOnly && preferred.length > 0;
+		const usePreferredOnly = preferredOnly && preferred.length > 0 && !pinnedModelForProvider(parsed.provider);
 		const registryModels = usePreferredOnly
 			? []
 			: [
@@ -6731,7 +6636,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		// once downgraded (e.g. gpt-5.4 after a momentary limit on gpt-5.5) is upgraded back to
 		// the latest the moment it is available again — instead of carrying the old model forever.
 		// Legacy mode keeps the current model first (never changes the model unless it has to).
-		const modelIds = config.preferLatestModel
+		const modelIds = config.preferLatestModel || pinnedModelForProvider(parsed.provider)
 			? [...preferred, ...keepCurrent, ...registryModels]
 			: [...keepCurrent, ...preferred, ...registryModels];
 		const result: any[] = [];
@@ -6739,7 +6644,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		for (const modelId of modelIds) {
 			if (seen.has(modelId)) continue;
 			const model = findModelIncludingHidden(ctx, parsed.provider, modelId);
-			if (!model) {
+			if (!isAccountChatModel(model)) {
 				seen.add(modelId);
 				continue;
 			}
@@ -6817,6 +6722,8 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			const sourceBand = modelQualityBand(currentModel?.id, currentModel?.provider);
 			const sourceExceptional = apexIdentity(currentModel?.id);
 			models = models.filter((model: any) => {
+				// A preference is not tier consent, including routed automatic compaction.
+				if (!pinQualityCompatible(model, currentModel)) return false;
 				const candidateBand = modelQualityBand(model.id, model.provider);
 				const candidateExceptional = apexIdentity(model.id);
 				// Cursor's Fable-named aliases are deliberately uncalibrated. A user may select one
@@ -6865,8 +6772,10 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 				// preferLatestModel still upgrades a known older sibling (gpt-5.4 → gpt-5.5)
 				// on a healthy account. An unranked catalog leftover (claude-4-sonnet beating
 				// grok only because it sorts first) must never steal the user's model.
+				const pinRepresentative = sameModelIdentity(pinnedModelForProvider(flagshipPick.provider), flagshipPick.id);
 				const upgrade =
 					config.preferLatestModel &&
+					!pinRepresentative &&
 					idRank !== Number.MAX_SAFE_INTEGER &&
 					flagRank < idRank;
 				pick = upgrade ? flagshipPick : identityPick;
@@ -7116,6 +7025,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			waitForQuotaRecovery?: boolean;
 		} = {},
 	) {
+		if (!isAccountChatModel(failedModel) || (ctx.model && !isAccountChatModel(ctx.model))) return false;
 		if (!options.manual && (isFailoverExempt(failedModel?.provider) || isFailoverExempt(ctx.model?.provider))) return false;
 		const switchEpoch = chainEpoch;
 		if (!automaticFailoverEnabled() || !failedModel?.provider || !failedModel?.id)
@@ -7376,6 +7286,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 	}
 
 	async function ensureReadyModel(ctx: any, reason: string) {
+		if (ctx.model && !isAccountChatModel(ctx.model)) return true;
 		// The launch candidate is authoritative in a pi-subagents child. Let the
 		// request produce its real error so the parent runner can advance its own
 		// fallbackModels chain instead of starting a competing router here.
@@ -9093,10 +9004,85 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		return true;
 	}
 
+	function modelPinLines(ctx: any): string[] {
+		const entries = Object.entries(config.pinnedModels).sort(([a], [b]) => a.localeCompare(b));
+		if (!entries.length) return ["  none — /multi-account pin <provider/model>"];
+		const models = [...ctx.modelRegistry.getAll(), ...[...hiddenProviderModels.values()].flat()];
+		const now = Date.now();
+		return entries.map(([scope, id]) => {
+			const matching = models.filter((model: any) => accountGroup(model.provider, config.qwenProvider) === scope &&
+				sameModelIdentity(model.id, id) && isAccountChatModel(model));
+			const usable = matching.filter((model: any) => !isInvalidated(model.provider) && providerHasUsableAuth(ctx, model.provider));
+			const sourceBand = modelQualityBand(ctx.model?.id, ctx.model?.provider);
+			const compatible = usable.filter((model: any) => {
+				const band = modelQualityBand(model.id, model.provider);
+				if (sourceBand === "apex") return band === "apex" && explicitlyAllowsPaidApexFallback(model, ctx.model);
+				return band !== "apex" && (!sourceBand || band === sourceBand) && (!apexIdentity(model.id) || sameModelIdentity(model.id, ctx.model?.id));
+			});
+			const free = compatible.filter((model: any) => providerRecoveryAt(model.provider, now) <= now &&
+				(exhaustedUntilByModel.get(`${model.provider}/${model.id}`) ?? 0) <= now);
+			const status = !matching.length ? "missing from catalog" : !usable.length ? "no usable account" :
+				!compatible.length ? "incompatible with current quality band" : !free.length ? "cooling" : "preference available";
+			return `  ${scope}: ${id} — ${status}`;
+		});
+	}
+
 	async function handleCommand(args: string, ctx: any) {
-		const [commandRaw, arg1] = args.trim().split(/\s+/);
+		const parts = args.trim().split(/\s+/);
+		const [commandRaw, arg1] = parts;
 		const command = (commandRaw || "status").toLowerCase();
 
+		if (command === "pins") {
+			if (parts.length > 2 || (arg1 && arg1 !== "list")) {
+				ctx.ui.notify("pi-multi-account: usage: /multi-account pins [list]", "warning");
+				return;
+			}
+			ctx.ui.notify(["pi-multi-account model pins (routing preferences, not foreground selections):", ...modelPinLines(ctx),
+				"Exact siblings, authentication, health and quality checks still apply. Other sessions adopt edits on reload/restart."].join("\n"), "info");
+			return;
+		}
+
+		if (command === "pin" || command === "unpin") {
+			const parsed = command === "pin" ? parseTarget(arg1) : undefined;
+			const provider = command === "pin" ? parsed?.provider : arg1;
+			if (parts.length !== 2 || !provider || !validModelPinScope(provider) ||
+				(command === "pin" && (!parsed?.modelId || /\s/.test(parsed.modelId)))) {
+				ctx.ui.notify("pi-multi-account: usage: /multi-account pin <provider/model> | unpin <provider-or-family> | pins [list]", "warning");
+				return;
+			}
+			if (subagentChild || sessionClosed || !ctx.isIdle()) {
+				ctx.ui.notify("pi-multi-account: change model pins from an idle live parent session; no preference was saved", "warning");
+				return;
+			}
+			const epoch = chainEpoch;
+			const selected = ctx.model ? ref(ctx.model.provider, ctx.model.id) : undefined;
+			const session = ctx.sessionManager?.getSessionId?.();
+			const canCommit = () => !subagentChild && !sessionClosed && ctx.isIdle() && epoch === chainEpoch &&
+				(ctx.model ? ref(ctx.model.provider, ctx.model.id) : undefined) === selected && ctx.sessionManager?.getSessionId?.() === session;
+			const scope = accountGroup(provider, config.qwenProvider);
+			const modelId = parsed?.modelId;
+			const exact = modelId ? findModelIncludingHidden(ctx, provider, modelId) : undefined;
+			const known = modelId ? [exact, ...ctx.modelRegistry.getAll(), ...[...hiddenProviderModels.values()].flat()].filter((model: any) =>
+				model && accountGroup(model.provider, config.qwenProvider) === scope && sameModelIdentity(model.id, modelId)) : [];
+			if ((exact && !isAccountChatModel(exact)) || (known.length > 0 && !known.some(isAccountChatModel))) {
+				ctx.ui.notify("pi-multi-account: only account chat models can be pinned; virtual/image/classifier models remain host-owned", "warning");
+				return;
+			}
+			try {
+				const pins = persistModelPin(CONFIG_PATH, scope, modelId, canCommit);
+				config = { ...config, pinnedModels: pins };
+				claimUserControl("model pin preference changed");
+				logEvent("model_pin_set", { scope, model: modelId ?? null });
+				ctx.ui.notify(command === "unpin"
+					? `pi-multi-account: removed model pin for ${scope}; the underlying preferredModels/catalog order is unchanged`
+					: `pi-multi-account: pinned ${scope}/${modelId} across sibling accounts.${known.length ? "" : " Saved but currently absent; inactive until the catalog supplies it."} Current model was not changed; select a cheaper tier explicitly. Other sessions adopt this preference on reload/restart.`,
+					known.length || command === "unpin" ? "info" : "warning");
+			} catch {
+				ctx.ui.notify("pi-multi-account: model pin was not saved; check config syntax, permissions/lock and session ownership. Runtime preference is unchanged", "error");
+			}
+			return;
+		}
+
 		if (command === "log" || command === "logs" || command === "debug") {
 			// Show the diagnostic black box so a misbehaviour can be reported precisely.
 			if (arg1 === "off") {
@@ -9389,14 +9375,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			configuredFallbacks = [];
 			config = { ...config, fallbacks: [] };
 			try {
-				const raw = existsSync(CONFIG_PATH)
-					? JSON.parse(readFileSync(CONFIG_PATH, "utf8"))
-					: {};
-				raw.fallbacks = [];
-				writeFileSync(CONFIG_PATH, `${JSON.stringify(raw, null, "\t")}\n`, {
-					encoding: "utf8",
-					mode: 0o600,
-				});
+				mutateConfigFile(CONFIG_PATH, () => ({ fallbacks: [] }));
 			} catch {
 				// non-fatal: in-memory state is still cleared
 			}
@@ -9610,7 +9589,8 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 				? `${parsed.provider}/${parsed.modelId}`
 				: parsed.provider;
 			const candidates = resolveTargets(ctx, resolvedTarget, ctx.model, true).filter(
-				(model: any) => providerHasUsableAuth(ctx, model.provider),
+				(model: any) => providerHasUsableAuth(ctx, model.provider) &&
+					(parsed.modelId !== undefined || pinQualityCompatible(model, ctx.model)),
 			);
 			if (candidates.length === 0) {
 				const hasAuth = providerHasUsableAuth(ctx, parsed.provider);
@@ -9755,14 +9735,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			onlyActiveModels = next2;
 			config = { ...config, onlyActive: next2 };
 			try {
-				const raw = existsSync(CONFIG_PATH)
-					? JSON.parse(readFileSync(CONFIG_PATH, "utf8"))
-					: {};
-				raw.onlyActive = next2;
-				writeFileSync(CONFIG_PATH, `${JSON.stringify(raw, null, "\t")}\n`, {
-					encoding: "utf8",
-					mode: 0o600,
-				});
+				mutateConfigFile(CONFIG_PATH, () => ({ onlyActive: next2 }));
 			} catch {
 				// non-fatal: the in-memory flag still applies for this session
 			}
@@ -9821,14 +9794,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 
 			config = { ...config, providerPriority: next };
 			try {
-				const raw = existsSync(CONFIG_PATH)
-					? JSON.parse(readFileSync(CONFIG_PATH, "utf8"))
-					: {};
-				raw.providerPriority = next;
-				writeFileSync(CONFIG_PATH, `${JSON.stringify(raw, null, "\t")}\n`, {
-					encoding: "utf8",
-					mode: 0o600,
-				});
+				mutateConfigFile(CONFIG_PATH, () => ({ providerPriority: next }));
 			} catch {
 				// non-fatal: the ladder still applies for this session
 			}
@@ -10004,7 +9970,8 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 				// list below, `switch` was effectively undiscoverable and `next` pressed repeatedly
 				// was the only way anyone found to reach a chosen account.
 				`Switch accounts: /multi-account best — jump straight to an account that can work now · /multi-account switch <provider> — e.g. /multi-account switch ${rotation.find((p) => p !== ctx.model?.provider) ?? rotation[0] ?? "<provider>"} · /multi-account next steps through the rotation in order`,
-				`Other commands: status | accounts [refresh] | best | priority [...] | limits [refresh] | models | pick | save-default | log [N|on|off] | only-active [on|off] | rediscover | add [anthropic|codex|kimi|cursor|ollama|qwen] | remove [anthropic|codex|kimi|cursor|ollama|qwen|<provider-id>] | revive <provider|all> | clear | stop | reset | reload | enable | disable`,
+				`Model pins: ${Object.entries(config.pinnedModels).map(([scope, id]) => `${scope}/${id}`).join(", ") || "none"} · /multi-account pins to inspect`,
+				`Other commands: status | accounts [refresh] | best | priority [...] | limits [refresh] | models | pick | pin <provider/model> | unpin <provider-or-family> | pins [list] | save-default | log [N|on|off] | only-active [on|off] | rediscover | add [anthropic|codex|kimi|cursor|ollama|qwen] | remove [anthropic|codex|kimi|cursor|ollama|qwen|<provider-id>] | revive <provider|all> | clear | stop | reset | reload | enable | disable`,
 			].join("\n"),
 			"info",
 		);
@@ -10084,6 +10051,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		const models = ids.map((m) =>
 			family === "ollama" ? ollamaModelDef(m, baseId) : qwenModelDef(m, baseId),
 		);
+		models.push(...configuredOperationModels(baseId));
 		pi.registerProvider(baseId, {
 			name: family === "ollama" ? "Ollama" : "Alibaba/Qwen",
 			baseUrl,
@@ -10799,8 +10767,10 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 	// An existing child-facing placeholder (possibly published by another root)
 	// must also stay on its canonical loopback, even when this instance's proxy is off.
 	function numberedAnthropicBaseUrl(id: string): string {
+		const raw = readAuthFileRaw()[id];
+		if (raw?.type === "api_key" && !isChildFacingPlaceholderForSlot(raw, id)) return "https://api.anthropic.com";
 		if (typeof slotProxyPort === "number") return publishedRouteFor(slotProxyPort, id);
-		if (isChildFacingPlaceholderForSlot(readAuthFileRaw()[id], id)) return publishedRouteFor(SLOT_PROXY_PORT, id);
+		if (isChildFacingPlaceholderForSlot(raw, id)) return publishedRouteFor(SLOT_PROXY_PORT, id);
 		return "https://api.anthropic.com";
 	}
 
@@ -10824,6 +10794,8 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 	 * the canonical loopback instead, even if this sibling disabled its own proxy.
 	 */
 	function numberedCodexBaseUrl(id: string): string {
+		const raw = readAuthFileRaw()[id];
+		if (raw?.type === "api_key" && !isChildFacingPlaceholderForSlot(raw, id)) return "https://chatgpt.com/backend-api";
 		if (typeof slotProxyPort === "number") return publishedRouteFor(slotProxyPort, id);
 		if (!config.childProxy && !isChildFacingPlaceholderForSlot(readAuthFileRaw()[id], id)) {
 			return "https://chatgpt.com/backend-api";
@@ -10847,7 +10819,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		let entry = readAuthFile()[slotId];
 		if (!entry) return undefined;
 		if (entry.type !== "oauth" || typeof entry.access !== "string") return entry;
-		const expiry = jwtExpMs(entry.access);
+		const expiry = oauthExpiryMs(entry);
 		// A minute of slack: a token that expires mid-flight fails the child's whole request, and
 		// refreshing one turn early costs nothing.
 		if (expiry !== undefined && expiry - 60_000 <= Date.now()) {
@@ -10884,10 +10856,9 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			return;
 		}
 		const parsed = parseProxyPath(req.url ?? "");
-		const presentedSecret =
-			parsed && typeof readAuthFile()[parsed.slotId]?.access === "string"
-				? readAuthFile()[parsed.slotId]?.access
-				: undefined;
+		const presentedEntry = parsed ? readAuthFile()[parsed.slotId] : undefined;
+		const presentedSecret = presentedEntry?.type === "oauth" ? presentedEntry.access :
+			presentedEntry?.type === "api_key" ? presentedEntry.key : undefined;
 		const verdict = admitRequest({
 			rawUrl: req.url ?? "",
 			headers: req.headers ?? {},
@@ -10920,9 +10891,9 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		let body: Buffer | undefined =
 			req.method === "GET" || req.method === "HEAD" ? undefined : await readRequestBody(req);
 		if (body && verdict.route.family === "anthropic" && credential?.type === "oauth") {
-			// The same shaping the in-process path applies: without it Anthropic rejects a
-			// subscription token outright. Done here because the child cannot do it — it has no
-			// idea it is talking to a proxy.
+			// The extension-owned billing shaping also applies to bare children. Their native
+			// host supplies OAuth identity/tool mapping through the token-shaped placeholder,
+			// but does not load this extension's billing-header maintenance.
 			try {
 				const parsed = JSON.parse(body.toString("utf8"));
 				const reshaped = shapeAnthropicOAuthPayload(parsed);
@@ -10932,11 +10903,18 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			}
 		}
 
+		if (res.destroyed) return;
+		const upstreamAbort = new AbortController();
+		const callerClosed = () => {
+			if (!res.writableFinished) upstreamAbort.abort();
+		};
+		res.once("close", callerClosed);
 		try {
 			const upstream = await fetch(shaped.url, {
 				method: req.method ?? "POST",
 				headers: shaped.headers,
 				body: body && body.length ? new Uint8Array(body) : undefined,
+				signal: upstreamAbort.signal,
 			});
 			const outgoing: Record<string, string> = {};
 			upstream.headers.forEach((value, name) => {
@@ -10948,7 +10926,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			if (upstream.body) {
 				await new Promise<void>((resolve) => {
 					const stream = Readable.fromWeb(upstream.body as any);
-					stream.on("error", () => resolve());
+					stream.on("error", () => { res.destroy(); resolve(); });
 					res.on("close", () => resolve());
 					stream.pipe(res);
 					res.on("finish", () => resolve());
@@ -10956,11 +10934,13 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			} else {
 				res.end();
 			}
-			logEvent("slot_proxy_forwarded", {
+			if (!upstreamAbort.signal.aborted) logEvent("slot_proxy_forwarded", {
 				slot: verdict.route.slotId,
 				status: upstream.status,
 			});
 		} catch (error) {
+			// A caller cancellation is not an upstream/provider failure or a quota verdict.
+			if (upstreamAbort.signal.aborted || res.destroyed) return;
 			const reason = error instanceof Error ? error.message : String(error);
 			logEvent("slot_proxy_upstream_failed", { slot: verdict.route.slotId, reason });
 			if (!res.headersSent) {
@@ -10969,6 +10949,8 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 			} else {
 				res.end();
 			}
+		} finally {
+			res.off("close", callerClosed);
 		}
 	}
 
@@ -11227,12 +11209,14 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 		for (const id of slots) {
 			const family = proxyFamilyOf(id);
 			if (!family) continue;
-			const baseUrl = publishedRouteFor(port, id);
+			const oauth = parent[id]?.type === "oauth";
+			const baseUrl = oauth ? publishedRouteFor(port, id) :
+				family === "anthropic" ? "https://api.anthropic.com" : "https://chatgpt.com/backend-api";
 			if (family === "anthropic") {
 				provisionNativeSlot(id, {
 					api: "anthropic-messages",
 					baseUrl,
-					apiKey: placeholderKeyFor(family),
+					apiKey: oauth ? placeholderKeyFor(family) : undefined,
 					models: DEFAULT_ANTHROPIC_MODELS.map((modelId) => ({
 						...anthropicModelDef(modelId, id),
 						baseUrl,
@@ -11253,7 +11237,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 				provisionNativeSlot(id, {
 					api: "openai-codex-responses",
 					baseUrl,
-					apiKey: placeholderKeyFor(family),
+					apiKey: oauth ? placeholderKeyFor(family) : undefined,
 					models,
 				});
 			}
@@ -12072,6 +12056,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 	});
 
 	safeOn("message_end", async (event, ctx) => {
+		if (!isAccountChatModel(ctx.model)) return;
 		const errorEpoch = chainEpoch;
 		const staleError = () => sessionClosed || errorEpoch !== chainEpoch || userAbortedChain || ctx.signal?.aborted;
 		const message = (event as any).message;
@@ -12287,6 +12272,7 @@ export default function piMultiAccount(pi: ExtensionAPI) {
 	});
 
 	safeOn("agent_end", async (event, ctx) => {
+		if (!isAccountChatModel(ctx.model)) return;
 		if (!automaticFailoverEnabled()) return;
 		const stop = lastAssistantStopReason((event as any).messages ?? []);
 		// Our own watchdog aborted a wedged resumed turn — this is RECOVERY, not a user cancel.