@intentic/sandbox-contract 1.331.0 → 1.332.0

package/src/models/agent-runtimes.ts

@@ -8,7 +8,7 @@ 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";
+    readonly runtime: "claude-code" | "codex" | "opencode" | "opencode-gemini" | "acp" | "devin" | "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.
@@ -59,6 +59,10 @@ export interface AgentCapabilities {
     // configuration the daemon does not own and reads files it never sees. Only a `none` loop on an untrusted provider is
     // refused while the shield is on.
     readonly privacy: "gateway" | "hooks" | "none";
+    // Whether a turn's tool list (TurnPolicy.allowedTools, an automation's `allowedTools`) is a real boundary here:
+    // every tool call the loop makes passes a check the daemon answers, or the loop is built with only the listed tools.
+    // A runtime that runs some tool without asking anyone cannot keep it, so a turn carrying a list never starts on one.
+    readonly toolAllowlist: boolean;
 }
 
 // The Claude Code Agent SDK loop, the ceiling every other runtime is measured against: the only one that owns the whole
@@ -85,6 +89,9 @@ export const CLAUDE_CODE: AgentCapabilities = {
     secrets: "masked",
     // Every request goes to ANTHROPIC_BASE_URL, which the daemon sets per turn.
     privacy: "gateway",
+    // A PreToolUse hook refuses every call off the list, under bypassPermissions and in subagents too
+    // (agent/tools/tool-allowlist.ts).
+    toolAllowlist: true,
 };
 
 // Codex app-server: item-level events, the turn's remote MCP servers over http, and four seams (steer, a question
@@ -112,6 +119,9 @@ export const CODEX: AgentCapabilities = {
     secrets: "none",
     // Its model provider's base_url is the daemon's, written into the per-thread config.
     privacy: "gateway",
+    // Codex runs the commands it judges read-only without asking (its known-safe list), and every tool it has is the
+    // shell, so no answer the daemon gives can keep a call off a list.
+    toolAllowlist: false,
 };
 
 // OpenCode (the Grok runtime): its own agentic loop and tools, with the turn's remote MCP servers mounted on the shared
@@ -140,6 +150,10 @@ export const OPENCODE: AgentCapabilities = {
     secrets: "none",
     // The shared server's provider baseURLs are written by the daemon at spawn.
     privacy: "gateway",
+    // Its session rules could deny every action off the list, but they apply after the server's and the last match wins,
+    // so allowing a listed shell command there would override the owner's rulebook asking about it. Not kept until the
+    // permission judge (opencode-permissions.ts) checks the list on every call instead.
+    toolAllowlist: false,
 };
 
 // The same OpenCode loop, serving Gemini instead of xAI, identical abilities. The Claude Code loop announces itself in
@@ -173,6 +187,16 @@ export const ACP: AgentCapabilities = {
     secrets: "none",
     // The agent picks its own provider and endpoint from its own login and environment.
     privacy: "none",
+    // Which calls the agent asks permission for is its own choice, and most run reads without asking.
+    toolAllowlist: false,
+};
+
+// Devin's own CLI (`devin acp`), the ACP floor with one seam an installed agent lacks: the daemon picks the model, from
+// the account's own list, through the session's model option. Its own runtime name, as OpenCode's Gemini twin has, since
+// adapter health keys off this field and Devin's readiness is an account and an engine, not an installed card.
+export const DEVIN: AgentCapabilities = {
+    ...ACP,
+    runtime: "devin",
 };
 
 // Pi driven over its RPC mode: above the ACP floor and below the Claude Code ceiling. Real mid-turn steering, an effort
@@ -199,6 +223,8 @@ export const PI: AgentCapabilities = {
     secrets: "none",
     // Pi calls its provider from its own login; the daemon names no endpoint.
     privacy: "none",
+    // No seam before a tool runs.
+    toolAllowlist: false,
 };
 
 // Cursor's own runtime, driven through `@cursor/sdk` from this daemon's process; an embedding surface, so most seams
