@intentic/sandbox-contract 1.247.0 → 1.248.0

package/src/model-pins.test.ts

@@ -1,19 +1,17 @@
 import { expect, test } from "vitest";
-import { type ModelSource, modelPinKey, parsePinned, resolveRoleModels } from "./model-pins.js";
+import { type ModelSource, modelPinKey, parsePinned, readyChain } from "./model-pins.js";
 import type { ModelPin } from "./schemas/agent.js";
 
 /* Which models a job spends, and in which order. The rule answers two surfaces at once: the daemon walks it,
- * the browser names its head in that job's settings row, so what these tests pin is that a sandbox's
- * connections alone decide it, with no stored id to go stale, and that there is always a rung underneath the
- * first one whenever the sandbox has another account to reach for.
+ * the browser names its head in that job's settings row, so what these tests pin is that the OWNER'S OWN LIST
+ * decides it and nothing else, and that there is a rung underneath the first one whenever they wrote one.
  *
- * `commit-message` and `pipeline-fix` stand in for the two KINDS of role here (model-roles.ts): the first is a
- * one-shot, whose empty list derives the Auto ladder, and the second is a whole session, whose empty list
- * resolves to nothing so the caller's own composer pick answers. Everything else about the two is identical,
- * which is why one resolver serves both. */
-
-const HELPER = `commit-message` as const;
-const RUN = `pipeline-fix` as const;
+ * NOTHING IS DERIVED FOR AN EMPTY LIST, and that is the property most of this file used to be about. A `helper`
+ * role with no models used to fall to an "Auto ladder" — every connected provider's cheapest row, best-first —
+ * so a sandbox nobody had configured still spent an account on commit messages and safety verdicts, on a
+ * ranking this package invented and re-ranked whenever an account was connected. Not set now means not set,
+ * for every role, and what the caller does with an empty answer is the caller's business: a one-shot does not
+ * run, a whole session opens on the owner's own composer pick. */
 
 // A pin as the settings rows store one. The tests are about ORDER, so most of them name only the pair; the
 // knobs an entry can carry ride through untouched and are asserted where that matters.
@@ -22,7 +20,8 @@ const pin = (key: string): ModelPin => {
     return { provider: key.slice(0, at), model: key.slice(at + 1) };
 };
 
-// Catalogs as their providers actually publish them: Claude's ranked list, the rest in registry order.
+// Catalogs as their providers actually publish them. The resolver reads none of them — a pin is taken verbatim
+// — but a ModelSource carries one, and a fixture that lied about it would hide a resolver that started looking.
 const CLAUDE: ModelSource = { provider: `claude`, ready: true, models: [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`] };
 const GOOGLE: ModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-flash`, `gemini-3-flash-lite`, `gemini-3-pro`] };
 const CODEX: ModelSource = { provider: `codex`, ready: true, models: [`gpt-5.4-mini`, `gpt-5.6`] };
