@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/models/model-order.ts

@@ -0,0 +1,163 @@
+// Orders a model catalog the same way for every provider, since only Anthropic's /v1/models returns one worth keeping.
+// Every other provider hands back a set in registry order, so this file derives an order instead, from the two facts an
+// id reliably carries: tier (the adjective) and release (the numbers).
+
+// A version-ish segment: digits/dots, optionally prefixed by v or k (`5.1`, `k3`); anything else is a name.
+const VERSION_SEGMENT = /^(?:v|k)?[\d.]+$/i;
+
+// A date stamp, not a version component: 6+ digits; conflating the two misorders a dated build's compare.
+const DATE_SEGMENT = /^\d{6,}$/;
+
+const segmentsOf = (id: string): string[] => id.split(/[-_]/);
+
+// A model's family: its id with every version-ish segment dropped, so claude-opus-5 and claude-opus-4-8 land together.
+// Derived, never listed.
+export const familyOf = (id: string): string => {
+    const stem = segmentsOf(id)
+        .filter((segment) => !VERSION_SEGMENT.test(segment))
+        .join("-");
+    // An all-numeric id, or an ACP row's empty one, has no stem: it stands as its own family.
+    return stem === "" ? id : stem;
+};
+
+export interface ModelRelease {
+    // Version components in id order; empty for an unversioned id, which then reads as the oldest of its tier.
+    readonly version: readonly number[];
+    // The id's date stamp, 0 for none: the tiebreak between two builds of the same version.
+    readonly date: number;
+}
+
+export const releaseOf = (id: string): ModelRelease => {
+    const numeric = segmentsOf(id)
+        .filter((segment) => VERSION_SEGMENT.test(segment))
+        .map((segment) => segment.replace(/^[vk]/i, ""));
+    const stamps = numeric.filter((segment) => DATE_SEGMENT.test(segment)).map(Number);
+    return {
+        version: numeric
+            .filter((segment) => !DATE_SEGMENT.test(segment))
+            .flatMap((segment) => segment.split(".").map(Number))
+            .filter((component) => Number.isFinite(component)),
+        date: Math.max(0, ...stamps),
+    };
+};
+
+// Newest first. A missing component reads as -1, so gpt-5 sorts under gpt-5.1; the date stamp breaks the rest.
+const compareRelease = (left: ModelRelease, right: ModelRelease): number => {
+    for (let index = 0; index < Math.max(left.version.length, right.version.length); index += 1) {
+        const diff = (right.version[index] ?? -1) - (left.version[index] ?? -1);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return right.date - left.date;
+};
+
+// Unranked families lead, not sink: an id with no tier word is likelier a new flagship than a budget model.
+const TIER_RANK: Readonly<Record<string, number>> = {
+    // Frontier: the tier a vendor ships last and charges most for.
+    opus: 0,
+    fable: 0,
+    pro: 0,
+    max: 0,
+    ultra: 0,
+    heavy: 0,
+    // Everyday: the workhorse a step below the frontier.
+    sonnet: 1,
+    flash: 1,
+    mini: 1,
+    // Efficient: the cheap/fast end, the rung that costs less than the one above it.
+    haiku: 2,
+    // An open-weights model re-served beside a vendor's line (gpt-oss on Google's) is this rung by construction.
+    oss: 2,
+    lite: 2,
+    nano: 2,
+    fast: 2,
+    small: 2,
+};
+
+const UNRANKED = -1;
+
+// A release-local ladder (Codex 5.6 sol>terra>luna), kept separate so cross-release recency still outranks it.
+const RELEASE_TIER_RANK: Readonly<Record<string, number>> = {
+    sol: 0,
+    terra: 1,
+    luna: 2,
+};
+
+const lastRankOf = (family: string, ranks: Readonly<Record<string, number>>): number => {
+    let rank = UNRANKED;
+    for (const segment of family.split("-")) {
+        const found = ranks[segment];
+        if (found !== undefined) {
+            rank = found;
+        }
+    }
+    return rank;
+};
+
+const releaseTierRankOf = (family: string): number => lastRankOf(family, RELEASE_TIER_RANK);
+
+// How hard an id says it will think; ties on tier, so only compareCheapestFirst's tiebreak may read it.
+const THINKING_RANK: Readonly<Record<string, number>> = {
+    minimal: 0,
+    none: 0,
+    low: 1,
+    medium: 3,
+    high: 4,
+    max: 4,
+    // A switch, not a level: vending `kimi-k2` beside `kimi-k2-thinking` names the same model, reasoning turned on.
+    thinking: 4,
+};
+
+// An id naming no level sits between both ends, the provider's default, not the cheapest or dearest reading.
+const UNSTATED_THINKING = 2;
+
+const thinkingRankOf = (family: string): number => {
+    const rank = lastRankOf(family, THINKING_RANK);
+    return rank === UNRANKED ? UNSTATED_THINKING : rank;
+};
+
+// The last recognized word wins: gemini-flash-lite is Flash's cheap end, gpt-codex-max is Codex's frontier end.
+export const tierRankOf = (family: string): number => lastRankOf(family, TIER_RANK);
+
+// The canonical order of two ids: tier first, then release, then a release-local tier. Stable under Array#toSorted, so
+// ids this rule cannot separate keep their arrival order.
+export const compareModelIds = (left: string, right: string): number => {
+    const leftFamily = familyOf(left);
+    const rightFamily = familyOf(right);
+    return (
+        tierRankOf(leftFamily) - tierRankOf(rightFamily) ||
+        compareRelease(releaseOf(left), releaseOf(right)) ||
+        releaseTierRankOf(leftFamily) - releaseTierRankOf(rightFamily)
+    );
+};
+
+// The order for a catalog its endpoint published as an unordered set (everything but Anthropic). Ties break on id, not
+// arrival order, since a registry can reorder a tied set between refreshes.
+export const compareUnrankedModelIds = (left: string, right: string): number => compareModelIds(left, right) || left.localeCompare(right);
+
+// The same tier scale read from the weakest end, for the caller that wants the cheapest model, not the strongest. An
+// unranked family still sinks last on both orders; a tier-less catalog (Kimi) falls back to its newest release.
+export const compareCheapestFirst = (left: string, right: string): number => {
+    const leftFamily = familyOf(left);
+    const rightFamily = familyOf(right);
+    return (
+        tierRankOf(rightFamily) - tierRankOf(leftFamily) ||
+        // Before release: two rows differing only by thinking are the same model; recency must not pick between them.
+        thinkingRankOf(leftFamily) - thinkingRankOf(rightFamily) ||
+        compareRelease(releaseOf(left), releaseOf(right)) ||
+        releaseTierRankOf(rightFamily) - releaseTierRankOf(leftFamily)
+    );
+};
+
+// Tier only, not release or thinking level, so a downgrade stays legible as one. An unranked family is false on either
+// side: an unranked candidate might be the next flagship, and an unranked pick's tier is unknown to have been beaten.
+export const isCheaperRung = (candidate: string, pick: string): boolean => {
+    const candidateRank = tierRankOf(familyOf(candidate));
+    const pickRank = tierRankOf(familyOf(pick));
+    return candidateRank !== UNRANKED && pickRank !== UNRANKED && candidateRank > pickRank;
+};
+
+// 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;

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

@@ -1,27 +1,17 @@
 import { expect, test } from "vitest";
 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 the OWNER'S OWN LIST
- * decides it and nothing else, and that there is a rung underneath the first one whenever they wrote one.
- *
- * 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.
+import type { ModelPin } from "../schemas/agent.js";
+
+// Which models a job spends, and in what order: the owner's own list decides, nothing is derived for an empty one, and
+// there is a fallback rung whenever one is written.
+
+// A pin as settings rows store one; tests focus on order, so most entries carry just provider:model.
 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. 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.
+// Catalogs as providers publish them; the resolver never reads them, so a wrong fixture would hide it.
 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`] };
@@ -29,21 +19,15 @@ 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 every surface naming
-// the spend up front reads.
+// The model that answers when nothing goes wrong: the head of the chain, what every surface 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` });
-    // The picker's custom-id escape hatch reaches here too: a catalog can lag a release, and running something
-    // other than what the settings row names would be the worse failure.
+    // The picker's custom-id escape hatch reaches here too: a lagging catalog still must run the exact id named.
     expect(head([CLAUDE], [`claude:claude-haiku-9`])).toEqual({ provider: `claude`, model: `claude-haiku-9` });
 });
 
