magus-cli 0.0.0-placeholder → 7.0.0

package/src/__tests__/models-core.test.ts

@@ -0,0 +1,802 @@
+/**
+ * Contract tests for the pure routing core.
+ *
+ * The behaviour asserted here is not invented: each rule cites the run in
+ * `benches/agent-model-routing/` (AMR-1) that measured it on real Claude Code, interactive,
+ * n=5. A test that drifts from those numbers is a bug in the code or a signal to re-run the
+ * bench — never a reason to relax the assertion.
+ */
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import {
+	BUILT_IN_PRESETS,
+	DEFAULT_AGENT_GRADES,
+	findPreset,
+	presetNames,
+} from "../data/models-presets.js";
+import {
+	EFFORTS,
+	type Effort,
+	GRADES,
+	MATES,
+	type ModelsConfig,
+	baseAlias,
+	buildSettingsPatch,
+	computeModelsStatus,
+	evaluateAgentHook,
+	isMate,
+	isRoutableModel,
+	resolveAgentRouting,
+	validateModelsConfig,
+} from "../services/models-core.js";
+
+const base = (): ModelsConfig => ({
+	version: 1,
+	preset: "test",
+	main: { model: "opus", effort: "medium" },
+	grades: {
+		smart: { model: "fable", effort: "xhigh" },
+		normal: { model: "opus", effort: "medium" },
+		cheap: { model: "sonnet", effort: "low" },
+	},
+	agents: {
+		"dev:architect": "smart",
+		Explore: "cheap",
+		"dev:researcher": { model: "inherit" },
+	},
+	fallback: "normal",
+});
+
+const noFullId = () => null;
+
+describe("validateModelsConfig", () => {
+	test("accepts a well-formed config", () => {
+		expect(validateModelsConfig(base())).toEqual([]);
+	});
+
+	test("every built-in preset validates", () => {
+		for (const p of BUILT_IN_PRESETS) {
+			expect({ preset: p.preset, errors: validateModelsConfig(p) }).toEqual({
+				preset: p.preset,
+				errors: [],
+			});
+		}
+	});
+
+	test("rejects a full model id, and says why", () => {
+		const c = base();
+		(c.main as { model: string }).model = "claude-opus-5";
+		const errors = validateModelsConfig(c);
+		expect(errors).toHaveLength(1);
+		expect(errors[0]?.path).toBe("main.model");
+		expect(errors[0]?.message).toContain("go stale");
+	});
+
+	test("rejects a non-alias on a grade — AMR-1 bogus-model: it refuses the spawn outright", () => {
+		const c = base();
+		(c.grades.cheap as { model: string }).model = "kimi-k2-thinking";
+		const errors = validateModelsConfig(c);
+		expect(errors.map((e) => e.path)).toEqual(["grades.cheap.model"]);
+	});
+
+	test("allows [1m] on main but not on a grade", () => {
+		const ok = base();
+		(ok.main as { model: string }).model = "opus[1m]";
+		expect(validateModelsConfig(ok)).toEqual([]);
+
+		const bad = base();
+		(bad.grades.smart as { model: string }).model = "opus[1m]";
+		expect(validateModelsConfig(bad).map((e) => e.path)).toEqual([
+			"grades.smart.model",
+		]);
+	});
+
+	test("rejects `inherit` on main — the main thread needs a real model", () => {
+		const c = base();
+		(c.main as { model: string }).model = "inherit";
+		expect(validateModelsConfig(c)[0]?.path).toBe("main.model");
+	});
+
+	test("rejects two efforts for one model, naming both sites", () => {
+		// modelSettings is keyed by MODEL, so one of the two would silently lose.
+		const c = base();
+		c.grades.normal = { model: "opus", effort: "xhigh" }; // main already claims opus/medium
+		const errors = validateModelsConfig(c);
+		expect(errors).toHaveLength(1);
+		expect(errors[0]?.path).toBe("grades.normal");
+		expect(errors[0]?.message).toContain("main");
+		expect(errors[0]?.message).toContain("medium");
+	});
+
+	test("the same model with the SAME effort twice is fine", () => {
+		const c = base();
+		c.grades.normal = { model: "opus", effort: "medium" };
+		expect(validateModelsConfig(c)).toEqual([]);
+	});
+
+	test("rejects effort on `inherit`, which names no model to key it by", () => {
+		const c = base();
+		c.agents["dev:researcher"] = { model: "inherit", effort: "low" } as never;
+		expect(validateModelsConfig(c).map((e) => e.path)).toEqual([
+			"agents.dev:researcher.effort",
+		]);
+	});
+
+	test("rejects an unknown grade name in agents", () => {
+		const c = base();
+		c.agents.whatever = "turbo" as never;
+		expect(validateModelsConfig(c).map((e) => e.path)).toEqual([
+			"agents.whatever",
+		]);
+	});
+
+	test("a wrong version stops immediately rather than emitting noise", () => {
+		const errors = validateModelsConfig({ version: 2, main: {}, grades: {} });
+		expect(errors).toHaveLength(1);
+		expect(errors[0]?.path).toBe("version");
+	});
+
+	test("a non-object is one clear error", () => {
+		expect(validateModelsConfig("nope")).toEqual([
+			{ path: "", message: "must be a JSON object" },
+		]);
+	});
+});
+
+describe("resolveAgentRouting", () => {
+	test("an explicit agent grade wins", () => {
+		expect(resolveAgentRouting(base(), "dev:architect")).toEqual({
+			model: "fable",
+			effort: "xhigh",
+			source: "agent-grade",
+			grade: "smart",
+		});
+	});
+
+	test("a per-agent override beats the grade table", () => {
+		expect(resolveAgentRouting(base(), "dev:researcher")).toEqual({
+			model: "inherit",
+			source: "agent-override",
+		});
+	});
+
+	test("an unknown agent falls to the fallback grade, so a new plugin routes on day one", () => {
+		expect(resolveAgentRouting(base(), "brand-new:agent")).toEqual({
+			model: "opus",
+			effort: "medium",
+			source: "default-grade",
+			grade: "normal",
+		});
+	});
+
+	test("a missing subagent_type still resolves", () => {
+		expect(resolveAgentRouting(base(), undefined).source).toBe("default-grade");
+	});
+});
+
+describe("evaluateAgentHook", () => {
+	const agentCall = (input: Record<string, unknown> = {}) => ({
+		tool_name: "Agent",
+		tool_input: { subagent_type: "dev:architect", prompt: "go", ...input },
+	});
+
+	test("rewrites the model and carries the whole input through", () => {
+		const d = evaluateAgentHook(agentCall(), base());
+		expect(d.kind).toBe("update");
+		if (d.kind !== "update") return;
+		expect(d.output.hookSpecificOutput.updatedInput).toEqual({
+			subagent_type: "dev:architect",
+			prompt: "go",
+			model: "fable",
+		});
+	});
+
+	test("ALWAYS emits hookEventName — AMR-1 hook-minimal fired 5/5 and was ignored without it", () => {
+		const d = evaluateAgentHook(agentCall(), base());
+		if (d.kind !== "update") throw new Error("expected an update");
+		expect(d.output.hookSpecificOutput.hookEventName).toBe("PreToolUse");
+	});
+
+	test("never emits permissionDecision — measured neither required nor harmful, so it only widens permission", () => {
+		const d = evaluateAgentHook(agentCall(), base());
+		if (d.kind !== "update") throw new Error("expected an update");
+		expect(Object.keys(d.output.hookSpecificOutput).sort()).toEqual([
+			"hookEventName",
+			"updatedInput",
+		]);
+	});
+
+	test("passes through a tool that is not Agent", () => {
+		expect(
+			evaluateAgentHook({ tool_name: "Bash", tool_input: {} }, base()),
+		).toEqual({
+			kind: "passthrough",
+			reason: "not-agent",
+		});
+	});
+
+	test("passes through with no config — fail open", () => {
+		expect(evaluateAgentHook(agentCall(), null)).toEqual({
+			kind: "passthrough",
+			reason: "no-config",
+		});
+	});
+
+	test("respects a model the caller already chose", () => {
+		expect(evaluateAgentHook(agentCall({ model: "haiku" }), base())).toEqual({
+			kind: "passthrough",
+			reason: "explicit-model",
+		});
+	});
+
+	test("`inherit` is the opt-out and touches nothing", () => {
+		expect(
+			evaluateAgentHook(agentCall({ subagent_type: "dev:researcher" }), base()),
+		).toEqual({
+			kind: "passthrough",
+			reason: "inherit",
+		});
+	});
+
+	test("refuses to inject an unroutable value even if a hand-edited config carries one", () => {
+		// AMR-1 bogus-model: injecting a non-alias refuses the spawn entirely, so passing
+		// through costs the routing while injecting costs the user every subagent.
+		const c = base();
+		(c.grades.smart as { model: string }).model = "kimi-k2-thinking";
+		expect(evaluateAgentHook(agentCall(), c)).toEqual({
+			kind: "passthrough",
+			reason: "unroutable-model",
+		});
+	});
+
+	test("an empty model string is not treated as a caller's choice", () => {
+		const d = evaluateAgentHook(agentCall({ model: "" }), base());
+		expect(d.kind).toBe("update");
+	});
+
+	/**
+	 * A mate passes through, and says so in its own words.
+	 *
+	 * The reason is not cosmetic. `unroutable-model` is the hook reporting a BROKEN config —
+	 * a value that would refuse the spawn if it were injected — and a mate is the config
+	 * working exactly as written. Reporting one as the other would make every deliberate
+	 * external routing look like a typo in the hook log, which is the only place a user can
+	 * see what the hook decided.
+	 */
+	test("a mate passes through as `mate`, never as `unroutable-model`", () => {
+		for (const mate of MATES) {
+			const c = base();
+			(c.grades.smart as { model: string; effort?: Effort }).model = mate;
+			// biome-ignore lint/performance/noDelete: a mate carries no effort
+			delete (c.grades.smart as { effort?: Effort }).effort;
+			const decision = evaluateAgentHook(agentCall(), c);
+			expect(decision).toEqual({ kind: "passthrough", reason: "mate" });
+		}
+	});
+
+	test("a mate pinned to one agent passes through, and the rest still route", () => {
+		const c = base();
+		c.agents["dev:docs"] = { model: "kangaroo" } as never;
+		expect(
+			evaluateAgentHook(agentCall({ subagent_type: "dev:docs" }), c),
+		).toEqual({ kind: "passthrough", reason: "mate" });
+		// The negative control: the mate changed nothing about the agents around it.
+		expect(evaluateAgentHook(agentCall(), c).kind).toBe("update");
+	});
+
+	test("a mate is never written into updatedInput — there is no update to write it into", () => {
+		const c = base();
+		c.agents["dev:docs"] = { model: "mate1" } as never;
+		const decision = evaluateAgentHook(
+			agentCall({ subagent_type: "dev:docs" }),
+			c,
+		);
+		// Stated as the absence of an `update`, because `updatedInput.model` is the exact
+		// field AMR-1 measured as spawn-refusing for a non-alias.
+		expect(decision.kind).not.toBe("update");
+	});
+});
+
+describe("buildSettingsPatch", () => {
+	test("writes main model and effort", () => {
+		const { set } = buildSettingsPatch(base(), noFullId);
+		expect(set.model).toBe("opus");
+		expect(set.effortLevel).toBe("medium");
+	});
+
+	test("writes BOTH key forms with the same value — AMR-1 effort-conflict: the full id wins", () => {
+		const resolve = (a: string) =>
+			a === "fable" ? "claude-fable-5-1" : `claude-${a}-5`;
+		const { set } = buildSettingsPatch(base(), resolve as never);
+		expect(set.modelSettings).toEqual({
+			opus: { effortLevel: "medium" },
+			"claude-opus-5": { effortLevel: "medium" },
+			fable: { effortLevel: "xhigh" },
+			"claude-fable-5-1": { effortLevel: "xhigh" },
+			sonnet: { effortLevel: "low" },
+			"claude-sonnet-5": { effortLevel: "low" },
+		});
+	});
+
+	test("a resolver that cannot answer leaves the alias key alone rather than inventing an id", () => {
+		const { set } = buildSettingsPatch(base(), noFullId);
+		expect(set.modelSettings).toEqual({
+			opus: { effortLevel: "medium" },
+			fable: { effortLevel: "xhigh" },
+			sonnet: { effortLevel: "low" },
+		});
+	});
+
+	test("omits modelSettings entirely when no effort is declared", () => {
+		const c = base();
+		c.main = { model: "opus" };
+		c.grades = {
+			smart: { model: "fable" },
+			normal: { model: "opus" },
+			cheap: { model: "sonnet" },
+		};
+		c.agents = {};
+		const { set } = buildSettingsPatch(c, noFullId);
+		expect(set.modelSettings).toBeUndefined();
+	});
+
+	/**
+	 * A mate may never reach `modelSettings`, and the guard that stops it is load-bearing.
+	 *
+	 * `add()` returns early on anything that is not an alias, which is currently the ONLY
+	 * thing keeping `mate1` out of settings — and it reads as an accident of ordering rather
+	 * than a rule, so it is pinned here. Two ways it could go wrong, both tested:
+	 *
+	 *   - a `mate1` key, which Claude Code can key nothing by;
+	 *   - an `undefined` key, which is what a `resolveFullId` returning null would write if
+	 *     the guard moved and the full-id branch ran on a name it cannot resolve.
+	 *
+	 * The config is built by hand past the validator on purpose: the validator refuses effort
+	 * on a mate, and this function is also reached from `doctor` and the TUI with whatever a
+	 * hand-edited file holds.
+	 */
+	test("a mate produces no modelSettings key of its own, and no `undefined` key", () => {
+		const c = base();
+		(c.grades.smart as { model: string; effort?: Effort }).model = "mate1";
+		c.agents.pinned = { model: "kangaroo" } as never;
+
+		const withResolver = buildSettingsPatch(
+			c,
+			((alias: string) => `claude-${alias}-5`) as never,
+		);
+		const keys = Object.keys(
+			withResolver.set.modelSettings as Record<string, unknown>,
+		);
+		for (const mate of ["mate1", "mate2", "kangaroo"]) {
+			expect(keys).not.toContain(mate);
+			expect(keys).not.toContain(`claude-${mate}-5`);
+		}
+		expect(keys).not.toContain("undefined");
+		// And the aliases beside it are untouched — the mate cost nothing else its entry.
+		expect(keys).toContain("opus");
+
+		// The same, with an effort the validator would have refused. This is the branch that
+		// actually exercises the `isModelAlias` gate rather than the `effort === undefined`
+		// one above it.
+		const forced = base();
+		forced.grades.smart = { model: "mate1", effort: "xhigh" } as never;
+		const patch = buildSettingsPatch(forced, noFullId);
+		const forcedKeys = Object.keys(
+			patch.set.modelSettings as Record<string, unknown>,
+		);
+		expect(forcedKeys).not.toContain("mate1");
+		expect(forcedKeys).not.toContain("undefined");
+		expect(forcedKeys.sort()).toEqual(["opus", "sonnet"]);
+	});
+
+	test("a [1m] main model keys its effort by the base alias", () => {
+		const c = base();
+		(c.main as { model: string }).model = "opus[1m]";
+		const { set } = buildSettingsPatch(c, noFullId);
+		expect(set.model).toBe("opus[1m]");
+		expect((set.modelSettings as Record<string, unknown>).opus).toEqual({
+			effortLevel: "medium",
+		});
+	});
+});
+
+describe("computeModelsStatus", () => {
+	const applied = () => buildSettingsPatch(base(), noFullId).set;
+
+	test("off when there is no config", () => {
+		expect(
+			computeModelsStatus({
+				config: null,
+				errors: [],
+				hookRegistered: true,
+				settings: {},
+				resolveFullId: noFullId,
+			}).state,
+		).toBe("off");
+	});
+
+	test("invalid reports the validation errors as drift", () => {
+		const s = computeModelsStatus({
+			config: null,
+			errors: [{ path: "main.model", message: "bad" }],
+			hookRegistered: true,
+			settings: {},
+			resolveFullId: noFullId,
+		});
+		expect(s.state).toBe("invalid");
+		expect(s.drift[0]).toContain("main.model");
+	});
+
+	test("unhooked outranks stale — nothing routes, so that is the headline", () => {
+		const s = computeModelsStatus({
+			config: base(),
+			errors: [],
+			hookRegistered: false,
+			settings: {},
+			resolveFullId: noFullId,
+		});
+		expect(s.state).toBe("unhooked");
+	});
+
+	test("applied when settings already match", () => {
+		const s = computeModelsStatus({
+			config: base(),
+			errors: [],
+			hookRegistered: true,
+			settings: applied(),
+			resolveFullId: noFullId,
+		});
+		expect(s.state).toBe("on");
+		expect(s.drift).toEqual([]);
+	});
+
+	test("settings differing from the config is CUSTOM, not a fault", () => {
+		// There is no state for it and no drift list. A project may run models and efforts no
+		// shipped preset names; the list says so with a `Custom` row carrying those settings,
+		// rather than the header reporting a difference as something to fix.
+		const s = computeModelsStatus({
+			config: base(),
+			errors: [],
+			hookRegistered: true,
+			settings: { ...applied(), effortLevel: "high" },
+			resolveFullId: noFullId,
+		});
+		expect(s.state).toBe("on");
+		expect(s.drift).toEqual([]);
+	});
+
+	test("settings written by nobody at all is still not a fault", () => {
+		// The strongest form of the same claim, and the one the old `1 drift` badge described
+		// most misleadingly: every key absent counted as ONE message.
+		const s = computeModelsStatus({
+			config: base(),
+			errors: [],
+			hookRegistered: true,
+			settings: {},
+			resolveFullId: noFullId,
+		});
+		expect(s.state).toBe("on");
+		expect(s.drift).toEqual([]);
+	});
+
+	test("drift survives for the states that ARE faults", () => {
+		// The negative control for the three tests above: `drift` was not emptied everywhere,
+		// only where it described a difference. An unhooked config routes NOTHING, and that
+		// line is the reason why.
+		const s = computeModelsStatus({
+			config: base(),
+			errors: [],
+			hookRegistered: false,
+			settings: applied(),
+			resolveFullId: noFullId,
+		});
+		expect(s.state).toBe("unhooked");
+		expect(s.drift.length).toBeGreaterThan(0);
+	});
+
+	test("warns that CLAUDE_CODE_SUBAGENT_MODEL is now inert", () => {
+		const s = computeModelsStatus({
+			config: base(),
+			errors: [],
+			hookRegistered: true,
+			settings: applied(),
+			resolveFullId: noFullId,
+			subagentModelEnv: "claude-haiku-4-5",
+		});
+		expect(s.warnings.join(" ")).toContain("CLAUDE_CODE_SUBAGENT_MODEL");
+		expect(s.state).toBe("on");
+	});
+});
+
+describe("presets", () => {
+	/**
+	 * The first request shape still ships verbatim: fable on the orchestrator at `medium`.
+	 *
+	 * The second — "fable main, opus for other tasks, sonnet for quick tasks" — does NOT,
+	 * because the revised preset spec took opus out of `fable-lead` entirely and made it
+	 * fable in every seat but `cheap`. That is a deliberate change to what the preset means,
+	 * not a regression, and it is asserted here so the removal stays visible rather than
+	 * being discovered later as a surprise.
+	 */
+	test("fable-lead puts fable on the orchestrator at medium", () => {
+		const fable = findPreset("fable-lead");
+		expect(fable?.main).toEqual({ model: "fable", effort: "medium" });
+		// opus is gone from this preset; the only non-fable seat is `cheap`.
+		expect(
+			GRADES.map((grade) => baseAlias(fable?.grades[grade].model ?? "")),
+		).toEqual(["fable", "fable", "sonnet"]);
+	});
+
+	/**
+	 * The orchestrator never gets the most spend.
+	 *
+	 * This replaced a test that ranked the models against each other — `haiku < sonnet <
+	 * opus < fable` — and asserted `smart` held the top-ranked one. That is a CAPABILITY
+	 * claim, it was written from memory, and it went stale the moment the presets started
+	 * treating fable as the fast model rather than the strongest. Effort is the axis this
+	 * config actually controls, so the principle is stated in effort: the thread that
+	 * dispatches the work is never strictly the biggest spend in the preset.
+	 *
+	 * A tie is allowed. `sonnet-economy` runs `main` and `smart` both at `xhigh`, because
+	 * its saving is the MODEL rather than a throttled effort on top of one.
+	 */
+	test("no preset spends more on the orchestrator than on the work it dispatches", () => {
+		const level = (effort: string | undefined) =>
+			effort ? EFFORTS.indexOf(effort as Effort) : -1;
+		for (const p of BUILT_IN_PRESETS) {
+			const highestTier = Math.max(
+				...Object.values(p.grades).map((g) => level(g.effort)),
+			);
+			expect({
+				preset: p.preset,
+				mainIsNotTheBiggestSpend: level(p.main.effort) <= highestTier,
+			}).toEqual({ preset: p.preset, mainIsNotTheBiggestSpend: true });
+		}
+	});
+
+	/**
+	 * One model, one effort — the only cross-seat rule there is.
+	 *
+	 * `modelSettings` is keyed by model, so a preset naming one model in two seats at two
+	 * efforts cannot be written to settings at all: one value silently wins. This replaced a
+	 * test that fixed each model's effort across EVERY preset (`fable` always `medium`, and
+	 * so on). That was a convention invented to satisfy this constraint, not the constraint
+	 * itself, and it blocked legitimate presets — `fable-lead` and `fable-top` differ by
+	 * nothing except fable's effort, which is the whole point of having both.
+	 *
+	 * Presets never collide with each other; only one is applied to a project at a time.
+	 */
+	test("within one preset, a model appears at exactly one effort", () => {
+		for (const p of BUILT_IN_PRESETS) {
+			const efforts = new Map<string, Set<string>>();
+			const seats = [
+				{ seat: "main", model: p.main.model, effort: p.main.effort },
+				...GRADES.map((grade) => ({
+					seat: grade,
+					model: p.grades[grade].model,
+					effort: p.grades[grade].effort,
+				})),
+			];
+			for (const { model, effort } of seats) {
+				const alias = baseAlias(model);
+				if (alias === "inherit" || effort === undefined) continue;
+				const seen = efforts.get(alias) ?? new Set<string>();
+				seen.add(effort);
+				efforts.set(alias, seen);
+			}
+			for (const [alias, seen] of efforts) {
+				expect({ preset: p.preset, model: alias, efforts: [...seen] }).toEqual({
+					preset: p.preset,
+					model: alias,
+					efforts: [...seen].slice(0, 1),
+				});
+			}
+		}
+	});
+
+	test("no preset uses haiku", () => {
+		// Excluded deliberately, not by oversight — asserted so re-adding it is a decision.
+		for (const p of BUILT_IN_PRESETS) {
+			const models = [
+				p.main.model,
+				...GRADES.map((grade) => p.grades[grade].model),
+			].map(baseAlias);
+			expect({ preset: p.preset, usesHaiku: models.includes("haiku") }).toEqual(
+				{
+					preset: p.preset,
+					usesHaiku: false,
+				},
+			);
+		}
+	});
+
+	test("preset names are unique", () => {
+		expect(new Set(presetNames()).size).toBe(presetNames().length);
+	});
+
+	test("the shared agent table only names real grades", () => {
+		for (const [agent, grade] of Object.entries(DEFAULT_AGENT_GRADES)) {
+			expect({
+				agent,
+				ok: ["smart", "normal", "cheap"].includes(grade),
+			}).toEqual({ agent, ok: true });
+		}
+	});
+});
+
+describe("isRoutableModel", () => {
+	test("accepts the four aliases and nothing else", () => {
+		for (const a of ["opus", "sonnet", "haiku", "fable"])
+			expect(isRoutableModel(a)).toBe(true);
+		for (const bad of [
+			"inherit",
+			"claude-opus-5",
+			"opus[1m]",
+			"",
+			"kimi-k2-thinking",
+			null,
+			5,
+		])
+			expect(isRoutableModel(bad)).toBe(false);
+	});
+
+	/**
+	 * THE constraint the whole mate feature is built around.
+	 *
+	 * AMR-1 `bogus-model` measured 5/5 that a non-alias `model` refuses the spawn outright —
+	 * the session gets a tool error and no subagent at all. A mate is a non-alias by
+	 * construction, so a change that made this pass would not route agents to claudish, it
+	 * would stop the agents spawning. There is no version of this that is a nice improvement.
+	 */
+	test("a mate is NEVER routable — injecting one would refuse the spawn", () => {
+		for (const mate of MATES) expect(isRoutableModel(mate)).toBe(false);
+	});
+});
+
+describe("mates", () => {
+	test("isMate is exact — no prefix rule, no near match", () => {
+		for (const mate of MATES) expect(isMate(mate)).toBe(true);
+		// `mate10` is a typo, not a tenth slot; `Mate1` is a different string. Resolving
+		// either into a real slot would route an agent somewhere nobody named.
+		for (const bad of [
+			"mate",
+			"mate10",
+			"Mate1",
+			"mate3",
+			"kangaroo ",
+			"",
+			null,
+			3,
+		])
+			expect(isMate(bad)).toBe(false);
+	});
+
+	test("`kangaroo` is mate3 under another name, so all three are one vocabulary", () => {
+		expect([...MATES]).toEqual(["mate1", "mate2", "kangaroo"]);
+	});
+
+	test("a grade may name a mate, with no effort", () => {
+		const c = base();
+		(c.grades.smart as { model: string; effort?: Effort }).model = "mate1";
+		// biome-ignore lint/performance/noDelete: absence is the point — a mate carries none
+		delete (c.grades.smart as { effort?: Effort }).effort;
+		expect(validateModelsConfig(c)).toEqual([]);
+	});
+
+	test("an agent may be pinned to a mate", () => {
+		const c = base();
+		c.agents["dev:researcher"] = { model: "kangaroo" } as never;
+		expect(validateModelsConfig(c)).toEqual([]);
+		expect(resolveAgentRouting(c, "dev:researcher")).toEqual({
+			model: "kangaroo",
+			source: "agent-override",
+		});
+	});
+
+	test("main REJECTS a mate, and the message says why the main thread cannot take one", () => {
+		const c = base();
+		(c.main as { model: string }).model = "mate1";
+		const errors = validateModelsConfig(c);
+		expect(errors.map((e) => e.path)).toEqual(["main.model"]);
+		// Not a bare "must be one of …": the reason is that magus writes this value into
+		// settings.model, which has to name a model Claude Code itself runs.
+		expect(errors[0]?.message).toContain("settings.model");
+		expect(errors[0]?.message).toContain("claudish");
+	});
+
+	test("effort on a mate is ALLOWED — the rule reversed", () => {
+		// It used to be an error, on the reasoning that effort is keyed by model and a mate
+		// owns no `modelSettings` key. The key part is still true; the conclusion was wrong. A
+		// mate's effort is a per-call value handed to claudish, not a settings key, so there
+		// is nothing for it to collide with and no reason to refuse it.
+		//
+		// What must remain true is that it never reaches `modelSettings` — pinned separately,
+		// on `buildSettingsPatch`, because that is where the damage would be.
+		const onGrade = base();
+		onGrade.grades.cheap = { model: "mate2", effort: "high" } as never;
+		expect(validateModelsConfig(onGrade)).toEqual([]);
+
+		const onAgent = base();
+		onAgent.agents["dev:docs"] = { model: "mate1", effort: "low" } as never;
+		expect(validateModelsConfig(onAgent)).toEqual([]);
+	});
+
+	test("effort on `inherit` is STILL an error — the two questions are not the same one", () => {
+		// The half of the old rule that survives. `inherit` names no model at all, so there is
+		// no key AND no call to attach a value to; a mate names one claudish resolves.
+		const onGrade = base();
+		onGrade.grades.cheap = { model: "inherit", effort: "high" } as never;
+		const gradeErrors = validateModelsConfig(onGrade);
+		expect(gradeErrors.map((e) => e.path)).toEqual(["grades.cheap.effort"]);
+		expect(gradeErrors[0]?.message).toContain("inherit names no model");
+
+		const onAgent = base();
+		onAgent.agents["dev:docs"] = { model: "inherit", effort: "low" } as never;
+		expect(validateModelsConfig(onAgent).map((e) => e.path)).toEqual([
+			"agents.dev:docs.effort",
+		]);
+	});
+
+	test("two mates on the same model may declare different efforts", () => {
+		// Not a conflict, for the same reason the one-model-one-effort pass skips mates
+		// entirely: neither owns a `modelSettings` key, so neither can lose one to the other.
+		const c = base();
+		c.agents.a = { model: "mate1", effort: "low" } as never;
+		c.agents.b = { model: "mate2", effort: "xhigh" } as never;
+		c.mates = {
+			mate1: { model: "grok-4.6" },
+			mate2: { model: "grok-4.6" },
+		} as never;
+		expect(validateModelsConfig(c)).toEqual([]);
+	});
+
+	/**
+	 * Two seats on one mate is not the `modelSettings` conflict two seats on one alias is.
+	 *
+	 * The one-model-one-effort pass exists because `modelSettings` is keyed by model and one
+	 * key cannot hold two efforts. A mate owns no key at all, so there is nothing to collide
+	 * — and sending several agents to the same external model is the ordinary way to use a
+	 * slot, not a mistake to report.
+	 */
+	test("several agents may share one mate", () => {
+		const c = base();
+		c.agents.a = { model: "mate1" } as never;
+		c.agents.b = { model: "mate1" } as never;
+		(c.grades.cheap as { model: string; effort?: Effort }).model = "mate1";
+		// biome-ignore lint/performance/noDelete: absence is the point — a mate carries none
+		delete (c.grades.cheap as { effort?: Effort }).effort;
+		expect(validateModelsConfig(c)).toEqual([]);
+	});
+
+	/**
+	 * Validity may not depend on the machine reading the file.
+	 *
+	 * `models.json` is committed and shared through `profiles.json`, so if `mate1` were only
+	 * valid where `multimodel@magus` happens to be installed, the same file would be valid on
+	 * one teammate's laptop and invalid on the next one's — and the error would land on
+	 * whoever had not installed the plugin, over a routing decision they did not make.
+	 *
+	 * Pinned at the strongest available level: the module imports NOTHING, so there is no
+	 * seam through which a machine fact could reach the validator. Whether the slots are
+	 * DRAWN is a separate question, answered in the renderers from a boolean passed in.
+	 */
+	test("the core imports nothing, so validity cannot depend on the machine", () => {
+		// Comments are stripped first, the way hook-import-policy.test.ts does it: this file
+		// explains itself in English, and a sentence containing `from "…"` is not an import.
+		const specifiersOf = (file: string): string[] => {
+			const source = readFileSync(
+				path.join(import.meta.dir, "..", "services", file),
+				"utf-8",
+			)
+				.replace(/\/\*[\s\S]*?\*\//g, "")
+				.replace(/\/\/[^\n]*/g, "");
+			return [...source.matchAll(/\bfrom\s+["']([^"']+)["']/g)].map(
+				(match) => match[1] as string,
+			);
+		};
+		expect(specifiersOf("models-core.ts")).toEqual([]);
+		// Negative control: a regex that matched nothing would pass that forever.
+		expect(specifiersOf("models-manager.ts").length).toBeGreaterThan(0);
+	});
+});