magus-cli 0.0.0-placeholder → 7.0.0

package/src/ui/renderers/modelRenderers.tsx

@@ -0,0 +1,1309 @@
+import type React from "react";
+import { WORKFLOWS } from "../../data/models-presets.js";
+import {
+	type CatalogModel,
+	stalenessNote,
+	unknownBindings,
+} from "../../services/mate-catalog.js";
+import {
+	type Effort,
+	GRADES,
+	MATES,
+	type ModelsConfig,
+	type ModelsState,
+	type ModelsStatus,
+	boundModel,
+	mateEffort,
+	matesInUse,
+	modelLabel,
+} from "../../services/models-core.js";
+import type {
+	ModelsBrowserItem,
+	ModelsPresetItem,
+	ModelsStatusItem,
+} from "../adapters/modelsAdapter.js";
+import {
+	DetailSection,
+	KeyValueLine,
+	ListCategoryRow,
+	MetaText,
+	SelectableRow,
+} from "../components/primitives/index.js";
+import { effortInk, trackFill } from "../theme-mode.js";
+import { type UiColor, theme } from "../theme.js";
+import {
+	type AgentRow,
+	type AgentTableLayout,
+	BarRow,
+	EffortGlyph,
+	ModelBadge,
+	ModelText,
+	NONE_CELL,
+	PRESET_MARKERS,
+	type PresetRowInput,
+	type PresetRowLayout,
+	agentDistribution,
+	agentRows,
+	agentTableHeaders,
+	barSegments,
+	clipCell,
+	effortLabel,
+	effortWord,
+	fitAgentTable,
+	fitModelKey,
+	fitPresetRows,
+	modelPad,
+	modelWidth,
+	padCell,
+	presetMarkerWidth,
+	workflowDistribution,
+} from "./modelVisuals.js";
+import { wrapText } from "./styleRenderers.js";
+
+// ─── State vocabulary ─────────────────────────────────────────────────────────
+
+/**
+ * One sentence per state, and each says what is HAPPENING, not what the field
+ * is called. "unhooked" on its own is a word nobody can act on; "the config is
+ * here, but no hook runs it" names the missing piece.
+ *
+ * The state WORD is not repeated here — it is drawn as a badge beside the
+ * sentence, which is the shape a discrete status wants and which also keeps an
+ * ambiguous-width glyph out of a line whose width has to be exact.
+ */
+const STATE_HEADLINE: Record<ModelsState, string> = {
+	off: "no .claude/models.json, so every subagent inherits the session model",
+	on: "every Agent call is routed through this config",
+	invalid: "the config does not validate, and nothing is routed",
+	unhooked: "the config is here, but no hook runs it, so nothing is routed",
+};
+
+const STATE_TONE: Record<ModelsState, UiColor> = {
+	off: theme.colors.muted,
+	on: theme.colors.success,
+	invalid: theme.colors.danger,
+	unhooked: theme.colors.danger,
+};
+
+/** Badge tone for the header row. `unhooked` is red with `invalid`: both route nothing. */
+const STATE_CATEGORY: Record<ModelsState, "gray" | "green" | "yellow" | "red"> =
+	{
+		off: "gray",
+		on: "green",
+		invalid: "red",
+		unhooked: "red",
+	};
+
+/**
+ * How many validation errors to draw before summarising the rest.
+ *
+ * MEASURED on a real config written before the tier rename: 23 errors, each wrapping to two
+ * lines, which filled the whole detail panel and pushed the one useful line — what to press
+ * — off the bottom of the screen. Every error after the first few says the same thing about
+ * a different key, so the list stops being information and becomes a wall.
+ */
+const MAX_DRIFT_LINES = 6;
+
+/** What the user should press next, per state. Empty when there is nothing to fix. */
+const STATE_FIX: Record<ModelsState, string> = {
+	off: "Pick a preset below and press a to start routing.",
+	on: "",
+	invalid:
+		"Fix .claude/models.json by hand, or press a on a preset to overwrite it.",
+	unhooked: "Press a on a preset — applying one registers the hook.",
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * A badge as a `<span>`, for a row that also carries text.
+ *
+ * The ONLY filled block this screen still paints outside the selection and the
+ * distribution bar — a discrete status is exactly what a fill is for, and there
+ * is one of them on screen rather than seventeen.
+ *
+ * Only ever called from inside a `<text>`. A `<span>` with no `<text>` parent
+ * swaps the entire UI for an error page and still exits 0, so this is a rule
+ * the type system cannot enforce and a test cannot see.
+ */
+function Chip({
+	label,
+	tone,
+}: {
+	label: string;
+	tone: keyof typeof theme.category;
+}): React.ReactNode {
+	const colors = theme.category[tone];
+	return (
+		<span bg={colors.bg} fg={colors.fg}>
+			<strong>{` ${label} `}</strong>
+		</span>
+	);
+}
+
+/**
+ * A paragraph, pre-wrapped to the panel.
+ *
+ * OpenTUI folds a long line rather than dropping it, but it folds at the box's
+ * width with no regard for words — so pre-wrapping is what keeps a sentence
+ * breaking between words instead of mid-token.
+ */
+function Wrapped({
+	text,
+	width,
+	tone,
+}: {
+	text: string;
+	width?: number;
+	/** `UiColor`, not `string`: the terminal's own foreground is an RGBA. */
+	tone?: UiColor;
+}): React.ReactNode {
+	return (
+		<box flexDirection="column">
+			{wrapText(text, width ?? 48).map((line, index) => (
+				<text
+					key={`${index}:${line.slice(0, 12)}`}
+					fg={tone ?? theme.colors.muted}
+				>
+					{line || " "}
+				</text>
+			))}
+		</box>
+	);
+}
+
+/**
+ * The state block: what is routed, what drifted, and what to press.
+ *
+ * Rendered above the preset on EVERY row, not only on the header. The question
+ * a reader has while looking at a preset is "is this the one that is running",
+ * and answering it one row away means switching rows to find out.
+ */
+function StateBlock({
+	status,
+	width,
+}: {
+	status: ModelsStatus | null;
+	width?: number;
+}): React.ReactNode {
+	if (!status) {
+		return <text fg={theme.colors.muted}>Reading the routing…</text>;
+	}
+	const fix = STATE_FIX[status.state];
+	const isInvalid = status.state === "invalid";
+	return (
+		<box flexDirection="column">
+			<text fg={theme.colors.text}>
+				<Chip label={status.state} tone={STATE_CATEGORY[status.state]} />
+			</text>
+			<Wrapped
+				text={STATE_HEADLINE[status.state]}
+				width={width}
+				tone={STATE_TONE[status.state]}
+			/>
+			{status.drift.length > 0 ? (
+				<box flexDirection="column" marginTop={1}>
+					<text fg={theme.colors.text}>
+						<Chip
+							label={`${isInvalid ? "errors" : "drift"} ${status.drift.length}`}
+							tone={isInvalid ? "red" : "yellow"}
+						/>
+					</text>
+					{status.drift.slice(0, MAX_DRIFT_LINES).map((line) => (
+						<Wrapped
+							key={line}
+							text={line}
+							width={width}
+							tone={isInvalid ? theme.colors.danger : theme.colors.warning}
+						/>
+					))}
+					{status.drift.length > MAX_DRIFT_LINES ? (
+						// `Wrapped`, not `MetaText`: MetaText returns a bare <span>, and a <span>
+						// with no <text> parent swaps the whole UI for an error page while still
+						// exiting 0. Typecheck and every unit test pass; only running it shows it.
+						<Wrapped
+							text={`…and ${status.drift.length - MAX_DRIFT_LINES} more — run magus models status`}
+							width={width}
+						/>
+					) : null}
+				</box>
+			) : null}
+			{status.warnings.length > 0 ? (
+				<box flexDirection="column" marginTop={1}>
+					<text fg={theme.colors.text}>
+						<Chip label={`warnings ${status.warnings.length}`} tone="yellow" />
+					</text>
+					{status.warnings.map((line) => (
+						<Wrapped
+							key={line}
+							text={line}
+							width={width}
+							tone={theme.colors.warning}
+						/>
+					))}
+				</box>
+			) : null}
+			{fix ? (
+				<box marginTop={1}>
+					<Wrapped text={fix} width={width} />
+				</box>
+			) : null}
+		</box>
+	);
+}
+
+// ─── The grade table ──────────────────────────────────────────────────────────
+
+/** Gutter for the row label, matching `KeyValueLine` so the columns line up. */
+const SPEC_LABEL_WIDTH = 10;
+
+/**
+ * The widest model column in a config, so every name in the table ends at the
+ * same column and the effort glyphs beside them form a straight edge.
+ *
+ * `withMates` is not a detail: measuring without the mate rows while DRAWING them leaves
+ * `modelPad` returning an empty string for those rows and the whole effort column jumps left
+ * on them. The flag is the same boolean that decides whether the rows are drawn at all,
+ * passed in rather than re-derived, because the two answers have to be the same answer.
+ *
+ * Measured from what each row WRITES, via `modelLabel`. It used to measure `MATES` themselves
+ * on the reasoning that `kangaroo` (8) was the widest thing the column could hold. A bound
+ * slot writes its catalogue id instead — up to 21 cells — so measuring the slot names now
+ * under-counts by more than the column is wide. An unbound slot writes `unset` (5).
+ */
+export function specModelColumn(
+	config: ModelsConfig,
+	withMates: boolean,
+): number {
+	return Math.max(
+		modelWidth(config.main.model),
+		...GRADES.map((grade) =>
+			modelWidth(modelLabel(config, config.grades[grade].model)),
+		),
+		...(withMates
+			? MATES.map((mate) => modelWidth(modelLabel(config, mate)))
+			: []),
+	);
+}
+
+/**
+ * One line of the grade table: `critical  fable   ▇ xhigh`.
+ *
+ * Effort is a bounded ordinal — four named levels, ordered — so it gets a ramp
+ * glyph and the word, rather than being parenthesised after the model name
+ * where its ordering is invisible. The glyph takes the MODEL's hue, so shape
+ * carries the level and colour still carries only one thing.
+ */
+function SpecRow({
+	label,
+	model,
+	modelText,
+	effort,
+	modelColumn,
+	highlight,
+}: {
+	label: string;
+	/** The routing value — decides the chip's INK. For a mate this is the slot. */
+	model: string;
+	/** What the chip WRITES. Defaults to `model`; a bound mate passes its catalogue id. */
+	modelText?: string;
+	effort: Effort | undefined;
+	modelColumn: number;
+	/** The grade an unassigned agent falls to — worth reading first. */
+	highlight?: boolean;
+}): React.ReactNode {
+	const text = modelText ?? model;
+	// The word takes the effort ramp whenever there is a level to name, a mate's included:
+	// claudish applies an external model's effort per run, so it is as live as a Claude
+	// subagent's. Only the absent case is muted, and it names a fallback rather than a level.
+	const live = effort !== undefined;
+	return (
+		<text fg={theme.colors.text}>
+			<span fg={highlight ? theme.colors.text : theme.colors.muted}>
+				{`${label} `.padEnd(SPEC_LABEL_WIDTH)}
+			</span>
+			{/* A CHIP here, text in the agent table below. Four of them read as a key;
+			    seventeen read as a solid column, which is what this screen was reported for.
+			    The chip's ink is the SLOT's and its text is the bound model: the slot is the
+			    stable identity, the binding is what changes. */}
+			<ModelBadge model={model} label={text} />
+			<span fg={theme.colors.border}>{`${modelPad(text, modelColumn)}  `}</span>
+			<EffortGlyph effort={effort} />
+			{/* `model` reaches `effortWord` so a mate row says `via claudish` (unbound effort)
+			    or `high (declared)` where a Claude model would say `inherits session`. Nothing
+			    of the session reaches an external model, so the second sentence would simply
+			    be untrue on those rows. */}
+			<span
+				fg={
+					live ? (effortInk(effort as string) as UiColor) : theme.colors.muted
+				}
+			>{` ${effortWord(effort, model)}`}</span>
+		</text>
+	);
+}
+
+// ─── Agent table ──────────────────────────────────────────────────────────────
+
+/**
+ * Every agent, one row, four aligned columns — and NOT ONE FILLED BLOCK.
+ *
+ * This replaced a paragraph of grouped names with a "+4 more" on the end. The
+ * question a reader brings is "what does MY agent get", and a sampled list
+ * cannot answer it; the detail pane scrolls (`^U/^D`, `PgUp/PgDn`), so the only
+ * real constraint is width, and `fitAgentTable` spends that in a fixed order
+ * rather than wrapping a cell.
+ *
+ * The model was a filled chip and the effort a filled four-cell meter. MEASURED
+ * on both a light and a dark terminal, seventeen such rows stacked into two
+ * solid vertical colour columns — two painted bars the height of the table,
+ * which read as slabs rather than as data. Coloured TEXT plus one ramp glyph
+ * says the same thing and leaves a table you can scan a column of.
+ *
+ * Colour stays on the model: the name and the glyph carry it, the agent name
+ * does not. A name is an identifier — colouring it made six agent names six
+ * different hues, with red (which means danger everywhere else here) landing on
+ * `dev:debugger` for no reason at all.
+ */
+function AgentTable({
+	config,
+	width,
+}: {
+	config: ModelsConfig;
+	width: number;
+}): React.ReactNode {
+	const rows = agentRows(config);
+	if (rows.length === 0) return null;
+	const layout = fitAgentTable(rows, width);
+	const headers = agentTableHeaders(layout);
+
+	return (
+		<box flexDirection="column">
+			<text fg={theme.colors.muted}>
+				{headers.map((cell, index) => (
+					<span key={cell.key} fg={theme.colors.muted}>
+						{index > 0 ? ` ${cell.text}` : cell.text}
+					</span>
+				))}
+			</text>
+			{rows.map((row) => (
+				<AgentTableRow key={row.name} row={row} layout={layout} />
+			))}
+		</box>
+	);
+}
+
+function AgentTableRow({
+	row,
+	layout,
+}: {
+	row: AgentRow;
+	layout: AgentTableLayout;
+}): React.ReactNode {
+	// `row.model` goes in so a mate row reads `— via claudish` rather than the
+	// `— inherits session` a Claude model with no effort gets. The two say opposite things:
+	// one inherits the session's effort, the other never sees the session at all.
+	const label = effortLabel(row.effort, layout.effort, row.model);
+	// Truncated HERE as well as fitted in `fitAgentTable`, because the two do different jobs:
+	// the fit decides how wide the column is, this decides what fits in it. The model cell is
+	// drawn as coloured text plus a separate pad span, so it cannot use `padCell` — and
+	// without a clip a 21-cell binding would simply overrun the column the fit just sized.
+	const modelText = clipCell(row.label, layout.model);
+	// Muted only when there is no level to name. Same rule as `SpecRow`, so the tier table
+	// and the agent table cannot end up grading the same effort differently.
+	const live = row.effort !== undefined;
+	return (
+		<text fg={theme.colors.text}>
+			<span fg={row.inherit ? theme.colors.dim : theme.colors.text}>
+				{padCell(row.name, layout.name)}
+			</span>
+			<span fg={theme.colors.border}> </span>
+			{layout.grade > 0 ? (
+				<span fg={theme.colors.muted}>{padCell(row.key, layout.grade)}</span>
+			) : null}
+			{layout.grade > 0 ? <span fg={theme.colors.border}> </span> : null}
+			{row.inherit ? (
+				<span fg={theme.colors.dim}>{padCell(NONE_CELL, layout.model)}</span>
+			) : (
+				<ModelText model={row.model} label={modelText} />
+			)}
+			{row.inherit ? null : (
+				<span fg={theme.colors.border}>
+					{modelPad(modelText, layout.model)}
+				</span>
+			)}
+			<span fg={theme.colors.border}> </span>
+			{row.inherit ? (
+				<span fg={theme.colors.dim}>{NONE_CELL}</span>
+			) : (
+				<EffortGlyph effort={row.effort} />
+			)}
+			{/* The word takes the SAME ink as the dots beside it. Dim grey made the pair read
+			    as two things — a coloured meter and an unrelated caption — when it is one
+			    reading with its value spelt out.
+
+			    With NO effort there are no lit dots to match, so the word takes the muted ink
+			    the dash already uses — which is what `SpecRow` does in the tier table above.
+			    It used to fall back to `effortInk("low")`, painting `inherits session` (and
+			    now `via claudish`) in the colour that means the lowest effort level: a value
+			    where an absence belongs. */}
+			{!row.inherit && label ? (
+				<span
+					fg={
+						live
+							? (effortInk(row.effort as string) as UiColor)
+							: theme.colors.muted
+					}
+				>{` ${label}`}</span>
+			) : null}
+		</text>
+	);
+}
+
+/**
+ * What labels the second row of a workflow's pair.
+ *
+ * NOT indented. It used to be `"  subagents"`, two cells in from the workflow name above it,
+ * on the reasoning that an indent says "these belong to that". Reported off a real screen:
+ * "on left dev and subagents wrongly aligned" — with six labels stacked down the panel, two
+ * different starting columns read as raggedness long before they read as hierarchy.
+ *
+ * The grouping is now said by the blank line BETWEEN workflows instead, which is a stronger
+ * signal and costs the labels nothing.
+ */
+export const SUBAGENT_ROW_LABEL = "subagents";
+
+/** Rows one workflow costs: its main thread, then everything it dispatches. */
+export const WORKFLOW_ROWS = 2;
+
+/** The blank row before every workflow except the first. See `AgentSpread`. */
+export const WORKFLOW_GAP_ROWS = 1;
+
+/**
+ * The label gutter, shared by both rows of every pair, and LEFT-aligned within it.
+ *
+ * Left rather than right: right-aligning would square the labels up against the bars and
+ * leave the outer edge ragged, and the outer edge is the one the eye runs down when it is
+ * scanning six labels for the workflow it wants. One straight left edge, one straight bar
+ * edge — the ragged part lands in the middle, where nothing is being compared.
+ *
+ * Derived from the longest label actually DRAWN, never a constant: `investigate` (11) is the
+ * longest today and `subagents` (9) is in the running, and a hardcoded 11 would silently
+ * clip the first workflow anyone adds with a longer name. The `+ 1` is the gap before the
+ * bar starts.
+ *
+ * Exported because a test measuring the bar has to start counting at the same column the
+ * renderer stops writing at, and a second copy of this expression is a test that keeps
+ * passing while the picture drifts.
+ */
+export const SPREAD_LABEL_CELLS =
+	Math.max(SUBAGENT_ROW_LABEL.length, ...WORKFLOWS.map((w) => w.name.length)) +
+	1;
+
+/**
+ * How the routed agents are spread, two rows per workflow.
+ *
+ * A category distribution, so a stacked bar rather than the list of counts it
+ * would otherwise be — and now the ONLY graphic on the screen, which is what
+ * lets it be saturated without competing with anything. It lives UNDER THE
+ * PRESET LIST, not in the detail pane, because a distribution is most useful
+ * exactly where you are choosing between presets. It follows the cursor, so
+ * moving between presets redraws it.
+ *
+ * ## Why the halves are gone
+ *
+ * One bar per workflow used to be split down the middle: `main` on the left, everything it
+ * dispatches crammed into the right. The shape was honest about the trade — the orchestrator
+ * against the work it hands out — and dishonest about the second half, which had to hold
+ * four or five segments in half a pane. At the widths this panel actually gets, the third
+ * and fourth subagent tiers were a cell or two each and nothing could be labelled.
+ *
+ * So the trade is now a PAIR OF ROWS, each across the full width. The main thread's row is
+ * one segment and reads instantly; the subagent row gets twice the cells it had, which is
+ * what makes an inline label possible at all. The caption that used to name the two halves
+ * is gone with them — `SUBAGENT_ROW_LABEL` says which row is which, on the row itself,
+ * where a caption under a chart never could.
+ *
+ * ## The blank line between workflows is what makes the pairs pairs
+ *
+ * Six adjacent rows is one block of six, not three blocks of two: `dev`'s subagent row and
+ * `debug`'s main row touched, so the pairing had to be worked out from the labels rather
+ * than seen. A blank row goes BETWEEN groups and never inside one — the two rows of a
+ * workflow stay adjacent precisely because their adjacency is the thing that says they
+ * belong together. None after the last group either: a trailing gap is a row spent
+ * separating the chart from nothing.
+ */
+export function AgentSpread({
+	config,
+	width,
+}: {
+	config: ModelsConfig;
+	width: number;
+}): React.ReactNode {
+	// One pair of bars per WORKFLOW, not one bar for every agent that exists.
+	//
+	// Nobody runs all seventeen agents; they run `/dev:dev`, `/dev:debug` or
+	// `/dev:investigate`, and each reaches for a different handful. A single lump-sum bar
+	// answered a question nobody asks and hid the one they do: what does THIS command cost
+	// under THIS preset.
+	const label = SPREAD_LABEL_CELLS;
+
+	return (
+		<box flexDirection="column" marginTop={1} width={width}>
+			{/*
+			 * The header is the WORD `workflow` and nothing else.
+			 *
+			 * It used to carry `▓ external model, via claudish` right-aligned beside it, and
+			 * that sentence was on screen three times at once: here, in the detail pane's own
+			 * paragraph about mates, and — in colour — as the key's chips under the chart.
+			 * Reported directly: "why do we have on top of diagram 'external models via
+			 * claudish' if we already have this described in the right and in the bottom".
+			 *
+			 * The weave stays; it is now explained by the `mates` chips in the key below,
+			 * which name the slots AND their bound models rather than restating the category.
+			 *
+			 * It cost no row — the note was right-aligned INSIDE this height-1 header — so
+			 * `SUMMARY_COST.spread` and `planModelsSummary` are untouched by its removal.
+			 */}
+			<box flexDirection="row" width={width} height={1}>
+				<text fg={theme.colors.muted}>workflow</text>
+			</box>
+			{WORKFLOWS.map((workflow, index) => (
+				<box
+					key={workflow.name}
+					flexDirection="column"
+					width={width}
+					// The separator, and it belongs to the group BELOW it rather than above:
+					// hung off the first group instead, the last one would carry a trailing
+					// blank row that separates the chart from nothing.
+					marginTop={index > 0 ? WORKFLOW_GAP_ROWS : 0}
+				>
+					<box flexDirection="row" width={width} height={1}>
+						<text fg={theme.colors.muted} flexShrink={0}>
+							{padCell(workflow.name, label)}
+						</text>
+						{/* The main thread is one segment across the full width — a share of one,
+						    because a row with a single segment has nothing to be a share OF. */}
+						<BarRow
+							segments={[{ id: "main", model: config.main.model, share: 1 }]}
+						/>
+					</box>
+					<box flexDirection="row" width={width} height={1}>
+						<text fg={theme.colors.muted} flexShrink={0}>
+							{padCell(SUBAGENT_ROW_LABEL, label)}
+						</text>
+						{/* `barSegments` is what folds every mate-routed agent into ONE run —
+						    the bar answers how much of this workflow leaves Claude Code, and
+						    that is one number however many slots it is spread across. The
+						    slots come back, with their bindings, in the key below. */}
+						{/* The external phases come from the WORKFLOW, not the config, so the run
+						    is drawn under every preset — a workflow calls out because its
+						    command says so, not because of the routing applied to it. */}
+						<BarRow
+							segments={barSegments(
+								workflowDistribution(
+									config,
+									workflow.agents,
+									workflow.external.length,
+								),
+							)}
+						/>
+					</box>
+				</box>
+			))}
+		</box>
+	);
+}
+
+// ─── Status renderer ──────────────────────────────────────────────────────────
+
+/**
+ * Deliberately NOT an `ItemRenderer`.
+ *
+ * Its detail needs the drift lines and warnings, which the item does not carry —
+ * they belong to the project rather than to a row, and copying them onto the
+ * item is how the two would end up disagreeing. So the row reads the item and
+ * the detail reads the status, and neither pretends to be the other.
+ */
+function renderStatusRow(
+	item: ModelsStatusItem,
+	isSelected: boolean,
+): React.ReactNode {
+	// NEITHER the file's `preset` string NOR a drift count.
+	//
+	// The string records what was last applied, so a config edited afterwards shows a
+	// built-in's name while not being that built-in — which is why the row for a diverged
+	// config is called `Custom` and reads nothing from the file.
+	//
+	// The drift count was a count of MESSAGES, not of differences, and one of those messages
+	// is "settings carry none of the config". `1 drift` therefore read as one small thing
+	// while meaning nothing is in force — a number that misleads is worse than no number.
+	const parts = [
+		item.warningCount > 0
+			? `${item.warningCount} warning${item.warningCount === 1 ? "" : "s"}`
+			: null,
+	].filter((part): part is string => part !== null);
+
+	return (
+		<ListCategoryRow
+			selected={isSelected}
+			title={`Model tiers: ${item.state}`}
+			badge={parts.length > 0 ? parts.join(" · ") : undefined}
+			tone={STATE_CATEGORY[item.state]}
+			// A section label, not a collapsible group — the cursor skips it, so a
+			// ▶ would advertise an interaction that is not there.
+			expandable={false}
+		/>
+	);
+}
+
+function renderStatusDetail(
+	status: ModelsStatus | null,
+	width?: number,
+): React.ReactNode {
+	return (
+		<box flexDirection="column">
+			<text fg={theme.colors.accent}>
+				<strong>Model tiers</strong>
+			</text>
+			<box marginTop={1}>
+				<StateBlock status={status} width={width} />
+			</box>
+			<box marginTop={1}>
+				<Wrapped
+					width={width}
+					text="Tiers say how much model you are spending: smart is the strongest, and deliberately not the orchestrator's. Move down to a preset to see what runs where."
+				/>
+			</box>
+		</box>
+	);
+}
+
+// ─── Preset rows: ONE layout for the whole list ───────────────────────────────
+
+/** A preset row reduced to what the column maths needs. */
+function presetRowInput(item: ModelsPresetItem): PresetRowInput {
+	return {
+		label: item.label,
+		main: item.config.main.model,
+		// Both halves of a mate's identity: the slot colours the text, the bound id IS the
+		// text. Passing only the slot is what printed a role where a model belonged.
+		smart: item.config.grades.smart.model,
+		smartLabel: modelLabel(item.config, item.config.grades.smart.model),
+		markers: presetMarkerWidth(item.isDefault),
+	};
+}
+
+/**
+ * The list's shared column layout, measured ONCE from every row.
+ *
+ * The screen computes this and hands the same object to every row. Rows used to
+ * fit themselves individually, and on a 120×30 terminal that meant the selected
+ * row dropped its `main` / `critical` labels while its three neighbours kept
+ * theirs — the same field labelled on some rows and not others, with nothing
+ * lining up down the column.
+ */
+export function fitPresetList(
+	items: ModelsBrowserItem[],
+	width: number,
+): PresetRowLayout {
+	const rows = items
+		.filter((item): item is ModelsPresetItem => item.kind === "preset")
+		.map(presetRowInput);
+	return fitPresetRows(rows, width);
+}
+
+/**
+ * The two models a row summarises, as spans for ONE `<text>`.
+ *
+ * Coloured text rather than two filled chips: a chip is a painted block, and
+ * two per row down a four-row list is two painted columns. The word already
+ * names the model; the hue only has to tie it to the bar below.
+ */
+function summarySpans(
+	config: ModelsConfig,
+	layout: PresetRowLayout,
+	selected: boolean,
+): React.ReactNode[] {
+	if (layout.detail === "none") return [];
+	const label = selected ? theme.selection.dim : theme.colors.muted;
+	const rule = selected ? theme.selection.dim : theme.colors.border;
+	const main = config.main.model;
+	const smart = config.grades.smart.model;
+	// Clipped to the column `fitPresetRows` capped, with the `…` that marks the cut. The cap
+	// is what stops one long binding dragging the whole list down a rung; the clip is what
+	// makes that cap honest rather than an overrun.
+	const smartText = clipCell(modelLabel(config, smart), layout.smart);
+
+	const parts: React.ReactNode[] = [
+		<span key="gap" fg={rule}>
+			{"  "}
+		</span>,
+	];
+	if (layout.detail === "labelled") {
+		parts.push(
+			<span key="main-label" fg={label}>
+				{"main "}
+			</span>,
+		);
+	}
+	parts.push(<ModelText key="main" model={main} selected={selected} />);
+	parts.push(
+		<span key="main-pad" fg={rule}>
+			{modelPad(main, layout.main)}
+		</span>,
+	);
+	// The narrowest rung that still says anything: one model, no separator to
+	// dangle after it.
+	if (layout.detail === "main") return parts;
+	parts.push(
+		<span key="sep" fg={rule}>
+			{" · "}
+		</span>,
+	);
+	if (layout.detail === "labelled" || layout.detail === "smart") {
+		parts.push(
+			<span key="critical-label" fg={label}>
+				{"smart "}
+			</span>,
+		);
+	}
+	parts.push(
+		<ModelText
+			key="smart"
+			model={smart}
+			label={smartText}
+			selected={selected}
+		/>,
+	);
+	parts.push(
+		<span key="smart-pad" fg={rule}>
+			{modelPad(smartText, layout.smart)}
+		</span>,
+	);
+	return parts;
+}
+
+// ─── Preset renderer ──────────────────────────────────────────────────────────
+
+/**
+ * One preset row, drawn against the layout the whole list shares.
+ *
+ * Deliberately NOT an `ItemRenderer.renderRow`: that signature takes a width
+ * and nothing else, so a renderer wearing it can only fit itself — which is
+ * precisely the defect this row was reported for. The layout is an argument.
+ */
+function renderPresetRow(
+	item: ModelsPresetItem,
+	isSelected: boolean,
+	layout: PresetRowLayout,
+): React.ReactNode {
+	// A NAME and its markers, nothing else.
+	//
+	// The row used to carry `[●]` plus `opus · smart fable` — a checkbox and a two-model
+	// summary of what the detail pane is already showing in full, three lines to the right.
+	// Repeating it made the list the same width as the detail and twice as busy, and the
+	// checkbox competed with the cursor for "which one is this". The cursor marks where you
+	// are; `●` marks what is running; the detail says what it does.
+	return (
+		<SelectableRow selected={isSelected} indent={1}>
+			<span
+				fg={isSelected ? theme.selection.fg : theme.colors.success}
+			>{`${item.active ? "●" : " "} `}</span>
+			<span fg={isSelected ? theme.selection.fg : theme.colors.text}>
+				{padCell(item.label, layout.name)}
+			</span>
+			{item.isDefault ? (
+				<MetaText text={PRESET_MARKERS.default} selected={isSelected} />
+			) : null}
+		</SelectableRow>
+	);
+}
+
+function renderPresetDetail(
+	item: ModelsPresetItem,
+	width: number | undefined,
+	/** Is `multimodel@magus` installed — i.e. is there anything to serve a mate? */
+	matesAvailable: boolean,
+	/** The live catalogue, or [] when it could not be read. ADVISORY ONLY. */
+	catalog: CatalogModel[],
+): React.ReactNode {
+	const { config } = item;
+	const modelColumn = specModelColumn(config, matesAvailable);
+	const barWidth = Math.max(8, width ?? 48);
+
+	// Slots that carry an effort. Named rather than counted, so the caveat below says WHICH
+	// rows it is about — with three slots on screen, "one of these is not applied" would
+	// leave the reader checking all three.
+	const declaredEfforts = MATES.filter(
+		(mate) => mateEffort(config, mate) !== undefined,
+	);
+	// Only the bindings this config actually ROUTES to. A slot bound in the `mates` block but
+	// assigned to no agent is dead weight, and warning that a model nothing uses may have
+	// been retired is noise about a decision with no consequences.
+	const bound = matesInUse(config)
+		.map((mate) => boundModel(config, mate))
+		.filter((id): id is string => id !== null);
+	const staleNote = stalenessNote(unknownBindings(bound, catalog));
+
+	return (
+		<box flexDirection="column">
+			<text fg={theme.colors.accent}>
+				<strong>{item.label}</strong>
+			</text>
+
+			{/*
+			 * `Active` / `Default` / `Source` used to be three key-value lines here, and they
+			 * are gone. Every one of them is already answered a few characters to the left:
+			 * the active preset carries `●` in the list, the default carries `(default)`, and
+			 * a hand-edited config carries its own marker. Restating them as sentences pushed
+			 * the tier table — the thing you opened this pane to read — below the fold.
+			 *
+			 * `item.custom` keeps its warning, because THAT one is not on the row: it changes
+			 * what applying does.
+			 */}
+			{item.custom ? (
+				<box marginTop={1}>
+					<Wrapped
+						width={width}
+						tone={theme.colors.warning}
+						text="This project's own config, not a built-in — applying re-writes the settings it implies."
+					/>
+				</box>
+			) : null}
+
+			<DetailSection title="Models">
+				<box flexDirection="column">
+					<text fg={theme.colors.muted}>
+						{`${padCell("tier", SPEC_LABEL_WIDTH)}${padCell("model", modelColumn + 4)}effort`}
+					</text>
+					<SpecRow
+						label="main"
+						model={config.main.model}
+						effort={config.main.effort}
+						modelColumn={modelColumn}
+						highlight
+					/>
+					{GRADES.map((grade) => (
+						<SpecRow
+							key={grade}
+							label={grade}
+							model={config.grades[grade].model}
+							// A grade routed to a bound mate writes the model, not the slot.
+							modelText={modelLabel(config, config.grades[grade].model)}
+							effort={config.grades[grade].effort}
+							modelColumn={modelColumn}
+							highlight={grade === config.fallback}
+						/>
+					))}
+					{/*
+					 * The mate slots, drawn only when `multimodel@magus` is installed.
+					 *
+					 * The tier column is the SLOT and the model column is what it is BOUND
+					 * to. Both columns used to carry the same word — the row read
+					 * `mate1  mate1  —` — because a slot was all a config could name. A slot
+					 * is a role; the `mates` block says which model plays it, and that model
+					 * is what belongs under `model`.
+					 *
+					 * An unbound slot writes `unset`, not a blank and not its own name: the
+					 * author decided to route here and has not yet said where, which is a
+					 * different state from the `—` that means nothing was decided at all.
+					 *
+					 * Without the plugin there is nothing to serve these calls, so drawing
+					 * three rows of routing that cannot happen would be an advertisement
+					 * rather than a status.
+					 */}
+					{matesAvailable
+						? MATES.map((mate) => (
+								<SpecRow
+									key={mate}
+									label={mate}
+									model={mate}
+									modelText={modelLabel(config, mate)}
+									effort={mateEffort(config, mate)}
+									modelColumn={modelColumn}
+								/>
+							))
+						: null}
+				</box>
+				{matesAvailable ? (
+					<box flexDirection="column" marginTop={1}>
+						<Wrapped
+							width={width}
+							text="A mate is an external model reached through claudish. Bind one in the `mates` block of .claude/models.json, then assign the slot to an agent — magus leaves those calls alone, so claudish decides how they run."
+						/>
+						{/* Where a mate's effort comes from, in the order it is resolved. The
+						    two rules are one sentence because they are one lookup: the slot
+						    answers if it can, the preset answers for the rest. */}
+						<box marginTop={1}>
+							<Wrapped
+								width={width}
+								tone={theme.colors.muted}
+								text="A mate runs at the effort its slot names, or the preset's if it names none. claudish applies it per run, clamped to what the model supports."
+							/>
+						</box>
+						{/*
+						 * The staleness advisory. Absent when the catalogue could not be read
+						 * — `unknownBindings` returns nothing on an empty catalogue, so a
+						 * machine with no claudish sees the pane exactly as before rather
+						 * than every binding flagged as retired.
+						 */}
+						{staleNote ? (
+							<box marginTop={1}>
+								<Wrapped
+									width={width}
+									tone={theme.colors.warning}
+									text={staleNote}
+								/>
+							</box>
+						) : null}
+					</box>
+				) : null}
+			</DetailSection>
+
+			<DetailSection title="Agents">
+				<box flexDirection="column">
+					<AgentTable config={config} width={barWidth} />
+					<box marginTop={1}>
+						<Wrapped
+							width={width}
+							text={`Anything unlisted runs at ${config.fallback}, including agents magus has never seen.`}
+						/>
+					</box>
+				</box>
+			</DetailSection>
+		</box>
+	);
+}
+
+// ─── The list panel's own footer ──────────────────────────────────────────────
+
+/**
+ * A path shortened from the LEFT, keeping the tail.
+ *
+ * `.claude/models.json` is the part that identifies the file; the machine's home
+ * directory in front of it is the part nobody reads. Truncating from the right
+ * would keep exactly the wrong half.
+ */
+export function shortConfigPath(
+	configPath: string,
+	projectPath: string,
+	max: number,
+): string {
+	const base = projectPath.endsWith("/") ? projectPath : `${projectPath}/`;
+	const relative = configPath.startsWith(base)
+		? configPath.slice(base.length)
+		: configPath;
+	if (relative.length <= max) return relative;
+	return `…${relative.slice(relative.length - Math.max(1, max - 1))}`;
+}
+
+/**
+ * The key to every colour on this screen: one model name, in its own hue.
+ *
+ * The bar is coloured by MODEL and labelled by GRADE, so without this row the
+ * hues have no key — a reader can see that two runs differ and not what they
+ * differ into. Names are dropped from the right when the panel is too narrow,
+ * because a key that overflows its panel is worse than a shorter key.
+ *
+ * These were filled chips. A chip here would be the only chip left on the
+ * screen and would teach a vocabulary nothing else uses — every model
+ * everywhere else is now its name in its colour, so the key is too.
+ *
+ * ## It describes the BAR, and only the bar
+ *
+ * This used to be built from `presets.map((preset) => preset.config)` — every selectable row
+ * in the list — while `AgentSpread` above it drew the SELECTED config alone. The two
+ * disagreed exactly when it mattered: a project config binding `dev:qa-engineer` to
+ * `mate1` put `mate1` in the key, the cursor sat on a built-in preset that has no mate, and
+ * the bar could not contain that colour at any width. Reported as "the mate is missing from
+ * the bar", which it was not — the key was naming a colour from a config nobody was looking
+ * at, and sent a reader hunting for a segment that was never going to be there.
+ *
+ * `modelsInUse` still takes an array, because it answers a genuine question about a set of
+ * configs and other callers may want it. `fitModelKey` passes exactly one: the config the
+ * graphic above is drawing.
+ *
+ * ## The mates are named here, and painted in ONE tone
+ *
+ * The bar collapses every mate-routed agent into a single `mates` run, so the slots have to
+ * be recoverable somewhere — and this row is the only part of the screen with room for a
+ * 21-character catalogue id. Each slot in use gets a chip reading `mate1 grok-4.6`.
+ *
+ * All of them wear the FAMILY ink, not their own. The key decodes the chart, the chart has
+ * one mate colour, and a legend showing ochre for `mate1` would name a tone that appears at
+ * no width in the graphic above it — which is this comment's own bug, one level down.
+ */
+function ModelKey({
+	config,
+	width,
+}: {
+	config: ModelsConfig;
+	width: number;
+}): React.ReactNode {
+	const label = "models  ";
+	// A SLOT IS WRITTEN WITH ITS BOUND MODEL here — `mate1 grok-4.6` — and that is the other
+	// half of collapsing the bar's mates into one run. The bar gave up which slot; this is
+	// where it comes back, in the one place on the screen wide enough for a catalogue id.
+	// The fitting, the three rungs and the reason it must not wrap live in `fitModelKey`.
+	// `WORKFLOWS` decides half of it: a preset that binds no slot still draws a mates run for
+	// every workflow with external phases, and a run with no chip under it is a texture the
+	// reader cannot decode.
+	const chips = fitModelKey(
+		config,
+		width,
+		label.length,
+		WORKFLOWS.some((workflow) => workflow.external.length > 0),
+	);
+	if (chips.length === 0) return null;
+
+	const parts: React.ReactNode[] = [
+		<span key="label" fg={theme.colors.muted}>
+			{label}
+		</span>,
+	];
+	chips.forEach((chip, index) => {
+		// No `·` between chips: a fill already separates them, and a separator
+		// between two blocks reads as a third thing.
+		if (index > 0) parts.push(<span key={`gap:${chip.text}`}> </span>);
+		parts.push(
+			<ModelBadge key={chip.text} model={chip.ink} label={chip.text} />,
+		);
+	});
+	return <text fg={theme.colors.text}>{parts}</text>;
+}
+
+/** Which blocks of the list-panel summary fit, and how many rows they cost. */
+export interface SummaryPlan {
+	spread: boolean;
+	key: boolean;
+	facts: boolean;
+	rows: number;
+}
+
+/**
+ * Rows each block costs, its own leading blank line included.
+ *
+ * The spread's cost is DERIVED, not a number typed here. It was `4` while the block drew a
+ * header, one bar per workflow and a caption — six rows including its margin — so the plan
+ * was already two rows short of what it drew, and every workflow added would have widened
+ * the gap silently. It is now the margin, the header, two rows per workflow, and one blank
+ * row between each pair of workflows — all counted from `WORKFLOWS` so the two cannot drift
+ * apart again.
+ *
+ * The separators make the chart two rows taller, and that is not free: at eleven rows — what
+ * an 80×24 terminal leaves under the list — the chart no longer fits and the panel draws
+ * nothing at all. That is the honest reading of the budget rather than a rounding to be
+ * softened: an over-tall block in a fixed-height box overprints, it does not clip.
+ */
+const SUMMARY_COST = {
+	rule: 1,
+	spread:
+		1 +
+		1 +
+		WORKFLOWS.length * WORKFLOW_ROWS +
+		Math.max(0, WORKFLOWS.length - 1) * WORKFLOW_GAP_ROWS,
+	key: 2,
+	facts: 3,
+} as const;
+
+/**
+ * Decide what the panel has room for, most valuable first.
+ *
+ * NOT cosmetic trimming. MEASURED at 80×24 before this existed: the blocks
+ * asked for about 17 rows in the 12 the list had left, and Yoga answered by
+ * SHRINKING them — two preset names composited into one, `off` printed on top
+ * of `—`, and two blocks vanished. An over-tall panel does not scroll and does
+ * not clip, it overprints.
+ *
+ * Drop order is by value: the distribution and the project's own facts are what
+ * a short terminal keeps, the colour key is what a tall one adds.
+ *
+ * There used to be a fourth block here — one bar per preset, stacked, so the
+ * presets could be compared. MEASURED on a dark 120×30 terminal it rendered as
+ * a purple bar, then ONE teal rectangle spanning the two presets that share a
+ * colour, then grey: three blocks where four comparisons were meant, because
+ * adjacent same-coloured bars had nothing between them. It was noise, and the
+ * rows it cost are rows the list now keeps.
+ */
+export function planModelsSummary(
+	available: number,
+	hasConfigPath: boolean,
+): SummaryPlan {
+	const plan: SummaryPlan = {
+		spread: false,
+		key: false,
+		facts: false,
+		rows: 0,
+	};
+	// The leading blank line plus the rule: the block cannot exist for less.
+	const base = 1 + SUMMARY_COST.rule;
+	if (available < base) return plan;
+	plan.rows = base;
+
+	const factsCost = SUMMARY_COST.facts + (hasConfigPath ? 1 : 0);
+
+	// A strict cascade, not a greedy fill: once something does not fit, nothing
+	// below it is considered either. Otherwise a cheap block slips in past an
+	// expensive one and the panel shows the colour key for a bar it did not draw.
+	let stopped = false;
+	const take = (cost: number, enabled: boolean) => {
+		if (stopped) return false;
+		if (!enabled || cost === 0) return false;
+		if (plan.rows + cost > available) {
+			stopped = true;
+			return false;
+		}
+		plan.rows += cost;
+		return true;
+	};
+
+	plan.spread = take(SUMMARY_COST.spread, true);
+	plan.facts = take(factsCost, true);
+	plan.key = take(SUMMARY_COST.key, true);
+	return plan;
+}
+
+/**
+ * What sits under the preset list: the selected preset's spread, the colour key,
+ * then the project's routing facts.
+ *
+ * The panel held four rows of text and roughly thirty-five unpainted ones at
+ * 145×45, and the screen's one graphic was buried at the bottom of a detail
+ * pane nobody had scrolled to. This is that widget, moved to where the choice is
+ * being made.
+ *
+ * `available` is rows, and it is not advisory — see `planModelsSummary`.
+ *
+ * It no longer takes the item LIST. Everything under the rule now describes one config — the
+ * one the cursor is on and the chart is drawing — and the only thing the full list was used
+ * for was a colour key built from every preset at once, which is the drift `ModelKey`
+ * documents.
+ */
+export function renderModelsSummary({
+	selected,
+	status,
+	configPath,
+	width,
+	available,
+}: {
+	selected: ModelsBrowserItem | undefined;
+	status: ModelsStatus | null;
+	configPath: string | null;
+	width: number;
+	/** Rows left under the list. Blocks are dropped until the block fits. */
+	available: number;
+}): React.ReactNode {
+	if (!status) return null;
+	const preset = selected?.kind === "preset" ? selected : undefined;
+	const plan = planModelsSummary(available, Boolean(configPath));
+	if (plan.rows === 0) return null;
+
+	// One column of indent, so this block's left edge lines up with the rows
+	// above it — every list row carries `indent={1}`.
+	const inner = Math.max(8, width - 1);
+
+	return (
+		<box flexDirection="column" marginTop={1} paddingLeft={1} flexShrink={0}>
+			<text fg={theme.colors.border}>{"─".repeat(inner)}</text>
+			{plan.spread && preset ? (
+				<AgentSpread config={preset.config} width={inner} />
+			) : null}
+			{/* Gated on `preset` for the same reason the chart is: the key describes the
+			    graphic above it, and with nothing selected there is no graphic to describe. */}
+			{plan.key && preset ? (
+				<box marginTop={1}>
+					<ModelKey config={preset.config} width={inner} />
+				</box>
+			) : null}
+			{/*
+			 * The `state / preset / config` block that used to sit here is GONE.
+			 *
+			 * All three were already on screen: the state is a chip in the panel header AND in
+			 * the title bar, the preset is the row the cursor is on, and the path is a detail
+			 * nobody acts on from a list. Restating them under the chart made the column read
+			 * as a form to fill in rather than a summary of what is running.
+			 *
+			 * `plan.facts` still exists in the layout plan: it is the rung that decides whether
+			 * the chart and the key fit at all, and deleting it would change the fitting maths
+			 * rather than only what is drawn.
+			 */}
+		</box>
+	);
+}
+
+// ─── Dispatch ─────────────────────────────────────────────────────────────────
+
+/**
+ * A row, drawn against the layout the WHOLE list shares.
+ *
+ * `layout` is not optional and is not derived here on purpose: deriving it
+ * per-row is exactly how four presets ended up in two different formats.
+ */
+export function renderModelRow(
+	item: ModelsBrowserItem,
+	_index: number,
+	isSelected: boolean,
+	layout: PresetRowLayout,
+): React.ReactNode {
+	if (item.kind === "status") {
+		return renderStatusRow(item, isSelected);
+	}
+	return renderPresetRow(item, isSelected, layout);
+}
+
+/**
+ * The detail pane.
+ *
+ * `status` is passed alongside the item rather than copied onto it: the drift
+ * lines belong to the project, not to whichever preset the cursor is on, and
+ * duplicating them per row is how the two would end up disagreeing.
+ *
+ * `matesAvailable` arrives the same way and for the same reason — it is a fact about the
+ * MACHINE (is `multimodel@magus` installed), not about the preset under the cursor. It is
+ * passed in rather than looked up here because this module is a renderer: answering it needs
+ * the filesystem and the network, which is the adapter layer's job. It defaults to false so
+ * a caller that has not asked yet draws the screen as it always was, rather than flickering
+ * three rows in on the first frame.
+ *
+ * `catalog` arrives the same way again, and defaults to EMPTY for a stronger reason than
+ * convenience: empty is what a failed lookup yields, and the advisory built from it returns
+ * nothing on an empty catalogue. So a caller that never asks, a machine with no claudish, and
+ * a claudish that timed out all render identically — the bound ids as written, unannotated.
+ */
+export function renderModelDetail(
+	item: ModelsBrowserItem | undefined,
+	status: ModelsStatus | null,
+	width?: number,
+	matesAvailable = false,
+	catalog: CatalogModel[] = [],
+): React.ReactNode {
+	if (!item) {
+		return (
+			<box flexDirection="column">
+				<text fg={theme.colors.muted}>No preset selected.</text>
+			</box>
+		);
+	}
+	if (item.kind === "status") {
+		return renderStatusDetail(status, width);
+	}
+	// The state block only when there is something to DO about it.
+	//
+	// `on` and `off` are already stated twice — in the title bar and on the list's own
+	// header row — so repeating "on / every Agent call is routed through this config"
+	// above every preset spent four rows restating the obvious and pushed the tier table
+	// down. `stale`, `invalid` and `unhooked` stay, because each one carries lines the
+	// reader has seen nowhere else and a fix to press.
+	const needsAttention =
+		status !== null && status.state !== "on" && status.state !== "off";
+	return (
+		<box flexDirection="column">
+			{needsAttention ? (
+				<box marginBottom={1}>
+					<StateBlock status={status} width={width} />
+				</box>
+			) : null}
+			{renderPresetDetail(item, width, matesAvailable, catalog)}
+		</box>
+	);
+}