@gajae-code/coding-agent 0.14.2 → 0.15.0

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

@@ -14,6 +14,15 @@ import {
 	truncateToWidth,
 } from "@gajae-code/tui";
 import { sanitizeText } from "@gajae-code/utils";
+import {
+	type AutoroutingProviderOrderHint,
+	type AutoroutingSetup,
+	autoroutingProviderOrderHint,
+	evaluateAutoroutingProvenanceState,
+	normalizeTierMap,
+	validateAutoroutingSetup,
+} from "../../config/autorouting-contract";
+
 import { isModelProfileProviderAvailable } from "../../config/model-profile-contract";
 import {
 	getModelProfilePresentation,
@@ -46,6 +55,8 @@ import { formatModelOnboardingInlineHint } from "../../setup/model-onboarding-gu
 import { formatClampedModelSelector, getThinkingLevelMetadata, parseThinkingLevel } from "../../thinking";
 import { getTabBarTheme } from "../shared";
 import { DynamicBorder } from "./dynamic-border";
+import type { SmartRoutingIntent, SmartRoutingPreview } from "./smart-routing-panel";
+import { SmartRoutingPanelComponent } from "./smart-routing-panel";
 
 function makeInvertedBadge(label: string, color: ThemeColor): string {
 	const fgAnsi = theme.getFgAnsi(color);
@@ -147,6 +158,10 @@ export type ModelSelectorSelection =
 	| {
 			kind: "deleteProfile";
 			profileName: string;
+	  }
+	| {
+			kind: "smartRouting";
+			intent: SmartRoutingIntent;
 	  };
 
 interface PendingThinkingChoice {
@@ -180,7 +195,7 @@ function createProviderTab(providerId: string): ProviderTabState {
 	return { id: providerId, label: formatProviderTabLabel(providerId), providerId };
 }
 
-type ModelSelectorViewMode = "presets" | "models";
+type ModelSelectorViewMode = "presets" | "models" | "smart-routing";
 
 interface PresetGroupRow {
 	kind: "group";
@@ -216,6 +231,10 @@ interface PresetImageRoleRow {
 	kind: "imageRole";
 }
 
+interface PresetSmartRoutingRow {
+	kind: "smartRouting";
+}
+
 type PresetLandingRow =
 	| PresetGroupRow
 	| PresetProfileRow
@@ -223,7 +242,8 @@ type PresetLandingRow =
 	| PresetCreateUnavailableRow
 	| PresetAlreadySavedRow
 	| PresetBrowseRow
-	| PresetImageRoleRow;
+	| PresetImageRoleRow
+	| PresetSmartRoutingRow;
 
 // Stable logical identity for a preset landing row, independent of its current
 // list position. Used to relocate the cursor after the expanded group changes so
@@ -244,6 +264,8 @@ function presetRowIdentity(row: PresetLandingRow): string {
 			return `alreadySaved:${row.profile.name}`;
 		case "imageRole":
 			return "imageRole";
+		case "smartRouting":
+			return "smartRouting";
 	}
 }
 
@@ -376,7 +398,10 @@ export class ModelSelectorComponent extends Container {
 	#assignmentState: "idle" | "assigning" = "idle";
 	#closeAfterAssignment = false;
 	#unsubscribeCatalogChanged: () => void = () => {};
+	#unsubscribeProviderOrderChanged: () => void = () => {};
 	#disposed = false;
+	/** Standalone smart-routing entry: cancel closes the selector instead of falling back to the preset landing. */
+	#smartRoutingOnly = false;
 
 	// Preset landing state
 	#viewMode: ModelSelectorViewMode = "presets";
@@ -391,6 +416,8 @@ export class ModelSelectorComponent extends Container {
 	#presetLoginHint?: string;
 	#authSessionId?: string;
 	#imageRoleFilter: boolean = false;
+	#smartRoutingPanel?: SmartRoutingPanelComponent;
+	#smartRoutingPreviewBuilder?: (draft: AutoroutingSetup) => SmartRoutingPreview;
 
 	// Tab state
 	#providers: ProviderTabState[] = STATIC_PROVIDER_TABS;
@@ -414,6 +441,9 @@ export class ModelSelectorComponent extends Container {
 			currentThinkingLevel?: ThinkingLevel;
 			activeModelProfile?: string;
 			configuredDefaultChain?: readonly string[];
+			smartRoutingPreview?: (draft: AutoroutingSetup) => SmartRoutingPreview;
+			/** Open the smart-routing panel directly instead of the preset landing. */
+			smartRoutingOnly?: boolean;
 		},
 	) {
 		super();
@@ -426,6 +456,7 @@ export class ModelSelectorComponent extends Container {
 		this.#onCancelCallback = onCancel;
 		this.#temporaryOnly = options?.temporaryOnly ?? false;
 		this.#authSessionId = options?.sessionId;
+		this.#smartRoutingPreviewBuilder = options?.smartRoutingPreview;
 		this.#currentModel = _currentModel;
 		this.#currentThinkingLevel = options?.currentThinkingLevel;
 		this.#activeModelProfile = options?.activeModelProfile;
@@ -442,7 +473,12 @@ export class ModelSelectorComponent extends Container {
 					? this.#isFastForProvider(this.#currentModel.provider, modelSupportsServiceTier(this.#currentModel))
 					: false);
 		const initialSearchInput = options?.initialSearchInput;
-		this.#viewMode = this.#temporaryOnly || initialSearchInput || scopedModels.length > 0 ? "models" : "presets";
+		this.#smartRoutingOnly = options?.smartRoutingOnly === true;
+		this.#viewMode = this.#smartRoutingOnly
+			? "smart-routing"
+			: this.#temporaryOnly || initialSearchInput || scopedModels.length > 0
+				? "models"
+				: "presets";
 
 		// Load current role assignments from settings
 		this.#rebuildRoleModels();
@@ -492,9 +528,25 @@ export class ModelSelectorComponent extends Container {
 			});
 		}
 
+		// Advisory drift only, and only while the smart-routing panel is mounted. This
+		// must not call refreshState: that would discard the user's unsaved draft.
+		this.#unsubscribeProviderOrderChanged = this.#settings.onChanged?.(path => {
+			if (this.#disposed || path !== "modelProviderOrder") return;
+			if (this.#viewMode !== "smart-routing") return;
+			const panel = this.#smartRoutingPanel;
+			if (!panel) return;
+			panel.updateProviderOrderHint(this.#providerOrderHintFor(panel.getProviderOrder()));
+			this.#tui.requestRender();
+		});
+
 		// Load models and do initial render
 		this.#loadModels().then(() => {
 			this.#buildProviderTabs();
+			if (this.#smartRoutingOnly) {
+				this.#enterSmartRoutingMode();
+				this.#tui.requestRender();
+				return;
+			}
 			if (this.#viewMode === "presets" && (this.#modelRegistry.getModelProfiles?.().size ?? 0) === 0) {
 				this.#viewMode = "models";
 			}
@@ -521,6 +573,7 @@ export class ModelSelectorComponent extends Container {
 		if (this.#disposed) return;
 		this.#disposed = true;
 		this.#unsubscribeCatalogChanged();
+		this.#unsubscribeProviderOrderChanged();
 		super.dispose();
 	}
 
@@ -805,17 +858,15 @@ export class ModelSelectorComponent extends Container {
 
 	#materializeModels(models: ModelItem[]): MaterializedCatalog {
 		const candidateModels = models.map(item => item.model);
-		const canonicalRecords = this.#modelRegistry.getCanonicalModels({
+		const canonicalSelections = this.#modelRegistry.getCanonicalModelSelections({
 			availableOnly: this.#scopedModels.length === 0,
 			candidates: candidateModels,
 		});
 		const scopedThinkingBySelector = new Map(models.map(item => [item.selector, item.thinkingLevel]));
-		const canonicalModels = canonicalRecords
-			.map((record): CanonicalModelItem | undefined => {
-				const selectedModel = this.#modelRegistry.resolveCanonicalModel(record.id, {
-					availableOnly: this.#scopedModels.length === 0,
-					candidates: candidateModels,
-				});
+		const canonicalModels = canonicalSelections
+			.map((selection): CanonicalModelItem | undefined => {
+				const record = selection.record;
+				const selectedModel = selection.model;
 				if (!selectedModel) return undefined;
 				const selectedSelector = `${selectedModel.provider}/${selectedModel.id}`;
 				const searchText = [
@@ -954,7 +1005,10 @@ export class ModelSelectorComponent extends Container {
 
 		let refreshError: unknown;
 		try {
-			await this.#modelRegistry.refreshProvider(providerId);
+			// Cache-aware: a fresh discovery cache answers instantly instead of
+			// forcing a provider round-trip (hundreds of ms on remote gateways)
+			// on every provider-tab visit. Stale/missing cache still fetches.
+			await this.#modelRegistry.refreshProvider(providerId, "online-if-uncached");
 		} catch (error) {
 			refreshError = error;
 		}
@@ -1229,6 +1283,7 @@ export class ModelSelectorComponent extends Container {
 			rows.push({ kind: "createUnavailable", label: "Select a model before creating a custom preset" });
 		}
 		rows.push({ kind: "imageRole" });
+		rows.push({ kind: "smartRouting" });
 		rows.push({ kind: "browse" });
 		return rows;
 	}
@@ -1435,7 +1490,8 @@ export class ModelSelectorComponent extends Container {
 			selected.kind === "create" ||
 			selected.kind === "createUnavailable" ||
 			selected.kind === "alreadySaved" ||
-			selected.kind === "imageRole"
+			selected.kind === "imageRole" ||
+			selected.kind === "smartRouting"
 		)
 			return;
 		if (this.#expandedPresetProviderId === selected.groupId) return;
@@ -1452,7 +1508,8 @@ export class ModelSelectorComponent extends Container {
 			selected.kind === "create" ||
 			selected.kind === "createUnavailable" ||
 			selected.kind === "alreadySaved" ||
-			selected.kind === "imageRole"
+			selected.kind === "imageRole" ||
+			selected.kind === "smartRouting"
 		)
 			return;
 		if (this.#expandedPresetProviderId !== selected.groupId) return;
@@ -1518,6 +1575,128 @@ export class ModelSelectorComponent extends Container {
 		return truncateToWidth(label, ROLE_BINDING_MAX_WIDTH);
 	}
 
+	/**
+	 * A recorded declaration always wins; otherwise seed from the deterministic
+	 * provider priority so the draft reflects the user's configured order instead of
+	 * raw catalog iteration. No hardcoded provider fallback: an empty catalog means
+	 * there is nothing to generate tiers from, and the caller refuses entry.
+	 */
+	#smartRoutingSetup(): AutoroutingSetup {
+		const stored = this.#settings.get("task.autorouting.setup");
+		if (validateAutoroutingSetup(stored).length === 0 && stored !== undefined) return structuredClone(stored);
+		return { schema: 1, providers: [...this.#modelRegistry.autoroutingProviderOrder()] };
+	}
+
+	/**
+	 * Advisory hint input is the panel's *current draft*, not the persisted setup, so
+	 * a user mid-reorder sees drift for what they are actually editing.
+	 */
+	#providerOrderHintFor(declared: readonly string[]): AutoroutingProviderOrderHint {
+		return autoroutingProviderOrderHint(declared, this.#modelRegistry.autoroutingProviderOrder());
+	}
+
+	#smartRoutingPreview(setup: AutoroutingSetup): SmartRoutingPreview {
+		if (!this.#smartRoutingPreviewBuilder) {
+			throw new Error("Smart-routing preview is unavailable in this selector context.");
+		}
+		return this.#smartRoutingPreviewBuilder(setup);
+	}
+
+	#smartRoutingIsStale(): boolean {
+		const provenance = this.#settings.get("task.autorouting.provenance");
+		if (!provenance || validateAutoroutingSetup(this.#smartRoutingSetup()).length > 0) return false;
+		try {
+			const preview = this.#smartRoutingPreview(this.#smartRoutingSetup());
+			const state = evaluateAutoroutingProvenanceState(provenance, {
+				catalogFingerprint: preview.sourceIdentity.catalogFingerprint,
+				mapFingerprint: preview.sourceIdentity.mapFingerprint,
+				tiers: this.#settings.get("task.autorouting.tiers") ?? {},
+			});
+			return state.staleMap || state.staleCatalog || state.handEdited;
+		} catch {
+			return true;
+		}
+	}
+
+	#smartRoutingReadOnly(): boolean {
+		return this.#temporaryOnly || this.#scopedModels.length > 0 || !this.#settings.canWriteDurableConfig();
+	}
+
+	#enterSmartRoutingMode(): void {
+		if (!this.#smartRoutingPreviewBuilder) {
+			if (this.#smartRoutingOnly) {
+				this.#onCancelCallback();
+				return;
+			}
+			this.#presetLoginHint = "Smart-routing setup is unavailable in this selector context.";
+			this.#renderPresetLanding();
+			return;
+		}
+
+		const setup = this.#smartRoutingSetup();
+		if (setup.providers.length === 0) {
+			// Nothing to generate tiers from; refuse entry instead of seeding a guess.
+			if (this.#smartRoutingOnly) {
+				this.#onCancelCallback();
+				return;
+			}
+			this.#presetLoginHint = "No providers are available to generate routing tiers.";
+			this.#renderPresetLanding();
+			return;
+		}
+		const preview = this.#smartRoutingPreview(setup);
+		const tiers = normalizeTierMap(this.#settings.get("task.autorouting.tiers"));
+		const provenance = this.#settings.get("task.autorouting.provenance");
+		this.#viewMode = "smart-routing";
+		this.#smartRoutingPanel = new SmartRoutingPanelComponent({
+			setup,
+			tiers,
+			provenance,
+			enabled: this.#settings.get("task.autorouting.enabled") === true,
+			providerOrderHint: this.#providerOrderHintFor(setup.providers),
+			readOnly: this.#smartRoutingReadOnly(),
+			stale: this.#smartRoutingIsStale(),
+			preview,
+			generatePreview: draft => this.#smartRoutingPreview(draft),
+			onSelect: async intent => {
+				await this.#onSelectCallback({ kind: "smartRouting", intent });
+				return intent.kind === "apply" ? this.#smartRoutingPreview(intent.draft) : undefined;
+			},
+			onCancel: () => (this.#smartRoutingOnly ? this.#onCancelCallback() : this.#switchToPresetMode()),
+		});
+		this.#headerContainer.clear();
+		this.#headerContainer.addChild(new Text(theme.fg("accent", "Smart routing"), 0, 0));
+		this.#tabBar = null;
+		this.#listContainer.clear();
+		this.#listContainer.addChild(this.#smartRoutingPanel);
+		this.#tui.requestRender();
+	}
+
+	#switchToPresetMode(): void {
+		this.#smartRoutingPanel = undefined;
+		this.#viewMode = "presets";
+		this.#presetCursor = Math.min(this.#presetCursor, Math.max(0, this.#getPresetRows().length - 1));
+		this.#renderPresetLanding();
+		this.#tui.requestRender();
+	}
+
+	refreshSmartRoutingState(): void {
+		const panel = this.#smartRoutingPanel;
+		if (!panel || this.#viewMode !== "smart-routing") return;
+		const setup = this.#smartRoutingSetup();
+		const preview = this.#smartRoutingPreview(setup);
+		panel.refreshState({
+			setup,
+			tiers: normalizeTierMap(this.#settings.get("task.autorouting.tiers")),
+			provenance: this.#settings.get("task.autorouting.provenance"),
+			enabled: this.#settings.get("task.autorouting.enabled") === true,
+			providerOrderHint: this.#providerOrderHintFor(setup.providers),
+			stale: this.#smartRoutingIsStale(),
+			preview,
+		});
+		this.#tui.requestRender();
+	}
+
 	#renderPresetLanding(): void {
 		this.#headerContainer.clear();
 		this.#tabBar = null;
@@ -1531,6 +1710,12 @@ export class ModelSelectorComponent extends Container {
 			const row = rows[i];
 			const selected = i === this.#presetCursor;
 			const prefix = selected ? theme.fg("accent", `${theme.nav.cursor} `) : "  ";
+			if (row.kind === "smartRouting") {
+				const stale = this.#smartRoutingIsStale();
+				const label = stale ? "Smart routing (stale)" : "Smart routing setup";
+				this.#listContainer.addChild(new Text(`${prefix}${selected ? theme.fg("accent", label) : label}`, 0, 0));
+				continue;
+			}
 			if (row.kind === "create") {
 				const label = "Create custom preset";
 				this.#listContainer.addChild(new Text(`${prefix}${selected ? theme.fg("accent", label) : label}`, 0, 0));
@@ -1921,6 +2106,10 @@ export class ModelSelectorComponent extends Container {
 	}
 
 	handleInput(keyData: string): void {
+		if (this.#viewMode === "smart-routing") {
+			this.#smartRoutingPanel?.handleInput(keyData);
+			return;
+		}
 		if (this.#assignmentState === "assigning") {
 			if (getKeybindings().matches(keyData, "tui.select.cancel")) {
 				this.#closeAfterAssignment = true;
@@ -2106,6 +2295,10 @@ export class ModelSelectorComponent extends Container {
 		}
 		const row = this.#getSelectedPresetRow();
 		if (!row) return;
+		if (row.kind === "smartRouting") {
+			this.#enterSmartRoutingMode();
+			return;
+		}
 		if (row.kind === "create") {
 			this.#onSelectCallback({ kind: "createProfile", profile: this.#buildCustomModelProfileSnapshot() });
 			return;
@@ -2431,6 +2624,16 @@ export class ModelSelectorComponent extends Container {
 		const row = this.#getSelectedPresetRow();
 		return row ? presetRowIdentity(row) : undefined;
 	}
+	__testGetSmartRoutingPanel(): SmartRoutingPanelComponent | undefined {
+		return this.#smartRoutingPanel;
+	}
+
+	__testViewMode(): ModelSelectorViewMode {
+		return this.#viewMode;
+	}
+	__testOpenSmartRoutingPanel(): void {
+		this.#enterSmartRoutingMode();
+	}
 }
 
 function getSelectableThinkingLevels(model: Model): ThinkingLevel[] {

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

@@ -146,15 +146,15 @@ export class OAuthSelectorComponent extends Container {
 			this.#authStorage.hasRuntimeApiKey(provider) ||
 			this.#authStorage.hasConfigApiKey(provider) ||
 			Boolean(getEnvApiKey(provider));
-		const rows = inventory.filter(row => this.#mode === "login" || row.credentialKind === "oauth");
+		const rows = this.#mode === "logout" ? inventory : inventory.filter(row => 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)),
+				this.#mode === "login"
+					? row.credentialKind === "oauth" && !apiKeyOverrideActive && !row.disabled
+					: targets.has(row.id),
 		}));
 		if (this.#mode === "login") {
 			this.#accountEntries.push(
@@ -441,8 +441,8 @@ export class OAuthSelectorComponent extends Container {
 			this.#statusMessage = undefined;
 			this.stopValidation();
 			if (selected.kind === "account") {
-				if (selected.row.credentialKind !== "oauth") return;
 				if (this.#mode === "login") {
+					if (selected.row.credentialKind !== "oauth") return;
 					void this.#onAccountSelect?.({ kind: "id", value: String(selected.row.id) });
 				} else if (selected.target) {
 					this.#confirmOrArmAccountRemoval([selected.target], "Remove this account?");

package/src/modes/components/skill-hud/render.ts

@@ -1,28 +1,24 @@
+import { truncateToWidth, visibleWidth } from "@gajae-code/tui";
 import {
 	collapsePlanningPipeline,
 	type SkillActiveEntry,
 	type WorkflowHudChip,
 } from "../../../skill-state/active-state";
 import { workflowReceiptStatus } from "../../../skill-state/workflow-state-contract";
+import { theme } from "../../theme/theme";
 
-const ANSI_RESET_FG = "\x1b[39m";
-const ANSI_RESET_BOLD = "\x1b[22m";
-const ANSI_BORDER = "\x1b[90m";
-const ANSI_ACCENT = "\x1b[36m";
-const ANSI_DIM = "\x1b[2m";
-const ANSI_BOLD = "\x1b[1m";
 const ANSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const MAX_HUD_ROWS = 2;
 
-function visibleWidth(text: string): number {
-	return text.replace(ANSI_PATTERN, "").length;
+type WidthTier = "wide" | "medium" | "tight";
+type HudToken = { text: string; mandatory: boolean; startsEntry?: boolean; reserveAfter?: number };
+
+function color(role: "border" | "accent" | "dim" | "muted" | "warning" | "error", text: string): string {
+	return theme?.fg(role, text) ?? text;
 }
 
-function truncateToWidth(text: string, maxWidth: number): string {
-	if (maxWidth <= 0) return "";
-	if (visibleWidth(text) <= maxWidth) return text;
-	const plain = text.replace(ANSI_PATTERN, "");
-	if (maxWidth === 1) return "…";
-	return `${plain.slice(0, maxWidth - 1)}…`;
+function statusSymbol(kind: "warning" | "error"): string {
+	return theme?.status[kind] ?? (kind === "error" ? "[!!]" : "[!]");
 }
 
 function sanitizeHudPart(value: string | undefined): string {
@@ -40,10 +36,21 @@ function compareChips(a: WorkflowHudChip, b: WorkflowHudChip): number {
 	return (a.priority ?? 50) - (b.priority ?? 50) || a.label.localeCompare(b.label);
 }
 
-function chipPrefix(chip: WorkflowHudChip): string {
-	if (chip.severity === "error") return "!";
-	if (chip.severity === "blocked") return "block";
-	if (chip.severity === "warning") return "warn";
+function tierForWidth(width: number): WidthTier {
+	return width >= 100 ? "wide" : width >= 60 ? "medium" : "tight";
+}
+
+function severityOf(chip: WorkflowHudChip): "error" | "warning" | undefined {
+	return chip.severity === "error" || chip.severity === "blocked"
+		? "error"
+		: chip.severity === "warning"
+			? "warning"
+			: undefined;
+}
+
+function severityGlyph(severity: WorkflowHudChip["severity"]): string {
+	if (severity === "error" || severity === "blocked") return color("error", statusSymbol("error"));
+	if (severity === "warning") return color("warning", statusSymbol("warning"));
 	return "";
 }
 
@@ -52,32 +59,163 @@ function formatChip(chip: WorkflowHudChip): string | null {
 	const value = sanitizeHudPart(chip.value);
 	if (!label) return null;
 	const body = value ? `${label}=${value}` : label;
-	const prefix = chipPrefix(chip);
-	return prefix ? `${prefix}:${body}` : body;
+	const role = severityOf(chip);
+	return role ? color(role, body) : color("dim", body);
 }
 
-function formatEntry(entry: SkillActiveEntry): string {
+function keyMetricChip(skill: string, chips: readonly WorkflowHudChip[]): WorkflowHudChip | undefined {
+	const preferredBySkill: Record<string, readonly string[]> = {
+		"deep-interview": ["ambiguity"],
+		ralplan: ["iter", "round", "stage"],
+		ultragoal: ["goals", "current"],
+		autoresearch: ["exp", "experiments"],
+	};
+	const preferred = preferredBySkill[skill] ?? [];
+	return (
+		preferred.map(label => chips.find(chip => chip.label === label && !severityOf(chip))).find(Boolean) ??
+		chips.find(chip => !severityOf(chip))
+	);
+}
+
+function buildEntryTokens(entry: SkillActiveEntry, tier: WidthTier, width: number): HudToken[] {
 	const skill = sanitizeHudPart(entry.skill);
 	const phase = sanitizeHudPart(entry.phase);
 	const base = phase ? `${skill}:${phase}` : skill;
-	const chips = [...(entry.hud?.chips ?? [])]
-		.sort(compareChips)
-		.map(formatChip)
-		.filter((chip): chip is string => Boolean(chip));
-	if (entry.stale === true) chips.unshift("warn:stale");
-	const receiptStatus = workflowReceiptStatus(entry.receipt);
-	if (receiptStatus === "stale") chips.unshift("warn:receipt=stale");
-	if (receiptStatus === "fresh") chips.push("receipt=fresh");
+	const chips = [...(entry.hud?.chips ?? [])].sort(compareChips);
+	if (entry.stale === true) chips.unshift({ label: "stale", priority: 0, severity: "warning" });
+	if (workflowReceiptStatus(entry.receipt) === "stale") {
+		chips.unshift({ label: "receipt", value: "stale", priority: 1, severity: "warning" });
+	}
+
+	const severity =
+		chips.find(chip => chip.severity === "error" || chip.severity === "blocked")?.severity ??
+		chips.find(chip => chip.severity === "warning")?.severity;
+	const glyph = severityGlyph(severity);
+	const baseText = color("accent", tier === "tight" ? skill : base);
+	if (
+		tier === "tight" &&
+		glyph &&
+		visibleWidth(glyph) <= width &&
+		visibleWidth(baseText) + 1 + visibleWidth(glyph) > width
+	) {
+		return [{ text: glyph, mandatory: true, startsEntry: true }];
+	}
+	const tokens: HudToken[] = [
+		{
+			text: baseText,
+			mandatory: true,
+			startsEntry: true,
+			reserveAfter: glyph ? visibleWidth(` ${glyph}`) : 0,
+		},
+	];
+	if (glyph) tokens.push({ text: glyph, mandatory: true });
+
+	if (tier === "medium") {
+		const metric = keyMetricChip(skill, chips);
+		const metricText = metric ? formatChip(metric) : null;
+		if (metricText) tokens.push({ text: metricText, mandatory: false });
+		return tokens;
+	}
+
 	const summary = sanitizeHudPart(entry.hud?.summary);
-	return [base, summary, ...chips].filter(Boolean).join(" ");
+	if (summary) tokens.push({ text: color("muted", summary), mandatory: false });
+	for (const chip of chips) {
+		const formatted = formatChip(chip);
+		if (formatted) tokens.push({ text: formatted, mandatory: false });
+	}
+	return tokens;
+}
+
+function appendOverflowMarker(row: string, width: number, protectedToken?: string): string {
+	if (!row || width <= 0) return row;
+	if (protectedToken) {
+		const tokenIndex = row.lastIndexOf(protectedToken);
+		if (tokenIndex >= 0) {
+			const prefix = row.slice(0, tokenIndex);
+			const tokenWidth = visibleWidth(protectedToken);
+			const plainPrefix = Bun.stripANSI(prefix).trimEnd();
+			const needsMarker = !plainPrefix.endsWith("…");
+			const prefixWidth = Math.max(0, width - tokenWidth - (needsMarker ? 1 : 0));
+			return `${truncateToWidth(prefix, prefixWidth)}${needsMarker ? "…" : ""}${protectedToken}`;
+		}
+	}
+	return truncateToWidth(`${row}…`, width);
 }
 
-export function renderSkillHudBar(entries: readonly SkillActiveEntry[], width: number): string | null {
+/**
+ * Render the HUD as physical rows rather than embedding a newline in one row.
+ * The bottom-pinned TUI layout counts array elements as rows; a newline inside
+ * one element corrupts that accounting and can overwrite the editor.
+ */
+export function renderSkillHudBar(entries: readonly SkillActiveEntry[], width: number): string[] | null {
 	const visible = collapsePlanningPipeline(entries.filter(entry => entry.active !== false));
 	const active = visible.filter(entry => sanitizeHudPart(entry.skill)).sort(compareEntries);
 	if (active.length === 0 || width <= 0) return null;
-	const body = active.map(formatEntry).join(" + ");
-	const prefix = `${ANSI_BORDER}◆${ANSI_RESET_FG} ${ANSI_BOLD}${ANSI_ACCENT}hud${ANSI_RESET_FG}${ANSI_RESET_BOLD} `;
-	const budget = Math.max(1, width - visibleWidth(prefix));
-	return truncateToWidth(`${prefix}${ANSI_DIM}${truncateToWidth(body, budget)}${ANSI_RESET_BOLD}`, width);
+
+	const tier = tierForWidth(width);
+	const rail = color("border", "◆");
+	const separator = color("dim", " + ");
+	const firstPrefix = visibleWidth(rail) + 1 <= width ? `${rail} ` : "";
+	const continuationPrefix = firstPrefix ? " ".repeat(visibleWidth(firstPrefix)) : "";
+	const rows: string[] = [];
+	let row = firstPrefix;
+	let rowIndex = 0;
+	let hasToken = false;
+	let omitted = false;
+	let lastSeverityToken: string | undefined;
+
+	const tryAppend = (token: HudToken, allowTruncate: boolean): boolean => {
+		let joiner = hasToken ? (token.startsEntry ? separator : " ") : "";
+		let available = width - visibleWidth(row) - visibleWidth(joiner);
+		if (!hasToken && visibleWidth(row) > 0 && visibleWidth(token.text) > available) {
+			row = "";
+			joiner = "";
+			available = width;
+		}
+		if (available <= 0) return false;
+		const textAvailable = Math.max(0, available - (allowTruncate ? (token.reserveAfter ?? 0) : 0));
+		const text =
+			visibleWidth(token.text) <= textAvailable
+				? token.text
+				: allowTruncate
+					? truncateToWidth(token.text, textAvailable)
+					: "";
+		if (!text || visibleWidth(text) <= 0) return false;
+		row = `${row}${joiner}${text}`;
+		hasToken = true;
+		return true;
+	};
+
+	const startNextRow = (): boolean => {
+		if (rowIndex >= MAX_HUD_ROWS - 1) return false;
+		if (hasToken) rows.push(truncateToWidth(row, width));
+		rowIndex += 1;
+		row = continuationPrefix;
+		hasToken = false;
+		return true;
+	};
+
+	for (const entry of active) {
+		for (const token of buildEntryTokens(entry, tier, width)) {
+			const append = (allowTruncate: boolean): boolean => {
+				const appended = tryAppend(token, allowTruncate);
+				if (appended && token.mandatory && !token.startsEntry) lastSeverityToken = token.text;
+				return appended;
+			};
+			if (append(false)) continue;
+			if (startNextRow() && append(false)) continue;
+			if (append(true)) continue;
+			if (token.mandatory && startNextRow() && append(true)) continue;
+			omitted = true;
+			break;
+		}
+		if (omitted) break;
+	}
+
+	if (hasToken) rows.push(truncateToWidth(row, width));
+	if (omitted && rows.length > 0) {
+		const last = rows.length - 1;
+		rows[last] = appendOverflowMarker(rows[last] ?? "", width, lastSeverityToken);
+	}
+	return rows.length > 0 ? rows.slice(0, MAX_HUD_ROWS) : null;
 }