@intentic/sandbox-contract 1.245.0 → 1.247.0

package/src/host-protocol.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 
 /* The handshake on /system/hosts/connect, the ONE message that is not oRPC.
  *
- * Everything a connected computer is asked lives in `hostContract` (contracts/host.contract.ts), spoken over
+ * Everything a connected device is asked lives in `hostContract` (contracts/host.contract.ts), spoken over
  * this socket by oRPC's websocket adapter: the machine hosts the server, the daemon holds the client. But a
  * socket has to prove whose it is before it can be given a typed client, and that proof cannot itself be an
  * oRPC call, the daemon has nothing to call yet, and would be attaching a link to a stranger.
@@ -12,7 +12,7 @@ import { z } from "zod";
  * wire is oRPC. Anything arriving before the link exists is either this frame or a closed socket. */
 
 // The MCP protocol revision the machine's tool server implements. Shared because the daemon answers the
-// handshake ITSELF when the machine is asleep (hosts/host.routes.ts), two spellings of this would mean an
+// handshake ITSELF when the machine is asleep (the daemon's peer bridge), two spellings of this would mean an
 // offline machine negotiating a different protocol than the same machine awake.
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
 

package/src/index.ts

@@ -1,5 +1,6 @@
 import type { ContractRoute } from "./routes.js";
 import { contractRoutes, requestPathFor, routeForProcedure, routeNameForRequest, routeShapes } from "./routes.js";
+import { accountsContract } from "./contracts/accounts.contract.js";
 import { activityContract } from "./contracts/activity.contract.js";
 import { agentContract } from "./contracts/agent.contract.js";
 import { agentsContract } from "./contracts/agents.contract.js";
@@ -8,14 +9,11 @@ import { automationsContract } from "./contracts/automations.contract.js";
 import { capabilitiesContract } from "./contracts/capabilities.contract.js";
 import { choresContract } from "./contracts/chores.contract.js";
 import { ciContract } from "./contracts/ci.contract.js";
-import { claudeContract } from "./contracts/claude.contract.js";
-import { cursorContract } from "./contracts/cursor.contract.js";
 import { endpointsContract } from "./contracts/endpoints.contract.js";
 import { exitContract } from "./contracts/exit.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
 import { personasContract } from "./contracts/personas.contract.js";
 import { gitContract } from "./contracts/git.contract.js";
-import { grokContract } from "./contracts/grok.contract.js";
 import { historyContract } from "./contracts/history.contract.js";
 import { intenticContract } from "./contracts/intentic.contract.js";
 import { inventoryContract } from "./contracts/inventory.contract.js";
@@ -26,7 +24,6 @@ import { panelsContract } from "./contracts/panels.contract.js";
 import { portsContract } from "./contracts/ports.contract.js";
 import { publicContract } from "./contracts/public.contract.js";
 import { prepushContract } from "./contracts/prepush.contract.js";
-import { keysContract } from "./contracts/keys.contract.js";
 import { providersContract } from "./contracts/providers.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
 import { safetyContract } from "./contracts/safety.contract.js";
@@ -42,6 +39,7 @@ import { vpnContract } from "./contracts/vpn.contract.js";
 import { workflowsContract } from "./contracts/workflows.contract.js";
 import { workspaceContract } from "./contracts/workspace.contract.js";
 
+export { accountsContract } from "./contracts/accounts.contract.js";
 export { activityContract } from "./contracts/activity.contract.js";
 export { agentContract } from "./contracts/agent.contract.js";
 export { agentsContract } from "./contracts/agents.contract.js";
@@ -50,17 +48,14 @@ export { automationsContract } from "./contracts/automations.contract.js";
 export { capabilitiesContract } from "./contracts/capabilities.contract.js";
 export { choresContract } from "./contracts/chores.contract.js";
 export { ciContract } from "./contracts/ci.contract.js";
-export { claudeContract } from "./contracts/claude.contract.js";
-export { cursorContract } from "./contracts/cursor.contract.js";
 export { endpointsContract, type TrialHealth, TrialStatusSchema, type TrialStatusResponse } from "./contracts/endpoints.contract.js";
 export { exitContract } from "./contracts/exit.contract.js";
 export { extensionsContract } from "./contracts/extensions.contract.js";
 export { personasContract } from "./contracts/personas.contract.js";
 export { gitContract } from "./contracts/git.contract.js";
