@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/models/agent-runtimes.ts

@@ -0,0 +1,201 @@
+// What each agentic loop can do, one record per runtime, nothing about which provider runs on it. A capability is
+// listed only if something reads it: a gate, a control, or limitationsOf. This file is the bottom of the provider graph
+// and imports nothing from the rest of the contract, so the arrow points one way.
+
+// An execution backend: one way a turn runs its own work, named for AgentCapabilities.execution and the persona switch
+// that grants it.
+export type ExecutionBackend = "shell" | "js";
+
+export interface AgentCapabilities {
+    // Which loop serves the turn; `opencode-gemini` stays separate since adapter health keys off this field.
+    readonly runtime: "claude-code" | "codex" | "opencode" | "opencode-gemini" | "acp" | "pi" | "cursor";
+    // Mid-turn injection (the SteeringQueue behind /agent/steer); needs the SDK's streaming-input mode.
+    readonly steering: boolean;
+    // How much of the permission-mode axis the runtime honours: every PermissionMode, or just propose-then-approve.
+    readonly permissions: "modes" | "plan";
+    // Can stop mid-turn and ask the user a multiple-choice question (`question` frames).
+    readonly questions: boolean;
+    // Which tools reach the agent, full down to none; never rounded up or down from what a runtime has.
+    readonly mcp: "full" | "tools" | "browser" | "http" | "none";
+    // Which ways of executing the daemon stands behind here; distinct from `mcp`, which names tools, not execution.
+    readonly execution: readonly ExecutionBackend[];
+    // Reasoning-effort selection is forwarded to the model.
+    readonly effort: boolean;
+    // Whether the loop can ask for fast speed; the route's own answer is decided separately, at the endpoint.
+    readonly fastMode: boolean;
+    // How an isolated turn's worktree is enforced: a mount namespace, or merely cwd'd in, /work still shared.
+    readonly isolation: "namespace" | "cwd";
+    // Publishes its slash commands (`commands` frames) for the composer's `/` popover.
+    readonly commands: boolean;
+    // Runs its shell in a tmux session the terminal panel can attach to (`terminal` frames).
+    readonly terminals: boolean;
+    // Fails with the coded frames auto-resume keys off, so a turn the provider killed is re-run once it's back.
+    readonly recovery: boolean;
+    // How much of the owner's instructions this runtime takes: replace the base, append to it, or no seam at all.
+    readonly instructions: "replace" | "append" | "none";
+    // How the runtime discovers loaded skills: scans its own filesystem, or the daemon names them in the opener.
+    readonly skillDiscovery: "native" | "prompt";
+    // Whether the owner's safety policy reaches this runtime, and how:
+    // hooks - its own pre-execution hook can park a call and wait for a card (Claude Code only).
+    // approval - a vendor approval channel the daemon answers from policy; the vendor picks which calls to raise.
+    // refuse-only - the same channel, but a clock forces a refusal instead of a park.
+    // none - no seam before a command runs; treated as tainted, never as clean.
+    readonly rulebook: "hooks" | "approval" | "refuse-only" | "none";
+    // Whether a credential is masked; "none" is structural, only the Claude Code loop can rewrite a model's read.
+    readonly secrets: "masked" | "none";
+}
+
+// The Claude Code Agent SDK loop, the ceiling every other runtime is measured against: the only one that owns the whole
+// request (permission callbacks, the ask tool, plugins, hooks, the mount-namespace spawn seam).
+export const CLAUDE_CODE: AgentCapabilities = {
+    runtime: "claude-code",
+    steering: true,
+    permissions: "modes",
+    questions: true,
+    mcp: "full",
+    // The one loop with a seam for the daemon's own backend, so it hosts JS beside its Bash.
+    execution: ["shell", "js"],
+    effort: true,
+    fastMode: true,
+    isolation: "namespace",
+    commands: true,
+    terminals: true,
+    recovery: true,
+    instructions: "replace",
+    skillDiscovery: "native",
+    // The only runtime with its own pre-execution hook, so the only one where a hold can park instead of refusing.
+    rulebook: "hooks",
+    secrets: "masked",
+};
+
+// Codex app-server: item-level events, process-backed MCP, and four seams (steer, a question request, the skills list,
+// the shared mount namespace). Daemon-side servers, plugins, server approvals stay unwired.
+export const CODEX: AgentCapabilities = {
+    runtime: "codex",
+    steering: true,
+    permissions: "plan",
+    questions: true,
+    mcp: "browser",
+    execution: ["shell"],
+    effort: true,
+    fastMode: false,
+    isolation: "namespace",
+    commands: true,
+    terminals: false,
+    recovery: false,
+    // Both ride the per-thread config: one replaces Codex's base prompt, the other adds a developer message.
+    instructions: "replace",
+    skillDiscovery: "native",
+    // Asked only when the owner has written command rules; an unconfigured workspace pays nothing for it.
+    rulebook: "approval",
+    secrets: "none",
+};
+
+// OpenCode (the Grok runtime): its own agentic loop, its own tools, allow-all permissions. Takes a model id, a prompt
+// and one system message of ours; no effort scale, no tools of ours, no command list.
+export const OPENCODE: AgentCapabilities = {
+    runtime: "opencode",
+    steering: false,
+    permissions: "plan",
+    questions: false,
+    mcp: "none",
+    execution: ["shell"],
+    effort: false,
+    fastMode: false,
+    isolation: "cwd",
+    commands: false,
+    terminals: false,
+    recovery: false,
+    // `system` on the prompt body, per message; adds to OpenCode's own prompt, with no seam to replace it.
+    instructions: "append",
+    skillDiscovery: "prompt",
+    // refuse-only for its inactivity watchdog, not its protocol: a paused approval reads as a stalled turn.
+    rulebook: "refuse-only",
+    secrets: "none",
+};
+
+// The same OpenCode loop, serving Gemini instead of xAI, identical abilities. The Claude Code loop announces itself in
+// every request, which Google's Antigravity channel refuses; this loop's prompt makes no such announcement.
+export const OPENCODE_GEMINI: AgentCapabilities = {
+    ...OPENCODE,
+    runtime: "opencode-gemini",
+};
+
+// Any agent speaking the Agent Client Protocol: a documented floor, not the native ceiling. Publishes commands and
+// terminals, takes http MCP tools when offered, but owns its own model, effort and permission posture.
+export const ACP: AgentCapabilities = {
+    runtime: "acp",
+    steering: false,
+    permissions: "plan",
+    questions: false,
+    mcp: "http",
+    execution: ["shell"],
+    effort: false,
+    fastMode: false,
+    isolation: "cwd",
+    commands: true,
+    terminals: true,
+    recovery: false,
+    // ACP's calls carry no system field: the agent owns its instructions, the persona note rides the message.
+    instructions: "none",
+    skillDiscovery: "prompt",
+    // In the protocol floor, so every agent has it; which calls it asks about is entirely its own choice.
+    rulebook: "approval",
+    secrets: "none",
+};
+
+// Pi driven over its RPC mode: above the ACP floor and below the Claude Code ceiling. Real mid-turn steering, an effort
+// scale, and a published command list; no MCP seam, no approval channel, bash runs in-process with no terminal session.
+export const PI: AgentCapabilities = {
+    runtime: "pi",
+    steering: true,
+    permissions: "plan",
+    questions: false,
+    mcp: "none",
+    execution: ["shell"],
+    effort: true,
+    fastMode: false,
+    isolation: "cwd",
+    commands: true,
+    terminals: false,
+    recovery: false,
+    // Pi's RPC sets no standing instructions; like ACP, it hears the persona note through the user message.
+    instructions: "none",
+    skillDiscovery: "prompt",
+    // The one runtime with no seam at all: bash runs in-process, and no rule the owner writes can apply.
+    rulebook: "none",
+    secrets: "none",
+};
+
+// Cursor's own runtime, driven through `@cursor/sdk` in this daemon's process; an embedding surface, so most seams
+// other runtimes lack are function arguments here. The harness axis doesn't apply: the SDK is the only door.
+export const CURSOR: AgentCapabilities = {
+    runtime: "cursor",
+    // The SDK's Run can be cancelled but not written to mid-flight; a second send errors rather than injecting.
+    steering: false,
+    // Cursor's own plan mode, not this repo's emulation; not "modes" since the hook can't gate the whole surface.
+    permissions: "plan",
+    // True since the daemon supplies its own ask tool; Cursor's own can fabricate an answer, so it's disallowed.
+    questions: true,
+    // stdio + http/sse MCP servers plus host callbacks; everything but a Claude Code plugin checkout.
+    mcp: "tools",
+    execution: ["shell"],
+    // Cursor publishes effort as model parameters, not one scale; true here just means it's forwardable at all.
+    effort: true,
+    fastMode: false,
+    // cwd: Cursor's loop runs inside the daemon's own process, whose /work must stay the shared checkout.
+    isolation: "cwd",
+    // Cursor's commands are files on disk the SDK loads but doesn't publish back, so there's no list to offer.
+    commands: false,
+    // The SDK runs its shell in-process; there is no tmux session for the terminal panel to attach to.
+    terminals: false,
+    // The SDK throws typed errors instead of dissolving a refusal into prose, so the adapter files coded frames.
+    recovery: true,
+    // append, reached differently: `beforeSubmitPrompt`'s reply folds the prompt onto Cursor's base, unreplaceable.
+    instructions: "append",
+    skillDiscovery: "prompt",
+    // The full hook tier, the only foreign runtime to reach it: a hold parks since the vendor waits on the hook.
+    rulebook: "hooks",
+    // none, structurally: its hooks only allow/deny or are discarded, nothing here to substitute a reference into.
+    secrets: "none",
+};