@@ -242,4 +268,7 @@ export const CURSOR: AgentCapabilities = {
     // to mask the output, the tools that read past both (grep, ls, glob, semantic search, fetch, lints) are withheld,
     // and MCP goes through the masking proxy (runtimes/cursor/cursor-shield.ts).
     privacy: "hooks",
+    // Its hooks are installed only for a shielded turn, and a hook that cannot tell which turn is asking allows; the
+    // built-in tool set is withheld by name, not granted. None of that is a list nothing gets past.
+    toolAllowlist: false,
 };

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

@@ -37,6 +37,10 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     // agent/run/decide/turn-decision.ts refuses a "none" runtime on an untrusted provider while the privacy shield is
     // on; "gateway" runtimes get the daemon's gateway as their base URL (privacy/gateway).
     privacy: "enforced",
+    // agent/run/decide/turn-decision.ts refuses a turn carrying a tool list on a runtime that cannot keep one, the
+    // automation ladder passes such rungs over, and agent/tools/tool-allowlist.ts refuses every off-list call on the
+    // Claude Code loop.
+    toolAllowlist: "enforced",
 
     // Descriptive: true of the runtime but nothing consults these; wiring one up moves it to enforced.
     questions: "descriptive",

package/src/models/model-order.ts

@@ -147,3 +147,16 @@ export const compareUnrankedModelIds = (left: string, right: string): number =>
 // True only for an id that spells out a level above the quiet end, so an unannotated id is never accused of it.
 // Exported so a settings row can label a pinned thinking variant.
 export const namesThinking = (id: string): boolean => thinkingRankOf(familyOf(id)) > UNSTATED_THINKING;
+
+// Which of three rungs an id stands on: 0 the frontier, 1 the everyday workhorse, 2 the cheap end. A tier word decides
+// where there is one, a release-local ladder (sol, terra, luna) where there is not, and an id with neither is read as
+// the frontier, as the catalog order already leads with it. What the preset setups are worked out from.
+export const modelRungOf = (id: string): number => {
+    const family = familyOf(id);
+    const tier = tierRankOf(family);
+    if (tier !== UNRANKED) {
+        return tier;
+    }
+    const release = releaseTierRankOf(family);
+    return release === UNRANKED ? 0 : release;
+};

package/src/models/model-pins.ts

@@ -1,8 +1,8 @@
 import type { AgentProvider, ModelPin } from "../schemas/agent.js";
 
-// The order to try models in for a role or job (settings.modelRoles), shared by daemon and browser so both agree what a
-// job will spend before it runs. An empty list resolves to nothing for every role: nothing is derived or auto-selected.
-// The caller decides what an empty answer means (a helper is off; a run falls back to the chat's own pick).
+// The order to try models in for a job's setup (model-setups.ts), shared by daemon and browser so both agree what a job
+// will spend before it runs. An empty list resolves to nothing: the caller decides what that means (a helper is off; a
+// run falls back to the chat's own pick).
 
 // One provider's standing in the decision: can a turn go, and what its catalog holds. ACP agents have no rung here (an
 // empty model id), but endpoint/<id> providers must be included, matching the picker's own options.
@@ -11,7 +11,8 @@ export interface ModelSource {
     readonly provider: AgentProvider;
     // Same connection predicate every surface gates on; a nonempty catalog does not imply ready to send.
     readonly ready: boolean;
-    // Nothing here reads this (a pin is verbatim); kept because it's what a source is, and callers still gather it.
+    // The models it can run a turn on, newest-first order not assumed. readyChain never reads it (a pin is verbatim);
+    // a preset setup is worked out from it (model-setups.ts `presetPins`), so a helper-only model is left out.
     readonly models: readonly string[];
 }
 

package/src/models/model-roles.test.ts

@@ -1,37 +1,15 @@
-import { MODEL_ROLE_BLOCKS, MODEL_ROLES, type ModelRoleSpec } from "./model-roles.js";
+import { MODEL_ROLES, PRESET_SETUPS } from "./model-roles.js";
 
-// The catalog draws the settings page directly, so its properties (every role in one block) must hold of the table
-// itself, not be remembered by whoever adds a row.
+// The catalog draws the settings page directly, so its properties must hold of the table itself, not be remembered by
+// whoever adds a row.
 
