@intentic/sandbox-contract 1.330.0 → 1.332.0

package/src/events/sandbox-notice.ts

@@ -26,7 +26,22 @@ const failure = {
 };
 
 // The re-runs a resumed turn's row can name (events/resume.ts); a reason a reader does not know draws the row's text.
-const ResumeNoticeReasonSchema = z.enum(["auth", "outage", "restart", "stopped", "limit", "switched", "carried", "refused", "door", "overflow", "flagged", "continued"]);
+const ResumeNoticeReasonSchema = z.enum([
+    "auth",
+    "outage",
+    "restart",
+    "stopped",
+    "limit",
+    "switched",
+    "carried",
+    "trimmed",
+    "summarized",
+    "refused",
+    "door",
+    "overflow",
+    "flagged",
+    "continued",
+]);
 export type ResumeNoticeReason = z.infer<typeof ResumeNoticeReasonSchema>;
 
 // Every code this build writes, one per sentence shape, each with the facts that shape needs.
@@ -66,6 +81,21 @@ export const SandboxNoticeSchema = z.discriminatedUnion("code", [
     // A turn sent thin for a small window ("16k"): what was left out, and whether the base instructions were swapped too.
     z.object({ code: z.literal("contextTrim"), params: z.object({ window: z.string(), omitted: z.string().optional(), base: z.boolean() }) }),
     z.object({ code: z.literal("resumed"), params: z.object({ reason: ResumeNoticeReasonSchema }) }),
+    // How a turn a spent allowance held continued the conversation (schemas/providers/handoff.ts): `tokens` the context
+    // it started from and `from` the one carrying the session whole would have re-read (both worded, "118k"); `cleared`
+    // older tool outputs a trimmed copy stubbed; `model` the one that wrote a summary. `fellBack` names the hand-off that
+    // was asked for and could not be built, which then went on with the record's short hand-off instead.
+    z.object({
+        code: z.literal("handedOff"),
+        params: z.object({
+            mode: z.enum(["carry", "trim", "summary"]),
+            tokens: z.string().optional(),
+            from: z.string().optional(),
+            cleared: count.optional(),
+            model: z.string().optional(),
+            fellBack: z.boolean().optional(),
+        }),
+    }),
     // An agent's own dependency install starting: into its conversation's own copy (`ownCopy`) or the main tree; the
     // workspace root (`root`) and up to three project folders named (`projects`, each with its slash, already joined),
     // and how many `more` were not named.

package/src/events/transcript.ts

@@ -5,6 +5,7 @@ import { TurnErrandSchema, TurnSpeakerSchema } from "../schemas/speaker.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
 import { NeedSchema } from "../schemas/needs.js";
 import { HeldEndingSchema, RetryLadderSchema } from "../schemas/turn-break.js";
+import { HandoffOfferSchema } from "../schemas/providers/handoff.js";
 import { NoticeCodeSchema } from "./sandbox-notice.js";
 import { TranscriptAgentNoticeSchema } from "./agent-ui.js";
 import type { ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind } from "./requests.js";
@@ -134,6 +135,18 @@ export const TranscriptToolSchema: z.ZodType<TranscriptTool> = z.lazy(() =>
         subagent: TranscriptSubagentSchema.optional().describe(
             "The helper this call started, as the daemon's registry sees it: what it is, how it is going, what it has spent. What a card can say about a backgrounded child whose result is minutes away.",
         ),
+        input: z
+            .string()
+            .optional()
+            .describe(
+                "What the call was given, as JSON text cut to a few kilobytes, on a call whose input names no one-line target: an MCP tool's arguments, a delegation's prompt. Read afterwards to learn what was asked when the card alone cannot say.",
+            ),
+        startedAt: z.number().optional().describe("When the call was seen, in milliseconds. Absent on calls recorded before cards were stamped."),
+        endedAt: z
+            .number()
+            .optional()
+            .describe("When its result arrived, in milliseconds; absent while it runs, and on a call whose result never came."),
+        exitCode: z.number().int().optional().describe("A command's exit code, where the runtime reports one as a number rather than in its output."),
     }),
 );
 // The subagent a call started, on that call's card whichever mechanism started it (transcript-fold.ts places it).
