@gajae-code/coding-agent 0.5.2 → 0.5.4

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.5.2",
+	"version": "0.5.4",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -51,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.5.2",
-		"@gajae-code/agent-core": "0.5.2",
-		"@gajae-code/ai": "0.5.2",
-		"@gajae-code/natives": "0.5.2",
-		"@gajae-code/tui": "0.5.2",
-		"@gajae-code/utils": "0.5.2",
+		"@gajae-code/stats": "0.5.4",
+		"@gajae-code/agent-core": "0.5.4",
+		"@gajae-code/ai": "0.5.4",
+		"@gajae-code/natives": "0.5.4",
+		"@gajae-code/tui": "0.5.4",
+		"@gajae-code/utils": "0.5.4",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/async/job-manager.ts

@@ -7,6 +7,11 @@ const DELIVERY_RETRY_JITTER_MS = 200;
 const DEFAULT_RETENTION_MS = 5 * 60 * 1000;
 const DEFAULT_MAX_RUNNING_JOBS = 15;
 const MONITOR_TOMBSTONE_TTL_MS = 5 * 60_000;
+const DEFAULT_MAX_DELIVERY_QUEUE = 100;
+const DELIVERY_MAX_TEXT_BYTES = 64 * 1024;
+const DELIVERY_PREVIEW_HEAD_BYTES = 32 * 1024;
+const DELIVERY_PREVIEW_TAIL_BYTES = 32 * 1024;
+const DELIVERY_MAX_ATTEMPTS = 3;
 
 export interface AsyncJob {
 	id: string;
@@ -113,6 +118,12 @@ export interface ResumeDescriptor {
 	data: unknown;
 }
 
+function sessionFileFromResumeDescriptorData(data: unknown): string | null {
+	if (typeof data !== "object" || data === null) return null;
+	const sessionFile = (data as { sessionFile?: unknown }).sessionFile;
+	return typeof sessionFile === "string" && sessionFile.trim().length > 0 ? sessionFile : null;
+}
+
 /** A pending resume awaiting a free concurrency slot. */
 interface ResumeQueueEntry {
 	subagentId: string;
@@ -128,9 +139,16 @@ export interface AsyncJobManagerOptions {
 	retentionMs?: number;
 }
 
+export interface AsyncJobDisposeDiagnostics {
+	stuckJobIds: string[];
+	deliveriesDrained: boolean;
+}
+
 interface AsyncJobDelivery {
 	jobId: string;
 	text: string;
+	originalBytes?: number;
+	truncated?: boolean;
 	attempt: number;
 	nextAttemptAt: number;
 	lastError?: string;
@@ -143,6 +161,7 @@ export interface AsyncJobDeliveryState {
 	delivering: boolean;
 	nextRetryAt?: number;
 	pendingJobIds: string[];
+	deadLettered: number;
 }
 
 export interface AsyncJobLifecycleCleanup {
@@ -198,6 +217,32 @@ function sliceTextFromUtf8ByteOffset(text: string, offsetBytes: number): string
 	return text.slice(codeUnitIndex);
 }
 
+function sliceTextAfterUtf8ByteOffset(text: string, offsetBytes: number): string {
+	if (offsetBytes <= 0) return text;
+	let consumedBytes = 0;
+	let codeUnitIndex = 0;
+	for (const char of text) {
+		const charBytes = Buffer.byteLength(char, "utf8");
+		consumedBytes += charBytes;
+		codeUnitIndex += char.length;
+		if (consumedBytes >= offsetBytes) break;
+	}
+	return text.slice(codeUnitIndex);
+}
+
+function sliceTextToUtf8ByteLength(text: string, maxBytes: number): string {
+	if (maxBytes <= 0) return "";
+	let consumedBytes = 0;
+	let codeUnitIndex = 0;
+	for (const char of text) {
+		const charBytes = Buffer.byteLength(char, "utf8");
+		if (consumedBytes + charBytes > maxBytes) break;
+		consumedBytes += charBytes;
+		codeUnitIndex += char.length;
+	}
+	return text.slice(0, codeUnitIndex);
+}
+
 /**
  * A slice of process-stream output for a background job, as recorded by
  * `appendOutput` / read by `readOutputSince`.
@@ -277,6 +322,8 @@ export class AsyncJobManager {
 	#resumeSeq = 0;
 	#resumeRunner?: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined;
 	readonly #resumeDescriptors = new Map<string, ResumeDescriptor>();
+	readonly #deadLetteredDeliveries = new Map<string, AsyncJobDelivery>();
+	#lastDisposeDiagnostics: AsyncJobDisposeDiagnostics = { stuckJobIds: [], deliveriesDrained: true };
 	/**
 	 * Change listeners notified on any mutation that can alter the live job set
 	 * (register, terminal/eviction transitions, dispose). Used by the status-line
@@ -381,7 +428,7 @@ export class AsyncJobManager {
 
 				if (job.status === "cancelled") {
 					job.resultText = outcome.kind === "completed" ? outcome.text : outcome.note;
-					this.#runLifecycle(id, "terminal");
+					this.#runLifecycle(id, "terminal", job);
 					this.#scheduleEviction(id);
 					this.#markRecordTerminal(id, "cancelled");
 					this.#drainResumeQueue();
@@ -403,20 +450,20 @@ export class AsyncJobManager {
 				this.#freezeEndTime(job);
 				job.resultText = outcome.text;
 				this.#enqueueDelivery(id, outcome.text);
-				this.#runLifecycle(id, "terminal");
+				this.#runLifecycle(id, "terminal", job);
 				this.#scheduleEviction(id);
 				this.#markRecordTerminal(id, "completed");
 				this.#drainResumeQueue();
 			} catch (error) {
 				if (job.status === "cancelled") {
 					job.errorText = error instanceof Error ? error.message : String(error);
-					this.#runLifecycle(id, "terminal");
+					this.#runLifecycle(id, "terminal", job);
 					this.#scheduleEviction(id);
 					this.#markRecordTerminal(id, "cancelled");
 					this.#drainResumeQueue();
 					return;
 				}
-				this.#runLifecycle(id, "terminal");
+				this.#runLifecycle(id, "terminal", job);
 				const errorText = error instanceof Error ? error.message : String(error);
 				job.status = "failed";
 				this.#freezeEndTime(job);
@@ -471,14 +518,14 @@ export class AsyncJobManager {
 		job.endTime ??= Date.now();
 	}
 
-	#runLifecycle(jobId: string, phase: "cancel" | "terminal" | "evict"): void {
+	#runLifecycle(jobId: string, phase: "cancel" | "terminal" | "evict", jobOverride?: AsyncJob): void {
+		const lifecycle = this.#lifecycles.get(jobId);
+		const job = jobOverride ?? this.#jobs.get(jobId);
+		if (!lifecycle || !job) return;
 		const fired = this.#lifecyclePhases.get(jobId) ?? new Set<"cancel" | "terminal" | "evict">();
 		if (fired.has(phase)) return;
 		fired.add(phase);
 		this.#lifecyclePhases.set(jobId, fired);
-		const lifecycle = this.#lifecycles.get(jobId);
-		const job = this.#jobs.get(jobId);
-		if (!lifecycle || !job) return;
 		try {
 			if (phase === "cancel") lifecycle.onCancel?.(job);
 			else if (phase === "terminal") lifecycle.onTerminal?.(job);
@@ -554,11 +601,31 @@ export class AsyncJobManager {
 		record.modelFellBack = model.modelFellBack;
 	}
 
+	#recordFromResumeDescriptor(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined {
+		const descriptor = this.getResumeDescriptor(subagentId, filter);
+		if (!descriptor) return undefined;
+		const sessionFile = sessionFileFromResumeDescriptorData(descriptor.data);
+		const record: SubagentRecord = {
+			subagentId: descriptor.subagentId,
+			ownerId: descriptor.ownerId,
+			currentJobId: null,
+			historicalJobIds: [],
+			status: "completed",
+			sessionFile,
+			resumable: sessionFile !== null,
+		};
+		this.#subagentRecords.set(record.subagentId, record);
+		return record;
+	}
+
 	getSubagentRecord(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined {
-		const rec = this.#subagentRecords.get(subagentId.trim());
-		if (!rec) return undefined;
-		if (filter?.ownerId && rec.ownerId !== filter.ownerId) return undefined;
-		return rec;
+		const trimmed = subagentId.trim();
+		const rec = this.#subagentRecords.get(trimmed);
+		if (rec) {
+			if (filter?.ownerId && rec.ownerId !== filter.ownerId) return undefined;
+			return rec;
+		}
+		return this.#recordFromResumeDescriptor(trimmed, filter);
 	}
 
 	getSubagentRecords(filter?: AsyncJobFilter): SubagentRecord[] {
@@ -649,6 +716,14 @@ export class AsyncJobManager {
 		}
 	}
 
+	#purgeTerminalSubagentStateForJob(jobId: string): void {
+		const rec = this.#recordByJobId(jobId);
+		if (!rec) return;
+		if (rec.status === "paused" || rec.status === "queued") return;
+		this.#liveHandles.delete(rec.subagentId);
+		this.#subagentProgress.delete(rec.subagentId);
+	}
+
 	#markRecordTerminal(jobId: string, status: "completed" | "failed" | "cancelled"): void {
 		const rec = this.#recordByJobId(jobId);
 		if (!rec) return;
@@ -967,6 +1042,10 @@ export class AsyncJobManager {
 	getDeliveryState(filter?: AsyncJobFilter): AsyncJobDeliveryState {
 		const deliveries = this.#filterDeliveries(filter);
 		const inFlightDeliveries = this.#filterInFlightDeliveries(filter);
+		const ownerId = filter?.ownerId;
+		const deadLettered = Array.from(this.#deadLetteredDeliveries.values()).filter(
+			delivery => !ownerId || delivery.ownerId === ownerId,
+		).length;
 		const nextRetryAt = deliveries.reduce<number | undefined>((next, delivery) => {
 			if (next === undefined) return delivery.nextAttemptAt;
 			return Math.min(next, delivery.nextAttemptAt);
@@ -977,6 +1056,7 @@ export class AsyncJobManager {
 			delivering: inFlightDeliveries.length > 0 || (this.#deliveryLoop !== undefined && deliveries.length > 0),
 			nextRetryAt,
 			pendingJobIds: deliveries.concat(inFlightDeliveries).map(delivery => delivery.jobId),
+			deadLettered,
 		};
 	}
 
@@ -1035,6 +1115,29 @@ export class AsyncJobManager {
 		}
 	}
 
+	getLastDisposeDiagnostics(): AsyncJobDisposeDiagnostics {
+		return { ...this.#lastDisposeDiagnostics, stuckJobIds: [...this.#lastDisposeDiagnostics.stuckJobIds] };
+	}
+
+	async #waitForAllWithDeadline(timeoutMs: number): Promise<{ completed: boolean; stuckJobIds: string[] }> {
+		const jobs = Array.from(this.#jobs.values());
+		if (jobs.length === 0) return { completed: true, stuckJobIds: [] };
+		let timedOut = false;
+		await Promise.race([
+			Promise.allSettled(jobs.map(job => job.promise)),
+			Bun.sleep(Math.max(0, timeoutMs)).then(() => {
+				timedOut = true;
+			}),
+		]);
+		if (!timedOut) return { completed: true, stuckJobIds: [] };
+		return {
+			completed: false,
+			stuckJobIds: Array.from(this.#jobs.values())
+				.filter(job => job.status === "running" || job.status === "cancelled")
+				.map(job => job.id),
+		};
+	}
+
 	async waitForAll(): Promise<void> {
 		await Promise.all(Array.from(this.#jobs.values()).map(job => job.promise));
 	}
@@ -1102,12 +1205,18 @@ export class AsyncJobManager {
 			}
 		}
 		this.#monitorTombstones.clear();
-		await this.waitForAll();
-		const drained = await this.drainDeliveries({ timeoutMs: options?.timeoutMs ?? 3_000 });
+		const timeoutMs = options?.timeoutMs ?? 3_000;
+		const waitResult = await this.#waitForAllWithDeadline(timeoutMs);
+		const drained = waitResult.completed ? await this.drainDeliveries({ timeoutMs }) : false;
+		this.#lastDisposeDiagnostics = { stuckJobIds: waitResult.stuckJobIds, deliveriesDrained: drained };
+		if (waitResult.stuckJobIds.length > 0) {
+			logger.warn("Async job manager dispose timed out waiting for jobs", { stuckJobIds: waitResult.stuckJobIds });
+		}
 		this.#clearEvictionTimers();
 		this.#jobs.clear();
 		this.#deliveries.length = 0;
 		this.#inFlightDeliveries.length = 0;
+		this.#deadLetteredDeliveries.clear();
 		this.#suppressedDeliveries.clear();
 		this.#watchedJobs.clear();
 		this.#outputState.clear();
@@ -1119,7 +1228,7 @@ export class AsyncJobManager {
 		this.#resumeQueue.length = 0;
 		this.#notifyChange();
 		this.#changeListeners.clear();
-		return drained;
+		return drained && waitResult.completed;
 	}
 
 	#resolveJobId(preferredId?: string): string {
@@ -1148,16 +1257,10 @@ export class AsyncJobManager {
 	}
 
 	#scheduleEviction(jobId: string): void {
+		if (this.#disposed) return;
 		this.#notifyChange();
 		if (this.#retentionMs <= 0) {
-			this.#recordMonitorTombstone(jobId);
-			this.#runLifecycle(jobId, "evict");
-			this.#jobs.delete(jobId);
-			this.#lifecycles.delete(jobId);
-			this.#lifecyclePhases.delete(jobId);
-			this.#suppressedDeliveries.delete(jobId);
-			this.#watchedJobs.delete(jobId);
-			this.#outputState.delete(jobId);
+			this.#evictJob(jobId);
 			return;
 		}
 		const existing = this.#evictionTimers.get(jobId);
@@ -1166,20 +1269,25 @@ export class AsyncJobManager {
 		}
 		const timer = setTimeout(() => {
 			this.#evictionTimers.delete(jobId);
-			this.#recordMonitorTombstone(jobId);
-			this.#runLifecycle(jobId, "evict");
-			this.#jobs.delete(jobId);
-			this.#lifecycles.delete(jobId);
-			this.#lifecyclePhases.delete(jobId);
-			this.#suppressedDeliveries.delete(jobId);
-			this.#watchedJobs.delete(jobId);
-			this.#outputState.delete(jobId);
+			this.#evictJob(jobId);
 			this.#notifyChange();
 		}, this.#retentionMs);
 		timer.unref();
 		this.#evictionTimers.set(jobId, timer);
 	}
 
+	#evictJob(jobId: string): void {
+		this.#recordMonitorTombstone(jobId);
+		this.#runLifecycle(jobId, "evict");
+		this.#purgeTerminalSubagentStateForJob(jobId);
+		this.#jobs.delete(jobId);
+		this.#lifecycles.delete(jobId);
+		this.#lifecyclePhases.delete(jobId);
+		this.#suppressedDeliveries.delete(jobId);
+		this.#watchedJobs.delete(jobId);
+		this.#outputState.delete(jobId);
+	}
+
 	#clearEvictionTimers(): void {
 		for (const timer of this.#evictionTimers.values()) {
 			clearTimeout(timer);
@@ -1245,17 +1353,38 @@ export class AsyncJobManager {
 		if (this.isDeliverySuppressed(jobId)) {
 			return;
 		}
+		const deliveryText = this.#boundedDeliveryText(text);
 		this.#deliveries.push({
 			jobId,
-			text,
+			text: deliveryText.text,
+			originalBytes: deliveryText.originalBytes,
+			truncated: deliveryText.truncated,
 			attempt: 0,
 			nextAttemptAt: Date.now(),
 			ownerId: this.#jobs.get(jobId)?.ownerId,
 		});
+		while (this.#deliveries.length > DEFAULT_MAX_DELIVERY_QUEUE) {
+			const dropped = this.#deliveries.shift();
+			if (dropped) this.#deadLetteredDeliveries.set(dropped.jobId, dropped);
+		}
 		this.#ensureDeliveryLoop();
 	}
 
+	#boundedDeliveryText(text: string): { text: string; originalBytes?: number; truncated?: boolean } {
+		const bytes = Buffer.byteLength(text, "utf8");
+		if (bytes <= DELIVERY_MAX_TEXT_BYTES) return { text };
+		const head = sliceTextToUtf8ByteLength(text, DELIVERY_PREVIEW_HEAD_BYTES);
+		const tailStart = Math.max(0, bytes - DELIVERY_PREVIEW_TAIL_BYTES);
+		const tail = sliceTextAfterUtf8ByteOffset(text, tailStart);
+		return {
+			text: `${head}\n\n[async delivery output truncated from ${bytes} bytes]\n\n${tail}`,
+			originalBytes: bytes,
+			truncated: true,
+		};
+	}
+
 	#ensureDeliveryLoop(): void {
+		if (this.#disposed) return;
 		if (this.#deliveryLoop) {
 			return;
 		}
@@ -1266,7 +1395,7 @@ export class AsyncJobManager {
 			})
 			.finally(() => {
 				this.#deliveryLoop = undefined;
-				if (this.#deliveries.length > 0) {
+				if (!this.#disposed && this.#deliveries.length > 0) {
 					this.#ensureDeliveryLoop();
 				}
 			});
@@ -1304,20 +1433,29 @@ export class AsyncJobManager {
 			} catch (error) {
 				delivery.attempt += 1;
 				delivery.lastError = error instanceof Error ? error.message : String(error);
-				delivery.nextAttemptAt = Date.now() + this.#getRetryDelay(delivery.attempt);
-				if (!this.isDeliverySuppressed(delivery.jobId)) {
-					this.#deliveries.push(delivery);
+				if (delivery.attempt >= DELIVERY_MAX_ATTEMPTS) {
+					this.#deadLetteredDeliveries.set(delivery.jobId, delivery);
+					logger.warn("Async job completion delivery reached retry cap", {
+						jobId: delivery.jobId,
+						attempt: delivery.attempt,
+						error: delivery.lastError,
+					});
+				} else {
+					delivery.nextAttemptAt = Date.now() + this.#getRetryDelay(delivery.attempt);
+					if (!this.isDeliverySuppressed(delivery.jobId)) {
+						this.#deliveries.push(delivery);
+					}
+					logger.warn("Async job completion delivery failed", {
+						jobId: delivery.jobId,
+						attempt: delivery.attempt,
+						nextRetryAt: delivery.nextAttemptAt,
+						error: delivery.lastError,
+					});
 				}
-				logger.warn("Async job completion delivery failed", {
-					jobId: delivery.jobId,
-					attempt: delivery.attempt,
-					nextRetryAt: delivery.nextAttemptAt,
-					error: delivery.lastError,
-				});
 			} finally {
 				const index = this.#inFlightDeliveries.indexOf(delivery);
 				if (index !== -1) this.#inFlightDeliveries.splice(index, 1);
-				if (this.#deliveries.length > 0) this.#ensureDeliveryLoop();
+				if (!this.#disposed && this.#deliveries.length > 0) this.#ensureDeliveryLoop();
 			}
 		})();
 		delivery.promise = promise;

package/src/config/file-lock.ts

@@ -101,7 +101,15 @@ function ownerLiveness(pid: number): OwnerLiveness {
 
 async function isLockStale(lockPath: string, staleMs: number): Promise<boolean> {
 	const info = await readLockInfo(lockPath);
-	if (!info) return true;
+	if (!info) {
+		try {
+			const stats = await fs.stat(lockPath);
+			return Date.now() - stats.mtimeMs > staleMs;
+		} catch (err) {
+			if (isEnoent(err)) return false;
+			throw err;
+		}
+	}
 
 	// Never reap a live owner by elapsed time: a long legitimate critical section must
 	// not have its lock stolen (#652). Reclaim a dead owner immediately. Only when owner

package/src/config/model-profile-activation.ts

@@ -61,6 +61,49 @@ function resolveModelProfileName(profileName: string, profiles: ReadonlyMap<stri
 	return replacement && profiles.has(replacement) ? replacement : profileName;
 }
 
+/**
+ * Rewrite a selector only within the selector provider's own alternative group.
+ * Strict providers are never rewritten, and authenticated alternative providers
+ * keep their original selectors.
+ */
+function rewriteSelectorProvider(
+	selector: string,
+	authenticatedProviders: ReadonlySet<string>,
+	alternativeGroups: readonly (readonly string[])[],
+): string {
+	const slash = selector.indexOf("/");
+	if (slash < 0) return selector;
+
+	const provider = selector.substring(0, slash);
+	if (authenticatedProviders.has(provider)) return selector;
+
+	const group = alternativeGroups.find(candidates => candidates.includes(provider));
+	if (!group) return selector;
+
+	const replacement = group.find(candidate => authenticatedProviders.has(candidate));
+	if (!replacement) return selector;
+
+	return replacement + selector.substring(slash);
+}
+
+function rewriteBindingsProviders(
+	bindings: { defaultSelector?: string; agentModelOverrides: Record<string, string> },
+	authenticatedProviders: ReadonlySet<string>,
+	alternativeGroups: readonly (readonly string[])[],
+): { defaultSelector?: string; agentModelOverrides: Record<string, string> } {
+	return {
+		defaultSelector: bindings.defaultSelector
+			? rewriteSelectorProvider(bindings.defaultSelector, authenticatedProviders, alternativeGroups)
+			: undefined,
+		agentModelOverrides: Object.fromEntries(
+			Object.entries(bindings.agentModelOverrides).map(([role, sel]) => [
+				role,
+				rewriteSelectorProvider(sel, authenticatedProviders, alternativeGroups),
+			]),
+		),
+	};
+}
+
 export async function prepareModelProfileActivation(
 	options: PrepareModelProfileActivationOptions,
 ): Promise<PreparedModelProfileActivation> {
@@ -72,19 +115,44 @@ export async function prepareModelProfileActivation(
 		throw new Error(`Unknown model profile "${options.profileName}". Available profiles: ${available}`);
 	}
 
+	const allProviders = aggregateModelProfileRequiredProviders(profile.requiredProviders, profile);
+	const alternativeGroups = profile.alternativeProviderGroups ?? [];
+	const alternativeSet = new Set(alternativeGroups.flat());
+
 	const missingProviders: string[] = [];
-	for (const provider of aggregateModelProfileRequiredProviders(profile.requiredProviders, profile)) {
+	const authenticatedProviders: string[] = [];
+	for (const provider of allProviders) {
 		const apiKey = await options.modelRegistry.getApiKeyForProvider(provider, options.session.sessionId);
 		if (!isAuthenticated(apiKey)) {
 			missingProviders.push(provider);
+		} else {
+			authenticatedProviders.push(provider);
 		}
 	}
-	if (missingProviders.length > 0) {
+
+	// Check strict (non-alternative) providers — all must be authenticated.
+	const strictMissing = missingProviders.filter(p => !alternativeSet.has(p));
+	if (strictMissing.length > 0) {
+		throw new Error(formatModelProfileCredentialError(options.profileName, strictMissing));
+	}
+
+	// Check alternative groups — at least one provider per group must be authenticated.
+	for (const group of alternativeGroups) {
+		const groupAuthenticated = group.some(p => authenticatedProviders.includes(p));
+		if (!groupAuthenticated) {
+			throw new Error(formatModelProfileCredentialError(options.profileName, [...group]));
+		}
+	}
+
+	if (authenticatedProviders.length === 0) {
 		throw new Error(formatModelProfileCredentialError(options.profileName, missingProviders));
 	}
 
 	const availableModels = options.modelRegistry.getAll();
-	const bindings = resolveProfileBindings(profile);
+	let bindings = resolveProfileBindings(profile);
+	if (missingProviders.length > 0 && alternativeGroups.length > 0) {
+		bindings = rewriteBindingsProviders(bindings, new Set(authenticatedProviders), alternativeGroups);
+	}
 	const resolvedDefault = bindings.defaultSelector
 		? resolveModelRoleValue(bindings.defaultSelector, availableModels, {
 				settings: options.settings as Settings,

package/src/config/model-profiles.ts

@@ -6,6 +6,16 @@ export type ModelProfileRole = GjcModelAssignmentTargetId;
 export interface ModelProfileDefinition {
 	name: string;
 	requiredProviders: string[];
+	/**
+	 * Optional groups of providers that are interchangeable fallbacks.
+	 * Each group is an array of provider ids where at least one must be
+	 * authenticated. Providers NOT in any group are treated as strict
+	 * requirements (all must be authenticated).
+	 *
+	 * Example: `[["xiaomi", "xiaomi-token-plan-sgp", "xiaomi-token-plan-ams", "xiaomi-token-plan-cn"]]`
+	 * means any single xiaomi credential satisfies the group.
+	 */
+	alternativeProviderGroups?: readonly (readonly string[])[];
 	modelMapping: Partial<Record<ModelProfileRole, string>>;
 	source: "builtin" | "user";
 }
@@ -46,9 +56,11 @@ const profile = (
 	name: string,
 	requiredProviders: string[],
 	modelMapping: Record<ModelProfileRole, string>,
+	alternativeProviderGroups?: readonly (readonly string[])[],
 ): ModelProfileDefinition => ({
 	name,
 	requiredProviders: aggregateModelProfileRequiredProviders(requiredProviders, { modelMapping }),
+	alternativeProviderGroups,
 	modelMapping,
 	source: "builtin",
 });
@@ -138,20 +150,30 @@ export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 		critic: "xiaomi/mimo-v2.5-pro:medium",
 		architect: "xiaomi/mimo-v2.5-pro:high",
 	}),
-	profile("mimo-medium", ["xiaomi"], {
-		default: "xiaomi/mimo-v2.5-pro:medium",
-		executor: "xiaomi/mimo-v2.5-pro:low",
-		planner: "xiaomi/mimo-v2.5-pro:medium",
-		critic: "xiaomi/mimo-v2.5-pro:high",
-		architect: "xiaomi/mimo-v2.5-pro:xhigh",
-	}),
-	profile("mimo-pro", ["xiaomi"], {
-		default: "xiaomi/mimo-v2.5-pro:xhigh",
-		executor: "xiaomi/mimo-v2.5-pro:medium",
-		planner: "xiaomi/mimo-v2.5-pro:high",
-		critic: "xiaomi/mimo-v2.5-pro:xhigh",
-		architect: "xiaomi/mimo-v2.5-pro:xhigh",
-	}),
+	profile(
+		"mimo-medium",
+		["xiaomi", "xiaomi-token-plan-sgp", "xiaomi-token-plan-ams", "xiaomi-token-plan-cn"],
+		{
+			default: "xiaomi/mimo-v2.5-pro:medium",
+			executor: "xiaomi/mimo-v2.5-pro:low",
+			planner: "xiaomi/mimo-v2.5-pro:medium",
+			critic: "xiaomi/mimo-v2.5-pro:high",
+			architect: "xiaomi/mimo-v2.5-pro:xhigh",
+		},
+		[["xiaomi", "xiaomi-token-plan-sgp", "xiaomi-token-plan-ams", "xiaomi-token-plan-cn"]],
+	),
+	profile(
+		"mimo-pro",
+		["xiaomi", "xiaomi-token-plan-sgp", "xiaomi-token-plan-ams", "xiaomi-token-plan-cn"],
+		{
+			default: "xiaomi/mimo-v2.5-pro:xhigh",
+			executor: "xiaomi/mimo-v2.5-pro:medium",
+			planner: "xiaomi/mimo-v2.5-pro:high",
+			critic: "xiaomi/mimo-v2.5-pro:xhigh",
+			architect: "xiaomi/mimo-v2.5-pro:xhigh",
+		},
+		[["xiaomi", "xiaomi-token-plan-sgp", "xiaomi-token-plan-ams", "xiaomi-token-plan-cn"]],
+	),
 	profile("grok-eco", ["xai"], {
 		default: "xai/grok-4.3:low",
 		executor: "xai/grok-4.3:minimal",
@@ -292,6 +314,9 @@ const PROFILE_RECOMMENDATIONS: Record<string, string> = {
 	zai: "glm-medium",
 	"kimi-code": "kimi-coding-plan-medium",
 	xiaomi: "mimo-medium",
+	"xiaomi-token-plan-sgp": "mimo-medium",
+	"xiaomi-token-plan-ams": "mimo-medium",
+	"xiaomi-token-plan-cn": "mimo-medium",
 	xai: "grok-medium",
 	"grok-build": "grok-build-pro",
 	cursor: "cursor-medium",