jeopi-cli 16.4.2 → 16.4.4

package/src/cli/update-cli.ts

@@ -112,6 +112,19 @@ async function getBunGlobalBinDir(): Promise<string | undefined> {
 	}
 }
 
+async function getNpmGlobalBinDir(): Promise<string | undefined> {
+	if (!$which("npm")) return undefined;
+	try {
+		const result = await $`npm prefix -g`.quiet().nothrow();
+		if (result.exitCode !== 0) return undefined;
+		const prefix = result.text().trim();
+		if (prefix.length === 0) return undefined;
+		return process.platform === "win32" ? prefix : path.join(prefix, "bin");
+	} catch {
+		return undefined;
+	}
+}
+
 async function getHomebrewFormulaPrefix(): Promise<string | undefined> {
 	if (!$which("brew")) return undefined;
 	for (const formula of [HOMEBREW_FORMULA, APP_NAME]) {
@@ -192,26 +205,36 @@ function isPathInDirectory(filePath: string, directoryPath: string): boolean {
 	return isPathInDirectoryLexical(resolvedFile, dirReal);
 }
 
-type UpdateMethod = "brew" | "mise" | "bun" | "binary";
+type UpdateMethod = "brew" | "mise" | "bun" | "npm" | "binary";
 
 interface UpdateMethodResolutionOptions {
 	homebrewPrefix?: string;
 	miseBinDirs?: readonly string[];
 	miseDataDir?: string;
+	npmBinDir?: string;
 }
 
-type UpdateTarget = { method: "brew" } | { method: "mise" } | { method: "bun" } | { method: "binary"; path: string };
+type UpdateTarget =
+	| { method: "brew" }
+	| { method: "mise" }
+	| { method: "bun" }
+	| { method: "npm" }
+	| { method: "binary"; path: string };
 
 function resolveUpdateMethod(
 	jeopiPath: string,
 	bunBinDir: string | undefined,
 	options: UpdateMethodResolutionOptions = {},
 ): UpdateMethod {
-	const { homebrewPrefix, miseBinDirs = [], miseDataDir } = options;
+	const { homebrewPrefix, miseBinDirs = [], miseDataDir, npmBinDir } = options;
+	const launcherExtension = path.extname(jeopiPath).toLowerCase();
+	const isWindowsScriptLauncher =
+		launcherExtension === ".cmd" || launcherExtension === ".ps1" || launcherExtension === ".bat";
 	if (homebrewPrefix && isPathInDirectory(jeopiPath, path.join(homebrewPrefix, "bin"))) return "brew";
 	if (miseBinDirs.some(dir => isPathInDirectory(jeopiPath, dir))) return "mise";
 	if (miseDataDir && isPathInDirectory(jeopiPath, path.join(miseDataDir, "shims"))) return "mise";
 	if (bunBinDir && isPathInDirectory(jeopiPath, bunBinDir)) return "bun";
+	if ((npmBinDir && isPathInDirectory(jeopiPath, npmBinDir)) || isWindowsScriptLauncher) return "npm";
 	return "binary";
 }
 
@@ -224,6 +247,7 @@ export function resolveUpdateMethodForTest(
 }
 async function resolveUpdateTarget(): Promise<UpdateTarget> {
 	const bunBinDir = await getBunGlobalBinDir();
+	const npmBinDir = await getNpmGlobalBinDir();
 	const homebrewPrefix = await getHomebrewFormulaPrefix();
 	const miseAvailable = $which("mise") !== undefined;
 	const miseBinDirs = miseAvailable ? await getMiseBinDirs() : [];
@@ -231,7 +255,7 @@ async function resolveUpdateTarget(): Promise<UpdateTarget> {
 	const jeopiPath = resolveJeopiPath();
 
 	if (jeopiPath) {
-		const method = resolveUpdateMethod(jeopiPath, bunBinDir, { homebrewPrefix, miseBinDirs, miseDataDir });
+		const method = resolveUpdateMethod(jeopiPath, bunBinDir, { homebrewPrefix, miseBinDirs, miseDataDir, npmBinDir });
 		if (method === "binary") return { method, path: jeopiPath };
 		return { method };
 	}
@@ -874,6 +898,15 @@ export async function replaceBinaryForUpdate(options: BinaryReplacementOptions):
 	}
 }
 
+function buildVersionedPackageInstallArgs(expectedVersion: string, nativeTag: string): string[] {
+	const args = [`${NPM_PACKAGE}@${expectedVersion}`, `${NATIVES_PACKAGE}@${expectedVersion}`];
+	const leafPackage = NATIVE_LEAF_PACKAGES.get(nativeTag);
+	if (leafPackage) {
+		args.push(`${leafPackage}@${expectedVersion}`);
+	}
+	return args;
+}
+
 /**
  * Build the bun argv used to globally install a specific jeopi version.
  *
@@ -905,19 +938,23 @@ export async function replaceBinaryForUpdate(options: BinaryReplacementOptions):
  * See #1824.
  */
 export function buildBunInstallArgs(expectedVersion: string, nativeTag: string = currentNativeTag()): string[] {
-	const args = [
+	return [
 		"install",
 		"-g",
 		"--no-cache",
 		`--registry=${NPM_REGISTRY}`,
-		`${NPM_PACKAGE}@${expectedVersion}`,
-		`${NATIVES_PACKAGE}@${expectedVersion}`,
+		...buildVersionedPackageInstallArgs(expectedVersion, nativeTag),
+	];
+}
+
+/** Build the npm argv used to update npm-managed global installs. */
+export function buildNpmInstallArgs(expectedVersion: string, nativeTag: string = currentNativeTag()): string[] {
+	return [
+		"install",
+		"-g",
+		`--registry=${NPM_REGISTRY}`,
+		...buildVersionedPackageInstallArgs(expectedVersion, nativeTag),
 	];
-	const leafPackage = NATIVE_LEAF_PACKAGES.get(nativeTag);
-	if (leafPackage) {
-		args.push(`${leafPackage}@${expectedVersion}`);
-	}
-	return args;
 }
 
 export function buildHomebrewUpdateArgs(force: boolean): string[] {
@@ -933,7 +970,7 @@ export function buildMiseForceInstallArgs(expectedVersion: string): string[] {
 }
 
 /**
- * Update via bun package manager.
+ * Update via package manager.
  */
 async function updateViaBun(expectedVersion: string): Promise<void> {
 	console.log(chalk.dim("Updating via bun..."));
@@ -954,6 +991,17 @@ async function updateViaBun(expectedVersion: string): Promise<void> {
 	}
 }
 
+async function updateViaNpm(expectedVersion: string): Promise<void> {
+	console.log(chalk.dim("Updating via npm..."));
+	const args = buildNpmInstallArgs(expectedVersion);
+	const result = await $`npm ${args}`.nothrow();
+	if (result.exitCode !== 0) {
+		throw new Error(`npm install failed with exit code ${result.exitCode}`);
+	}
+
+	await printVerification(expectedVersion);
+}
+
 async function updateViaHomebrew(expectedVersion: string, force: boolean): Promise<void> {
 	console.log(chalk.dim("Updating Homebrew formulae..."));
 	const update = await $`brew update`.nothrow();
@@ -1089,6 +1137,8 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 			await updateViaMise(release.version, opts.force);
 		} else if (target.method === "bun") {
 			await updateViaBun(release.version);
+		} else if (target.method === "npm") {
+			await updateViaNpm(release.version);
 		} else {
 			await updateViaBinaryAt(target.path, release.version);
 		}

package/src/cli/usage-error.ts

@@ -0,0 +1,7 @@
+/** Command-line input error that should be rendered without a stack trace. */
+export class CliUsageError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CliUsageError";
+	}
+}

package/src/commands/acp.ts

@@ -5,7 +5,7 @@
  * ACP terminal-auth flag asks the same command to open the interactive TUI.
  */
 import { Command } from "jeopi-utils/cli";
-import { parseArgs } from "../cli/args";
+import { type Args as ParsedArgs, parseArgs, reportCliUsageError } from "../cli/args";
 import { runRootCommand } from "../main";
 import { prepareAcpTerminalAuthArgs } from "../modes/acp/terminal-auth";
 
@@ -15,7 +15,16 @@ export default class Acp extends Command {
 
 	async run(): Promise<void> {
 		const { args, terminalAuth } = prepareAcpTerminalAuthArgs(this.argv);
-		const parsed = parseArgs(args);
+		let parsed: ParsedArgs;
+		try {
+			parsed = parseArgs(args);
+		} catch (error) {
+			if (reportCliUsageError(error)) {
+				process.exitCode = 2;
+				return;
+			}
+			throw error;
+		}
 		if (!terminalAuth) {
 			parsed.mode = "acp";
 		}

package/src/commands/launch.ts

@@ -4,7 +4,7 @@
 
 import { APP_NAME } from "jeopi-utils";
 import { Args, Command, Flags } from "jeopi-utils/cli";
-import { parseArgs } from "../cli/args";
+import { type Args as ParsedArgs, parseArgs, reportCliUsageError } from "../cli/args";
 import { runRootCommand } from "../main";
 import { prepareAcpTerminalAuthArgs } from "../modes/acp/terminal-auth";
 import { CLI_THINKING_LEVELS } from "../thinking";
@@ -140,7 +140,7 @@ export default class Index extends Command {
 			description: "Include thinking blocks in print mode text output",
 		}),
 		"max-time": Flags.string({
-			description: "Stop the session after this many seconds",
+			description: "Stop the session after this duration (e.g., 600, 10m, 1h)",
 		}),
 		// `--auto-approve` / `--yolo`: declared here so oclif's auto-generated `--help` lists it.
 		// Runtime parsing happens in `cli/args.ts parseArgs` (line 176 in that file) — `runRootCommand`
@@ -176,7 +176,16 @@ export default class Index extends Command {
 
 	async run(): Promise<void> {
 		const { args } = prepareAcpTerminalAuthArgs(this.argv);
-		const parsed = parseArgs(args);
+		let parsed: ParsedArgs;
+		try {
+			parsed = parseArgs(args);
+		} catch (error) {
+			if (reportCliUsageError(error)) {
+				process.exitCode = 2;
+				return;
+			}
+			throw error;
+		}
 		await runRootCommand(parsed, args);
 	}
 }

package/src/commit/agentic/agent.ts

@@ -29,6 +29,7 @@ export interface CommitAgentInput {
 	requireChangelog: boolean;
 	diffText?: string;
 	existingChangelogEntries?: ExistingChangelogEntries[];
+	onComplete?: (state: CommitAgentState) => Promise<void> | void;
 }
 
 export interface ExistingChangelogEntries {
@@ -175,6 +176,9 @@ export async function runCommitAgentSession(input: CommitAgentInput): Promise<Co
 			});
 		}
 
+		if (input.onComplete) {
+			await input.onComplete(state);
+		}
 		return state;
 	} finally {
 		unsubscribe();

package/src/commit/agentic/index.ts

@@ -6,7 +6,7 @@ import { detectChangelogBoundaries } from "../../commit/changelog/detect";
 import { parseUnreleasedSection } from "../../commit/changelog/parse";
 import { formatCommitMessage } from "../../commit/message";
 import { resolvePrimaryModel, resolveSmolModel } from "../../commit/model-selection";
-import type { CommitCommandArgs, ConventionalAnalysis } from "../../commit/types";
+import type { CommitCommandArgs, ConventionalAnalysis, NumstatEntry } from "../../commit/types";
 import { ModelRegistry } from "../../config/model-registry";
 import { Settings } from "../../config/settings";
 import { discoverAuthStorage, discoverContextFiles } from "../../sdk";
@@ -121,11 +121,10 @@ export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
 	}
 
 	process.stdout.write("● Starting commit agent...\n");