-/* 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();
@@ -51,33 +35,22 @@ 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 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", () => {
-    // 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(readyChain([CLAUDE], [configured])).toEqual([configured]);
 });
 
 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();
 });
 
-/* 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(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` },
@@ -94,28 +67,21 @@ 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(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 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.
+    // A duplicate pin is a real state (hand-edited lists, one entry reused across jobs), not a bug to collapse.
     expect(readyChain([CLAUDE], [`claude:claude-haiku-4-5`, `claude:claude-haiku-4-5`].map(pin))).toEqual([
         { provider: `claude`, model: `claude-haiku-4-5` },
     ]);
 });
 
-/* 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. */
+// A configured endpoint is a provider like any other here: its picker options come from the same catalog.
 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.
+    // parsePinned splits on the first colon; an id with its own colon needs the slash form or parsing breaks.
     expect(modelPinKey({ provider: `endpoint/ollama`, model: `qwen3-coder` })).toBe(`endpoint/ollama:qwen3-coder`);
 });

package/src/models/model-pins.ts

@@ -0,0 +1,57 @@
+import { modelsFor } from "./agent-catalog.js";
+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).
+
+// 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.
+export interface ModelSource {
+    // AgentProvider, not NativeProvider: an endpoint's id is user-created, no fixed union; nothing here ranks cost.
+    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.
+    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 picker mints. Used to compare
+// entries, dedupe a role list, and store autoFastModels.
+export const modelPinKey = (choice: ModelChoice): string => `${choice.provider}:${choice.model}`;
+
+// Splits on the first colon only: a provider id never contains one, a model id might. Exported since autoFastModels
+// stores these keys.
+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, or the raw id when the static catalog has not caught up with it
+// (a real case, via the picker's custom-id escape hatch).
+export const pinnedModelLabel = (choice: ModelChoice): string =>
+    modelsFor(choice.provider).find((option) => option.value === choice.model)?.label ?? choice.model;
+
+// Filters pinned entries to ready providers only; there is no floor beneath a written list, so an account left unnamed
+// is never reached. Returns whole pins, not bare pairs, since effort, thinking and harness must survive with the pick.
+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: the picker's custom-id escape hatch must run exactly the id it names.
+    const requested = pinned.filter((pin) => ready.has(pin.provider));
+    // First occurrence wins, whole: two entries can name one model with different knobs, and the earlier is meant.
+    const chain: ModelPin[] = [];
+    for (const pin of requested) {
+        if (!chain.some((held) => modelPinKey(held) === modelPinKey(pin))) {
+            chain.push(pin);
+        }
+    }
+    return chain;
+};

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