package/src/models/capability-ledger.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { capabilitiesOf, limitationsOf } from "./agent-catalog.js";
+import type { AgentCapabilities } from "./agent-runtimes.js";
+
+// Whether a capability claim is backed by an enforcement seam or merely descriptive prose reaching the user through
+// limitationsOf; the split must stay exhaustive against AgentCapabilities.
+
+type Backing = "enforced" | "descriptive";
+
+const LEDGER: Record<keyof AgentCapabilities, Backing> = {
+    // adapter-registry.ts maps this runtime to its serving adapter; also keys per-runtime health probes.
+    runtime: "enforced",
+    // conversation.ts's `steerable`: the composer offers mid-turn injection only where there is a queue.
+    steering: "enforced",
+    // turn-plan.ts forwards permissionMode only under "modes"; the composer's mode list is built from it.
+    permissions: "enforced",
+    // turn-plan.ts opens the tool seam on "full"; anything less gets the setup notice instead.
+    mcp: "enforced",
+    // turn-plan.ts drops effort unless the runtime takes it; ComposerEffort.vue renders no scale without it.
+    effort: "enforced",
+    // turn-plan.ts drops fast unless the loop can request it; fastAllowed, not this field, is the real answer.
+    fastMode: "enforced",
+    // turn-plan.ts tells a "cwd" turn its worktree path; under "namespace" the mount makes that unnecessary.
+    isolation: "enforced",
+    // system-prompt.ts composes standing instructions against this: replace, append, or a user-message note.
+    instructions: "enforced",
+    // turn-plan.ts notes the catalogue only for "prompt"; "native" runtimes use their own loader instead.
+    skillDiscovery: "enforced",
+    // turn-plan.ts plans jsExecution only where "js" is declared; without it no Code tool is mounted.
+    execution: "enforced",
+    // turn-plan.ts carries this on every request; guard/turn-gate.ts derives the gate's shape from it:
+    // - none: no consult, taint bit stays permanently set
+    // - refuse-only: a hold refuses instead of parking
+    // - other values: park on a card
+    rulebook: "enforced",
+
+    // Descriptive: true of the runtime but nothing consults these; wiring one up moves it to enforced.
+    questions: "descriptive",
+    commands: "descriptive",
+    terminals: "descriptive",
+    recovery: "descriptive",
+    // descriptive: only the Claude Code loop can mask a secret before the model reads it, via its PostToolUse hook.
+    secrets: "descriptive",
+};
+
+// Every ability true, read live from the catalog: the ceiling limitationsOf has nothing to disclose against.
+const CEILING = capabilitiesOf("claude", "native");
+
+const fieldsWhere = (backing: Backing): (keyof AgentCapabilities)[] =>
+    (Object.keys(LEDGER) as (keyof AgentCapabilities)[]).filter((field) => LEDGER[field] === backing);
+
+it("classifies exactly the fields a live record carries", () => {
+    expect(Object.keys(LEDGER).toSorted()).toEqual(Object.keys(CEILING).toSorted());
+});
+
+// Checked per field rather than by an aggregate count, so one field silently contributing nothing still fails.
+describe("a descriptive claim reaches the user", () => {
+    it("has something to disclose against: the ceiling discloses nothing", () => {
+        expect(limitationsOf(CEILING)).toEqual([]);
+    });
+
+    // A boolean field's floor is false; every other descriptive field must name its own weak value here.
+    const DIMINISHED: Partial<Record<keyof AgentCapabilities, unknown>> = { secrets: "none" };
+
+    it.each(fieldsWhere("descriptive"))("%s puts its own sentence in the picker when the runtime lacks it", (field) => {
+        const boolean = typeof CEILING[field] === "boolean";
+        // A boolean's floor is false and needs no entry here; every other descriptive field must have one or this
+        // fails.
+        expect(
+            boolean ? [field] : Object.keys(DIMINISHED),
+            `${field} is descriptive and not a boolean: add its weakest value to DIMINISHED above`,
+        ).toContain(field);
+        const floor = boolean ? false : DIMINISHED[field];
+
+        const lacking: AgentCapabilities = { ...CEILING, [field]: floor };
+
+        expect(limitationsOf(lacking)).toHaveLength(1);
+    });
+});
+
+it("is a real split: neither side is empty", () => {
+    expect(fieldsWhere("enforced").length).toBeGreaterThan(0);
+    expect(fieldsWhere("descriptive").length).toBeGreaterThan(0);
+});

