claudeup 6.7.1 → 6.8.0

package/src/services/models-core.ts

@@ -54,9 +54,65 @@ export type Effort = (typeof EFFORTS)[number];
 export const GRADES = ["smart", "normal", "cheap"] as const;
 export type Grade = (typeof GRADES)[number];
 
-/** An agent's model: an alias, or `inherit` to leave the call alone. */
-export type AgentModel = ModelAlias | "inherit";
-/** The main thread may also ask for a long-context variant. */
+/**
+ * Subagents whose model is a third-party external one, reached through claudish rather than
+ * through Claude Code's own aliases.
+ *
+ * Named for what they are to this tool: someone else's model, helping out. `kangaroo` is
+ * `mate3` — it is a joke, and it is load-bearing only in the sense that nobody mistakes it
+ * for a Claude alias.
+ *
+ * These are NOT routable. `MODEL_ALIASES` is the entire set the Agent tool accepts, and
+ * AMR-1 measured that anything else refuses the spawn (5/5). A mate therefore behaves like
+ * `inherit` at the hook: claudeup declines to rewrite the call, and whatever claudish or the
+ * agent's own frontmatter decides is what runs.
+ */
+export const MATES = ["mate1", "mate2", "kangaroo"] as const;
+export type Mate = (typeof MATES)[number];
+
+/**
+ * An agent's model: an alias, `inherit` to leave the call alone, or a mate.
+ *
+ * A mate is the second opt-out, and it says something `inherit` does not: `inherit` means the
+ * author declined to decide, a mate means the author sent this agent somewhere claudeup has
+ * no say over. Both produce the same hook behaviour and different words on screen.
+ */
+export type AgentModel = ModelAlias | "inherit" | Mate;
+
+/**
+ * What a slot is BOUND to: a real external model, and optionally an effort for it.
+ *
+ * A slot is a ROLE — "the first external helper" — and a role is not a model. Until this
+ * existed the screen had nothing else to print in its Model column and printed the slot name
+ * there, so a row read `mate1 mate1 —`: the same word twice, neither of them naming a model.
+ *
+ * `model` is a BARE CATALOG ID (`grok-4.6`), never an `openrouterId` (`moonshotai/kimi-k3`)
+ * and never an Access route (`kc@kimi-k3`). Both of those forms PIN THE PROVIDER, which
+ * bypasses claudish's subscription-aware routing — the committed file should record the
+ * model's IDENTITY and leave the route to the thing that owns routing. The validator rejects
+ * `/` and `@` for exactly that reason, and says so.
+ */
+export interface MateBinding {
+	/** A bare catalog id. No `@`, no `/` — see above. */
+	model: string;
+	/**
+	 * DECLARED, not applied. claudeup writes it and nothing in claudeup reads it back:
+	 * effort reaches a Claude subagent through `settings.modelSettings`, which is keyed by
+	 * models Claude Code runs, and an external model has no key there. It is here for
+	 * claudish to read. Every place it is drawn says so — see `effortWord`.
+	 */
+	effort?: Effort;
+}
+
+/** The bindings, by slot. A slot may be absent: unbound is legal, and renders as unset. */
+export type MatesConfig = Partial<Record<Mate, MateBinding>>;
+/**
+ * The main thread may also ask for a long-context variant.
+ *
+ * Deliberately NOT widened to `Mate`. claudeup writes `main.model` straight into
+ * `settings.model`, which has to name a model Claude Code itself runs — a mate names one it
+ * has never heard of. The validator rejects it and says so; see `validateModelsConfig`.
+ */
 export type MainModel = ModelAlias | `${ModelAlias}[1m]`;
 
 export interface GradeSpec {
@@ -82,6 +138,24 @@ export interface ModelsConfig {
 	agents: Record<string, AgentAssignment>;
 	/** Grade for an agent with no assignment. */
 	fallback: Grade;
+	/**
+	 * Which external model each slot names. Optional in full: every config written before
+	 * this existed stays valid, and an unbound slot renders as unset rather than erroring.
+	 */
+	mates?: MatesConfig;
+	/**
+	 * The effort every slot runs at unless it names its own.
+	 *
+	 * A PRESET DECISION, like the grades above it. A preset cannot bind a slot to a model —
+	 * it ships in this repo and a catalogue id would go stale — but it can say how hard the
+	 * external work should try, and that is the half of the answer that does not depend on
+	 * which model serves it.
+	 *
+	 * A slot's own `mates[slot].effort` wins where it is set, so a project can raise or lower
+	 * one slot without leaving the preset. `mateEffort()` is the single place that resolution
+	 * happens.
+	 */
+	mateEffort?: Effort;
 }
 
 export interface ValidationError {
@@ -106,6 +180,84 @@ export function isGrade(v: unknown): v is Grade {
 	return typeof v === "string" && (GRADES as readonly string[]).includes(v);
 }
 
+/**
+ * Is this one of the three external-model slots?
+ *
+ * Exact match only, and no prefix rule: `mate1` is a slot, `mate10` is a typo, and near-
+ * matching one into the other would route an agent somewhere its author never named.
+ */
+export function isMate(v: unknown): v is Mate {
+	return typeof v === "string" && (MATES as readonly string[]).includes(v);
+}
+
+/**
+ * The values that own no `modelSettings` KEY: `inherit`, and every mate.
+ *
+ * Effort reaches a subagent through `modelSettings`, which is keyed BY MODEL (AMR-1 rule 5).
+ * `inherit` names none by construction; a mate names one Claude Code has never heard of, so
+ * a key under it could not select anything.
+ *
+ * This is now used by exactly ONE rule — the one-model-one-effort conflict pass — and it
+ * deliberately no longer gates VALIDATION. Those two questions looked identical and are not:
+ *
+ *   - "may this carry an effort at all?"  `inherit` no, a mate YES. A mate's effort is a
+ *     per-call value for claudish, not a settings key, so it is a legitimate thing to write.
+ *   - "can this collide with another effort over a shared key?"  neither, because neither
+ *     has a key to collide over. Two mates bound to the SAME external model may still carry
+ *     different efforts, and that is not a conflict for the same reason.
+ *
+ * Collapsing them back into one predicate is what made an effort on a mate a validation
+ * error in the first place.
+ */
+function namesNoKeyableModel(model: unknown): boolean {
+	return model === "inherit" || isMate(model);
+}
+
+/**
+ * Why a bare catalog id, and not the two forms that also identify a model.
+ *
+ * Both rejected forms name a ROUTE rather than an identity, and a committed file that pins a
+ * route makes every reader of it use that route — including a reader whose subscription
+ * would have served the same model directly. Routing is claudish's to decide; this file
+ * records WHICH MODEL, and nothing about how to reach it.
+ */
+const ROUTE_PINNED =
+	"pins the provider and bypasses claudish's subscription-aware routing — store the model's identity, not a route to it";
+
+/** Shape-check one `mates` entry. Returns the errors, which may be empty. */
+function validateMateBinding(slot: string, value: unknown): ValidationError[] {
+	const out: ValidationError[] = [];
+	const at = `mates.${slot}`;
+	if (!isRec(value)) {
+		return [{ path: at, message: "must be an object with a `model`" }];
+	}
+	const model = value.model;
+	if (typeof model !== "string" || model.length === 0) {
+		out.push({
+			path: `${at}.model`,
+			message:
+				"must be a non-empty string naming a model in claudish's catalogue",
+		});
+	} else if (model.includes("/")) {
+		out.push({
+			path: `${at}.model`,
+			message: `${JSON.stringify(model)} looks like an openrouterId. A provider-prefixed id ${ROUTE_PINNED}. Use the bare catalogue id — \`${model.slice(model.lastIndexOf("/") + 1)}\``,
+		});
+	} else if (model.includes("@")) {
+		out.push({
+			path: `${at}.model`,
+			message: `${JSON.stringify(model)} looks like an Access route. A \`provider@model\` selector ${ROUTE_PINNED}. Use the bare catalogue id — \`${model.slice(model.indexOf("@") + 1)}\``,
+		});
+	}
+	if (value.effort !== undefined && !isEffort(value.effort)) {
+		out.push({
+			path: `${at}.effort`,
+			message: `must be one of ${EFFORTS.join(", ")}`,
+		});
+	}
+	return out;
+}
+
 /**
  * Is this a value the Agent tool will accept as `model`?
  *
@@ -114,6 +266,10 @@ export function isGrade(v: unknown): v is Grade {
  * purpose — at write time, at install time, and again in the hook — because the cost of a bad
  * value is not a bad model, it is every subagent spawn failing for everyone who pulled the
  * config.
+ *
+ * Mates are excluded DELIBERATELY, and widening this to admit them would be the one change
+ * that turns the whole feature into an outage: a mate is a name claudish understands and the
+ * Agent tool does not, so injecting one is exactly the `bogus-model` case measured above.
  */
 export function isRoutableModel(v: unknown): v is ModelAlias {
 	return isModelAlias(v);
@@ -131,6 +287,13 @@ export function baseAlias(model: string): string {
  * Hand-rolled rather than schema-library-driven, matching `manifest.ts validateManifest`:
  * claudeup ships no validation dependency, and the errors here are meant to be read by a
  * person fixing a committed file.
+ *
+ * A MATE IS VALID WHEREVER AN AGENT MODEL IS, whether or not the multimodel plugin is
+ * installed on this machine. Validity is a property of the file, not of the machine reading
+ * it: a `models.json` is committed and shared, so gating `mate1` on a local install would
+ * make the same file valid on one teammate's laptop and invalid on the next one's — and the
+ * failure would land on whoever had not installed the plugin yet, over a routing decision
+ * they did not make. Whether the slots are DRAWN is a UI question, answered in the renderers.
  */
 export function validateModelsConfig(raw: unknown): ValidationError[] {
 	const errors: ValidationError[] = [];
@@ -160,6 +323,15 @@ export function validateModelsConfig(raw: unknown): ValidationError[] {
 				"main.model",
 				"`inherit` is for agents only — the main thread needs a real model",
 			);
+		} else if (isMate(m)) {
+			// The main thread is the one seat a mate can never take. Its model is written to
+			// `settings.model`, which Claude Code reads to start the session itself — a name
+			// only claudish understands would leave the session with no model at all, and
+			// unlike a subagent there is nothing left to fall back to.
+			err(
+				"main.model",
+				`\`${m}\` is for subagents only — claudeup writes main.model into settings.model, so it has to name a model Claude Code runs (${MODEL_ALIASES.join(", ")}). A mate names an external model reached through claudish, which the main thread cannot use`,
+			);
 		} else if (!isModelAlias(baseAlias(m))) {
 			err(
 				"main.model",
@@ -186,16 +358,23 @@ export function validateModelsConfig(raw: unknown): ValidationError[] {
 				err(`grades.${g}`, "must be an object with a `model`");
 				continue;
 			}
-			if (spec.model !== "inherit" && !isModelAlias(spec.model)) {
+			if (
+				spec.model !== "inherit" &&
+				!isMate(spec.model) &&
+				!isModelAlias(spec.model)
+			) {
 				err(
 					`grades.${g}.model`,
-					`must be one of ${MODEL_ALIASES.join(", ")} or "inherit", got ${JSON.stringify(spec.model)}`,
+					`must be one of ${MODEL_ALIASES.join(", ")}, "inherit", or a mate (${MATES.join(", ")}), got ${JSON.stringify(spec.model)}`,
 				);
 			}
+			// `inherit` ONLY. An effort on a MATE is valid — declared for claudish rather
+			// than written to modelSettings — so `namesNoKeyableModel` is deliberately not
+			// used here; its comment explains why the two questions are not the same one.
 			if (spec.model === "inherit" && spec.effort !== undefined) {
 				err(
 					`grades.${g}.effort`,
-					"cannot set effort on `inherit` — effort is applied per model, and inherit names no model",
+					"cannot set effort on `inherit` — effort is applied per model through modelSettings, and inherit names no model",
 				);
 			}
 			if (spec.effort !== undefined && !isEffort(spec.effort)) {
@@ -242,21 +421,54 @@ export function validateModelsConfig(raw: unknown): ValidationError[] {
 				);
 				continue;
 			}
-			if (value.model !== "inherit" && !isModelAlias(value.model)) {
+			if (
+				value.model !== "inherit" &&
+				!isMate(value.model) &&
+				!isModelAlias(value.model)
+			) {
 				err(
 					`agents.${name}.model`,
-					`must be one of ${MODEL_ALIASES.join(", ")} or "inherit", got ${JSON.stringify(value.model)}`,
+					`must be one of ${MODEL_ALIASES.join(", ")}, "inherit", or a mate (${MATES.join(", ")}), got ${JSON.stringify(value.model)}`,
 				);
 			}
 			if (value.effort !== undefined && !isEffort(value.effort)) {
 				err(`agents.${name}.effort`, `must be one of ${EFFORTS.join(", ")}`);
 			}
+			// `inherit` ONLY — see the identical rule on grades above.
 			if (value.model === "inherit" && value.effort !== undefined) {
 				err(
 					`agents.${name}.effort`,
-					"cannot set effort on `inherit` — effort is applied per model",
+					"cannot set effort on `inherit` — effort is applied per model, and inherit names no model",
+				);
+			}
+		}
+	}
+
+	// ── mates ───────────────────────────────────────────────────────────────────────────
+	//
+	// VALIDATION IS OFFLINE AND CONSULTS NO CATALOGUE. Shape only — that `grok-4.6` is a
+	// plausible bare id, never that it exists.
+	//
+	// A `models.json` is committed and shared, so its validity has to be a property of the
+	// FILE. A validator that reached the network would make the same file valid on a
+	// connected laptop and invalid on a plane, and the failure would land on whoever happened
+	// to open it offline, over a routing decision they did not make. Whether a bound id is
+	// still in the live catalogue is a real question, and it is answered separately, as an
+	// ADVISORY note — `services/mate-catalog.ts`, which never blocks anything.
+	if (raw.mates !== undefined && !isRec(raw.mates)) {
+		err("mates", `must be an object keyed by ${MATES.join(", ")}`);
+	} else if (isRec(raw.mates)) {
+		for (const [slot, value] of Object.entries(raw.mates)) {
+			if (!isMate(slot)) {
+				// No near-matching: `mate10` is a typo, not `mate1`, and quietly binding one
+				// to the other would send an agent to a model its author never named.
+				err(
+					`mates.${slot}`,
+					`unknown slot — expected one of ${MATES.join(", ")}`,
 				);
+				continue;
 			}
+			for (const e of validateMateBinding(slot, value)) errors.push(e);
 		}
 	}
 
@@ -269,7 +481,17 @@ export function validateModelsConfig(raw: unknown): ValidationError[] {
 		const cfg = raw as unknown as ModelsConfig;
 		const claims = new Map<string, { effort: Effort; at: string }>();
 		const claim = (model: string, effort: Effort | undefined, at: string) => {
-			if (effort === undefined || model === "inherit") return;
+			// Mates are skipped with `inherit`, and by the same predicate: neither owns a
+			// `modelSettings` key, so neither can collide with anything over one. Two seats
+			// on `mate1` are not a conflict — they are two agents sent to claudish, which is
+			// the normal way to use a slot.
+			//
+			// This exemption now carries real weight. Mates DO carry effort (the rule was
+			// reversed), so without it two agents on `mate1` at different efforts would be
+			// reported as a conflict — and it is not one. Effort on a mate is a per-call
+			// value handed to claudish, not a settings key, so two mates bound to the very
+			// same external model may still legitimately declare different efforts.
+			if (effort === undefined || namesNoKeyableModel(model)) return;
 			const key = baseAlias(model);
 			const prior = claims.get(key);
 			if (prior && prior.effort !== effort) {
@@ -293,6 +515,103 @@ export function validateModelsConfig(raw: unknown): ValidationError[] {
 	return errors;
 }
 
+// ─── Reading a binding ────────────────────────────────────────────────────────────────────
+
+/**
+ * What the Model column shows for an unbound slot.
+ *
+ * NOT the slot name repeated, and not a blank. The slot name in a Model column is what this
+ * whole change exists to remove — it said `mate1 mate1 —` and neither word named a model. A
+ * blank would read as the `—` that means "nothing was decided", which is the opposite: the
+ * author decided to route here and has not yet said where.
+ */
+export const UNBOUND_MATE = "unset";
+
+/** The catalogue id a slot is bound to, or null when it is unbound. */
+export function boundModel(
+	config: Pick<ModelsConfig, "mates">,
+	slot: Mate,
+): string | null {
+	return config.mates?.[slot]?.model ?? null;
+}
+
+/**
+ * The effort a slot runs at: its own if it names one, otherwise the preset's.
+ *
+ * Two rungs and no third. The slot is the specific answer and wins; the preset is the
+ * general one and covers every slot that did not bother. Resolved here rather than at each
+ * call site, so the tier table, the agent table and the CLI cannot disagree about what a
+ * slot with no effort of its own is actually running at.
+ */
+export function mateEffort(
+	config: Pick<ModelsConfig, "mates" | "mateEffort">,
+	slot: Mate,
+): Effort | undefined {
+	return config.mates?.[slot]?.effort ?? config.mateEffort;
+}
+
+/**
+ * The text that names a routing value: a bound slot resolves to its model, everything else
+ * is already a model name.
+ *
+ * One function, because the Model column, its width maths and the CLI all have to print the
+ * SAME string. The renderers measure a column from this and then draw from it; the defect
+ * `modelWidth` exists to prevent — a column measured from a different string than the one
+ * rendered — is exactly what two copies of this rule would reintroduce.
+ */
+export function modelLabel(
+	config: Pick<ModelsConfig, "mates">,
+	model: string,
+): string {
+	if (!isMate(model)) return model;
+	return boundModel(config, model) ?? UNBOUND_MATE;
+}
+
+/**
+ * A config as a canonical string, for comparing two of them.
+ *
+ * Key order is normalised because the two sides come from different places: a built-in preset
+ * is a TypeScript literal and a project's config is parsed from a file, so a plain
+ * `JSON.stringify` comparison would call two identical configs different whenever the file
+ * happened to list `fallback` before `agents`.
+ */
+function canonical(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (value && typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>)
+			// `undefined` members are ABSENT, not present-and-empty: `{effort: undefined}` and
+			// `{}` describe the same routing, and a JSON round-trip turns the first into the
+			// second — so a literal compared against a parsed file would differ over nothing.
+			.filter(([, v]) => v !== undefined)
+			.sort(([a], [b]) => a.localeCompare(b));
+		return `{${entries.map(([k, v]) => `${k}:${canonical(v)}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+/**
+ * Do these two configs describe the same routing?
+ *
+ * Exists because "is the project running a built-in" cannot be answered by NAME. `claudeup
+ * models use opus-lead` writes `preset: "opus-lead"`, and every hand edit afterwards — a
+ * `mates` block, a rebound agent — leaves that name untouched. A name check therefore reports
+ * a diverged config as a built-in, which is how the one config on the machine that can name a
+ * mate became invisible to the TUI.
+ */
+export function sameRouting(a: ModelsConfig, b: ModelsConfig): boolean {
+	return canonical(a) === canonical(b);
+}
+
+/** Every slot a config actually uses — assigned to a grade or to an agent. */
+export function matesInUse(config: ModelsConfig): Mate[] {
+	const seen = new Set<string>();
+	for (const grade of GRADES) seen.add(config.grades[grade].model);
+	for (const assignment of Object.values(config.agents ?? {})) {
+		if (typeof assignment !== "string") seen.add(assignment.model);
+	}
+	return MATES.filter((mate) => seen.has(mate));
+}
+
 export interface Routing {
 	model: AgentModel;
 	effort?: Effort;
@@ -347,6 +666,7 @@ export type AgentHookDecision =
 				| "invalid-config"
 				| "explicit-model"
 				| "inherit"
+				| "mate"
 				| "unroutable-model";
 	  }
 	| {
@@ -399,6 +719,15 @@ export function evaluateAgentHook(
 	if (routing.model === "inherit")
 		return { kind: "passthrough", reason: "inherit" };
 
+	// A mate's model is claudish's to choose, not ours. Same passthrough as `inherit`, kept as
+	// its own reason so the hook log distinguishes "the author opted out" from "the author sent
+	// this one outside".
+	//
+	// BEFORE the guard below, not after: a mate would fail `isRoutableModel` too, and reporting
+	// it as `unroutable-model` would read as a broken config — the one state the log exists to
+	// make obvious — when it is the config working exactly as written.
+	if (isMate(routing.model)) return { kind: "passthrough", reason: "mate" };
+
 	// Belt and braces over the writer's validation. A hand-edited profile or an older claudeup
 	// can put an unroutable value here, and MEASURED (AMR-1 `bogus-model`) that does not
 	// degrade — it refuses the spawn outright. Passing through costs the routing; injecting
@@ -450,6 +779,16 @@ export function buildSettingsPatch(
 	const add = (model: string, effort: Effort | undefined) => {
 		if (effort === undefined || model === "inherit") return;
 		const alias = baseAlias(model);
+		// The `isModelAlias` gate is what keeps a MATE out of `modelSettings`, and it is the
+		// only thing that does. It is now LOAD-BEARING rather than belt-and-braces: an effort
+		// on a mate used to be a validation error, so nothing could reach here carrying one,
+		// and today it is valid and ordinary. `modelSettings` is keyed by models Claude Code
+		// RUNS — a `mate1` key selects nothing, and a `grok-4.6` key selects nothing either.
+		//
+		// A mate's effort is written to the `mates` block and read by claudish. It never
+		// reaches settings, from any path: `add()` is the only writer and this line is the
+		// only gate, so the test that pins it asserts on the whole map (no slot, no external
+		// id, no `undefined` key) rather than on this branch.
 		if (!isModelAlias(alias)) return;
 		modelSettings[alias] = { effortLevel: effort };
 		const full = resolveFullId(alias);
@@ -466,7 +805,14 @@ export function buildSettingsPatch(
 	return { set, unset: [] };
 }
 
-export type ModelsState = "off" | "on" | "stale" | "invalid" | "unhooked";
+/**
+ * The four states routing can be in. Each is a fact the reader can act on.
+ *
+ * There is no state for "the settings differ from the config". Differing is what a CUSTOM
+ * config is, and the list says so with a `Custom` row rather than the header saying it with
+ * a warning.
+ */
+export type ModelsState = "off" | "on" | "invalid" | "unhooked";
 
 export interface ModelsStatus {
 	state: ModelsState;
@@ -525,27 +871,22 @@ export function computeModelsStatus(args: {
 		};
 	}
 
-	const patch = buildSettingsPatch(config, resolveFullId);
-	const entries = Object.entries(patch.set);
-	const differing = entries.filter(
-		([key, want]) => JSON.stringify(settings[key]) !== JSON.stringify(want),
-	);
-
-	// Nothing written at all is ONE fact, not three. Listing `model`, `effortLevel` and
-	// `modelSettings` separately when every one of them is absent reads as three distinct
-	// problems and buries the only thing that matters: no settings were ever written here.
-	const allMissing =
-		differing.length === entries.length &&
-		differing.every(([key]) => settings[key] === undefined);
-
-	const drift = allMissing
-		? ["settings carry none of the config — none of it is in force"]
-		: differing.map(([key, want]) => describeDrift(key, settings[key], want));
-
+	// A config whose settings differ from a built-in's is CUSTOM, and custom is not a fault.
+	//
+	// There is no comparison here any more, and no state for the result of one. A project may
+	// legitimately run models and efforts no shipped preset names; saying so as a state called
+	// `stale`, with a count of the differences, described a thing you have as a thing that is
+	// wrong with you — and the count was of MESSAGES rather than of differences, so `1 drift`
+	// could mean every setting differed.
+	//
+	// The list carries the fact instead: a config matching no built-in gets its own `Custom`
+	// row holding those settings, with its own tier table and chart. `drift` survives for the
+	// two states that ARE faults — a config that does not validate, and one with no hook to
+	// run it — where the lines name something the reader has to fix.
 	return {
-		state: drift.length ? "stale" : "on",
+		state: "on",
 		preset: config.preset,
-		drift,
+		drift: [],
 		warnings,
 	};
 }

package/src/ui/adapters/modelsAdapter.ts

@@ -8,6 +8,7 @@ import {
 	type ModelsConfig,
 	type ModelsState,
 	type ModelsStatus,
+	sameRouting,
 } from "../../services/models-core.js";
 
 // ─── Item types ───────────────────────────────────────────────────────────────
@@ -20,6 +21,14 @@ import {
  * warnings behind the counts live on the `ModelsStatus` the detail renderer is
  * handed, so they are not stored twice and cannot disagree.
  */
+/**
+ * What the row for a diverged config is called.
+ *
+ * A fixed word, never the file's `preset` string: that string names whatever was last
+ * applied, and a config edited afterwards would wear a built-in's name while not being it.
+ */
+export const CUSTOM_LABEL = "Custom";
+
 export interface ModelsStatusItem {
 	id: string;
 	kind: "status";
@@ -73,11 +82,16 @@ function matches(config: ModelsConfig, lowerQuery: string): boolean {
 	// Both names are searchable: the row SHOWS "Opus with Fable help", and a user who knows
 	// the command types "fable-advisor". Matching only one of them makes the other look like
 	// a missing preset.
+	//
+	// Bound models are searchable too: a project that routes `smart` to `mate1` → `grok-4.6`
+	// is findable by typing `grok`, which is the name its author thinks in. The slot names
+	// come along with the grade models above, so both halves of the binding match.
 	const haystack = [
 		config.preset,
 		presetLabel(config.preset),
 		config.main.model,
 		...GRADES.map((grade) => config.grades[grade].model),
+		...Object.values(config.mates ?? {}).map((binding) => binding.model),
 	]
 		.join(" ")
 		.toLowerCase();
@@ -105,7 +119,29 @@ export function buildModelsItems({
 
 	const lowerQuery = query.trim().toLowerCase();
 	const activeName = config?.preset ?? null;
-	const builtInNames = new Set(presets.map((preset) => preset.preset));
+
+	// DOES THE PROJECT'S OWN CONFIG SAY SOMETHING NO BUILT-IN DOES?
+	//
+	// The test used to be "does it name a preset the built-ins do not", and that missed the
+	// ordinary case entirely. `claudeup models use opus-lead` writes `preset: "opus-lead"`,
+	// and hand-editing the file afterwards — adding a `mates` block, rebinding an agent —
+	// leaves that name untouched. So the config carrying the mate assignments matched a
+	// built-in by NAME, got no row of its own, and the list rendered the BUILT-IN's contents
+	// under the built-in's label.
+	//
+	// The consequence was not cosmetic: the only config on the machine that can name a mate
+	// was unreachable on screen, so neither the agent table nor the workflow bar could ever
+	// show one, no matter what the file said. `claudeup models list` printed it correctly the
+	// whole time, which is what made the gap look like a rendering bug rather than a missing
+	// row.
+	//
+	// Compared by CONTENT now, so a project that merely applied a preset still gets one row
+	// (its file and the built-in agree) and a project that changed anything gets two.
+	const builtInNamed = presets.find((preset) => preset.preset === activeName);
+	const projectOwn =
+		config && (!builtInNamed || !sameRouting(config, builtInNamed))
+			? config
+			: null;
 
 	const rows: ModelsPresetItem[] = presets
 		.filter((preset) => matches(preset, lowerQuery))
@@ -114,26 +150,33 @@ export function buildModelsItems({
 			kind: "preset" as const,
 			label: presetLabel(preset.preset),
 			config: preset,
-			active: preset.preset === activeName,
+			// `●` marks WHAT IS RUNNING, and when the project has diverged the built-in of
+			// that name is not it. Leaving the mark on both rows would say two different
+			// routings are simultaneously in force.
+			active: preset.preset === activeName && projectOwn === null,
 			isDefault: preset.preset === DEFAULT_PRESET,
 			custom: false,
 		}));
 
-	// A project that hand-edited its models.json names a preset no built-in
-	// carries. It is the routing actually in force, so it gets a row of its own —
-	// otherwise the list shows four presets with none of them marked, which reads
-	// as "routing is off" when it is emphatically on.
-	if (
-		config &&
-		activeName &&
-		!builtInNames.has(activeName) &&
-		matches(config, lowerQuery)
-	) {
+	// A project whose settings differ from every built-in gets ONE row, called `Custom`.
+	//
+	// Divergence is a THING YOU HAVE, not a fault to warn about. A project can legitimately
+	// run models or efforts no preset ships, and the list's job is to show that as one more
+	// option carrying those settings — selectable, inspectable, with its own tier table and
+	// chart — rather than as a badge saying the config and the settings disagree.
+	//
+	// It is called `Custom` and never the string in the file's `preset` field. That string is
+	// whatever was last applied — `models use opus-lead` writes `opus-lead` and hand-editing
+	// afterwards leaves it — so showing it puts a built-in's name on a row that is not that
+	// built-in.
+	if (projectOwn && matches(projectOwn, lowerQuery)) {
 		rows.push({
-			id: `preset:${activeName}`,
+			// `project:` rather than `preset:`, because the name it carries may be a built-in's
+			// and two rows may not share an id.
+			id: `project:${projectOwn.preset}`,
 			kind: "preset",
-			label: presetLabel(activeName),
-			config,
+			label: CUSTOM_LABEL,
+			config: projectOwn,
 			active: true,
 			isDefault: false,
 			custom: true,

package/src/ui/components/layout/ScreenLayout.tsx

@@ -275,7 +275,12 @@ export function ScreenLayout({
 				{/* Detail panel — scrollable. The thumb is themed so the reader can
 				    see there is more below the fold; the track keeps the library
 				    default so it stays chrome, not signal. */}
-				<box width="50%" height={panelHeight} paddingLeft={1}>
+				{/* `overflow: hidden`, like the list panel opposite. Without it a line wider
+				    than the panel is drawn OUTSIDE it, over the terminal's right edge, and the
+				    reader loses characters off the end of a sentence with nothing to say they
+				    were lost. Clipping at the panel is the guarantee; wrapping to
+				    `detailPanelWidth` is what keeps there being nothing to clip. */}
+				<box width="50%" height={panelHeight} paddingLeft={1} overflow="hidden">
 					<scrollbox
 						ref={detailScrollRef}
 						height={panelHeight}