@@ -30,42 +29,9 @@ const KIMI: ModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2.6`,
 
 const offline = (source: ModelSource): ModelSource => ({ ...source, ready: false });
 
-// The model that answers when nothing goes wrong: the head of the chain, which is what most of what follows is
-// about and what every surface naming the spend up front reads.
-const head = (sources: readonly ModelSource[], pinned: readonly string[]): ModelPin | undefined =>
-    resolveRoleModels(sources, pinned.map(pin), HELPER)[0];
-
-test("reaches for the efficient rung of the one connected provider, never its flagship", () => {
-    expect(head([CLAUDE], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
-});
-
-test("spends the FREE channel over the subscription when both offer the same rung", () => {
-    // Both publish a cheap-tier row, so nothing separates them on capability, and one of them costs the user
-    // nothing while the other eats headroom they watch. A background helper should not quietly bill the Claude plan.
-    expect(head([CLAUDE, GOOGLE], [])).toEqual({ provider: `gemini`, model: `gemini-3-flash-lite` });
-});
-
-test("puts tier ahead of cost: a free frontier model is still the wrong tool for a commit message", () => {
-    // Google connected but publishing only its Pro line. Ordering on price first would seat a flagship here,
-    // which is the exact outcome the feature exists to avoid.
-    const proOnly: ModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-pro`] };
-
-    expect(head([CLAUDE, proOnly], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
-});
-
-test("uses stable provider order when two subscriptions offer the same tier", () => {
-    const kimiCheap: ModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-mini`] };
-    const claudeCheap: ModelSource = { provider: `claude`, ready: true, models: [`claude-haiku-4-5`] };
-
-    expect(head([kimiCheap, claudeCheap], [])?.provider).toBe(`claude`);
-});
-
-test("answers the same thing however the connected providers happen to be listed", () => {
-    // The daemon assembles these from live stores and the browser from its own refs; neither order is a fact.
-    const answers = [head([CLAUDE, GOOGLE, CODEX], []), head([CODEX, CLAUDE, GOOGLE], []), head([GOOGLE, CODEX, CLAUDE], [])];
-
-    expect(new Set(answers.map((answer) => modelPinKey(answer!))).size).toBe(1);
-});
+// The model that answers when nothing goes wrong: the head of the chain, which is what every surface naming
+// the spend up front reads.
+const head = (sources: readonly ModelSource[], pinned: readonly string[]): ModelPin | undefined => readyChain(sources, pinned.map(pin))[0];
 
 test("honours a pinned model verbatim, including an id no catalog lists yet", () => {
     expect(head([CLAUDE, GOOGLE], [`claude:claude-opus-5`])).toEqual({ provider: `claude`, model: `claude-opus-5` });
@@ -74,14 +40,6 @@ test("honours a pinned model verbatim, including an id no catalog lists yet", ()
     expect(head([CLAUDE], [`claude:claude-haiku-9`])).toEqual({ provider: `claude`, model: `claude-haiku-9` });
 });
 
-test("falls back to Auto when the pinned provider is no longer connected", () => {
-    // Rather than failing every click with a credential error while the sandbox can plainly still answer.
-    expect(head([offline(CLAUDE), GOOGLE], [`claude:claude-haiku-4-5-20251001`])).toEqual({
-        provider: `gemini`,
-        model: `gemini-3-flash-lite`,
-    });
-});
-
 /* A MALFORMED KEY IS REFUSED WHERE KEYS STILL EXIST. A role's list holds PINS, whose two halves are separate
  * fields the schema requires (ModelPinSchema), so "claude with an empty model" is no longer a shape the
  * resolver can be handed — it is rejected at the settings boundary instead. What still travels as a key is
@@ -93,53 +51,35 @@ test("refuses a malformed key rather than reading half a pin out of it", () => {
     expect(parsePinned(`claude:claude-haiku-4-5`)).toEqual({ provider: `claude`, model: `claude-haiku-4-5` });
 });
 
-/* THE TWO KINDS OF ROLE DIFFER ON EXACTLY ONE THING: what an empty list means. It is the whole reason the
- * resolver takes a role rather than a boolean, and the reason the two used to be separate files. */
-test("derives a ladder for an unpinned one-shot and nothing at all for an unpinned session", () => {
-    // A commit message exists to stay off the frontier tier, so working it out from what is connected is a good
-    // answer and gets better as accounts are added.
-    expect(resolveRoleModels([CLAUDE, GOOGLE], [], HELPER)).toEqual([
-        { provider: `gemini`, model: `gemini-3-flash-lite` },
-        { provider: `claude`, model: `claude-haiku-4-5-20251001` },
-    ]);
-    // A pipeline fix is a whole session billed whole, and nothing here can judge what one is worth — so the
-    // caller's own floor (the owner's composer pick) answers instead of a ladder this file invented.
-    expect(resolveRoleModels([CLAUDE, GOOGLE], [], RUN)).toEqual([]);
+/* THE CLAIM THIS FILE EXISTS FOR NOW. An unset job resolves to NOTHING however much is connected, and it does
+ * so for both kinds of role: a resolver that reached for the cheapest rung here is the whole feature that was
+ * removed, and it would come back invisibly — the daemon would simply start spending again and the settings
+ * row would look unchanged. */
+test("resolves an unset job to nothing, however many accounts are connected", () => {
+    expect(readyChain([CLAUDE, GOOGLE, KIMI], [])).toEqual([]);
+    expect(head([CLAUDE, GOOGLE], [])).toBeUndefined();
 });
 
-test("carries an entry's run settings through untouched, on either kind of role", () => {
+test("carries an entry's run settings through untouched", () => {
     // The resolver picks WHICH entry; how that entry runs is the entry's own business and rides along whole,
     // because the turn (or the one-shot) is composed from all of it.
     const configured: ModelPin = { provider: `claude`, model: `claude-opus-5`, effort: `max`, thinking: true, harness: `claude-code` };
 
-    expect(resolveRoleModels([CLAUDE], [configured], RUN)).toEqual([configured]);
-    expect(resolveRoleModels([CLAUDE], [configured], HELPER)).toEqual([configured]);
-});
-
-test("serves the newest of a catalog that publishes no cheap tier at all", () => {
-    // Kimi names no tier word anywhere. There is no cheaper rung to find, so the newest row is the honest answer.
-    expect(head([KIMI], [])).toEqual({ provider: `kimi`, model: `kimi-k3` });
+    expect(readyChain([CLAUDE], [configured])).toEqual([configured]);
 });
 
-test("reports nothing when no account is connected, so the button can say so instead of failing on click", () => {
-    expect(head([offline(CLAUDE), offline(GOOGLE)], [])).toBeUndefined();
-    expect(resolveRoleModels([offline(CLAUDE), offline(GOOGLE)], [], HELPER)).toEqual([]);
+test("reports nothing when the accounts a job named have all gone", () => {
+    // A live button that fails on click is the failure this prevents: the caller renders the state instead.
+    expect(head([offline(CLAUDE), GOOGLE], [`claude:claude-haiku-4-5-20251001`])).toBeUndefined();
     expect(head([], [`claude:claude-haiku-4-5`])).toBeUndefined();
 });
 
-test("skips a connected provider whose catalog has not loaded yet", () => {
-    const unloaded: ModelSource = { provider: `grok`, ready: true, models: [] };
-
-    expect(head([unloaded, CLAUDE], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
-    expect(head([unloaded], [])).toBeUndefined();
-});
-
 /* THE CHAIN: what the daemon walks when the model at the top of it refuses. A spent allowance is the ordinary
  * case, not the exotic one: the account a helper shares with the chat runs out mid-afternoon, and the whole
  * point of the list is that the click still lands on the next rung down. */
 
 test("keeps the pinned models in the order they were written", () => {
-    expect(resolveRoleModels([CLAUDE, GOOGLE, CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5-20251001`].map(pin), HELPER)).toEqual([
+    expect(readyChain([CLAUDE, GOOGLE, CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5-20251001`].map(pin))).toEqual([
         { provider: `codex`, model: `gpt-5.6` },
         { provider: `gemini`, model: `gemini-3-flash` },
         { provider: `claude`, model: `claude-haiku-4-5-20251001` },
@@ -147,7 +87,7 @@ test("keeps the pinned models in the order they were written", () => {
 });
 
 test("drops a pin whose provider went away and keeps the rest of the order intact", () => {
-    expect(resolveRoleModels([CLAUDE, offline(GOOGLE), CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5`].map(pin), HELPER)).toEqual([
+    expect(readyChain([CLAUDE, offline(GOOGLE), CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5`].map(pin))).toEqual([
         { provider: `codex`, model: `gpt-5.6` },
         { provider: `claude`, model: `claude-haiku-4-5` },
     ]);
@@ -156,24 +96,17 @@ test("drops a pin whose provider went away and keeps the rest of the order intac
 test("stops at the end of a pinned list rather than reaching for an account the user left out", () => {
     // Google and Kimi are connected and cheaper. The user wrote down one model, so one model is what this may
     // spend: a pin exists precisely to keep a helper off the accounts it does not name.
-    expect(resolveRoleModels([CLAUDE, GOOGLE, KIMI], [`claude:claude-haiku-4-5`].map(pin), HELPER)).toEqual([{ provider: `claude`, model: `claude-haiku-4-5` }]);
+    expect(readyChain([CLAUDE, GOOGLE, KIMI], [`claude:claude-haiku-4-5`].map(pin))).toEqual([{ provider: `claude`, model: `claude-haiku-4-5` }]);
 });
 
 test("names each model once, however many times the list repeats it", () => {
-    // The list is edited by hand; a duplicate would spend a second attempt proving the same account is out.
-    expect(resolveRoleModels([CLAUDE], [`claude:claude-haiku-4-5`, `claude:claude-haiku-4-5`].map(pin), HELPER)).toEqual([
+    // The list is hand-edited and the settings page can write one pin across many jobs, so a duplicate is a
+    // real state; unchecked it would spend a second attempt proving the same account is out.
+    expect(readyChain([CLAUDE], [`claude:claude-haiku-4-5`, `claude:claude-haiku-4-5`].map(pin))).toEqual([
         { provider: `claude`, model: `claude-haiku-4-5` },
     ]);
 });
 
-test("Auto is a ladder too, every connected provider's cheap rung, best first", () => {
-    expect(resolveRoleModels([CLAUDE, GOOGLE, KIMI], [], HELPER)).toEqual([
-        { provider: `gemini`, model: `gemini-3-flash-lite` },
-        { provider: `claude`, model: `claude-haiku-4-5-20251001` },
-        { provider: `kimi`, model: `kimi-k3` },
-    ]);
-});
-
 /* A MODEL ENDPOINT the user configured is a provider like any other here, and the reason it has to be is the
  * settings row: its options are built from the same picker catalog, so a pin naming one that this resolver
  * dropped would print one model's name in the settings row and spend a different account entirely. */
@@ -186,17 +119,3 @@ test("honours a pin on a configured endpoint: the whole id, not the half before
     // as "endpoint" and the model as "ollama:qwen3-coder": a pin that silently resolves to nothing.
     expect(modelPinKey({ provider: `endpoint/ollama`, model: `qwen3-coder` })).toBe(`endpoint/ollama:qwen3-coder`);
 });
-
-test("leaves Auto to the providers whose price is known, rather than reaching for someone's own server", () => {
-    // Claude publishes a Haiku-class row; the endpoint's ids carry no tier word at all, so they are UNRANKED and
-    // lose on tier. What a turn on a user's own model API costs is not a fact this repo holds, and Auto should
-    // not be asserting one.
-    expect(head([CLAUDE, OLLAMA], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
-});
-
-test("still answers from an endpoint when it is the only thing configured", () => {
-    // No tier word in either id, so the shared id-derived ordering decides between them exactly as it does for
-    // Kimi above: the point here is that a sandbox whose only model API is its owner's still gets an answer
-    // rather than the disabled "nothing connected" button.
-    expect(head([offline(CLAUDE), OLLAMA], [])).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
-});

package/src/model-pins.ts

@@ -1,7 +1,4 @@
-import { accessFor, modelsFor, PROVIDERS } from "./agent-catalog.js";
-import { ACCESS_COST } from "./provider-specs.js";
-import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
-import { type ModelRole, modelRole } from "./model-roles.js";
+import { modelsFor } from "./agent-catalog.js";
 import type { AgentProvider, ModelPin } from "./schemas/agent.js";
 
 /* WHICH MODELS A ROLE MAY RUN, IN THE ORDER TO TRY THEM. One resolver over every list in
@@ -15,30 +12,41 @@ import type { AgentProvider, ModelPin } from "./schemas/agent.js";
  * this side says what the running order is.
  *
  * THE RULE LIVES IN THE CONTRACT because both sides need the same answer for different jobs: the daemon runs
- * the model, and the browser has to NAME it, in the settings row's "Auto: …" line, before anything has run. Two
+ * the model, and the browser has to NAME it, in that job's settings row, before anything has run. Two
  * implementations would drift precisely where it matters most, since a row promising Haiku while the daemon
  * bills Opus is worse than no row at all.
  *
- * WHAT AN EMPTY LIST MEANS IS THE ROLE'S OWN ANSWER (model-roles.ts): a `helper` role derives the Auto ladder
- * from whatever is connected, a `run` role resolves to nothing and lets the caller's floor answer. That fork
- * used to be two near-identical files; it is one line here because it was always one difference. */
+ * AN EMPTY LIST RESOLVES TO NOTHING, FOR EVERY ROLE, and this file no longer derives a floor for any of them.
+ * It used to: a `helper` role with no list got an "Auto ladder" worked out from whatever was connected —
+ * every provider's cheapest row, best-first — so an owner who had never opened the settings page still got
+ * commit messages, session titles and safety verdicts from a model this file picked. That was the wrong
+ * default, and the settings row saying "Auto: Gemini 3 Flash Lite, then Claude Haiku 4.5, then …" was the
+ * tell: a recommendation nobody asked for, over accounts they had connected for something else, changing
+ * under them whenever an account was added. NOT SET NOW MEANS NOT SET. Nothing is auto-selected and nothing
+ * is recommended: the owner names the models for a job or the job does not run, which is a state they can
+ * read off the row and a bill they cannot be surprised by.
+ *
+ * The two kinds of role (model-roles.ts) still differ in what the CALLER does with an empty answer — a
+ * `helper` is simply off, a `run` falls to the model the owner picked for their own chat — but that is the
+ * caller's business, and nothing here has to know which kind it is holding. */
 
 /* One provider's standing in the decision: whether a turn on it can be sent at all, and what its catalog holds.
  *
  * ACP agents are deliberately not expressible here — an ACP row's model id is empty because the agent owns its
  * own model, so there is no rung to point it at. `endpoint/<id>` providers ARE, and have to be: their models
  * appear in the same picker the settings rows build their options from, so a pin naming one has to hold rather
- * than fall silently back to Auto and spend an account the user was deliberately steering away from. */
+ * than drop out and leave the job running on an account the user was deliberately steering away from. */
 export interface ModelSource {
-    // AgentProvider, not NativeProvider: an endpoint's id is user-created and cannot be in a fixed union. Auto's
-    // ranking degrades gracefully for one, costOf falls to the metered rung and an id with no tier word is
-    // UNRANKED, which is genuine last place, so an endpoint effectively only wins Auto when nothing else is
-    // connected, while a PIN on one holds. Both are the right answers: what a turn on someone's own model server
-    // costs is not a fact this repo can know, so it is not one Auto should be asserting.
+    // AgentProvider, not NativeProvider: an endpoint's id is user-created and cannot be in a fixed union, and
+    // what a turn on somebody's own model server costs is not a fact this repo can know — which is fine here,
+    // because nothing on this side ranks anything. A pin either names a provider that can run it or it does not.
     readonly provider: AgentProvider;
     // The same connection predicate every other surface gates on (access.ts web-side, the daemon's own account
     // stores daemon-side). A catalog is never empty by construction, so "has rows" says nothing about "can send".
     readonly ready: boolean;
+    // What the provider publishes. NOTHING IN THIS FILE READS IT any more: it was the input to the derived Auto
+    // ladder, and a pin is taken verbatim. Kept because it is what a source IS, and the daemon's helper walk
+    // still gathers it (role-model.ts); a caller with no catalog to hand passes an empty list and loses nothing.
     readonly models: readonly string[];
 }
 
@@ -72,97 +80,43 @@ export const parsePinned = (pinned: string): ModelChoice | undefined => {
 export const pinnedModelLabel = (choice: ModelChoice): string =>
     modelsFor(choice.provider).find((option) => option.value === choice.model)?.label ?? choice.model;
 
-// The cheapest row a provider publishes, its whole catalog read from the cheap end. Undefined for a catalog
-// that hasn't loaded yet, which is a real state: every provider serves a floor, but only once something has
-// asked it.
-const cheapestOf = (source: ModelSource): string | undefined => source.models.toSorted(compareCheapestFirst)[0];
-
-// Where a provider's cheapest row sits on the shared tier scale, and therefore how well it answers the question
-// Auto asks. UNRANKED (-1) is a genuine last place: it means the id carries no tier word we know, so the row is
-// the provider's base line rather than its budget one.
-const tierOf = (model: string): number => tierRankOf(familyOf(model));
-
-// PROVIDERS order, as the final tiebreak. Arbitrary, but the SAME arbitrary answer on every read, the property
-// compareUnrankedModelIds exists to guarantee, and the one a default actually needs. An endpoint is in no fixed
-// list, so it reads -1 and leads the tiebreak; unreachable in practice, since it can never tie on cost.
-const providerOrder = (provider: AgentProvider): number => PROVIDERS.findIndex((entry) => entry.value === provider);
-
-/* WHAT AN ENDPOINT COSTS, one rung past every provider's, and the reason it is a number here rather than a
- * member of AccessKind. That axis describes the providers this repo ships, and every one of them is unlocked by
- * signing in to something the user already holds, so none of them is metered per call. An endpoint is the
- * opposite: whatever gateway somebody pointed us at, whose bill this repo cannot see. Reading it as dearer than
- * anything on the table is the conservative answer, and it is what keeps Auto from reaching for a paid gateway
- * on its own initiative. */
-const METERED_COST = Math.max(...Object.values(ACCESS_COST)) + 1;
-
-// How much a call on this provider costs at the margin. Every native provider declares an access kind; an
-// endpoint declares none, and takes the metered rung above.
-const costOf = (provider: AgentProvider): number => {
-    const access = accessFor(provider);
-    return access === undefined ? METERED_COST : ACCESS_COST[access.kind];
-};
-
-/* AUTO, every connected provider's cheapest row, best-first, as a ladder rather than a winner. The floor under
- * every `helper` role, and under nothing else.
- *
- * Ranked on TIER FIRST, then cost. That order is the point: a helper's Auto exists to not be the frontier
- * model, so a free flagship is still the wrong tool, while a free Haiku-class row and a subscription
- * Haiku-class row differ only in whose quota they spend. Cost then breaks that tie towards the channel the user
- * is not paying per token for, and against the one they are.
- *
- * NOTE WHAT AUTO IS AND IS NOT AN ARGUMENT FOR. It is the answer for an owner who has said nothing, not a claim
- * that cheap is right: an owner who pins Opus to commit messages is not being talked out of it, which is the
- * whole reason these lists are per role. Auto is what a row says while it is empty.
- *
- * The whole ladder, not just its head, because the same ranking that picks the best answer also states the best
- * SECOND answer, and a sandbox with three accounts connected should not lose its commit messages for six hours
- * because one of them is spent. */
-export const autoLadder = (sources: readonly ModelSource[]): readonly ModelPin[] =>
-    sources
-        .filter((source) => source.ready)
-        .flatMap((source) => {
-            const model = cheapestOf(source);
-            return model === undefined ? [] : [{ provider: source.provider, model }];
-        })
-        .toSorted(
-            (left, right) =>
-                tierOf(right.model) - tierOf(left.model) ||
-                costOf(left.provider) - costOf(right.provider) ||
-                providerOrder(left.provider) - providerOrder(right.provider),
-        );
-
 /* WHICH MODELS THIS ROLE MAY RUN, IN THE ORDER TO TRY THEM, given what this sandbox has connected.
- * `pinned` is the stored setting: settings.modelRoles[role], an ordered list of pins, empty for the role's own
- * floor.
+ * `pinned` is the stored setting: settings.modelRoles[role], an ordered list of pins.
  *
  * A pin only holds while its provider is READY: an account the user disconnected would otherwise sit at the
- * head of the chain failing on a credential error, when the sandbox can plainly still answer. Dropping it is
- * the same move the composer already makes when a live catalog stops offering the selected model. It stays on
- * SCREEN, greyed — the settings row renders the stored list, not this one — because a setting that vanished
- * from view would look like the app had eaten it.
+ * head of the chain failing on a credential error while the sandbox can plainly still answer from the rung
+ * below. It stays on SCREEN, greyed — the settings row renders the stored list, not this one — because a
+ * setting that vanished from view would look like the app had eaten it.
  *
- * THE PINNED LIST IS THE WHOLE ANSWER whenever any of it survives that filter. The floor is NOT appended
- * underneath, and that is deliberate: a user who writes down three models has said which accounts this job may
- * spend, and quietly reaching for a fourth when all three are out is exactly the "spend an account they were
- * steering away from" failure a pin exists to prevent. When NONE of the pins is connected any more the list has
- * stopped saying anything about this sandbox, so the floor takes over rather than leaving a dead button.
+ * THE PINNED LIST IS THE WHOLE ANSWER, and there is nothing underneath it. A user who writes down three models
+ * has said which accounts this job may spend, and reaching for a fourth when all three are out is exactly the
+ * "spend an account they were steering away from" failure a pin exists to prevent. A user who writes down none
+ * has said the job picks no model at all.
  *
  * THE WHOLE PIN SURVIVES, not the pair inside it: an entry's effort, thinking, speed and harness are what the
  * work is composed from, so a resolver handing back a bare (provider, model) would silently run the head of the
  * list at the provider's defaults. Nothing here reads or judges those fields, which is the point of carrying
  * them whole.
  *
- * Empty out means the role has nothing it can reach. For a `helper` that is a sandbox with nothing connected at
- * all, and the caller renders a control that says so rather than a live button that fails on click; for a `run`
- * it is the ordinary state of an unpinned role, and the caller's own floor answers. */
-export const resolveRoleModels = (sources: readonly ModelSource[], pinned: readonly ModelPin[], role: ModelRole): readonly ModelPin[] => {
+ * EMPTY OUT MEANS THE LIST HAS NOTHING IT MAY REACH, from two different causes the caller can tell apart by
+ * looking at `pinned`: an empty list is an owner who set no model, and a full list that survives none of the
+ * readiness filter is an owner whose accounts have gone. The first is the job being switched off, the second
+ * is worth a sentence about the accounts.
+ *
+ * ONE FUNCTION FOR BOTH KINDS OF LADDER, and it is `resolveRoleModels` that stopped existing rather than this
+ * one arriving to replace it. A role's list used to add the role's own floor beneath the ready chain, which is
+ * the only thing it did that a persona card's list (schemas/personas.ts `personaModels`) did not — so the walk
+ * was split out to be shared. With the floor gone there is no difference left to share around: a role's list
+ * and a card's list are the same question over the same sources, and two names for it would be two places to
+ * read before believing they agree. */
+export const readyChain = (sources: readonly ModelSource[], pinned: readonly ModelPin[]): readonly ModelPin[] => {
     const ready = new Set(sources.filter((source) => source.ready).map((source) => source.provider));
     // Taken verbatim, unvalidated against the catalog on purpose: the picker offers a custom-id escape hatch for
     // a model a catalog hasn't caught up with, and second-guessing the user's own id here would silently run a
     // different model than the settings row names.
     const requested = pinned.filter((pin) => ready.has(pin.provider));
     /* The same model twice would spend two attempts proving one account is out — a real state, since the list is
-     * hand-edited and Auto's ladder can rank a provider the user has also pinned.
+     * hand-edited and the bulk editor writes one pin across many jobs.
      *
      * THE FIRST OF A PAIR WINS, WHOLE. Two entries can name one model and differ in their knobs (the same Sonnet
      * at Max and again at Low, written while reordering the list), and the one the user reads first is the one
@@ -174,10 +128,5 @@ export const resolveRoleModels = (sources: readonly ModelSource[], pinned: reado
             chain.push(pin);
         }
     }
-    if (chain.length > 0) {
-        return chain;
-    }
-    // The floor, which the role declares. An id outside the table has no floor to fall to, and answering with
-    // the cheapest connected model for it would be this file inventing a job.
-    return modelRole(role)?.kind === `helper` ? autoLadder(sources) : [];
+    return chain;
 };

package/src/model-roles.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "vitest";
+import { MODEL_ROLE_BLOCKS, MODEL_ROLES, type ModelRoleSpec } from "./model-roles.js";
+
+/* THE CATALOG DRAWS THE SETTINGS PAGE, so the properties the page relies on have to be true of the TABLE rather
+ * than remembered by whoever last added a row. Eighteen jobs in one unbroken list is what the blocks exist to
+ * break up, and the failure they replace is a silent one: a role that belongs to no block is simply missing
+ * from Sandbox ▸ Agent ▸ Models, with no error anywhere and a page that looks completely normal. */
+
+// The table at its declared width rather than as the literal tuple: `trigger` is absent from a helper's literal
+// type, and what is under test is exactly whether it is absent where it should be.
+const roles: readonly ModelRoleSpec[] = MODEL_ROLES;
+
+/* WHAT STARTS A RUN IS THE BLOCK IT IS READ IN, and asserting the two against each other is what stops them
+ * drifting: a run whose trigger says one thing while the page draws it under the other heading is a row telling
+ * an owner that a session nobody is watching is one they start. A helper answers with its own kind, because it
+ * has no trigger and its block is the kind itself. */
+test("every whole session says what starts it, and it is the block it is drawn in", () => {
+    const blockOf = new Map(MODEL_ROLE_BLOCKS.flatMap((block) => block.roles.map((role) => [role.id, block.id] as const)));
+
+    for (const role of roles) {
+        expect(role.kind === `run` ? role.trigger : role.kind, role.id).toBe(blockOf.get(role.id));
+    }
+});
+
+test("a one-shot declares no trigger at all: nothing presses a commit subject into being", () => {
+    for (const helper of roles.filter((role) => role.kind === `helper`)) {
+        expect(Object.keys(helper), helper.id).not.toContain(`trigger`);
+    }
+});
+
+/* THE BLOCKS PARTITION THE TABLE: every role in exactly one, nothing invented. Asserted as a partition rather
+ * than block by block, because the two ways to get this wrong are opposites and only one of them is visible —
+ * a role in no block vanishes from the page, a role in two is drawn twice and would be caught by eye. */
+test("the blocks hold every role once, in the table's own order", () => {
+    const blocked = MODEL_ROLE_BLOCKS.flatMap((block) => block.roles.map((role) => role.id));
+
+    expect(blocked.toSorted()).toEqual(MODEL_ROLES.map((role) => role.id).toSorted());
+    /* AND THE ORDER SURVIVES THE SPLIT. Reading the blocks in order is reading the table in order: the table
+     * argues its sequence is REACH (jobs nobody picked a model for, then sessions a click starts, then sessions
+     * that start without one), and a block re-sorted here would leave that argument describing a page it no
+     * longer matches. */
+    expect(blocked).toEqual(MODEL_ROLES.map((role) => role.id));
+});
+
+test("each block says what it is, so the page keeps no headings of its own", () => {
+    for (const block of MODEL_ROLE_BLOCKS) {
+        expect(block.label, block.id).toMatch(/\S/);
+        expect(block.caption, block.id).toMatch(/\S/);
+        // A block with nothing in it would draw a heading over an empty surface.
+        expect(block.roles.length, block.id).toBeGreaterThan(0);
+    }
+});