-	let commitState: CommitAgentState;
-	let usedFallback = false;
+	let agentSessionCompleted = false;
 
 	try {
-		commitState = await runCommitAgentSession({
+		await runCommitAgentSession({
 			cwd,
 			model: agentModel,
 			thinkingLevel: agentThinkingLevel,
@@ -138,42 +137,67 @@ export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
 			requireChangelog: !args.noChangelog && changelogTargets.length > 0,
 			diffText: diff,
 			existingChangelogEntries,
+			onComplete: async commitState => {
+				agentSessionCompleted = true;
+				await completeAgentCommitState(commitState, {
+					cwd,
+					dryRun: args.dryRun,
+					push: args.push,
+					noChangelog: args.noChangelog,
+					changelogTargets,
+					numstat,
+				});
+			},
 		});
+		return;
 	} catch (error) {
+		if (agentSessionCompleted) {
+			throw error;
+		}
 		const errorMessage = error instanceof Error ? error.message : String(error);
 		process.stderr.write(`Agent error: ${errorMessage}\n`);
 		if (error instanceof Error && error.stack && $env.DEBUG) {
 			process.stderr.write(`${error.stack}\n`);
 		}
 		process.stdout.write("● Using fallback commit generation...\n");
-		commitState = { proposal: generateFallbackProposal(numstat) };
-		usedFallback = true;
+		const fallbackProposal = generateFallbackProposal(numstat);
+		await runSingleCommit(fallbackProposal, { cwd, dryRun: args.dryRun, push: args.push });
+		return;
 	}
+}
 
-	if (!usedFallback && !commitState.proposal && !commitState.splitProposal) {
+async function completeAgentCommitState(
+	commitState: CommitAgentState,
+	ctx: CommitExecutionContext & {
+		noChangelog: boolean;
+		changelogTargets: string[];
+		numstat: NumstatEntry[];
+	},
+): Promise<void> {
+	let usedFallback = false;
+	if (!commitState.proposal && !commitState.splitProposal) {
 		if ($env.PI_COMMIT_NO_FALLBACK?.toLowerCase() !== "true") {
 			process.stdout.write("● Agent did not provide proposal, using fallback...\n");
-			commitState.proposal = generateFallbackProposal(numstat);
+			commitState.proposal = generateFallbackProposal(ctx.numstat);
 			usedFallback = true;
 		}
 	}
 
 	let updatedChangelogFiles: string[] = [];
-	if (!args.noChangelog && changelogTargets.length > 0 && !usedFallback) {
+	if (!ctx.noChangelog && ctx.changelogTargets.length > 0 && !usedFallback) {
 		if (!commitState.changelogProposal) {
-			process.stderr.write("Commit agent did not provide changelog entries.\n");
-			return;
+			throw new Error("Commit agent did not provide changelog entries.");
 		}
 		process.stdout.write("● Applying changelog entries...\n");
 		const updated = await applyChangelogProposals({
-			cwd,
+			cwd: ctx.cwd,
 			proposals: commitState.changelogProposal.entries,
-			dryRun: args.dryRun,
+			dryRun: ctx.dryRun,
 			onProgress: message => {
 				process.stdout.write(`  ├─ ${message}\n`);
 			},
 		});
-		updatedChangelogFiles = updated.map(filePath => path.relative(cwd, filePath));
+		updatedChangelogFiles = updated.map(filePath => path.relative(ctx.cwd, filePath));
 		if (updated.length > 0) {
 			for (const filePath of updated) {
 				process.stdout.write(`  └─ ${filePath}\n`);
@@ -184,21 +208,21 @@ export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
 	}
 
 	if (commitState.proposal) {
-		await runSingleCommit(commitState.proposal, { cwd, dryRun: args.dryRun, push: args.push });
+		await runSingleCommit(commitState.proposal, ctx);
 		return;
 	}
 
 	if (commitState.splitProposal) {
 		await runSplitCommit(commitState.splitProposal, {
-			cwd,
-			dryRun: args.dryRun,
-			push: args.push,
+			cwd: ctx.cwd,
+			dryRun: ctx.dryRun,
+			push: ctx.push,
 			additionalFiles: updatedChangelogFiles,
 		});
 		return;
 	}
 
-	process.stderr.write("Commit agent did not provide a proposal.\n");
+	throw new Error("Commit agent did not provide a proposal.");
 }
 
 async function runSingleCommit(proposal: CommitProposal, ctx: CommitExecutionContext): Promise<void> {
@@ -211,6 +235,7 @@ async function runSingleCommit(proposal: CommitProposal, ctx: CommitExecutionCon
 		process.stdout.write(`${commitMessage}\n`);
 		return;
 	}
+	process.stdout.write("● Creating commit...\n");
 	await git.commit(ctx.cwd, commitMessage);
 	process.stdout.write("Commit created.\n");
 	if (ctx.push) {
@@ -233,8 +258,7 @@ async function runSplitCommit(
 	const plannedFiles = new Set(plan.commits.flatMap(commit => commit.changes.map(change => change.path)));
 	const missingFiles = stagedFiles.filter(file => !plannedFiles.has(file));
 	if (missingFiles.length > 0) {
-		process.stderr.write(`Split commit plan missing staged files: ${missingFiles.join(", ")}\n`);
-		return;
+		throw new Error(`Split commit plan missing staged files: ${missingFiles.join(", ")}`);
 	}
 
 	if (ctx.dryRun) {
@@ -266,6 +290,7 @@ async function runSplitCommit(
 		throw new Error(order.error);
 	}
 
+	process.stdout.write("● Creating split commits...\n");
 	const stagedDiff = await git.diff(ctx.cwd, { cached: true });
 	await git.stage.reset(ctx.cwd);
 	for (const commitIndex of order) {

package/src/config/config-file.ts

@@ -11,9 +11,9 @@ interface ConfigSchemaError {
 }
 
 /**
- * Module-private cache of (jsonPath, ymlPath) pairs we already migrated this
- * process. Prevents `ConfigFile.relocate()` / repeated `tryLoad()` calls from
- * re-running the migration over and over on the boot path.
+ * Module-private cache of JSON → YAML migrations this process already ran.
+ * Prevents `ConfigFile.relocate()` / repeated `tryLoad()` calls from re-running
+ * the migration over and over on the boot path.
  */
 const migratedPaths = new Set<string>();
 
@@ -123,6 +123,7 @@ export type LoadResult<T> =
 
 export class ConfigFile<T> implements IConfigFile<T> {
 	readonly #basePath: string;
+	readonly #yamlFallbackPath: string | null;
 	readonly #jsonMigrationPath: string | null;
 	#cache?: LoadResult<T>;
 	#auxValidate?: (value: T) => void;
@@ -134,13 +135,17 @@ export class ConfigFile<T> implements IConfigFile<T> {
 	) {
 		this.#basePath = configPath;
 		if (configPath.endsWith(".yml")) {
+			this.#yamlFallbackPath = `${configPath.slice(0, -4)}.yaml`;
 			this.#jsonMigrationPath = `${configPath.slice(0, -4)}.json`;
 		} else if (configPath.endsWith(".yaml")) {
+			this.#yamlFallbackPath = null;
 			this.#jsonMigrationPath = `${configPath.slice(0, -5)}.json`;
 		} else if (configPath.endsWith(".json") || configPath.endsWith(".jsonc")) {
+			this.#yamlFallbackPath = null;
 			// JSON configs are still supported without migration.
 			this.#jsonMigrationPath = null;
 		} else {
+			this.#yamlFallbackPath = null;
 			throw new Error(`Invalid config file path: ${configPath}`);
 		}
 	}
@@ -150,9 +155,21 @@ export class ConfigFile<T> implements IConfigFile<T> {
 	 * Sync callers (tests, settings init) hit this implicitly via {@link tryLoad}.
 	 */
 	#ensureMigrated(): void {
-		if (this.#jsonMigrationPath) {
-			migrateJsonToYml(this.#jsonMigrationPath, this.#basePath);
+		if (!this.#jsonMigrationPath) return;
+		if (this.#yamlFallbackPath && !fs.existsSync(this.#basePath) && fs.existsSync(this.#yamlFallbackPath)) {
+			return;
 		}
+		migrateJsonToYml(this.#jsonMigrationPath, this.#basePath);
+	}
+
+	#resolveReadPath(): string {
+		if (fs.existsSync(this.#basePath)) {
+			return this.#basePath;
+		}
+		if (this.#yamlFallbackPath && fs.existsSync(this.#yamlFallbackPath)) {
+			return this.#yamlFallbackPath;
+		}
+		return this.#basePath;
 	}
 
 	relocate(configPath?: string): ConfigFile<T> {
@@ -165,7 +182,7 @@ export class ConfigFile<T> implements IConfigFile<T> {
 
 	getMtimeMs(): number | null {
 		try {
-			return fs.statSync(this.path()).mtimeMs;
+			return fs.statSync(this.#resolveReadPath()).mtimeMs;
 		} catch (err) {
 			if (isEnoent(err)) return null;
 			throw err;
@@ -211,12 +228,13 @@ export class ConfigFile<T> implements IConfigFile<T> {
 	#parseContent(content: string): LoadResult<T> {
 		try {
 			let parsed: unknown;
-			if (this.#basePath.endsWith(".json") || this.#basePath.endsWith(".jsonc")) {
+			const readPath = this.#resolveReadPath();
+			if (readPath.endsWith(".json") || readPath.endsWith(".jsonc")) {
 				parsed = JSONC.parse(content);
-			} else if (this.#basePath.endsWith(".yml") || this.#basePath.endsWith(".yaml")) {
+			} else if (readPath.endsWith(".yml") || readPath.endsWith(".yaml")) {
 				parsed = YAML.parse(content);
 			} else {
-				throw new Error(`Invalid config file path: ${this.#basePath}`);
+				throw new Error(`Invalid config file path: ${readPath}`);
 			}
 
 			const checked = this.schema(parsed);
@@ -255,7 +273,7 @@ export class ConfigFile<T> implements IConfigFile<T> {
 
 		let content: string;
 		try {
-			content = fs.readFileSync(this.path(), "utf-8").trim();
+			content = fs.readFileSync(this.#resolveReadPath(), "utf-8").trim();
 		} catch (error) {
 			if (isEnoent(error)) {
 				return this.#storeCache({ status: "not-found" });
@@ -275,7 +293,7 @@ export class ConfigFile<T> implements IConfigFile<T> {
 
 		let content: string;
 		try {
-			content = (await Bun.file(this.path()).text()).trim();
+			content = (await Bun.file(this.#resolveReadPath()).text()).trim();
 		} catch (error) {
 			if (isEnoent(error)) {
 				return this.#storeCache({ status: "not-found" });
@@ -306,7 +324,7 @@ export class ConfigFile<T> implements IConfigFile<T> {
 	}
 
 	path(): string {
-		return this.#basePath;
+		return this.#resolveReadPath();
 	}
 
 	invalidate() {

package/src/config/model-registry.ts

@@ -234,7 +234,7 @@ export interface ProviderDiscoveryState {
 	error?: string;
 }
 
-/** Result of loading custom models from models.json */
+/** Result of loading custom models config. */
 interface CustomModelsResult {
 	models?: CustomModelOverlay[];
 	overrides?: Map<string, ProviderOverride>;
@@ -271,7 +271,7 @@ interface CommandApiKeyResolution {
 	value?: string;
 }
 /**
- * Resolve a models.yml secret/config value to an actual value.
+ * Resolve a models.yml/models.yaml secret/config value to an actual value.
  * `!cmd` runs a shell command and returns trimmed stdout, otherwise env vars are
  * checked first and the input falls back to a literal value.
  */
@@ -784,7 +784,7 @@ export class ModelRegistry {
 	}
 
 	/**
-	 * Reload models from disk (built-in + custom from models.json).
+	 * Reload models from disk (built-in + custom config).
 	 */
 	async refresh(strategy: ModelRefreshStrategy = "online-if-uncached"): Promise<void> {
 		this.#reloadStaticModels();
@@ -889,7 +889,7 @@ export class ModelRegistry {
 	#reloadStaticModels(): void {
 		const currentMtime = this.#modelsConfigFile.getMtimeMs();
 		if (currentMtime !== null && currentMtime === this.#lastStaticLoadMtime) {
-			// models.json unchanged since last load; reloading would be redundant.
+			// Models config unchanged since last load; reloading would be redundant.
 			return;
 		}
 		this.#modelsConfigFile.invalidate();
@@ -913,14 +913,14 @@ export class ModelRegistry {
 	}
 
 	/**
-	 * Get any error from loading models.json (undefined if no error).
+	 * Get any error from loading custom models config (undefined if no error).
 	 */
 	getError(): ConfigError | undefined {
 		return this.#configError;
 	}
 
 	#loadModels() {
-		// Load custom models from models.json first (to know which providers to override)
+		// Load custom config first (to know which providers to override).
 		const {
 			models: customModels = [],
 			overrides = new Map(),
@@ -1823,7 +1823,7 @@ export class ModelRegistry {
 
 	/**
 	 * Get all models (built-in + custom).
-	 * If models.json had errors, returns only built-in models.
+	 * If custom config had errors, returns only built-in models.
 	 */
 	getAll(): Model<Api>[] {
 		return this.#models;

package/src/config/model-resolver.ts

@@ -1149,20 +1149,32 @@ export function resolveModelOverride(
 	modelPatterns: string[],
 	modelRegistry: ModelLookupRegistry,
 	settings?: Settings,
-): { model?: Model<Api>; thinkingLevel?: ConfiguredThinkingLevel; explicitThinkingLevel: boolean } {
+): {
+	model?: Model<Api>;
+	thinkingLevel?: ConfiguredThinkingLevel;
+	explicitThinkingLevel: boolean;
+	warning?: string;
+} {
 	if (modelPatterns.length === 0) return { explicitThinkingLevel: false };
 	const availableModels = modelRegistry.getAvailable();
 	const matchPreferences = getModelMatchPreferences(settings);
+	let warning: string | undefined;
 	for (const pattern of modelPatterns) {
-		const { model, thinkingLevel, explicitThinkingLevel } = resolveModelRoleValue(pattern, availableModels, {
+		const {
+			model,
+			thinkingLevel,
+			explicitThinkingLevel,
+			warning: patternWarning,
+		} = resolveModelRoleValue(pattern, availableModels, {
 			settings,
 			matchPreferences,
 		});
 		if (model) {
-			return { model, thinkingLevel, explicitThinkingLevel };
+			return { model, thinkingLevel, explicitThinkingLevel, warning: patternWarning };
 		}
+		if (!warning && patternWarning) warning = patternWarning;
 	}
-	return { explicitThinkingLevel: false };
+	return { explicitThinkingLevel: false, warning };
 }
 
 /**
@@ -1176,6 +1188,10 @@ export function resolveModelOverride(
  * `modelRoles.task` pointing at an unqualified id whose only available
  * provider variant has no configured credentials — see #985).
  *
+ * `sessionId` is forwarded to `getApiKey` so that session-sticky OAuth
+ * credentials resolve correctly during the pre-flight auth check. Without it,
+ * providers with multiple OAuth accounts may return `undefined` even though
+ * the credential is usable once the subagent session starts — see #5325.
  * Keyless-by-design providers (llama.cpp, ollama, lm-studio) advertise the
  * `kNoAuth` sentinel from `getApiKey` to signal that they do not require
  * credentials. Those are treated as authenticated here so an explicitly
@@ -1191,18 +1207,20 @@ export async function resolveModelOverrideWithAuthFallback(
 	parentActiveModelPattern: string | undefined,
 	modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">,
 	settings?: Settings,
+	sessionId?: string,
 ): Promise<{
 	model?: Model<Api>;
 	thinkingLevel?: ConfiguredThinkingLevel;
 	explicitThinkingLevel: boolean;
 	authFallbackUsed: boolean;
+	warning?: string;
 }> {
 	const primary = resolveModelOverride(modelPatterns, modelRegistry, settings);
 	if (!primary.model || !parentActiveModelPattern) {
 		return { ...primary, authFallbackUsed: false };
 	}
 
-	const primaryKey = await modelRegistry.getApiKey(primary.model);
+	const primaryKey = await modelRegistry.getApiKey(primary.model, sessionId);
 	if (primaryKey === kNoAuth || isAuthenticated(primaryKey)) {
 		return { ...primary, authFallbackUsed: false };
 	}
@@ -1214,7 +1232,7 @@ export async function resolveModelOverrideWithAuthFallback(
 	if (modelsAreEqual(fallback.model, primary.model)) {
 		return { ...primary, authFallbackUsed: false };
 	}
-	const fallbackKey = await modelRegistry.getApiKey(fallback.model);
+	const fallbackKey = await modelRegistry.getApiKey(fallback.model, sessionId);
 	if (!isAuthenticated(fallbackKey)) {
 		return { ...primary, authFallbackUsed: false };
 	}

package/src/config/models-config.ts

@@ -1,5 +1,5 @@
 /**
- * models.json config file handle and provider configuration validation.
+ * Custom model/provider config file handle and validation.
  */
 
 import type { Api, ModelSpec } from "jeopi-ai/types";