@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/modes/components/oauth-selector.ts

@@ -1,3 +1,5 @@
+import type { AuthCredentialSelector, CredentialInventoryRecord, CredentialRemovalTarget } from "@gajae-code/ai/core";
+import { getEnvApiKey } from "@gajae-code/ai/core";
 import { getOAuthProviders } from "@gajae-code/ai/utils/oauth";
 import type { OAuthProviderInfo } from "@gajae-code/ai/utils/oauth/types";
 import { Container, fuzzyFilter, Input, matchesKey, Spacer, TruncatedText } from "@gajae-code/tui";
@@ -10,16 +12,44 @@ import type { ImportableCredential } from "../../setup/credential-import";
 import { DynamicBorder } from "./dynamic-border";
 
 const OAUTH_SELECTOR_MAX_VISIBLE = 10;
-/**
- * Component that renders an OAuth provider selector.
- */
+const SAFE_LABEL_MAX_LENGTH = 160;
+
+export interface OAuthSelectorAccountOptions {
+	accountProviderId?: string;
+	onAccountSelect?: (selector: AuthCredentialSelector) => void | Promise<void>;
+	onAutoSelect?: () => void | Promise<void>;
+	onAddAccount?: () => void | Promise<void>;
+	onAccountRemove?: (targets: readonly CredentialRemovalTarget[]) => void | Promise<void>;
+}
+
+type AccountEntry =
+	| { kind: "account"; row: CredentialInventoryRecord; target?: CredentialRemovalTarget; selectable: boolean }
+	| { kind: "auto"; selectable: true }
+	| { kind: "add"; selectable: boolean }
+	| { kind: "all"; selectable: boolean };
+
+function safeLabel(value: unknown, fallback: string): string {
+	if (typeof value !== "string") return fallback;
+	const normalized = value
+		.replace(/bearer\s+[^\s,;]+/gi, "Bearer [redacted]")
+		.replace(/(api[_-]?key|token|secret|authorization)[=:]\s*[^\s,;]+/gi, "$1=[redacted]")
+		.replace(/[\u0000-\u001f\u007f]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim()
+		.slice(0, SAFE_LABEL_MAX_LENGTH);
+	return normalized || fallback;
+}
+
+/** Component that renders an OAuth provider selector or a provider-scoped account selector. */
 export class OAuthSelectorComponent extends Container {
 	#listContainer: Container;
 	#allProviders: OAuthProviderInfo[] = [];
 	#sortedProviders: OAuthProviderInfo[] = [];
 	#filteredProviders: OAuthProviderInfo[] = [];
+	#accountEntries: AccountEntry[] = [];
+	#filteredAccountEntries: AccountEntry[] = [];
 	#searchInput: Input;
-	#selectedIndex: number = 0;
+	#selectedIndex = 0;
 	#mode: "login" | "logout";
 	#authStorage: AuthStorage;
 	#onSelectCallback: (providerId: string) => void;
@@ -29,9 +59,16 @@ export class OAuthSelectorComponent extends Container {
 	#requestRenderCallback?: () => void;
 	#authState: Map<string, "checking" | "valid" | "invalid"> = new Map();
 	#externalCredentialCandidates: ImportableCredential[] = [];
-	#spinnerFrame: number = 0;
+	#spinnerFrame = 0;
 	#spinnerInterval?: NodeJS.Timeout;
-	#validationGeneration: number = 0;
+	#validationGeneration = 0;
+	#accountProviderId?: string;
+	#onAccountSelect?: (selector: AuthCredentialSelector) => void | Promise<void>;
+	#onAutoSelect?: () => void | Promise<void>;
+	#onAddAccount?: () => void | Promise<void>;
+	#onAccountRemove?: (targets: readonly CredentialRemovalTarget[]) => void | Promise<void>;
+	#pendingAccountRemovalTargets?: readonly CredentialRemovalTarget[];
+
 	constructor(
 		mode: "login" | "logout",
 		authStorage: AuthStorage,
@@ -41,7 +78,7 @@ export class OAuthSelectorComponent extends Container {
 			validateAuth?: (providerId: string) => Promise<boolean>;
 			requestRender?: () => void;
 			externalCredentialCandidates?: ImportableCredential[];
-		},
+		} & Partial<OAuthSelectorAccountOptions>,
 	) {
 		super();
 		this.#mode = mode;
@@ -51,29 +88,32 @@ export class OAuthSelectorComponent extends Container {
 		this.#validateAuthCallback = options?.validateAuth;
 		this.#requestRenderCallback = options?.requestRender;
 		this.#externalCredentialCandidates = options?.externalCredentialCandidates ?? [];
-		// Load all OAuth providers
-		this.#loadProviders();
+		this.#accountProviderId = options?.accountProviderId;
+		this.#onAccountSelect = options?.onAccountSelect;
+		this.#onAutoSelect = options?.onAutoSelect;
+		this.#onAddAccount = options?.onAddAccount;
+		this.#onAccountRemove = options?.onAccountRemove;
+
+		if (this.#accountProviderId) this.#loadAccountEntries();
+		else this.#loadProviders();
+
 		this.addChild(new DynamicBorder());
 		this.addChild(new Spacer(1));
-		// Add title
-		const title = mode === "login" ? "Select provider to login:" : "Select provider to logout:";
+		const title = this.#accountProviderId
+			? `${mode === "login" ? "Select account to login for" : "Select account to logout from"} ${safeLabel(this.#accountProviderId, "provider")}:`
+			: mode === "login"
+				? "Select provider to login:"
+				: "Select provider to logout:";
 		this.addChild(new TruncatedText(theme.bold(title)));
 		this.addChild(new Spacer(1));
-		// Filter box: the provider list is long enough that arrow-key-only
-		// navigation buries entries below the visible window.
 		this.#searchInput = new Input();
-		this.#searchInput.onSubmit = () => {
-			this.#selectCurrentProvider();
-		};
+		this.#searchInput.onSubmit = () => this.#selectCurrent();
 		this.addChild(this.#searchInput);
 		this.addChild(new Spacer(1));
-		// Create list container
 		this.#listContainer = new Container();
 		this.addChild(this.#listContainer);
 		this.addChild(new Spacer(1));
-		// Add bottom border
 		this.addChild(new DynamicBorder());
-		// Initial render
 		this.#updateList();
 		this.#startValidation();
 	}
@@ -87,12 +127,47 @@ export class OAuthSelectorComponent extends Container {
 		this.stopValidation();
 		super.dispose();
 	}
+
 	#loadProviders(): void {
 		this.#allProviders = getOAuthProviders();
 	}
 
+	#loadAccountEntries(): void {
+		const provider = this.#accountProviderId;
+		if (!provider) return;
+		const inventory = this.#authStorage
+			.listCredentialInventory(provider)
+			.filter(row => row.provider === provider)
+			.sort((left, right) => left.id - right.id);
+		const targets = new Map(
+			this.#authStorage.listCredentialRemovalTargets(provider).map(target => [target.id, target]),
+		);
+		const apiKeyOverrideActive =
+			this.#authStorage.hasRuntimeApiKey(provider) ||
+			this.#authStorage.hasConfigApiKey(provider) ||
+			Boolean(getEnvApiKey(provider));
+		const rows = inventory.filter(row => this.#mode === "login" || row.credentialKind === "oauth");
+		this.#accountEntries = rows.map(row => ({
+			kind: "account" as const,
+			row,
+			target: targets.get(row.id),
+			selectable:
+				row.credentialKind === "oauth" &&
+				!apiKeyOverrideActive &&
+				(this.#mode === "login" ? !row.disabled : targets.has(row.id)),
+		}));
+		if (this.#mode === "login") {
+			this.#accountEntries.push(
+				{ kind: "auto", selectable: true },
+				{ kind: "add", selectable: this.#onAddAccount !== undefined },
+			);
+		} else if (this.#accountEntries.some(entry => entry.kind === "account" && entry.selectable)) {
+			this.#accountEntries.push({ kind: "all", selectable: this.#onAccountRemove !== undefined });
+		}
+	}
+
 	#startValidation(): void {
-		if (!this.#validateAuthCallback) return;
+		if (this.#accountProviderId || !this.#validateAuthCallback) return;
 		const generation = this.#validationGeneration + 1;
 		this.#validationGeneration = generation;
 
@@ -122,17 +197,12 @@ export class OAuthSelectorComponent extends Container {
 		} catch {
 			isValid = false;
 		}
-
 		if (generation !== this.#validationGeneration) return;
 		this.#authState.set(providerId, isValid ? "valid" : "invalid");
-		// Only record the ordering hint when the credentials validated are still the
-		// current ones; a result from a superseded generation must not describe them.
 		if (authGeneration === this.#authStorage.getGeneration()) {
 			recordProviderAuthHealth(this.#authStorage, providerId, isValid ? "valid" : "invalid");
 		}
-		if (![...this.#authState.values()].includes("checking")) {
-			this.#stopSpinner();
-		}
+		if (![...this.#authState.values()].includes("checking")) this.#stopSpinner();
 		this.#updateList();
 		this.#requestRenderCallback?.();
 	}
@@ -141,9 +211,7 @@ export class OAuthSelectorComponent extends Container {
 		if (this.#spinnerInterval) return;
 		this.#spinnerInterval = setInterval(() => {
 			const frameCount = theme.spinnerFrames.length;
-			if (frameCount > 0) {
-				this.#spinnerFrame = (this.#spinnerFrame + 1) % frameCount;
-			}
+			if (frameCount > 0) this.#spinnerFrame = (this.#spinnerFrame + 1) % frameCount;
 			this.#updateList();
 			this.#requestRenderCallback?.();
 		}, 80);
@@ -167,15 +235,70 @@ export class OAuthSelectorComponent extends Container {
 			const spinner = frameCount > 0 ? theme.spinnerFrames[this.#spinnerFrame % frameCount] : theme.status.pending;
 			return theme.fg("warning", ` ${spinner} checking`);
 		}
-		if (state === "invalid") {
-			return theme.fg("error", ` ${theme.status.error} invalid`);
+		if (state === "invalid") return theme.fg("error", ` ${theme.status.error} invalid`);
+		if (state === "valid") return theme.fg("success", ` ${theme.status.success} logged in`);
+		return this.#authStorage.hasAuth(providerId) ? theme.fg("success", ` ${theme.status.success} logged in`) : "";
+	}
+
+	#accountLabel(entry: AccountEntry): string {
+		switch (entry.kind) {
+			case "auto":
+				return "AUTO (ranked)";
+			case "add":
+				return "Add new account";
+			case "all":
+				return "Remove all accounts";
+			case "account": {
+				const identity =
+					entry.row.credentialKind === "oauth"
+						? safeLabel(entry.row.identityLabel, `OAuth account · row ${entry.row.id}`)
+						: `API key · row ${entry.row.id}`;
+				const status = entry.row.disabled
+					? `disabled${entry.row.disabledCause ? `: ${safeLabel(entry.row.disabledCause, "disabled")}` : ""}`
+					: "active";
+				return `${identity} (${status})`;
+			}
 		}
-		if (state === "valid") {
-			return theme.fg("success", ` ${theme.status.success} logged in`);
+	}
+
+	#clearPendingAccountRemoval(): boolean {
+		if (this.#pendingAccountRemovalTargets === undefined) return false;
+		this.#pendingAccountRemovalTargets = undefined;
+		this.#statusMessage = undefined;
+		return true;
+	}
+
+	#getAccountRemovalTargets(): CredentialRemovalTarget[] {
+		return this.#accountEntries
+			.filter(
+				(entry): entry is Extract<AccountEntry, { kind: "account" }> =>
+					entry.kind === "account" && entry.selectable && entry.target !== undefined,
+			)
+			.map(entry => entry.target as CredentialRemovalTarget);
+	}
+
+	#confirmOrArmAccountRemoval(targets: readonly CredentialRemovalTarget[], prompt: string): void {
+		if (this.#pendingAccountRemovalTargets !== undefined) {
+			const pending = this.#pendingAccountRemovalTargets;
+			this.#pendingAccountRemovalTargets = undefined;
+			this.#statusMessage = undefined;
+			void this.#onAccountRemove?.(pending);
+			return;
 		}
-		return this.#authStorage.hasAuth(providerId) ? theme.fg("success", ` ${theme.status.success} logged in`) : "";
+		if (targets.length === 0) {
+			this.#statusMessage = "No accounts available to remove.";
+		} else {
+			this.#pendingAccountRemovalTargets = targets;
+			this.#statusMessage = `${prompt} Enter to confirm, Esc to cancel`;
+		}
+		this.#updateList();
 	}
 	#updateList(): void {
+		if (this.#accountProviderId) {
+			this.#updateAccountList();
+			return;
+		}
+
 		const selectedProviderId = this.#filteredProviders[this.#selectedIndex]?.id;
 		const rankedProviders = this.#allProviders.map(provider => ({
 			provider,
@@ -185,8 +308,6 @@ export class OAuthSelectorComponent extends Container {
 		}));
 		rankedProviders.sort(compareRankedProviders);
 		this.#sortedProviders = rankedProviders.map(({ provider }) => provider);
-		// Filter after ranking so an empty query preserves the curated order and a
-		// query still surfaces matches in that same order of preference.
 		this.#filteredProviders = fuzzyFilter(
 			this.#sortedProviders,
 			this.#searchInput.getValue(),
@@ -208,33 +329,25 @@ export class OAuthSelectorComponent extends Container {
 				? 0
 				: Math.max(0, Math.min(this.#selectedIndex - Math.floor(maxVisible / 2), total - maxVisible));
 		const endIndex = Math.min(startIndex + maxVisible, total);
-
 		for (let i = startIndex; i < endIndex; i++) {
 			const provider = this.#filteredProviders[i];
 			if (!provider) continue;
 			const isSelected = i === this.#selectedIndex;
 			const isAvailable = provider.available;
 			const statusIndicator = this.#getStatusIndicator(provider.id);
-
-			let line = "";
-			if (isSelected) {
-				const prefix = theme.fg("accent", `${theme.nav.cursor} `);
-				const text = isAvailable ? theme.fg("accent", provider.name) : theme.fg("dim", provider.name);
-				line = prefix + text + statusIndicator;
-			} else {
-				const text = isAvailable ? `  ${provider.name}` : theme.fg("dim", `  ${provider.name}`);
-				line = text + statusIndicator;
-			}
-			this.#listContainer.addChild(new TruncatedText(line, 0, 0));
+			const prefix = isSelected ? theme.fg("accent", `${theme.nav.cursor} `) : "  ";
+			const text = isAvailable
+				? isSelected
+					? theme.fg("accent", provider.name)
+					: provider.name
+				: theme.fg("dim", provider.name);
+			this.#listContainer.addChild(new TruncatedText(prefix + text + statusIndicator, 0, 0));
 		}
-
-		// Scroll indicator when list is windowed
 		if (startIndex > 0 || endIndex < total) {
-			const scrollInfo = theme.fg("muted", `  (${this.#selectedIndex + 1}/${total})`);
-			this.#listContainer.addChild(new TruncatedText(scrollInfo, 0, 0));
+			this.#listContainer.addChild(
+				new TruncatedText(theme.fg("muted", `  (${this.#selectedIndex + 1}/${total})`), 0, 0),
+			);
 		}
-
-		// Show "no providers" if empty
 		if (total === 0) {
 			const message = this.#searchInput.getValue().trim()
 				? "No providers match the filter"
@@ -245,7 +358,13 @@ export class OAuthSelectorComponent extends Container {
 		}
 		if (this.#statusMessage) {
 			this.#listContainer.addChild(new Spacer(1));
-			this.#listContainer.addChild(new TruncatedText(theme.fg("warning", `  ${this.#statusMessage}`), 0, 0));
+			this.#listContainer.addChild(
+				new TruncatedText(
+					theme.fg("warning", `  ${safeLabel(this.#statusMessage, "Unable to select provider")}`),
+					0,
+					0,
+				),
+			);
 		}
 		if (this.#mode === "login" && this.#externalCredentialCandidates.length > 0) {
 			this.#listContainer.addChild(new Spacer(1));
@@ -254,7 +373,7 @@ export class OAuthSelectorComponent extends Container {
 					new TruncatedText(
 						theme.fg(
 							"success",
-							`  ${theme.status.success} Imported ${credential.provider} from ${credential.source}`,
+							`  ${theme.status.success} Imported ${safeLabel(credential.provider, "provider")} from ${safeLabel(credential.source, "external source")}`,
 						),
 						0,
 						0,
@@ -263,7 +382,88 @@ export class OAuthSelectorComponent extends Container {
 			}
 		}
 	}
-	#selectCurrentProvider(): void {
+
+	#updateAccountList(): void {
+		const query = this.#searchInput.getValue().trim().toLowerCase();
+		this.#filteredAccountEntries = this.#accountEntries.filter(entry =>
+			this.#accountLabel(entry).toLowerCase().includes(query),
+		);
+		if (this.#selectedIndex >= this.#filteredAccountEntries.length) {
+			this.#selectedIndex = Math.max(0, this.#filteredAccountEntries.length - 1);
+		}
+		this.#listContainer.clear();
+		const total = this.#filteredAccountEntries.length;
+		const maxVisible = OAUTH_SELECTOR_MAX_VISIBLE;
+		const startIndex =
+			total <= maxVisible
+				? 0
+				: Math.max(0, Math.min(this.#selectedIndex - Math.floor(maxVisible / 2), total - maxVisible));
+		const endIndex = Math.min(startIndex + maxVisible, total);
+		for (let i = startIndex; i < endIndex; i++) {
+			const entry = this.#filteredAccountEntries[i];
+			if (!entry) continue;
+			const selected = i === this.#selectedIndex;
+			const prefix = selected ? theme.fg("accent", `${theme.nav.cursor} `) : "  ";
+			const label = this.#accountLabel(entry);
+			const disabled = !entry.selectable;
+			const text = disabled ? theme.fg("dim", label) : selected ? theme.fg("accent", label) : label;
+			this.#listContainer.addChild(new TruncatedText(prefix + text, 0, 0));
+		}
+		if (startIndex > 0 || endIndex < total) {
+			this.#listContainer.addChild(
+				new TruncatedText(theme.fg("muted", `  (${this.#selectedIndex + 1}/${total})`), 0, 0),
+			);
+		}
+		if (total === 0) {
+			this.#listContainer.addChild(new TruncatedText(theme.fg("muted", "  No accounts available"), 0, 0));
+		}
+		if (this.#statusMessage) {
+			this.#listContainer.addChild(new Spacer(1));
+			this.#listContainer.addChild(
+				new TruncatedText(
+					theme.fg("warning", `  ${safeLabel(this.#statusMessage, "Unable to select account")}`),
+					0,
+					0,
+				),
+			);
+		}
+	}
+
+	#selectCurrent(): void {
+		if (this.#accountProviderId) {
+			const selected = this.#filteredAccountEntries[this.#selectedIndex];
+			if (!selected) return;
+			if (!selected.selectable) {
+				this.#statusMessage = "This account is not selectable.";
+				this.#updateList();
+				return;
+			}
+			this.#statusMessage = undefined;
+			this.stopValidation();
+			if (selected.kind === "account") {
+				if (selected.row.credentialKind !== "oauth") return;
+				if (this.#mode === "login") {
+					void this.#onAccountSelect?.({ kind: "id", value: String(selected.row.id) });
+				} else if (selected.target) {
+					this.#confirmOrArmAccountRemoval([selected.target], "Remove this account?");
+				}
+			} else if (selected.kind === "auto") {
+				void this.#onAutoSelect?.();
+			} else if (selected.kind === "add") {
+				void this.#onAddAccount?.();
+			} else if (selected.kind === "all") {
+				if (this.#pendingAccountRemovalTargets !== undefined) {
+					const targets = this.#pendingAccountRemovalTargets;
+					this.#pendingAccountRemovalTargets = undefined;
+					void this.#onAccountRemove?.(targets);
+				} else {
+					const targets = this.#getAccountRemovalTargets();
+					this.#confirmOrArmAccountRemoval(targets, `Remove all ${targets.length} accounts?`);
+				}
+			}
+			return;
+		}
+
 		const selectedProvider = this.#filteredProviders[this.#selectedIndex];
 		if (selectedProvider?.available) {
 			this.#statusMessage = undefined;
@@ -274,64 +474,55 @@ export class OAuthSelectorComponent extends Container {
 			this.#updateList();
 		}
 	}
+
 	handleInput(keyData: string): void {
-		// Up arrow
+		const isConfirm = matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n";
+		const isCancel = matchesSelectCancel(keyData);
+		const pendingConfirmationCleared = !isConfirm && !isCancel ? this.#clearPendingAccountRemoval() : false;
+		const itemCount = this.#accountProviderId ? this.#filteredAccountEntries.length : this.#filteredProviders.length;
 		if (matchesKey(keyData, "up")) {
-			if (this.#filteredProviders.length > 0) {
-				this.#selectedIndex =
-					this.#selectedIndex === 0 ? this.#filteredProviders.length - 1 : this.#selectedIndex - 1;
-			}
+			this.#clearPendingAccountRemoval();
+			if (itemCount > 0) this.#selectedIndex = this.#selectedIndex === 0 ? itemCount - 1 : this.#selectedIndex - 1;
 			this.#statusMessage = undefined;
 			this.#updateList();
 			return;
 		}
-		// Down arrow
 		if (matchesKey(keyData, "down")) {
-			if (this.#filteredProviders.length > 0) {
-				this.#selectedIndex =
-					this.#selectedIndex === this.#filteredProviders.length - 1 ? 0 : this.#selectedIndex + 1;
-			}
+			this.#clearPendingAccountRemoval();
+			if (itemCount > 0) this.#selectedIndex = this.#selectedIndex === itemCount - 1 ? 0 : this.#selectedIndex + 1;
 			this.#statusMessage = undefined;
 			this.#updateList();
 			return;
 		}
-		// Page up - jump up by one visible page
 		if (matchesKey(keyData, "pageUp")) {
-			if (this.#filteredProviders.length > 0) {
-				this.#selectedIndex = Math.max(0, this.#selectedIndex - OAUTH_SELECTOR_MAX_VISIBLE);
-			}
+			this.#clearPendingAccountRemoval();
+			if (itemCount > 0) this.#selectedIndex = Math.max(0, this.#selectedIndex - OAUTH_SELECTOR_MAX_VISIBLE);
 			this.#statusMessage = undefined;
 			this.#updateList();
 			return;
 		}
-		// Page down - jump down by one visible page
 		if (matchesKey(keyData, "pageDown")) {
-			if (this.#filteredProviders.length > 0) {
-				this.#selectedIndex = Math.min(
-					this.#filteredProviders.length - 1,
-					this.#selectedIndex + OAUTH_SELECTOR_MAX_VISIBLE,
-				);
-			}
+			this.#clearPendingAccountRemoval();
+			if (itemCount > 0)
+				this.#selectedIndex = Math.min(itemCount - 1, this.#selectedIndex + OAUTH_SELECTOR_MAX_VISIBLE);
 			this.#statusMessage = undefined;
 			this.#updateList();
 			return;
 		}
-		// Enter
-		if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
-			this.#selectCurrentProvider();
+		if (isConfirm) {
+			this.#selectCurrent();
 			return;
 		}
-		// Escape or Ctrl+C
-		if (matchesSelectCancel(keyData)) {
+		if (isCancel) {
+			const pending = this.#clearPendingAccountRemoval();
 			this.stopValidation();
+			if (pending) this.#updateList();
 			this.#onCancelCallback();
 			return;
 		}
-		// Everything else edits the filter. A changed query invalidates the current
-		// position, so selection restarts at the best match.
 		const previousQuery = this.#searchInput.getValue();
 		this.#searchInput.handleInput(keyData);
-		if (this.#searchInput.getValue() !== previousQuery) {
+		if (pendingConfirmationCleared || this.#searchInput.getValue() !== previousQuery) {
 			this.#selectedIndex = 0;
 			this.#statusMessage = undefined;
 			this.#updateList();

package/src/modes/components/pet-capability.ts

@@ -6,8 +6,9 @@ import {
 	shouldProbeSixelCapability,
 	TERMINAL,
 } from "@gajae-code/tui";
+import type { PetTransportAvailability } from "./iterm-pet-transport";
 
-export type PetPixelProtocol = "sixel" | "kitty";
+export type PetPixelProtocol = "sixel" | "kitty" | "iterm";
 
 export const PET_UNAVAILABLE_DESCRIPTION = "Unavailable: requires compatible Kitty or Sixel overlay rendering";
 export const PET_SAVED_UNAVAILABLE_DESCRIPTION =
@@ -21,9 +22,34 @@ export function getPetUnavailableWarning(env: NodeJS.ProcessEnv = Bun.env): stri
 	return isUnderTerminalMultiplexer(env) ? PET_MULTIPLEXER_UNAVAILABLE_WARNING : PET_UNAVAILABLE_WARNING;
 }
 
+let latestItermAvailability: PetTransportAvailability | undefined;
+let verifiedItermAvailability: PetTransportAvailability | undefined;
+const verifiedItermListeners = new Set<(availability: PetTransportAvailability | undefined) => void>();
+export function subscribeVerifiedItermPetAvailability(
+	callback: (availability: PetTransportAvailability | undefined) => void,
+): () => void {
+	verifiedItermListeners.add(callback);
+	return () => verifiedItermListeners.delete(callback);
+}
+export function setVerifiedItermPetAvailability(availability: PetTransportAvailability | undefined): void {
+	latestItermAvailability = availability;
+	verifiedItermAvailability = availability?.available ? availability : undefined;
+	for (const listener of verifiedItermListeners) listener(verifiedItermAvailability);
+}
+export function getItermPetAvailability(): PetTransportAvailability | undefined {
+	return latestItermAvailability;
+}
+export function getVerifiedItermPetAvailability(): PetTransportAvailability | undefined {
+	return verifiedItermAvailability;
+}
+export function getItermPetUnavailableReason(): string | undefined {
+	return latestItermAvailability?.available ? undefined : latestItermAvailability?.reason;
+}
+
 export function getPetPixelProtocol(): PetPixelProtocol | null {
-	if (TERMINAL.imageProtocol === ImageProtocol.Kitty) return "kitty";
+	if (TERMINAL.imageProtocol === ImageProtocol.Kitty && !isUnderTerminalMultiplexer()) return "kitty";
 	if (TERMINAL.imageProtocol === ImageProtocol.Sixel) return "sixel";
+	if (verifiedItermAvailability?.available) return "iterm";
 	return null;
 }
 
@@ -41,31 +67,13 @@ export function createPetSelectItems(
 		const current = option.value === currentValue;
 		const savedUnavailable = disabled && current;
 		let description = `${option.description ?? ""}${current ? " (current)" : ""}`;
-		if (disabled) {
-			description = savedUnavailable ? PET_SAVED_UNAVAILABLE_DESCRIPTION : PET_UNAVAILABLE_DESCRIPTION;
-		}
-		return {
-			...option,
-			label: savedUnavailable ? `${option.label} (saved)` : option.label,
-			description,
-			disabled,
-		};
+		if (disabled) description = savedUnavailable ? PET_SAVED_UNAVAILABLE_DESCRIPTION : PET_UNAVAILABLE_DESCRIPTION;
+		return { ...option, label: savedUnavailable ? `${option.label} (saved)` : option.label, description, disabled };
 	});
 }
 
-/**
- * Grace period before declaring the terminal pet-incapable at startup. The
- * asynchronous Sixel capability probe starts inside `TUI.start()` and answers
- * within its own 250 ms deadline; this margin covers probe scheduling so a
- * supported terminal is never told it is incompatible while the probe is
- * still in flight.
- */
 export const PET_CAPABILITY_SETTLE_MS = 1_000;
 
-/**
- * Whether the asynchronous startup Sixel capability probe may still enable
- * graphics for this session, meaning current unavailability is not final.
- */
 export function isPetCapabilityProbePending(
 	env: NodeJS.ProcessEnv = Bun.env,
 	platform: NodeJS.Platform = process.platform,
@@ -75,15 +83,6 @@ export function isPetCapabilityProbePending(
 	return shouldProbeSixelCapability(env, platform);
 }
 
-/**
- * Deliver the pet-unavailable startup warning only once the capability
- * question is settled. With no probe pending, unavailability is final and
- * `onUnavailable` fires immediately. While a probe may still enable
- * graphics, the warning is deferred: a protocol-change event cancels it (the
- * saved pet re-applies through the existing subscription), and only the
- * settle deadline passing with the terminal still unavailable emits it.
- * Returns a disposer that cancels the pending decision.
- */
 export function warnWhenPetCapabilitySettled(options: {
 	probePending: boolean;
 	isAvailable?: () => boolean;
@@ -96,16 +95,21 @@ export function warnWhenPetCapabilitySettled(options: {
 	}
 	const isAvailable = options.isAvailable ?? isPetAvailable;
 	let settled = false;
+	let unsubscribeIterm = () => {};
 	const finish = () => {
 		if (settled) return;
 		settled = true;
 		clearTimeout(timer);
 		unsubscribe();
+		unsubscribeIterm();
 	};
 	const unsubscribe = onImageProtocolChanged(protocol => {
 		if (!protocol) return;
 		finish();
 	});
+	unsubscribeIterm = subscribeVerifiedItermPetAvailability(availability => {
+		if (availability?.available) finish();
+	});
 	const timer = setTimeout(() => {
 		finish();
 		if (!isAvailable()) options.onUnavailable();