-// Typed at its declared width, not the literal tuple: trigger is absent from a helper's type, under test here.
-const roles: readonly ModelRoleSpec[] = MODEL_ROLES;
+test("the page reads one-shots first, then whole sessions, in the table's own order", () => {
+    const kinds = MODEL_ROLES.map((role) => role.kind);
 
-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`);
-    }
-});
-
-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());
-    // The block order mirrors reach ordering (unpicked jobs, then click-started sessions, then auto-started ones).
-    expect(blocked).toEqual(MODEL_ROLES.map((role) => role.id));
+    expect(kinds.indexOf(`run`)).toBe(kinds.lastIndexOf(`helper`) + 1);
 });
 
-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/);
-        // A block with nothing in it would draw a heading over an empty surface.
-        expect(block.roles.length, block.id).toBeGreaterThan(1);
-    }
+test("every job is suggested a preset, and the cheap one is never suggested for a whole session", () => {
+    expect(MODEL_ROLES.every((role) => PRESET_SETUPS.includes(role.setup))).toBe(true);
+    expect(new Set<string>(MODEL_ROLES.filter((role) => role.kind === `run`).map((role) => role.setup)).has(`low`)).toBe(false);
 });

package/src/models/model-roles.ts

@@ -1,15 +1,17 @@
 import { z } from "zod";
 
-// Every job that picks a model, one row per job; the unit is the role, not a difficulty tier. Each list is an ordered
-// fallback ladder; empty means the job is off (helper) or falls back to the caller's own chat model (run). Adding a
-// role is one row here, settings, resolver and daemon all read this table.
+// Every job that picks a model, one row per job; the unit is the role, not a difficulty tier. A job runs on the setup it
+// was put on (model-setups.ts), an ordered fallback ladder it shares with every other job put there; a job on none, or
+// on an empty one, is off (helper) or falls back to the caller's own chat model (run). Adding a role is one row here, settings, resolver
+// and daemon all read this table.
 
 export const ModelRoleKindSchema = z.enum(["helper", "run"]);
 export type ModelRoleKind = z.infer<typeof ModelRoleKindSchema>;
 
-// Which block a run role sorts into on the settings page: pressed by the owner, or started unprompted; helpers declare
-// none.
-export type ModelRoleTrigger = "pressed" | "unprompted";
+// The three setups every sandbox has, cheapest first: worked out from what is connected until the owner edits one
+// (model-setups.ts `presetPins`). Ids are stored, so they are wire-stable.
+export const PRESET_SETUPS = ["low", "medium", "high"] as const;
+export type PresetSetup = (typeof PRESET_SETUPS)[number];
 
 // `id` is a bare string here; narrowed to the role union on `ModelRoleSpec` below, since that union derives from this
 // table via `satisfies`.
@@ -20,13 +22,14 @@ interface ModelRoleRow {
     // Must add information beyond the label, not restate it.
     readonly blurb: string;
     readonly kind: ModelRoleKind;
-    /** Required when `kind` is "run"; unset for helpers. */
-    readonly trigger?: ModelRoleTrigger;
     // Icon name from the shared icon set; kept here, not in a separate web-side map keyed by id.
     readonly icon: string;
+    // The preset suggested for this job, offered when it is placed: what the work needs, not what it costs today. Only
+    // a suggestion: a job runs on nothing until someone puts it on a setup.
+    readonly setup: PresetSetup;
 }
 
-// Ids are wire-stable (`AgentTurn.runRole`); order matches the settings page's block grouping below.
+// Ids are wire-stable (`AgentTurn.runRole`); order is the settings page's: one-shot helpers first, then whole sessions.
 export const MODEL_ROLES = [
     {
         id: "commit-message",
@@ -34,6 +37,7 @@ export const MODEL_ROLES = [
         blurb: "The subject written when an agent's work lands, and the release note under it.",
         kind: "helper",
         icon: "file-edit",
+        setup: "low",
     },
     {
         id: "session-title",
@@ -41,6 +45,7 @@ export const MODEL_ROLES = [
         blurb: "The name a conversation wears on the board, written a second into its first turn.",
         kind: "helper",
         icon: "pencil",
+        setup: "low",
     },
     {
         // Prompt includes the command about to run, which may be attacker-controlled; a small model can be swayed.
@@ -49,6 +54,7 @@ export const MODEL_ROLES = [
         blurb: "Which model reads your safety policy before a flagged command runs.",
         kind: "helper",
         icon: "shield",
+        setup: "medium",
     },
     {
         id: "loop-verdict",
@@ -56,6 +62,16 @@ export const MODEL_ROLES = [
         blurb: "Whether a loop's iteration met the goal, or the loop goes round again.",
         kind: "helper",
         icon: "check-square",
+        setup: "medium",
+    },
+    {
+        // Reads a whole conversation (capped tool output) once, so a small model with a large window suits it best.
+        id: "handoff-summary",
+        label: "Hand-off summaries",
+        blurb: "The summary a fresh session opens with when you choose to summarise a long conversation that hit a usage limit, instead of re-reading it all.",
+        kind: "helper",
+        icon: "align-left",
+        setup: "low",
     },
     {
         // One reading answering both halves of "what does this chat open on": an offered `provider:model` line with an
@@ -67,79 +83,79 @@ export const MODEL_ROLES = [
         blurb: "Which model reads a new chat's first message and picks what it opens on: the model, effort and account, and the persona.",
         kind: "helper",
         icon: "sparkles",
+        setup: "low",
     },
     {
         id: "pipeline-fix",
         label: "Pipeline fixes",
         blurb: "The agent started by Fix on a failed pipeline.",
         kind: "run",
-        trigger: "pressed",
         icon: "wave-pulse",
+        setup: "high",
     },
     {
         id: "deployment-fix",
         label: "Deployment fixes",
         blurb: "The agent started by Fix on a deployment that is down.",
         kind: "run",
-        trigger: "pressed",
         icon: "server",
+        setup: "high",
     },
     {
         id: "maintenance-chore",
         label: "Maintenance chores",
         blurb: "A chore run started from the Maintenance board.",
         kind: "run",
-        trigger: "pressed",
         icon: "wrench",
+        setup: "medium",
     },
     {
         id: "refactor-run",
         label: "Refactors",
         blurb: "The agent started from a hotspot or key module on a repository's Health tab.",
         kind: "run",
-        trigger: "pressed",
         icon: "hammer",
+        setup: "high",
     },
     {
         id: "documentation-run",
         label: "Documentation runs",
         blurb: "A pass over a repo's own documentation.",
         kind: "run",
-        trigger: "pressed",
         icon: "book",
+        setup: "medium",
     },
     {
         id: "acceptance-run",
         label: "Acceptance runs",
         blurb: "One session per story in an acceptance fan-out.",
         kind: "run",
-        trigger: "pressed",
         icon: "list-check",
+        setup: "high",
     },
     {
-        // Pressed trigger: the owner's approval click starts this turn; the queue between is just machinery.
         id: "approval-queue",
         label: "Approvals queue",
         blurb: "The turn that publishes or acts on what you approved.",
         kind: "run",
-        trigger: "pressed",
         icon: "check-circle",
+        setup: "medium",
     },
     {
         id: "extension-review",
         label: "Extension update reviews",
         blurb: "The agent that reads an extension update before it is applied.",
         kind: "run",
-        trigger: "unprompted",
         icon: "box",
+        setup: "medium",
     },
     {
         id: "loop-iteration",
         label: "Loop iterations",
         blurb: "Each round of a loop working towards its goal.",
         kind: "run",
-        trigger: "unprompted",
         icon: "repeat",
+        setup: "high",
     },
 ] as const satisfies readonly ModelRoleRow[];
 
@@ -150,34 +166,3 @@ export const MODEL_ROLE_IDS = MODEL_ROLES.map((role) => role.id) as readonly Mod
 
 // Enum, not a string: an id outside this table names nothing, so it should fail loudly rather than be ignored.
 export const ModelRoleSchema = z.enum(MODEL_ROLE_IDS as [ModelRole, ...ModelRole[]]);
-
-// Groups MODEL_ROLES for the settings page by kind and trigger; each role belongs to exactly one block, in table order.
-export type ModelRoleBlockId = "helper" | "pressed" | "unprompted";
-
-export interface ModelRoleBlock {
-    readonly id: ModelRoleBlockId;
-    /** Heading shown on the settings page. */
-    readonly label: string;
-    /** Its roles, in MODEL_ROLES order. */
-    readonly roles: readonly ModelRoleSpec[];
-}
-
-const rolesWhere = (match: (role: ModelRoleSpec) => boolean): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => match(role));
-
-export const MODEL_ROLE_BLOCKS: readonly ModelRoleBlock[] = [
-    {
-        id: "helper",
-        label: "Automatic helpers",
-        roles: rolesWhere((role) => role.kind === "helper"),
-    },
-    {
-        id: "pressed",
-        label: "Runs you start",
-        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "pressed"),
-    },
-    {
-        id: "unprompted",
-        label: "Runs that start themselves",
-        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "unprompted"),
-    },
-];

package/src/models/model-setups.test.ts

@@ -0,0 +1,100 @@
+import type { ModelPin } from "../schemas/agent.js";
+import type { ModelSource } from "./model-pins.js";
+import { endpointProvider } from "./agent-catalog.js";
+import type { ModelRole } from "./model-roles.js";
+import { ladderIsEmpty, presetPins, roleLadder, rolePins, roleSetupId, setupsFromRoleLists } from "./model-setups.js";
+
+// What a job runs on is read here by the daemon and the browser alike, so the rules are pinned once: where a job starts,
+// what a preset is worked out from, and what a written setup overrides.
+
+const opus: ModelPin = { provider: `claude`, model: `claude-opus-5-5`, effort: `high` };
+const haiku: ModelPin = { provider: `claude`, model: `claude-haiku-4-5` };
+
+const CLAUDE: ModelSource = { provider: `claude`, ready: true, models: [`claude-haiku-4-5-20251001`, `claude-opus-4-8`, `claude-opus-5`, `claude-sonnet-5`] };
+const CODEX: ModelSource = { provider: `codex`, ready: true, models: [`gpt-5.2-codex`, `gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5-mini`] };
+const GEMINI: ModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-flash`, `gemini-3-flash-lite`, `gemini-3-pro`] };
+
+const NOTHING_SET = { modelSetups: [], roleSetups: {} };
+
+describe(`a preset worked out from what is connected`, () => {
+    test(`takes each connected provider's newest model on the preset's rung, in the order they come`, () => {
+        expect(presetPins(`high`, [CLAUDE, CODEX, GEMINI]).map((pin) => pin.model)).toEqual([`claude-opus-5`, `gpt-5.6-sol`, `gemini-3-pro`]);
+        expect(presetPins(`medium`, [CLAUDE, CODEX, GEMINI]).map((pin) => pin.model)).toEqual([`claude-sonnet-5`, `gpt-5.6-terra`, `gemini-3-flash`]);
+        expect(presetPins(`low`, [CLAUDE, CODEX, GEMINI]).map((pin) => pin.model)).toEqual([`claude-haiku-4-5-20251001`, `gpt-5.6-luna`, `gemini-3-flash-lite`]);
+    });
+
+    test(`leaves out a provider that is not connected, a local endpoint, and anything past three`, () => {
+        const local: ModelSource = { provider: endpointProvider(`ollama`), ready: true, models: [`qwen-coder`] };
+        const extra: ModelSource = { provider: `grok`, ready: true, models: [`grok-5-heavy`] };
+        expect(presetPins(`high`, [{ ...CLAUDE, ready: false }, local, CODEX, GEMINI, extra]).map((pin) => pin.provider)).toEqual([`codex`, `gemini`, `grok`]);
+        expect(presetPins(`high`, [CLAUDE, CODEX, GEMINI, extra])).toHaveLength(3);
+    });
+
+    test(`takes a provider's own model over one it serves from another maker`, () => {
+        const google: ModelSource = { provider: `gemini`, ready: true, models: [`claude-opus-4-6-thinking`, `gemini-3-pro`, `gemini-3-flash`] };
+        expect(presetPins(`high`, [google])).toEqual([{ provider: `gemini`, model: `gemini-3-pro` }]);
+        // With none of its own on the rung, the borrowed one still serves.
+        expect(presetPins(`high`, [{ ...google, models: [`claude-opus-4-6-thinking`, `gemini-3-flash`, `gemini-3-flash-lite`] }])).toEqual([
+            { provider: `gemini`, model: `claude-opus-4-6-thinking` },
+        ]);
+    });
+
+    test(`is empty while nothing is connected`, () => {
+        expect(presetPins(`low`, [])).toEqual([]);
+    });
+});
+
+describe(`which setup a job runs on`, () => {
+    test(`a job nobody placed runs on nothing, however much is connected`, () => {
+        expect(roleSetupId(NOTHING_SET, `commit-message`)).toBeUndefined();
+        expect(ladderIsEmpty(roleLadder(NOTHING_SET, `safety-judge`))).toBe(true);
+        expect(rolePins(NOTHING_SET, `pipeline-fix`, [CLAUDE, CODEX, GEMINI])).toEqual([]);
+    });
+
+    test(`a job put on a preset nobody edited runs what is connected, and follows it`, () => {
+        const settings = { modelSetups: [], roleSetups: { "commit-message": `low` } };
+        expect(roleLadder(settings, `commit-message`)).toEqual({ kind: `preset`, preset: `low` });
+        expect(rolePins(settings, `commit-message`, [CLAUDE])).toEqual([{ provider: `claude`, model: `claude-haiku-4-5-20251001` }]);
+    });
+
+    test(`a written preset is run as written, and stops following what is connected`, () => {
+        const settings = { modelSetups: [{ id: `low`, pins: [opus] }], roleSetups: { "commit-message": `low` } };
+        expect(rolePins(settings, `commit-message`, [CLAUDE, CODEX])).toEqual([opus]);
+    });
+
+    test(`a preset that was only renamed still follows what is connected`, () => {
+        const settings = { modelSetups: [{ id: `low`, name: `Cheap` }], roleSetups: { "commit-message": `low` } };
+        expect(roleLadder(settings, `commit-message`)).toEqual({ kind: `preset`, preset: `low` });
+    });
+
+    test(`a job put on a setup of the owner's runs that setup's models`, () => {
+        const settings = { modelSetups: [{ id: `setup-1`, name: `Reviews`, pins: [opus, haiku] }], roleSetups: { "commit-message": `setup-1` } };
+        expect(rolePins(settings, `commit-message`, [CLAUDE])).toEqual([opus, haiku]);
+    });
+
+    test(`a job put on a setup that is gone is on none`, () => {
+        const settings = { modelSetups: [], roleSetups: { "commit-message": `setup-9` } };
+        expect(roleSetupId(settings, `commit-message`)).toBeUndefined();
+    });
+
+    test(`a setup of the owner's with no models is empty, never a preset`, () => {
+        const settings = { modelSetups: [{ id: `setup-1`, name: `Later` }], roleSetups: { "pipeline-fix": `setup-1` } };
+        expect(ladderIsEmpty(roleLadder(settings, `pipeline-fix`))).toBe(true);
+    });
+});
+
+test(`per-job lists become setups every job runs exactly as before on`, () => {
+    const cases = [
+        [`commit-message`, [haiku]],
+        [`session-title`, [haiku]],
+        [`pipeline-fix`, [opus]],
+        [`safety-judge`, []],
+    ] as const satisfies readonly (readonly [ModelRole, readonly ModelPin[]])[];
+    const settings = setupsFromRoleLists(Object.fromEntries(cases));
+
+    for (const [role, pins] of cases) {
+        expect(rolePins(settings, role, [CLAUDE, CODEX])).toEqual(pins);
+    }
+    // A job that never had a list, or had an empty one, ran on nothing and is on none.
+    expect([settings.roleSetups[`loop-iteration`], settings.roleSetups[`safety-judge`]]).toEqual([undefined, undefined]);
+});