@@ -0,0 +1,38 @@
+import { expect, test } from "vitest";
+import { MODEL_ROLE_BLOCKS, MODEL_ROLES, type ModelRoleSpec } 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.
+
+// 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("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));
+});
+
+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);
+    }
+});

package/src/models/model-roles.ts

@@ -0,0 +1,180 @@
+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.
+
+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";
+
+// `id` is a bare string here; narrowed to the role union on `ModelRoleSpec` below, since that union derives from this
+// table via `satisfies`.
+interface ModelRoleRow {
+    readonly id: string;
+    // The owner's own words for the job; never a difficulty tier.
+    readonly label: string;
+    // 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;
+}
+
+// Ids are wire-stable (`AgentTurn.runRole`); order matches the settings page's block grouping below.
+export const MODEL_ROLES = [
+    {
+        id: "commit-message",
+        label: "Commit messages",
+        blurb: "The subject written when an agent's work lands, and the release note under it.",
+        kind: "helper",
+        icon: "file-edit",
+    },
+    {
+        id: "session-title",
+        label: "Session titles",
+        blurb: "The name a conversation wears on the board, written a second into its first turn.",
+        kind: "helper",
+        icon: "pencil",
+    },
+    {
+        // Prompt includes the command about to run, which may be attacker-controlled; a small model can be swayed.
+        id: "safety-judge",
+        label: "Safety judge",
+        blurb: "Which model reads your safety policy before a flagged command runs.",
+        kind: "helper",
+        icon: "shield",
+    },
+    {
+        id: "loop-verdict",
+        label: "Loop verdicts",
+        blurb: "Whether a loop's iteration met the goal, or the loop goes round again.",
+        kind: "helper",
+        icon: "check-square",
+    },
+    {
+        // Picks one persona id or none from a fixed list; a classification, not free text.
+        id: "persona-router",
+        label: "Persona routing",
+        blurb: "Which model reads a new chat's first message and picks the persona for it.",
+        kind: "helper",
+        icon: "users",
+    },
+    {
+        id: "pipeline-fix",
+        label: "Pipeline fixes",
+        blurb: "The agent started by Fix on a red pipeline.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "wave-pulse",
+    },
+    {
+        id: "deployment-fix",
+        label: "Deployment fixes",
+        blurb: "The agent started by Fix on a deployment that is down.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "server",
+    },
+    {
+        id: "maintenance-chore",
+        label: "Maintenance chores",
+        blurb: "A chore run started from the Maintenance board.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "wrench",
+    },
+    {
+        id: "documentation-run",
+        label: "Documentation runs",
+        blurb: "A pass over a repo's own documentation.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "book",
+    },
+    {
+        id: "acceptance-run",
+        label: "Acceptance runs",
+        blurb: "One session per story in an acceptance fan-out.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "list-check",
+    },
+    {
+        id: "pre-push-fix",
+        label: "Pre-push fixes",
+        blurb: "The fix proposed when a check fails on the way to a push.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "cloud-upload",
+    },
+    {
+        // 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",
+    },
+    {
+        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",
+    },
+    {
+        id: "loop-iteration",
+        label: "Loop iterations",
+        blurb: "Each round of a loop working towards its goal.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "repeat",
+    },
+] as const satisfies readonly ModelRoleRow[];
+
+export type ModelRole = (typeof MODEL_ROLES)[number]["id"];
+export type ModelRoleSpec = ModelRoleRow & { readonly id: ModelRole };
+
+export const MODEL_ROLE_IDS = MODEL_ROLES.map((role) => role.id) as readonly ModelRole[];
+
+// 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/{plan-pools.test.ts → models/plan-pools.test.ts}