@@ -176,6 +189,10 @@ export interface TranscriptTool {
     nested?: number | undefined;
     thinking?: string | undefined;
     subagent?: TranscriptSubagent | undefined;
+    input?: string | undefined;
+    startedAt?: number | undefined;
+    endedAt?: number | undefined;
+    exitCode?: number | undefined;
 }
 
 // Every ending that wakes a conversation off a condition watch; composing and parsing the wake is watch-wake.ts.
@@ -260,12 +277,17 @@ export const TranscriptRowSchema = z.object({
         .describe(
             "The run that produced this row. Present on everything a turn produced, absent on rows written outside one. A client draws a run's rows over whatever it already holds for that run, which is what this identifies; content cannot, because the last row of a live run keeps growing.",
         ),
-    // The turn's send time (user rows only), not settlement; the only row-moment the daemon actually knows.
+    // The turn's send time (user rows only), not settlement; the agent's rows carry `openedAt` instead.
     sentAt: z
+        .number()
+        .optional()
+        .describe("When it was sent, in milliseconds. On the user's rows only; the agent's own rows and notices carry `openedAt`."),
+    // Stamped by the daemon as it folds the frame that opens the row, since the frames themselves carry no clock.
+    openedAt: z
         .number()
         .optional()
         .describe(
-            "When it was sent, in milliseconds. On the user's rows only, because that is the only moment actually known: a turn's own frames arrive with no clock, so stamping the agent's rows could only ever mean the whole turn's start or end.",
+            "When an assistant bubble or a notice opened, in milliseconds, as the daemon folded the frame that started it. Absent on user rows, which carry `sentAt`, and on rows recorded before rows were stamped.",
         ),
     // A position moves under a rewind and a message's words can repeat, so this is the one name a message keeps.
     messageId: z
@@ -476,6 +498,9 @@ export const TurnEndingSchema = z.object({
                 .describe(
                     "The account the owner's policy is already moving this turn to, when it is; the surface then reports the move rather than offering a press.",
                 ),
+            handoff: HandoffOfferSchema.optional().describe(
+                "How the held turn can continue once its cache is cold: carry the session, trim it, or summarise it, which one the sandbox suggests, and which one a person picked. Absent where there is nothing to carry.",
+            ),
         })
         .optional()
         .describe("Present when the daemon still holds the refused turn whole, so a press re-runs it rather than appending a message after it."),

package/src/index.ts

@@ -188,6 +188,7 @@ export * from "./models/model-order.js";
 export * from "./models/model-offer.js";
 export * from "./models/model-pins.js";
 export * from "./models/model-roles.js";
+export * from "./models/model-setups.js";
 export * from "./models/plan-pools.js";
 export * from "./text/path-refs.js";
 export * from "./text/archives.js";
@@ -224,6 +225,7 @@ export * from "./schemas/extension-updates.js";
 export * from "./schemas/providers/fast-mode.js";
 export * from "./schemas/diff.js";
 export * from "./schemas/git/git.js";
+export * from "./schemas/git/git-scope.js";
 export * from "./schemas/git/git-history.js";
 export * from "./schemas/history.js";
 export * from "./schemas/hosts.js";
@@ -242,7 +244,9 @@ export * from "./schemas/panels.js";
 export * from "./schemas/personas.js";
 export * from "./schemas/privacy.js";
 export * from "./schemas/providers/plan-limits.js";
+export * from "./schemas/providers/handoff.js";
 export * from "./schemas/platform-link.js";
+export * from "./schemas/project-bring-back.js";
 export * from "./schemas/ports.js";
 export * from "./schemas/providers/provider-oauth.js";
 export * from "./schemas/providers/provider-subscriptions.js";
@@ -257,6 +261,7 @@ export * from "./schemas/settings.js";
 export * from "./schemas/settings-history.js";
 export * from "./schemas/share.js";
 export * from "./schemas/shared.js";
+export * from "./schemas/short-codes.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
 export * from "./schemas/state-plan.js";

package/src/models/agent-catalog.test.ts

@@ -29,7 +29,7 @@ describe("every provider/harness pair declares what it can do", () => {
     it.each(pairs)("$provider on the $harness harness", ({ provider, harness }) => {
         const capabilities = capabilitiesOf(provider, harness);
 
-        expect(["claude-code", "codex", "cursor", "opencode", "opencode-gemini", "acp", "pi"]).toContain(capabilities.runtime);
+        expect(["claude-code", "codex", "cursor", "opencode", "opencode-gemini", "acp", "devin", "pi"]).toContain(capabilities.runtime);
         expect(["modes", "plan"]).toContain(capabilities.permissions);
         expect(["full", "tools", "http", "none"]).toContain(capabilities.mcp);
         expect(capabilities.execution).toContain("shell");
@@ -163,11 +163,12 @@ test("every axis a record can lack has words for it", () => {
         rulebook: "none",
         secrets: "none",
         privacy: "none",
+        toolAllowlist: false,
     };
 
-    // Thirteen disclosable axes, thirteen sentences; `fastMode` is disclosed via fastAllowed, and `warm` (keep-warm, off by
+    // Fourteen disclosable axes, fourteen sentences; `fastMode` is disclosed via fastAllowed, and `warm` (keep-warm, off by
     // default) is no limit on the turn itself.
-    expect(limitationsOf(nothing)).toHaveLength(13);
+    expect(limitationsOf(nothing)).toHaveLength(14);
     expect(limitationsOf(nothing).join(" ")).not.toContain("fast");
 });
 

package/src/models/agent-catalog.ts

@@ -106,19 +106,21 @@ export const modesFor = (capabilities: AgentCapabilities): readonly PermissionMo
 export const clampMode = (mode: PermissionMode, capabilities: AgentCapabilities): PermissionMode =>
     modesFor(capabilities).includes(mode) ? mode : "bypassPermissions";
 
+// What each reach of `mcp` leaves out, said once per answer.
+const MCP_LIMITS = {
+    none: ["no MCP tools or plugins"],
+    http: ["MCP servers only, none of the daemon's own tools, no plugins"],
+    tools: ["no plugins"],
+    full: [],
+} as const satisfies Record<AgentCapabilities["mcp"], readonly string[]>;
+
 // What this pair cannot do, phrased for the sender; empty means the full ceiling. `fastMode` is deliberately not
 // disclosed here, since it also depends on the route and model; fastAllowed answers that instead.
 export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.permissions === "plan" ? ["no per-tool approvals"] : []),
     ...(capabilities.questions ? [] : ["no clarifying questions"]),
     ...(capabilities.steering ? [] : ["no mid-turn steering"]),
-    ...(capabilities.mcp === "none"
-        ? ["no MCP tools or plugins"]
-        : capabilities.mcp === "http"
-          ? ["MCP servers only, none of the daemon's own tools, no plugins"]
-          : capabilities.mcp === "tools"
-            ? ["no plugins"]
-            : []),
+    ...MCP_LIMITS[capabilities.mcp],
     ...(capabilities.execution.includes("js") ? [] : ["no code runs, shell only"]),
     ...(capabilities.effort ? [] : ["no effort control"]),
     ...(capabilities.commands ? [] : ["no slash commands"]),
@@ -131,6 +133,7 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.rulebook === "refuse-only" ? ["command rules can refuse but not hold"] : []),
     ...(capabilities.rulebook === "none" ? ["command rules not applied"] : []),
     ...(capabilities.secrets === "none" ? ["secrets reach the model unmasked"] : []),
+    ...(capabilities.toolAllowlist ? [] : ["no tool lists: an automation limited to some tools won't run here"]),
 ];
 
 // Claude's compile-time model floor, shared by daemon and web pre-load; versioned ids only, never a tier alias.

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,71 +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",
+        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[];
 
@@ -142,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"),
-    },
-];