package/src/{fast-tier.test.ts → models/fast-tier.test.ts}

@@ -1,13 +1,8 @@
 import { expect, test } from "vitest";
 import { fastTierModel } from "./fast-tier.js";
 
-/* WHERE A DOWNGRADED TURN ACTUALLY LANDS. The judge (prompt-complexity.ts) says a turn could be cheaper; this
- * says whether there is anywhere cheaper to put it, on the provider it is already on.
- *
- * Two properties carry the whole feature, and everything below is one of them: a downgrade is only ever to a
- * genuinely CHEAPER rung of the same catalog (so "cheaper" can never quietly become "older", or "the same model
- * with less thinking"), and it never crosses PROVIDER (because that retires the conversation's session, which
- * throws away the context that made the follow-up cheap to answer in the first place). */
+// Whether a downgraded turn has anywhere cheaper to land on its current provider; a downgrade must be a genuinely
+// cheaper rung of the same catalog and never cross provider, since that retires the session.
 
 const CLAUDE = [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`];
 const GOOGLE = [`gemini-3-pro`, `gemini-3-flash`, `gemini-3-flash-lite`];
@@ -28,20 +23,16 @@ test("reads the cheap end the same way the quick model does, on every vendor's v
 // --- the ceiling: the user's own pick -------------------------------------------------------------------
 
 test("a user already on the cheap rung has nowhere to be sent", () => {
-    // The common case worth being exact about rather than an edge case. Undefined means "run what they asked
-    // for", which is the honest answer and the one that costs nothing to be wrong about.
+    // undefined means run the original pick: the safe default when nothing is cheaper.
     expect(fastFor(`claude-haiku-4-5-20251001`)).toBeUndefined();
 });
 
 test("never swaps a model for an older build of the same tier", () => {
-    // A downgrade has to be legible AS a downgrade. Last year's Sonnet under this year's Sonnet is not a
-    // saving the feature promised, it is a different turn wearing the user's own model name.
     expect(fastFor(`claude-sonnet-5`, { models: [`claude-sonnet-5`, `claude-sonnet-4`] })).toBeUndefined();
 });
 
 test("never downgrades a model whose family this build does not recognise", () => {
-    // An id carrying no tier word is a provider's base line or a family nobody here has heard of, and betting
-    // a user's turn on the guess that an unknown id is the budget one is the wrong direction to be wrong in.
+    // An id with no tier word is either the provider's own baseline or an unrecognised family.
     expect(fastFor(`claude-opus-5`, { models: [`some-new-thing`] })).toBeUndefined();
     expect(fastFor(`some-new-thing`, { models: CLAUDE })).toBeUndefined();
 });
@@ -61,19 +52,17 @@ test("a pin on this provider wins over the catalog's own cheap end", () => {
 });
 
 test("takes a pinned id verbatim, so a model the static catalog has not caught up with is still pinnable", () => {
-    // The same call readyChain makes, and for the same reason: the picker offers a custom-id escape
-    // hatch, and second-guessing the id here would run a different model than the settings row names.
+    // Takes a pinned id verbatim: second-guessing it would run a different model than the settings row names.
     expect(fastFor(`claude-opus-5`, { pinned: [`claude:claude-haiku-9`] })).toBe(`claude-haiku-9`);
 });
 
 test("drops a pin naming another provider rather than crossing to it", () => {
-    // Switching provider retires the conversation's session (turnRequest.ts `resumes`). Starting the
-    // conversation over to save a fraction of a cent is not a saving, so the pin is ignored and Auto answers.
+    // Crossing provider retires the session (turnRequest.ts's resumes); the pin is ignored instead.
     expect(fastFor(`claude-opus-5`, { pinned: [`gemini:gemini-3-flash-lite`] })).toBe(`claude-haiku-4-5-20251001`);
 });
 
 test("skips a pin that is not actually cheaper than what the user picked", () => {
-    // A pin is a preference about WHICH cheap rung, never a licence to swap a model for its equal or better.
+    // A pin picks which cheap rung, never licence to swap to an equal or better model.
     expect(fastFor(`claude-sonnet-5`, { pinned: [`claude:claude-opus-5`] })).toBe(`claude-haiku-4-5-20251001`);
 });
 

package/src/models/fast-tier.ts

@@ -0,0 +1,36 @@
+import { compareCheapestFirst, isCheaperRung } from "./model-order.js";
+import { parsePinned } from "./model-pins.js";
+import type { AgentProvider } from "../schemas/agent.js";
+
+// Picks which model a downgraded turn runs on, once prompt-complexity.ts decides a turn could be cheaper. Only routes
+// down to a cheaper rung of the model the user already picked; ambiguous cases resolve to undefined, meaning run their
+// pick. Never crosses provider: that retires the session and loses the context that made the follow-up cheap.
+
+export interface FastTierInput {
+    readonly provider: AgentProvider;
+    // Empty means the composer has not resolved a pick yet; that resolves to no downgrade, not a guess.
+    readonly model: string;
+    // Empty is a real state (catalog not loaded yet), and resolves to no downgrade rather than a guess.
+    readonly models: readonly string[];
+    // settings.autoFastModels: ordered `${provider}:${modelId}` keys, empty for Auto; other providers drop.
+    readonly pinned: readonly string[];
+}
+
+// A pin is taken verbatim but must still be cheaper than the pick; Auto falls back to the cheapest rung, in the same
+// cheap-first order the quick model uses. Undefined means nothing is cheaper.
+export const fastTierModel = (input: FastTierInput): string | undefined => {
+    if (input.model === "") {
+        return undefined;
+    }
+    const pinned = input.pinned
+        .flatMap((key) => {
+            const choice = parsePinned(key);
+            return choice === undefined || choice.provider !== input.provider ? [] : [choice.model];
+        })
+        .find((model) => isCheaperRung(model, input.model));
+    if (pinned !== undefined) {
+        return pinned;
+    }
+    const cheapest = input.models.toSorted(compareCheapestFirst)[0];
+    return cheapest !== undefined && isCheaperRung(cheapest, input.model) ? cheapest : undefined;
+};

package/src/{model-order.test.ts → models/model-order.test.ts}

@@ -1,17 +1,14 @@
 import { expect, test } from "vitest";
 import { compareCheapestFirst, compareModelIds, compareUnrankedModelIds, familyOf, namesThinking, releaseOf, tierRankOf } from "./model-order.js";
 
-/* The order every provider's catalog is served and browsed in. The rule exists because only Anthropic publishes
- * a ranking: the OpenAI-compatible endpoints behind Codex, Gemini, Kimi and Grok hand back a SET, and taking
- * their registry order for a preference is what opened the Codex group on GPT 5.4 Mini and started fresh Codex
- * conversations on whichever id sorted first. */
+// The order every provider's catalog is served and browsed in; only Anthropic's catalog arrives ranked, the rest hand
+// back sets, so their registry order is not a preference.
 
 // A Codex catalog exactly as an OpenAI-compatible /v1/models hands it over: alphabetical, i.e. meaningless.
 const CODEX = ["gpt-5.1-codex", "gpt-5.4-mini", "gpt-5.5", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra"];
 
 test("ranks the frontier line above the cheap one and the newest release above its predecessors", () => {
-    // The base line (no tier word) leads, newest first; the mini rung sinks under all of it regardless of how
-    // recently it shipped, which is the whole decision a user makes in this list.
+    // The base (no-tier) line leads, newest first; mini sinks below all of it regardless of recency.
     expect(CODEX.toSorted(compareModelIds)).toEqual(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.1-codex", "gpt-5.4-mini"]);
 });
 
@@ -43,13 +40,12 @@ test("the Codex release-tier order is stable across catalog refreshes", () => {
     for (const arrival of arrivals) {
         expect(arrival.toSorted(compareUnrankedModelIds)).toEqual(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]);
     }
-    // Same rule, so ranking still outranks the tiebreak: the mini rung stays at the tail, under every sibling.
+    // Ranking still outranks the tiebreak: mini stays at the tail under every sibling.
     expect(["gpt-5.4-mini", ...arrivals[0]!].toSorted(compareUnrankedModelIds).at(-1)).toBe("gpt-5.4-mini");
 });
 
 test("leaves a RANKED catalog's ties alone: the id tiebreak is for sets, and Anthropic publishes an opinion", () => {
-    // compareUnrankedModelIds would seat claude-fable-5 ahead of claude-opus-5 on the id alone. Anthropic's
-    // catalog arrives newest-first, so that order is a fact about the provider, not a leftover to be broken.
+    // compareUnrankedModelIds would rank fable ahead of opus by id; ranked catalogs keep the provider's own order.
     expect(["claude-opus-5", "claude-fable-5"].toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-fable-5"]);
     expect(["claude-opus-5", "claude-fable-5"].toSorted(compareUnrankedModelIds)).toEqual(["claude-fable-5", "claude-opus-5"]);
 });
@@ -82,20 +78,17 @@ test("reads Kimi's k-prefixed generation so K3 leads the K2.x catalog", () => {
 });
 
 test("the rightmost tier word wins, because tier words compose", () => {
-    // flash-lite is the cheap end of Flash, codex-max the frontier end of Codex: reading the leftmost word
-    // instead would file both under the tier they modify.
+    // flash-lite is Flash's cheap end, codex-max is Codex's frontier end; the leftmost word would misfile both.
     expect(tierRankOf(familyOf("gemini-3-flash-lite"))).toBe(tierRankOf("lite"));
     expect(tierRankOf(familyOf("gpt-5.1-codex-max"))).toBe(tierRankOf("max"));
 });
 
 test("leads with a family carrying no tier word at all, so a brand-new flagship is never buried by its novelty", () => {
-    // The precise inverse of the ranking this replaced, which sank unrecognized ids BELOW the everyday tier.
     expect(["claude-sonnet-5", "claude-mythos-1", "claude-opus-5"].toSorted(compareModelIds)[0]).toBe("claude-mythos-1");
 });
 
 test("files a re-served open-weights model on the cheap rung, not at the head of the catalog it visits", () => {
-    // Google's channel vends gpt-oss beside Gemini and Claude. It carries no tier word of its own, so the
-    // lead-the-unknown rule would open that whole section on it: above Opus.
+    // gpt-oss also ships on Google's channel; with no tier word, lead-unknown would wrongly rank it above Opus.
     expect(["gpt-oss-120b-medium", "claude-opus-4-6-thinking", "gemini-pro-agent"].toSorted(compareModelIds)).toEqual([
         "claude-opus-4-6-thinking",
         "gemini-pro-agent",
@@ -104,7 +97,6 @@ test("files a re-served open-weights model on the cheap rung, not at the head of
 });
 
 test("keeps the arrival order between ids the rule cannot separate: Anthropic's catalog IS ranked", () => {
-    // Same tier, same version: nothing here outranks the order the provider itself reported.
     expect(["claude-opus-5", "claude-fable-5"].toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-fable-5"]);
     expect(["claude-fable-5", "claude-opus-5"].toSorted(compareModelIds)).toEqual(["claude-fable-5", "claude-opus-5"]);
 });
@@ -123,8 +115,6 @@ test("stands an id with nothing but numbers (and an ACP row's empty one) as its
 });
 
 test("holds date stamps apart from version components, or a dated build outranks the point release after it", () => {
-    // The failure this prevents: claude-opus-4-1-20250805 (Opus 4.1) read as (4,1,20250805) loses to
-    // claude-opus-4-20250514 (Opus 4.0) read as (4,20250514): the older model, by six digits.
     expect(releaseOf("claude-opus-4-1-20250805")).toEqual({ version: [4, 1], date: 20250805 });
     expect(["claude-opus-4-20250514", "claude-opus-4-1-20250805"].toSorted(compareModelIds)).toEqual([
         "claude-opus-4-1-20250805",
@@ -144,14 +134,13 @@ test("reads a longer version as the newer one, so 5.1 outranks 5", () => {
 });
 
 test("sorts an unversioned rolling alias under the releases that name their version", () => {
-    // `kimi-latest` claims no release; guessing one for it would seat it above models that do say what they are.
+    // `kimi-latest` claims no release; guessing one would seat it above models that do say what they are.
     expect(releaseOf("kimi-latest").version).toEqual([]);
     expect(["kimi-latest", "kimi-k2-0711-preview"].toSorted(compareModelIds)).toEqual(["kimi-k2-0711-preview", "kimi-latest"]);
 });
 
-// --- the cheap end (compareCheapestFirst) ---------------------------------------------------------------
-// What the quick model behind a one-click helper resolves against: the same tier scale, read for the weakest
-// row instead of the strongest.
+// compareCheapestFirst: what the quick model's one-click helper resolves against, the same tier scale read
+// weakest-first.
 
 test("opens on the efficient rung and buries the frontier one: the exact inverse of the picker's order", () => {
     const claude = ["claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5-20251001"];
@@ -161,9 +150,7 @@ test("opens on the efficient rung and buries the frontier one: the exact inverse
 });
 
 test("keeps an UNRANKED family off the cheap end, where a plain reversal would have seated it first", () => {
-    // The whole reason this is not `-compareModelIds`. An id with no tier word is the provider's base line, and
-    // an unheard-of family is likelier the next flagship than the next budget tier, so both orders agree it is
-    // not the efficient rung, and a helper never spends frontier money on a commit message.
+    // An id with no tier word is the provider's baseline, likelier the next flagship than a budget tier.
     expect(["gpt-5.6", "gpt-5.4-mini"].toSorted(compareCheapestFirst)).toEqual(["gpt-5.4-mini", "gpt-5.6"]);
     expect(["claude-mythos-1", "claude-haiku-4-5", "claude-sonnet-5"].toSorted(compareCheapestFirst).at(-1)).toBe("claude-mythos-1");
 });
@@ -176,8 +163,7 @@ test("takes the NEWEST build of the cheap rung, not merely any of them", () => {
 
 test("finds each vendor's own cheap rung, including a re-served open-weights row", () => {
     expect(["gemini-3-pro", "gemini-3-flash", "gemini-3-flash-lite"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3-flash-lite");
-    // Google's channel vends gpt-oss beside Gemini's own line; it is there to be the cheap option, and `oss`
-    // is what says so: without that word the id carries no tier at all and would sink to the bottom.
+    // gpt-oss is Google's cheap option; `oss` is its only tier signal, without it the id would sink instead of lead.
     expect(["claude-opus-4-6-thinking", "gpt-oss-120b-medium"].toSorted(compareCheapestFirst)[0]).toBe("gpt-oss-120b-medium");
     expect(["grok-4", "grok-4-fast"].toSorted(compareCheapestFirst)[0]).toBe("grok-4-fast");
 });
@@ -187,38 +173,31 @@ test("reads a release-local tier ladder from the cheap end too", () => {
 });
 
 test("refuses the thinking variant of a model, however new it is", () => {
-    /* The bug this rule exists for, in the shape the live catalog actually publishes it: a routed channel vends
-     * one row per thinking LEVEL, and the newest row of the cheapest model was the high one, so the ladder
-     * whose whole job is to be the cheap rung reached for the most expensive reading of it, and a commit
-     * message that takes 2s took closer to 30. */
+    // A routed channel vends one row per thinking level; the cheapest model's top row must not win here.
     expect(["gemini-3.6-flash-high", "gemini-3.5-flash-extra-low"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.5-flash-extra-low");
-    // …and it is the LEVEL that decides, not the release: same model, quieter row wins.
+    // …and it is the level that decides, not the release: same model, quieter row wins.
     expect(["gemini-3.5-flash-high", "gemini-3.5-flash-minimal"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.5-flash-minimal");
-    // Tier still outranks it: a thinking cheap model beats a silent expensive one, which is the order that
-    // keeps this from quietly promoting a frontier row for being unannotated.
+    // Tier still outranks thinking: a cheap thinking model beats a silent expensive one.
     expect(["gemini-3-pro", "gemini-3.6-flash-high"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.6-flash-high");
-    // An id nobody annotated is not accused of thinking, and is not credited with silence either: it sits
-    // between the stated ends.
+    // An unannotated id is neither accused of thinking nor credited with silence: it sits between the stated ends.
     expect(["gemini-3-flash", "gemini-3.5-flash-low"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.5-flash-low");
     expect(["gemini-3-flash", "gemini-3.6-flash-high"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3-flash");
 });
 
 test("names the thinking rows, and only those", () => {
-    // What a settings row shows beside a pin, so that choosing one is a choice rather than an accident.
+    // What a settings row shows beside a pin.
     expect(namesThinking("gemini-3.6-flash-high")).toBe(true);
     expect(namesThinking("gemini-3.1-pro-low")).toBe(false);
     expect(namesThinking("gemini-3.5-flash-extra-low")).toBe(false);
     expect(namesThinking("claude-haiku-4-5-20251001")).toBe(false);
     expect(namesThinking("gpt-5.6-luna")).toBe(false);
-    // An effort word that is not `high` still names one; so does the on/off form a channel vends beside its
-    // quiet row.
+    // An effort word other than `high` still names one; so does the on/off form beside its quiet row.
     expect(namesThinking("gpt-oss-120b-medium")).toBe(true);
     expect(namesThinking("kimi-k2-thinking")).toBe(true);
     expect(namesThinking("kimi-k2")).toBe(false);
 });
 
 test("falls back on the newest release for a catalog that publishes no cheap tier at all", () => {
-    // Kimi names no tier word anywhere, so every row is UNRANKED and the tier term cancels. Serving the newest
-    // of what it does publish is the honest answer: there is no cheaper rung to find.
+    // Kimi names no tier word anywhere; with tier cancelled out, newest is the honest fallback.
     expect(["kimi-k2-0711-preview", "kimi-k2-0905-preview"].toSorted(compareCheapestFirst)[0]).toBe("kimi-k2-0905-preview");
 });