-export { grokContract } from "./contracts/grok.contract.js";
 export { historyContract } from "./contracts/history.contract.js";
 /* Deliberately NOT part of `sandboxContract` below: that map is the daemon's own HTTP surface, and this one is
- * spoken the other way round, over a connected computer's WebSocket, with the MACHINE implementing it. */
+ * spoken the other way round, over a connected device's WebSocket, with the MACHINE implementing it. */
 export { hostContract } from "./contracts/host.contract.js";
 // The same inversion again, one layer in: spoken over the socket a BROWSER EXTENSION opened, with the
 // extension implementing it (contracts/webext.contract.ts).
@@ -77,7 +72,6 @@ export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";
 export { publicContract } from "./contracts/public.contract.js";
 export { prepushContract } from "./contracts/prepush.contract.js";
-export { keysContract } from "./contracts/keys.contract.js";
 export { providersContract } from "./contracts/providers.contract.js";
 export { pushContract } from "./contracts/push.contract.js";
 export { safetyContract } from "./contracts/safety.contract.js";
@@ -119,7 +113,6 @@ export * from "./history-state.js";
 export * from "./agent-runtimes.js";
 export * from "./provider-specs.js";
 export * from "./agent-catalog.js";
-export * from "./agent-run-model.js";
 export * from "./capability-env.js";
 export * from "./command-classes.js";
 export * from "./command-run.js";
@@ -137,10 +130,11 @@ export * from "./listener-protocol.js";
 export * from "./hostnames.js";
 export * from "./overlay-lint.js";
 export * from "./model-order.js";
+export * from "./model-pins.js";
+export * from "./model-roles.js";
 export * from "./plan-pools.js";
 export * from "./path-refs.js";
 export * from "./prompt-complexity.js";
-export * from "./quick-model.js";
 export * from "./output-fields.js";
 export * from "./approvals-execution.js";
 /* The wire shapes, one module per subject area, mirroring `contracts/` above: every request and response the
@@ -159,7 +153,8 @@ export * from "./schemas/capabilities.js";
 export * from "./schemas/ci.js";
 export * from "./schemas/claude-gate.js";
 export * from "./schemas/codebase-health.js";
-export * from "./schemas/computers.js";
+export * from "./schemas/context.js";
+export * from "./schemas/devices.js";
 export * from "./schemas/engines.js";
 export * from "./schemas/environment.js";
 export * from "./schemas/exit.js";
@@ -212,6 +207,7 @@ export * from "./workflow-faults.js";
 // browser's typed oRPC client (ContractRouterClient<typeof sandboxContract>). The wire paths it declares are
 // mounted at the sandbox root, so /health and /workspace/raw (plain Hono routes) sit alongside it.
 export const sandboxContract = {
+    accounts: accountsContract,
     activity: activityContract,
     agent: agentContract,
     agents: agentsContract,
@@ -220,8 +216,6 @@ export const sandboxContract = {
     capabilities: capabilitiesContract,
     chores: choresContract,
     ci: ciContract,
-    claude: claudeContract,
-    cursor: cursorContract,
     endpoints: endpointsContract,
     extensions: extensionsContract,
     personas: personasContract,
@@ -232,7 +226,6 @@ export const sandboxContract = {
     skills: skillsContract,
     intentic: intenticContract,
     git: gitContract,
-    grok: grokContract,
     history: historyContract,
     workspace: workspaceContract,
     inventory: inventoryContract,
@@ -243,7 +236,6 @@ export const sandboxContract = {
     ports: portsContract,
     public: publicContract,
     prepush: prepushContract,
-    keys: keysContract,
     providers: providersContract,
     push: pushContract,
     secrets: secretsContract,

package/src/model-order.ts

@@ -146,7 +146,7 @@ const releaseTierRankOf = (family: string): number => lastRankOf(family, RELEASE
  *
  * That is not a small mis-sort. Thinking is the difference between a commit message that is in the box before
  * the user has finished reading the file list and one that arrives half a minute later, measured at ~2s versus
- * ~27s on the same model and the same diff (agent/one-shot.ts, which disables thinking for the rungs where a
+ * ~27s on the same model and the same diff (claude/claude-one-shot.ts, which disables thinking for the rungs where a
  * request parameter can). For a routed rung there is no such parameter: the id IS the setting, so this ranking
  * is the only place the choice can be made.
  *

package/src/{quick-model.test.ts → model-pins.test.ts}

@@ -1,23 +1,39 @@
 import { expect, test } from "vitest";
-import { type QuickModelChoice, type QuickModelSource, quickModelKey, resolveQuickModels } from "./quick-model.js";
-
-/* Which models a small automatic helper spends, and in which order. The rule answers two surfaces at once:
- * the daemon walks it, the browser names its head in the 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. */
+import { type ModelSource, modelPinKey, parsePinned, resolveRoleModels } 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.
+ *
+ * `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;
+
+// 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.
+const pin = (key: string): ModelPin => {
+    const at = key.indexOf(`:`);
+    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.
-const CLAUDE: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`] };
-const GOOGLE: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-flash`, `gemini-3-flash-lite`, `gemini-3-pro`] };
-const CODEX: QuickModelSource = { provider: `codex`, ready: true, models: [`gpt-5.4-mini`, `gpt-5.6`] };
-const KIMI: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2.6`, `kimi-k2.7-code`, `kimi-k3`] };
+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`] };
+const KIMI: ModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2.6`, `kimi-k2.7-code`, `kimi-k3`] };
 