@@ -1,10 +1,9 @@
 import { expect, test } from "vitest";
 import { bindingWindow, gatesModel, gatingWindows, scopedWindow } from "./plan-pools.js";
-import type { AccountUsage, UsageWindow } from "./schemas/plan-limits.js";
+import type { AccountUsage, UsageWindow } from "../schemas/plan-limits.js";
 
-/* ONE RULE FOR "WHICH POOL STANDS IN THE WAY OF THIS MODEL", shared by the daemon's picker and the browser's
- * rings. What these pin is the case the six rules it replaced disagreed on: a plan that meters models
- * separately, where the account's fullest pool and the pool a given model spends are different allowances. */
+// One rule for which pool blocks a given model, shared by the daemon and the browser: a plan can meter models
+// separately, so the account's fullest pool need not be the model's own.
 
 const window = (over: Partial<UsageWindow> & Pick<UsageWindow, "kind">): UsageWindow => ({ utilization: 10, gates: "all", ...over });
 const usage = (...windows: UsageWindow[]): AccountUsage => ({ windows, measuredAt: 0 });
@@ -24,7 +23,6 @@ const CLAUDE = usage(
 test("matches a pool's names as runs of whole words against the id and the label alike", () => {
     expect(gatesModel({ models: ["opus"] }, { id: "claude-opus-4-6" })).toBe(true);
     expect(gatesModel({ models: ["Opus"] }, { id: "some-id", label: "Claude Opus 4.6" })).toBe(true);
-    // "Sonnet" is not in "claude-opus-4-6", and a substring test is what would have said "son" was.
     expect(gatesModel({ models: ["son"] }, { id: "claude-sonnet-4-6" })).toBe(false);
     expect(gatesModel({ models: ["claude opus"] }, { id: "claude-opus-4-6" })).toBe(true);
     expect(gatesModel({ models: ["opus claude"] }, { id: "claude-opus-4-6" })).toBe(false);
@@ -33,12 +31,11 @@ test("matches a pool's names as runs of whole words against the id and the label
 });
 
 test("a Google account spent for Gemini still has room for Claude Opus, and the other way round", () => {
-    // The Antigravity case: one sign-in, two allowances on two clocks. Reading the account's fullest pool put a
-    // red ring over Claude Opus while its own pool sat at 27%.
+    // One account, two independently metered pools (Gemini vs Claude/GPT), each on its own clock.
     expect(bindingWindow(GOOGLE, { id: "claude-opus-4-6-thinking" })?.kind).toBe("google:3p-weekly");
     expect(bindingWindow(GOOGLE, { id: "gpt-oss-120b" })?.kind).toBe("google:3p-weekly");
     expect(bindingWindow(GOOGLE, { id: "gemini-3-pro" })?.kind).toBe("google:gemini-weekly");
-    // A family the channel has not published a pool for is gated by nothing: unmeasured, never blocked.
+    // A model family with no published pool is unmeasured, not blocked.
     expect(bindingWindow(GOOGLE, { id: "kimi-k2" })).toBeUndefined();
 });
 
@@ -49,8 +46,6 @@ test("a Claude account's spent Opus slice does not bind a Haiku call, and its ow
 });
 
 test("with no model named, the account's tightest pool is the answer, and a pool gating nothing is never it", () => {
-    // The Cowork surface pool is at 99% and gates none of this sandbox's turns: shown on the roster, never the
-    // account's headroom.
     expect(bindingWindow(CLAUDE)?.kind).toBe("model:Opus");
     expect(gatingWindows(CLAUDE).map((entry) => entry.kind)).toEqual(["five_hour", "seven_day", "model:Opus"]);
     expect(bindingWindow(undefined)).toBeUndefined();
@@ -59,7 +54,7 @@ test("with no model named, the account's tightest pool is the answer, and a pool
 
 test("names the pool a plan meters this model by on its own, preferring the more specific and refusing a tie", () => {
     expect(scopedWindow(CLAUDE, { id: "claude-opus-4-6" })?.kind).toBe("model:Opus");
-    // The all-models weekly is not this model's own allowance, so a plan with no slice for it says nothing.
+    // five_hour and seven_day meter all models, not just this one; scopedWindow needs a model-specific pool.
     expect(scopedWindow(CLAUDE, { id: "claude-haiku-4-5" })).toBeUndefined();
     const layered = usage(
         window({ kind: "model:Opus", gates: { models: ["Opus"] } }),