package/src/models/model-setups.ts

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import { type ModelPin, ModelPinSchema } from "../schemas/agent.js";
+import { isEndpointProvider } from "./agent-catalog.js";
+import { compareModelIds, modelRungOf } from "./model-order.js";
+import type { ModelSource } from "./model-pins.js";
+import { MODEL_ROLE_IDS, MODEL_ROLES, type ModelRole, PRESET_SETUPS, type PresetSetup } from "./model-roles.js";
+
+// A setup is a named, ordered list of models that any number of jobs run on: edited once, used by every job put there.
+// Every sandbox has three, Low, Medium and High, worked out from the accounts it has connected until the owner edits
+// one; the owner adds any others. A job runs on nothing until someone puts it on a setup: nothing spends an account, and
+// no judge starts holding commands, because an account was connected. Each job's catalog row suggests a preset
+// (model-roles.ts `setup`) for when it is placed. Every reader resolves a job through here, daemon and browser alike, so
+// the settings page shows what will run.
+
+export const MODEL_SETUP_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+export const ModelSetupSchema = z.object({
+    id: z.string().regex(MODEL_SETUP_ID).describe("Which setup this is. `low`, `medium` and `high` are the three every sandbox has; any other is one you made."),
+    name: z.string().trim().min(1).max(40).optional().describe("What it is called on the settings page. Left out, a preset keeps its own name."),
+    pins: z
+        .array(ModelPinSchema)
+        .max(10)
+        .optional()
+        .describe(
+            "The models it runs on, tried in order, so one spent account does not take its jobs down. Left out on a preset, it is worked out from the accounts this sandbox has connected and follows them as they change; left out on one you made, it has none.",
+        ),
+});
+export type ModelSetup = z.infer<typeof ModelSetupSchema>;
+
+export const isPresetSetup = (id: string): id is PresetSetup => PRESET_SETUPS.some((preset) => preset === id);
+
+// The settings a job's models are read from; a slice, so a caller holding only these two can resolve.
+export interface SetupSettings {
+    readonly modelSetups: readonly ModelSetup[];
+    readonly roleSetups: Partial<Record<ModelRole, string>>;
+}
+
+const SUGGESTED = new Map<ModelRole, PresetSetup>(MODEL_ROLES.map((role) => [role.id, role.setup]));
+
+/** The preset suggested for a job when it is placed. */
+export const suggestedSetup = (role: ModelRole): PresetSetup => SUGGESTED.get(role) ?? `medium`;
+
+// First entry wins: a hand-edited file holding one id twice means the earlier, as everywhere else a list is read.
+export const storedSetup = (settings: Pick<SetupSettings, "modelSetups">, id: string): ModelSetup | undefined =>
+    settings.modelSetups.find((setup) => setup.id === id);
+
+/** The setup a job runs on, or undefined while it is on none (never placed, or placed on a setup that is gone). */
+export const roleSetupId = (settings: SetupSettings, role: ModelRole): string | undefined => {
+    const assigned = settings.roleSetups[role];
+    return assigned !== undefined && (isPresetSetup(assigned) || storedSetup(settings, assigned) !== undefined) ? assigned : undefined;
+};
+
+// What a setup runs on before anything is connected or resolved: a written list, or a preset still to be worked out.
+// A snapshot of this is what a turn carries, so it is judged by one setup however its accounts change mid-turn.
+export type SetupLadder = { readonly kind: `pins`; readonly pins: readonly ModelPin[] } | { readonly kind: `preset`; readonly preset: PresetSetup };
+
+const NO_MODELS: SetupLadder = { kind: `pins`, pins: [] };
+
+export const setupLadder = (settings: Pick<SetupSettings, "modelSetups">, id: string | undefined): SetupLadder => {
+    if (id === undefined) {
+        return NO_MODELS;
+    }
+    const pins = storedSetup(settings, id)?.pins;
+    if (pins !== undefined) {
+        return { kind: `pins`, pins };
+    }
+    return isPresetSetup(id) ? { kind: `preset`, preset: id } : NO_MODELS;
+};
+
+export const roleLadder = (settings: SetupSettings, role: ModelRole): SetupLadder => setupLadder(settings, roleSetupId(settings, role));
+
+/** True only for a ladder that can never name a model, whatever is connected: a written list left empty. */
+export const ladderIsEmpty = (ladder: SetupLadder): boolean => ladder.kind === `pins` && ladder.pins.length === 0;
+
+const PRESET_RUNG = { high: 0, medium: 1, low: 2 } as const satisfies Record<PresetSetup, number>;
+
+// Enough to step over one spent account and then another; a preset longer than this would mostly be read, not tried.
+const PRESET_LENGTH = 3;
+
+// The first segment most of a catalog's ids share (`gemini`, `gpt`, `claude`): the provider's own family, as opposed to
+// a model it also serves from someone else, which Google's catalog does with Claude's.
+const ownPrefix = (models: readonly string[]): string | undefined => {
+    const counts = new Map<string, number>();
+    for (const model of models) {
+        const prefix = model.split(/[-_]/)[0] ?? model;
+        counts.set(prefix, (counts.get(prefix) ?? 0) + 1);
+    }
+    return [...counts].toSorted(([, a], [, b]) => b - a)[0]?.[0];
+};
+
+// A provider's pick for a rung: its own newest there, or a borrowed one only when it has none of its own.
+const newestOnRung = (models: readonly string[], rung: number): string | undefined => {
+    const own = ownPrefix(models);
+    const onRung = models.filter((model) => modelRungOf(model) === rung).toSorted(compareModelIds);
+    return onRung.find((model) => model.split(/[-_]/)[0] === own) ?? onRung[0];
+};
+
+/**
+ * A preset's models, from what is connected: each connected provider's newest model of its own on the preset's rung, in
+ * the order the sources come in, at most three. `models` must hold only models that can run a turn, since a preset feeds whole
+ * sessions as well as one-shot jobs. Local endpoints are left out: what someone installed for themselves is theirs to
+ * put on a setup, not a suggestion.
+ */
+export const presetPins = (preset: PresetSetup, sources: readonly ModelSource[]): readonly ModelPin[] =>
+    sources
+        .filter((source) => source.ready && !isEndpointProvider(source.provider))
+        .flatMap((source) => {
+            const newest = newestOnRung(source.models, PRESET_RUNG[preset]);
+            return newest === undefined ? [] : [{ provider: source.provider, model: newest }];
+        })
+        .slice(0, PRESET_LENGTH);
+
+export const ladderPins = (ladder: SetupLadder, sources: readonly ModelSource[]): readonly ModelPin[] =>
+    ladder.kind === `pins` ? ladder.pins : presetPins(ladder.preset, sources);
+
+/** The models a job runs on, in try order, before readiness filters them (model-pins.ts `readyChain`). */
+export const rolePins = (settings: SetupSettings, role: ModelRole, sources: readonly ModelSource[]): readonly ModelPin[] =>
+    ladderPins(roleLadder(settings, role), sources);
+
+/**
+ * Setups for a set of per-job lists, the shape settings had before setups (2026-10-12): jobs holding the same list share
+ * one setup, a list most of whose jobs are suggested one preset becomes that preset while it is free, and the rest are
+ * new setups. A job with no list, or an empty one, ran on nothing and is left on none. Exported for the settings
+ * history and for tests that want a job on exact models.
+ */
+export const setupsFromRoleLists = (lists: Partial<Record<ModelRole, readonly ModelPin[]>>): SetupSettings & { modelSetups: ModelSetup[] } => {
+    const modelSetups: ModelSetup[] = [];
+    const roleSetups: Partial<Record<ModelRole, string>> = {};
+    const groups = new Map<string, ModelRole[]>();
+    for (const role of MODEL_ROLE_IDS) {
+        const list = lists[role];
+        if (list !== undefined && list.length > 0) {
+            const key = JSON.stringify(list);
+            groups.set(key, [...(groups.get(key) ?? []), role]);
+        }
+    }
+    let made = 0;
+    for (const roles of groups.values()) {
+        const pins = lists[roles[0]!] ?? [];
+        // The preset most of these jobs are suggested; a tie goes to the first job's, the table's own order.
+        const votes = roles.map(suggestedSetup);
+        const preset = votes.toSorted((a, b) => votes.filter((vote) => vote === b).length - votes.filter((vote) => vote === a).length)[0]!;
+        const free = storedSetup({ modelSetups }, preset) === undefined;
+        const id = free ? preset : `setup-${++made}`;
+        modelSetups.push(free ? { id, pins: [...pins] } : { id, name: `Setup ${made}`, pins: [...pins] });
+        for (const role of roles) {
+            roleSetups[role] = id;
+        }
+    }
+    return { modelSetups, roleSetups };
+};