-const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
+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 QuickModelSource[], pinned: readonly string[]): QuickModelChoice | undefined =>
-    resolveQuickModels(sources, pinned)[0];
+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` });
@@ -32,14 +48,14 @@ test("spends the FREE channel over the subscription when both offer the same run
 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: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-pro`] };
+    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: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-mini`] };
-    const claudeCheap: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-haiku-4-5`] };
+    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`);
 });
@@ -48,7 +64,7 @@ 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) => quickModelKey(answer!))).size).toBe(1);
+    expect(new Set(answers.map((answer) => modelPinKey(answer!))).size).toBe(1);
 });
 
 test("honours a pinned model verbatim, including an id no catalog lists yet", () => {
@@ -66,10 +82,38 @@ test("falls back to Auto when the pinned provider is no longer connected", () =>
     });
 });
 
-test("ignores a malformed pin instead of running an empty model id", () => {
-    for (const pinned of [`claude`, `claude:`, `:claude-haiku-4-5`, ` `]) {
-        expect(head([CLAUDE], [pinned])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+/* 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
+ * `autoFastModels`, so the rule lives with the parser that reads one, and this is where it is pinned. */
+test("refuses a malformed key rather than reading half a pin out of it", () => {
+    for (const key of [`claude`, `claude:`, `:claude-haiku-4-5`, ` `]) {
+        expect(parsePinned(key)).toBeUndefined();
     }
+    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([]);
+});
+
+test("carries an entry's run settings through untouched, on either kind of role", () => {
+    // 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", () => {
@@ -79,12 +123,12 @@ test("serves the newest of a catalog that publishes no cheap tier at all", () =>
 
 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(resolveQuickModels([offline(CLAUDE), offline(GOOGLE)], [])).toEqual([]);
+    expect(resolveRoleModels([offline(CLAUDE), offline(GOOGLE)], [], HELPER)).toEqual([]);
     expect(head([], [`claude:claude-haiku-4-5`])).toBeUndefined();
 });
 
 test("skips a connected provider whose catalog has not loaded yet", () => {
-    const unloaded: QuickModelSource = { provider: `grok`, ready: true, models: [] };
+    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();
@@ -95,7 +139,7 @@ test("skips a connected provider whose catalog has not loaded yet", () => {
  * 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(resolveQuickModels([CLAUDE, GOOGLE, CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5-20251001`])).toEqual([
+    expect(resolveRoleModels([CLAUDE, GOOGLE, CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5-20251001`].map(pin), HELPER)).toEqual([
         { provider: `codex`, model: `gpt-5.6` },
         { provider: `gemini`, model: `gemini-3-flash` },
         { provider: `claude`, model: `claude-haiku-4-5-20251001` },
@@ -103,7 +147,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(resolveQuickModels([CLAUDE, offline(GOOGLE), CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5`])).toEqual([
+    expect(resolveRoleModels([CLAUDE, offline(GOOGLE), CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5`].map(pin), HELPER)).toEqual([
         { provider: `codex`, model: `gpt-5.6` },
         { provider: `claude`, model: `claude-haiku-4-5` },
     ]);
@@ -112,18 +156,18 @@ 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(resolveQuickModels([CLAUDE, GOOGLE, KIMI], [`claude:claude-haiku-4-5`])).toEqual([{ provider: `claude`, model: `claude-haiku-4-5` }]);
+    expect(resolveRoleModels([CLAUDE, GOOGLE, KIMI], [`claude:claude-haiku-4-5`].map(pin), HELPER)).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(resolveQuickModels([CLAUDE], [`claude:claude-haiku-4-5`, `claude:claude-haiku-4-5`])).toEqual([
+    expect(resolveRoleModels([CLAUDE], [`claude:claude-haiku-4-5`, `claude:claude-haiku-4-5`].map(pin), HELPER)).toEqual([
         { provider: `claude`, model: `claude-haiku-4-5` },
     ]);
 });
 
 test("Auto is a ladder too, every connected provider's cheap rung, best first", () => {
-    expect(resolveQuickModels([CLAUDE, GOOGLE, KIMI], [])).toEqual([
+    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` },
@@ -133,14 +177,14 @@ test("Auto is a ladder too, every connected provider's cheap rung, best first",
 /* 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. */
-const OLLAMA: QuickModelSource = { provider: `endpoint/ollama`, ready: true, models: [`qwen3-coder`, `gemma3-27b`] };
+const OLLAMA: ModelSource = { provider: `endpoint/ollama`, ready: true, models: [`qwen3-coder`, `gemma3-27b`] };
 
 test("honours a pin on a configured endpoint: the whole id, not the half before its slash", () => {
     expect(head([CLAUDE, OLLAMA], [`endpoint/ollama:qwen3-coder`])).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
     // And it round-trips through the key shape the picker mints, which is where the slash-not-colon rule earns
     // itself: parsePinned splits on the FIRST colon, so an `endpoint:ollama` id would have parsed the provider
     // as "endpoint" and the model as "ollama:qwen3-coder": a pin that silently resolves to nothing.
-    expect(quickModelKey({ provider: `endpoint/ollama`, model: `qwen3-coder` })).toBe(`endpoint/ollama:qwen3-coder`);
+    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", () => {

package/src/model-pins.ts

@@ -0,0 +1,183 @@
+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 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
+ * settings.modelRoles, and the browser and the daemon both read it.
+ *
+ * IT IS AN ORDER, NOT A MODEL, and that is the shape of every list this file answers for. A single pick is a
+ * single point of failure: the account it names spends its allowance on the chat all morning, and the role
+ * fails on a limit for the rest of the day while three other connected providers sit idle. So a setting is a
+ * LIST read top to bottom, this hands back the whole ladder, and the caller walks it until one answers. Nothing
+ * here decides WHICH failures are worth stepping over — only the runner has made the call and seen it fail —
+ * 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
+ * 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. */
+
+/* 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. */
+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.
+    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;
+    readonly models: readonly string[];
+}
+
+export interface ModelChoice {
+    readonly provider: AgentProvider;
+    readonly model: string;
+}
+
+// A (provider, model) pair on the wire: `${provider}:${modelId}`, the same key shape the model picker mints for
+// its entries (PickerEntry.key). Every role list stores PINS rather than these keys — an entry says how it runs
+// as well as which model it is — but the key is still how two entries are compared, how a role list dedupes,
+// and how `autoFastModels` (which pins no knobs, see its own note in settings.ts) is stored.
+export const modelPinKey = (choice: ModelChoice): string => `${choice.provider}:${choice.model}`;
+
+/* Split on the FIRST colon only: a provider id never contains one and a model id might. Exported because
+ * `autoFastModels` stores these keys, and because a session composed from a pin travels as one
+ * (composeSession). */
+export const parsePinned = (pinned: string): ModelChoice | undefined => {
+    const separator = pinned.indexOf(`:`);
+    if (separator <= 0 || separator === pinned.length - 1) {
+        return undefined;
+    }
+    return { provider: pinned.slice(0, separator), model: pinned.slice(separator + 1) };
+};
+
+/* A pin as a person reads it: the catalog's own label for the id, or the id itself for one the static catalog
+ * has not caught up with (the picker offers a custom-id escape hatch, so this is a real case rather than a
+ * defensive branch). Beside parsePinned because the two are always wanted together, by any surface that has to
+ * name what a click is about to spend BEFORE it spends it, and the two loudest of those are extensions that
+ * share no other code with each other. */
+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.
+ *
+ * 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.
+ *
+ * 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 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[] => {
+    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.
+     *
+     * 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
+     * they meant; keeping the earlier position with the later entry's effort would run a tier that appears
+     * nowhere the pin does. */
+    const chain: ModelPin[] = [];
+    for (const pin of requested) {
+        if (!chain.some((held) => modelPinKey(held) === modelPinKey(pin))) {
+            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) : [];
+};