@gajae-code/coding-agent 0.4.1 → 0.4.3

package/src/async/job-manager.ts

@@ -6,6 +6,7 @@ const DELIVERY_RETRY_MAX_MS = 30_000;
 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;
 
 export interface AsyncJob {
 	id: string;
@@ -120,6 +121,27 @@ export interface AsyncJobDeliveryState {
 	pendingJobIds: string[];
 }
 
+export interface AsyncJobLifecycleCleanup {
+	onCancel?: (job: AsyncJob) => void;
+	onTerminal?: (job: AsyncJob) => void;
+	onEvict?: (job: AsyncJob) => void;
+	/**
+	 * Idempotent residual cleanup invoked by a post-eviction tombstone purge
+	 * (e.g. a late `job cancel` after the job left the registry). Kept distinct
+	 * from the at-most-once lifecycle phases so a tombstone purge never has to
+	 * re-invoke a phase hook. Must be safe to call repeatedly.
+	 */
+	onTombstonePurge?: (job: AsyncJob) => void;
+}
+
+export interface MonitorTombstone {
+	jobId: string;
+	ownerId?: string;
+	status: AsyncJob["status"];
+	expiresAt: number;
+	purge: () => unknown;
+}
+
 export interface AsyncJobRegisterOptions {
 	id?: string;
 	/** Registry id of the agent that owns this job; used to scope cancelAll. */
@@ -127,6 +149,7 @@ export interface AsyncJobRegisterOptions {
 	/** Structured metadata for tool-specific control surfaces. */
 	metadata?: AsyncJobMetadata;
 	onProgress?: (text: string, details?: Record<string, unknown>) => void | Promise<void>;
+	lifecycle?: AsyncJobLifecycleCleanup;
 }
 
 /**
@@ -214,6 +237,9 @@ export class AsyncJobManager {
 	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
 	readonly #outputState = new Map<string, AsyncJobOutputState>();
 	readonly #ownerCleanups = new Map<string, Set<() => void>>();
+	readonly #lifecycles = new Map<string, AsyncJobLifecycleCleanup>();
+	readonly #lifecyclePhases = new Map<string, Set<"cancel" | "terminal" | "evict">>();
+	readonly #monitorTombstones = new Map<string, MonitorTombstone>();
 	readonly #outputRetentionBytes = DEFAULT_JOB_OUTPUT_RETENTION_BYTES;
 	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
 	readonly #maxRunningJobs: number;
@@ -292,6 +318,7 @@ export class AsyncJobManager {
 			);
 		}
 
+		this.#expireMonitorTombstones();
 		const id = this.#resolveJobId(options?.id);
 		this.#suppressedDeliveries.delete(id);
 		const abortController = new AbortController();
@@ -308,6 +335,7 @@ export class AsyncJobManager {
 			ownerId: options?.ownerId,
 			metadata: options?.metadata,
 		};
+		if (options?.lifecycle) this.#lifecycles.set(id, options.lifecycle);
 
 		const reportProgress = async (text: string, details?: Record<string, unknown>): Promise<void> => {
 			if (!options?.onProgress) return;
@@ -325,8 +353,10 @@ export class AsyncJobManager {
 				const result = await run({ jobId: id, signal: abortController.signal, reportProgress });
 				const outcome: SubagentRunOutcome =
 					typeof result === "string" ? { kind: "completed", text: result } : result;
+
 				if (job.status === "cancelled") {
 					job.resultText = outcome.kind === "completed" ? outcome.text : outcome.note;
+					this.#runLifecycle(id, "terminal");
 					this.#scheduleEviction(id);
 					this.#markRecordTerminal(id, "cancelled");
 					this.#drainResumeQueue();
@@ -342,20 +372,24 @@ export class AsyncJobManager {
 					this.#drainResumeQueue();
 					return;
 				}
+
 				job.status = "completed";
 				job.resultText = outcome.text;
 				this.#enqueueDelivery(id, outcome.text);
+				this.#runLifecycle(id, "terminal");
 				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.#scheduleEviction(id);
 					this.#markRecordTerminal(id, "cancelled");
 					this.#drainResumeQueue();
 					return;
 				}
+				this.#runLifecycle(id, "terminal");
 				const errorText = error instanceof Error ? error.message : String(error);
 				job.status = "failed";
 				job.errorText = errorText;
@@ -381,6 +415,7 @@ export class AsyncJobManager {
 		if (!job) return false;
 		if (filter?.ownerId && job.ownerId !== filter.ownerId) return false;
 		if (job.status === "paused") {
+			this.#runLifecycle(id, "cancel");
 			// Paused jobs have no running promise to abort; transition directly.
 			// The session file is kept, so the record stays resumable by id.
 			job.status = "cancelled";
@@ -390,12 +425,76 @@ export class AsyncJobManager {
 			return true;
 		}
 		if (job.status !== "running") return false;
+		this.#runLifecycle(id, "cancel");
 		job.status = "cancelled";
 		job.abortController.abort();
-		this.#scheduleEviction(id);
 		return true;
 	}
 
+	#runLifecycle(jobId: string, phase: "cancel" | "terminal" | "evict"): void {
+		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);
+			else lifecycle.onEvict?.(job);
+		} catch (error) {
+			logger.warn("Async job lifecycle cleanup failed", {
+				jobId,
+				phase,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
+	#expireMonitorTombstones(): void {
+		const now = Date.now();
+		for (const [jobId, tombstone] of this.#monitorTombstones) {
+			if (tombstone.expiresAt <= now) this.#monitorTombstones.delete(jobId);
+		}
+	}
+
+	#recordMonitorTombstone(jobId: string): void {
+		const job = this.#jobs.get(jobId);
+		if (!job?.metadata?.monitor) return;
+		const lifecycle = this.#lifecycles.get(jobId);
+		this.#monitorTombstones.set(jobId, {
+			jobId,
+			ownerId: job.ownerId,
+			status: job.status,
+			expiresAt: Date.now() + MONITOR_TOMBSTONE_TTL_MS,
+			purge: () => (lifecycle?.onTombstonePurge ?? lifecycle?.onEvict)?.(job),
+		});
+	}
+
+	getMonitorTombstone(jobId: string, filter?: AsyncJobFilter): MonitorTombstone | undefined {
+		this.#expireMonitorTombstones();
+		const tombstone = this.#monitorTombstones.get(jobId);
+		if (!tombstone) return undefined;
+		if (filter?.ownerId && tombstone.ownerId !== filter.ownerId) return undefined;
+		return tombstone;
+	}
+
+	purgeMonitorTombstone(jobId: string, filter?: AsyncJobFilter): { found: boolean; status?: AsyncJob["status"] } {
+		const tombstone = this.getMonitorTombstone(jobId, filter);
+		if (!tombstone) return { found: false };
+		this.#monitorTombstones.delete(jobId);
+		try {
+			tombstone.purge();
+		} catch (error) {
+			logger.warn("Monitor tombstone purge failed", {
+				jobId,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+		return { found: true, status: tombstone.status };
+	}
+
 	// ── Subagent control plane (pause / resume / steer support) ──────────
 
 	/** Register or replace the canonical record for a subagent. */
@@ -836,6 +935,7 @@ export class AsyncJobManager {
 	 */
 	cancelAll(filter?: AsyncJobFilter): void {
 		for (const job of this.getRunningJobs(filter)) {
+			this.#runLifecycle(job.id, "cancel");
 			job.status = "cancelled";
 			job.abortController.abort();
 			this.#scheduleEviction(job.id);
@@ -898,6 +998,17 @@ export class AsyncJobManager {
 		// manager. Errors in cleanup callbacks are logged but never escalated.
 		this.runOwnerCleanups();
 		this.cancelAll();
+		for (const tombstone of this.#monitorTombstones.values()) {
+			try {
+				tombstone.purge();
+			} catch (error) {
+				logger.warn("Monitor tombstone purge failed during dispose", {
+					jobId: tombstone.jobId,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+		this.#monitorTombstones.clear();
 		await this.waitForAll();
 		const drained = await this.drainDeliveries({ timeoutMs: options?.timeoutMs ?? 3_000 });
 		this.#clearEvictionTimers();
@@ -945,7 +1056,11 @@ export class AsyncJobManager {
 	#scheduleEviction(jobId: string): void {
 		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);
@@ -957,7 +1072,11 @@ 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);

package/src/cli/grep-cli.ts

@@ -98,7 +98,7 @@ export async function runGrepCommand(cmd: GrepCommandArgs): Promise<void> {
 		console.log(chalk.green(`Files with matches: ${result.filesWithMatches}`));
 		console.log(chalk.green(`Files searched: ${result.filesSearched}`));
 		if (result.limitReached) {
-			console.log(chalk.yellow(`Limit reached: true`));
+			console.log(chalk.yellow(`Result limit reached (${cmd.limit} matches). Use --limit to show more.`));
 		}
 		console.log("");
 

package/src/commands/harness.ts

@@ -241,6 +241,12 @@ interface OwnerExitEvidence {
 	lastSignal: string | null;
 	promptAcceptedSeen: boolean;
 	completedSeen: boolean;
+	/** True only when the owner is genuinely gone (lease missing or process dead). */
+	terminal: boolean;
+	/** True when the owner process is provably alive (live lease + fresh heartbeat) but the endpoint did not route. */
+	transient: boolean;
+	/** ISO timestamp of the most recent non-terminal RPC-derived owner event, if any (observability only). */
+	lastRpcActivityAt: string | null;
 }
 
 async function buildOwnerExitEvidence(root: string, state: SessionState): Promise<OwnerExitEvidence> {
@@ -251,12 +257,23 @@ async function buildOwnerExitEvidence(root: string, state: SessionState): Promis
 	let lastSignal: string | null = null;
 	let promptAcceptedSeen = false;
 	let completedSeen = false;
+	let lastRpcActivityAt: string | null = null;
 	for (const event of events) {
 		const signal = (event.evidence as { signal?: unknown } | undefined)?.signal;
 		if (typeof signal === "string") lastSignal = signal;
 		if (event.kind === "prompt_accepted" || signal === "prompt-accepted") promptAcceptedSeen = true;
 		if (event.kind === "rpc_agent_completed" || signal === "completed") completedSeen = true;
+		// Terminal completion/failure frames are NOT owner liveness — exclude them from activity.
+		if (event.kind.startsWith("rpc_") && event.kind !== "rpc_agent_completed" && event.kind !== "rpc_agent_failed") {
+			lastRpcActivityAt = event.createdAt;
+		}
 	}
+	// Owner liveness is the lease heartbeat, never RPC frames: a "live" lease means the owner process
+	// is alive and heartbeating within TTL, so a failed endpoint call is a transient observation gap.
+	// Real owner loss (missing/dead lease) stays terminal and keeps its original reason string so
+	// existing consumers that match on the reason continue to escalate.
+	const terminal = !lease || leaseStatus === "dead";
+	const transient = leaseStatus === "live";
 	let reason = "owner-not-live";
 	if (!lease) {
 		reason = promptAcceptedSeen && !completedSeen ? "owner-exited-after-prompt-acceptance" : "owner-lease-missing";
@@ -281,6 +298,9 @@ async function buildOwnerExitEvidence(root: string, state: SessionState): Promis
 		lastSignal,
 		promptAcceptedSeen,
 		completedSeen,
+		terminal,
+		transient,
+		lastRpcActivityAt,
 	};
 }
 
@@ -684,6 +704,7 @@ export default class Harness extends Command {
 		const handle: SessionHandle = {
 			sessionId,
 			harness,
+			mode: input.mode === "review" || input.reviewOnly === true ? "review" : "implement",
 			repo: typeof input.repo === "string" ? input.repo : null,
 			workspace,
 			branch: preflight.declaredBranch ?? preflight.actualBranch,
@@ -953,9 +974,27 @@ export default class Harness extends Command {
 			observation: { ...observation, lifecycle: state.lifecycle },
 			retryBudget: budget,
 		});
-		const vanishReceiptId = await writeVanishReceiptForDecision(root, state, observation, decision.classification);
+		// A session persisted as `started` whose owner was never spawned (no lease,
+		// no endpoint, no owner-run evidence) is not a vanish — it simply never had
+		// an owner. Bootstrap a fresh owner instead of deadlocking on the missing
+		// prior endpoint (which `start` without `--detach` never records).
+		const ownerNeverStarted =
+			state.lifecycle === "started" &&
+			!beforeExit.endpointPresent &&
+			!beforeExit.promptAcceptedSeen &&
+			!beforeExit.completedSeen &&
+			beforeExit.lastEventKind === null &&
+			observation.risk !== "deleted-worktree";
+		// Bootstrapping a never-started owner is not a vanish, so it needs no vanish receipt.
+		const vanishReceiptId = ownerNeverStarted
+			? null
+			: await writeVanishReceiptForDecision(root, state, observation, decision.classification);
+		// A never-started owner has no in-flight work to preserve, so bootstrapping it does not
+		// depend on the vanish classifier's `ownerRequired` verdict — that gate exists to protect a
+		// vanished owner's worktree. Without this, a session started in a non-git workspace (git
+		// delta `unknown` → classifier `human-check` with `ownerRequired: false`) would stay stuck.
 		const restoredOwner =
-			decision.ownerRequired && beforeExit.endpointPresent
+			ownerNeverStarted || (decision.ownerRequired && beforeExit.endpointPresent)
 				? await this.#spawnDetachedOwner(root, sessionId, state.handle.workspace)
 				: null;
 		if (restoredOwner?.live) {
@@ -968,7 +1007,7 @@ export default class Harness extends Command {
 				writeJson(
 					buildResponse(state, true, {
 						pending: false,
-						restoredOwner: true,
+						...(ownerNeverStarted ? { bootstrappedOwner: true } : { restoredOwner: true }),
 						decision,
 						observation: { ...observation, lifecycle: state.lifecycle, ownerLive: true },
 						ownerExit: beforeExit,

package/src/commands/ultragoal.ts

@@ -1,6 +1,7 @@
 import { Command } from "@gajae-code/utils/cli";
 import {
 	GJC_SESSION_FILE_ENV,
+	GJC_SESSION_ID_ENV,
 	isUltragoalCreateGoalsInvocation,
 	readUltragoalGjcObjective,
 	writeCurrentSessionGoalModeState,
@@ -12,6 +13,7 @@ export default class Ultragoal extends Command {
 	static description = "Run native GJC Ultragoal workflow commands";
 	static strict = false;
 	static examples = ["$ gjc ultragoal status --json"];
+	static delegateHelp = true;
 
 	async run(): Promise<void> {
 		const shouldActivateGoalMode = isUltragoalCreateGoalsInvocation(this.argv);
@@ -27,6 +29,11 @@ export default class Ultragoal extends Command {
 			sessionFile: process.env[GJC_SESSION_FILE_ENV],
 			objective,
 		});
-		await writePendingGoalModeRequest({ cwd, objective, goalsPath });
+		await writePendingGoalModeRequest({
+			cwd,
+			objective,
+			goalsPath,
+			sessionId: process.env[GJC_SESSION_ID_ENV],
+		});
 	}
 }

package/src/commit/agentic/index.ts

@@ -5,7 +5,7 @@ import { applyChangelogProposals } from "../../commit/changelog";
 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 { resolvePrimaryModel, resolveSecondaryCommitModel } from "../../commit/model-selection";
 import type { CommitCommandArgs, ConventionalAnalysis } from "../../commit/types";
 import { ModelRegistry } from "../../config/model-registry";
 import { Settings } from "../../config/settings";
@@ -47,7 +47,7 @@ export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
 	const { model: primaryModel, apiKey: primaryApiKey } = primaryModelResult;
 	process.stdout.write(`  └─ ${primaryModel.name}\n`);
 
-	const { model: agentModel, thinkingLevel: agentThinkingLevel } = await resolveSmolModel(
+	const { model: agentModel, thinkingLevel: agentThinkingLevel } = await resolveSecondaryCommitModel(
 		settings,
 		modelRegistry,
 		primaryModel,

package/src/commit/model-selection.ts

@@ -1,14 +1,7 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Api, Model } from "@gajae-code/ai";
-import { MODEL_ROLE_IDS } from "../config/model-registry";
-import {
-	type ModelLookupRegistry,
-	parseModelPattern,
-	resolveModelRoleValue,
-	resolveRoleSelection,
-} from "../config/model-resolver";
+import { type ModelLookupRegistry, resolveModelRoleValue, resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
-import MODEL_PRIO from "../priority.json" with { type: "json" };
 
 export interface ResolvedCommitModel {
 	model: Model<Api>;
@@ -29,7 +22,7 @@ export async function resolvePrimaryModel(
 	const matchPreferences = { usageOrder: settings.getStorage()?.getModelUsageOrder() };
 	const resolved = override
 		? resolveModelRoleValue(override, available, { settings, matchPreferences, modelRegistry })
-		: resolveRoleSelection(["commit", "smol", ...MODEL_ROLE_IDS], settings, available, modelRegistry);
+		: resolveRoleSelection(["default"], settings, available, modelRegistry);
 	const model = resolved?.model;
 	if (!model) {
 		throw new Error("No model available for commit generation");
@@ -41,25 +34,17 @@ export async function resolvePrimaryModel(
 	return { model, apiKey, thinkingLevel: resolved?.thinkingLevel };
 }
 
-export async function resolveSmolModel(
+export async function resolveSecondaryCommitModel(
 	settings: Settings,
 	modelRegistry: CommitModelRegistry,
 	fallbackModel: Model<Api>,
 	fallbackApiKey: string,
 ): Promise<ResolvedCommitModel> {
 	const available = modelRegistry.getAvailable();
-	const resolvedSmol = resolveRoleSelection(["smol"], settings, available, modelRegistry);
-	if (resolvedSmol?.model) {
-		const apiKey = await modelRegistry.getApiKey(resolvedSmol.model);
-		if (apiKey) return { model: resolvedSmol.model, apiKey, thinkingLevel: resolvedSmol.thinkingLevel };
-	}
-
-	const matchPreferences = { usageOrder: settings.getStorage()?.getModelUsageOrder() };
-	for (const pattern of MODEL_PRIO.smol) {
-		const candidate = parseModelPattern(pattern, available, matchPreferences, { modelRegistry }).model;
-		if (!candidate) continue;
-		const apiKey = await modelRegistry.getApiKey(candidate);
-		if (apiKey) return { model: candidate, apiKey };
+	const resolved = resolveRoleSelection(["default"], settings, available, modelRegistry);
+	if (resolved?.model) {
+		const apiKey = await modelRegistry.getApiKey(resolved.model);
+		if (apiKey) return { model: resolved.model, apiKey, thinkingLevel: resolved.thinkingLevel };
 	}
 
 	return { model: fallbackModel, apiKey: fallbackApiKey };

package/src/commit/pipeline.ts

@@ -18,7 +18,7 @@ import {
 import { runChangelogFlow } from "./changelog";
 import { runMapReduceAnalysis, shouldUseMapReduce } from "./map-reduce";
 import { formatCommitMessage } from "./message";
-import { resolvePrimaryModel, resolveSmolModel } from "./model-selection";
+import { resolvePrimaryModel, resolveSecondaryCommitModel } from "./model-selection";
 import summaryRetryPrompt from "./prompts/summary-retry.md" with { type: "text" };
 import typesDescriptionPrompt from "./prompts/types-description.md" with { type: "text" };
 import type { CommitCommandArgs, ConventionalAnalysis } from "./types";
@@ -56,7 +56,7 @@ async function runLegacyCommitCommand(args: CommitCommandArgs): Promise<void> {
 		model: smolModel,
 		apiKey: smolApiKey,
 		thinkingLevel: smolThinkingLevel,
-	} = await resolveSmolModel(settings, modelRegistry, primaryModel, primaryApiKey);
+	} = await resolveSecondaryCommitModel(settings, modelRegistry, primaryModel, primaryApiKey);
 
 	let stagedFiles = await git.diff.changedFiles(cwd, { cached: true });
 	if (stagedFiles.length === 0) {

package/src/config/model-registry.ts

@@ -62,7 +62,7 @@ export function isAuthenticated(apiKey: string | undefined | null): apiKey is st
 	return Boolean(apiKey) && apiKey !== kNoAuth;
 }
 
-export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "designer" | "commit" | "task";
+export type ModelRole = "default";
 
 export interface ModelRoleInfo {
 	tag?: string;
@@ -72,16 +72,9 @@ export interface ModelRoleInfo {
 
 export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
 	default: { tag: "DEFAULT", name: "Default", color: "success" },
-	smol: { tag: "SMOL", name: "Fast", color: "warning" },
-	slow: { tag: "SLOW", name: "Thinking", color: "accent" },
-	vision: { tag: "VISION", name: "Vision", color: "error" },
-	plan: { tag: "PLAN", name: "Architect", color: "muted" },
-	designer: { tag: "DESIGNER", name: "Designer", color: "muted" },
-	commit: { tag: "COMMIT", name: "Commit", color: "dim" },
-	task: { tag: "TASK", name: "Subtask", color: "muted" },
 };
 
-export const MODEL_ROLE_IDS: ModelRole[] = ["default", "smol", "slow", "vision", "plan", "designer", "commit", "task"];
+export const MODEL_ROLE_IDS: ModelRole[] = ["default"];
 
 export type GjcModelAssignmentTargetId = "default" | "executor" | "architect" | "planner" | "critic";
 
@@ -688,6 +681,7 @@ function applyModelOverride(model: Model<Api>, override: ModelOverride): Model<A
 	if (override.reasoning !== undefined) result.reasoning = override.reasoning;
 	if (override.thinking !== undefined) result.thinking = override.thinking as ThinkingConfig;
 	if (override.input !== undefined) result.input = override.input as ("text" | "image")[];
+	if (override.output !== undefined) result.output = override.output as ("text" | "image")[];
 	if (override.cacheRetention !== undefined) result.cacheRetention = override.cacheRetention;
 	if (override.contextWindow !== undefined) result.contextWindow = override.contextWindow;
 	if (override.maxTokens !== undefined) result.maxTokens = override.maxTokens;
@@ -718,6 +712,7 @@ interface CustomModelDefinitionLike {
 	reasoning?: boolean;
 	thinking?: ThinkingConfig;
 	input?: ("text" | "image")[];
+	output?: ("text" | "image")[];
 	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
 	contextWindow?: number;
 	maxTokens?: number;
@@ -743,6 +738,7 @@ type CustomModelOverlay = {
 	reasoning?: boolean;
 	thinking?: ThinkingConfig;
 	input?: ("text" | "image")[];
+	output?: ("text" | "image")[];
 	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
 	contextWindow?: number;
 	maxTokens?: number;
@@ -818,6 +814,7 @@ function buildCustomModelOverlay(
 		reasoning: modelDef.reasoning,
 		thinking: modelDef.thinking as ThinkingConfig | undefined,
 		input: modelDef.input as ("text" | "image")[] | undefined,
+		output: modelDef.output as ("text" | "image")[] | undefined,
 		cost: modelDef.cost,
 		contextWindow: modelDef.contextWindow,
 		maxTokens: modelDef.maxTokens,
@@ -910,6 +907,7 @@ function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuil
 		reference?.cost ??
 		(options.useDefaults ? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } : undefined);
 	const input = resolvedModel.input ?? reference?.input ?? (options.useDefaults ? ["text"] : undefined);
+	const output = resolvedModel.output ?? reference?.output;
 	return enrichModelThinking({
 		id: resolvedModel.id,
 		name: resolvedModel.name ?? (options.useDefaults ? resolvedModel.id : undefined),
@@ -919,6 +917,7 @@ function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuil
 		reasoning: resolvedModel.reasoning ?? reference?.reasoning ?? (options.useDefaults ? false : undefined),
 		thinking: resolvedModel.thinking ?? reference?.thinking,
 		input: input as ("text" | "image")[],
+		output: output as ("text" | "image")[] | undefined,
 		cost,
 		contextWindow:
 			resolvedModel.contextWindow ?? reference?.contextWindow ?? (options.useDefaults ? 128000 : undefined),
@@ -1213,6 +1212,7 @@ export class ModelRegistry {
 					reasoning: customModel.reasoning ?? existingModel.reasoning,
 					thinking: customModel.thinking ?? existingModel.thinking,
 					input: customModel.input ?? existingModel.input,
+					output: customModel.output ?? existingModel.output,
 					cost: customModel.cost ?? existingModel.cost,
 					contextWindow: customModel.contextWindow ?? existingModel.contextWindow,
 					maxTokens: customModel.maxTokens ?? existingModel.maxTokens,
@@ -2325,6 +2325,14 @@ export class ModelRegistry {
 			fallback: 3,
 		};
 		return [...variants].sort((left, right) => {
+			// Prefer vision-capable variants over configured provider order so an
+			// ambiguous canonical id never resolves to a text-only namesake when a
+			// vision-capable variant of the same id is available.
+			const leftVision = left.model.input.includes("image") ? 0 : 1;
+			const rightVision = right.model.input.includes("image") ? 0 : 1;
+			if (leftVision !== rightVision) {
+				return leftVision - rightVision;
+			}
 			const leftProviderRank = providerRank.get(left.model.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER;
 			const rightProviderRank = providerRank.get(right.model.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER;
 			if (leftProviderRank !== rightProviderRank) {