@intentic/sandbox-contract 1.330.0 → 1.332.0

package/src/schemas/project-bring-back.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+
+// BRINGING AN AGENT'S WORK BACK FROM A FOLDER'S OWN SANDBOX: what the machine agent's `sync changes`, `sync bring-back`,
+// `sync restore` and `sync direction --json` print, and so what the editor reads off the `intentic:project` event. The
+// desktop app (project.rs) runs the verb and relays its JSON whole as `result`, beside a `kind` of its own, so it
+// keeps no field of these: a new one reaches the editor without a desktop release. The machine agent wrote these as
+// TypeScript interfaces and the editor as its own zod, which disagreed in name (the agent's internal `held` reason
+// prints as `conflict: true`).
+
+export const ProjectDirectionSchema = z.enum(["to-sandbox", "both"]);
+export type ProjectDirection = z.infer<typeof ProjectDirectionSchema>;
+
+export const ProjectChangeKindSchema = z.enum(["added", "modified", "deleted"]);
+export type ProjectChangeKind = z.infer<typeof ProjectChangeKindSchema>;
+
+// One entry the sandbox changed that the folder has not. `size` is the sandbox copy's, what bringing it back writes;
+// `conflict` marks a `modified` path changed in the folder too, which a bring-back lists but keeps the folder's copy of.
+export const ProjectChangeSchema = z.object({
+    path: z.string().min(1),
+    kind: ProjectChangeKindSchema,
+    size: z.number().optional(),
+    // The agent only ever prints `true`; a reader takes any boolean.
+    conflict: z.boolean().optional(),
+});
+export type ProjectChange = z.infer<typeof ProjectChangeSchema>;
+
+// An entry a bring-back or restore left alone, and why (the folder's copy changed too, say).
+export const ProjectSkippedSchema = z.object({ path: z.string(), reason: z.string() });
+export type ProjectSkipped = z.infer<typeof ProjectSkippedSchema>;
+
+export const ProjectAppliedSchema = z.object({ path: z.string(), kind: ProjectChangeKindSchema });
+export type ProjectApplied = z.infer<typeof ProjectAppliedSchema>;
+
+// A verb that ran and failed, in the agent's own sentence.
+export const ProjectFailedSchema = z.object({ ok: z.literal(false), error: z.string() });
+
+export const ProjectChangesResultSchema = z.object({
+    ok: z.literal(true),
+    // The pairing's key, which names the folder and its sandbox.
+    pairing: z.string().optional(),
+    direction: ProjectDirectionSchema,
+    changes: z.array(ProjectChangeSchema),
+    // More changes than the agent lists (its CHANGES_MAX); the rest are not named.
+    truncated: z.boolean().optional(),
+});
+export type ProjectChangesResult = z.infer<typeof ProjectChangesResultSchema>;
+
+export const BringBackResultSchema = z.object({
+    ok: z.literal(true),
+    // The restore point that undoes it.
+    point: z.string().min(1),
+    applied: z.array(ProjectAppliedSchema),
+    skipped: z.array(ProjectSkippedSchema).optional(),
+});
+export type BringBackResult = z.infer<typeof BringBackResultSchema>;
+
+export const RestoreResultSchema = z.object({
+    ok: z.literal(true),
+    restored: z.number(),
+    // The editor only counts what a restore did, so a skipped list of a shape it does not know reads as no list rather
+    // than costing the whole answer, and with it the step that waits for it.
+    skipped: z.array(ProjectSkippedSchema).optional().catch(undefined),
+});
+export type RestoreResult = z.infer<typeof RestoreResultSchema>;
+
+export const DirectionResultSchema = z.object({ ok: z.literal(true), direction: ProjectDirectionSchema });
+export type DirectionResult = z.infer<typeof DirectionResultSchema>;
+
+// The `intentic:project` event's detail: the verb's kind with its result, or a verb that never reached its sandbox
+// (no machine agent runs on this computer, say).
+export const ProjectAnswerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("changes"), result: z.union([ProjectChangesResultSchema, ProjectFailedSchema]) }),
+    z.object({ kind: z.literal("brought-back"), result: z.union([BringBackResultSchema, ProjectFailedSchema]) }),
+    z.object({ kind: z.literal("restored"), result: z.union([RestoreResultSchema, ProjectFailedSchema]) }),
+    z.object({ kind: z.literal("direction"), result: z.union([DirectionResultSchema, ProjectFailedSchema]) }),
+    z.object({ kind: z.literal("error"), verb: z.string(), error: z.string() }),
+]);
+export type ProjectAnswer = z.infer<typeof ProjectAnswerSchema>;

package/src/schemas/providers/handoff.test.ts

@@ -0,0 +1,42 @@
+import { type HandoffMode, handedOffLine, handedOffNotice, suggestHandoff } from "./handoff.js";
+
+const THRESHOLDS = { carryUnder: 150_000, summaryOver: 700_000 };
+const all = (): boolean => true;
+
+describe("suggestHandoff", () => {
+    it("carries a small session, trims the middle band, summarises a very large one", () => {
+        expect(suggestHandoff(90_000, all, THRESHOLDS)).toBe("carry");
+        expect(suggestHandoff(150_000, all, THRESHOLDS)).toBe("trim");
+        expect(suggestHandoff(699_999, all, THRESHOLDS)).toBe("trim");
+        expect(suggestHandoff(700_000, all, THRESHOLDS)).toBe("summary");
+    });
+
+    it("carries when nothing measured the session, since there is no size to save on", () => {
+        expect(suggestHandoff(undefined, all, THRESHOLDS)).toBe("carry");
+    });
+
+    it("falls to the next way where the preferred one is not available", () => {
+        const noTrim = (mode: HandoffMode): boolean => mode !== "trim";
+        expect(suggestHandoff(400_000, noTrim, THRESHOLDS)).toBe("summary");
+        const carryOnly = (mode: HandoffMode): boolean => mode === "carry";
+        expect(suggestHandoff(900_000, carryOnly, THRESHOLDS)).toBe("carry");
+        expect(suggestHandoff(900_000, () => false, THRESHOLDS)).toBeUndefined();
+    });
+});
+
+describe("handedOffLine", () => {
+    it("names what the continuing session started from beside what carrying would have re-read", () => {
+        expect(handedOffLine({ mode: "trim", tokens: 112_400, from: 431_000, cleared: 180 })).toBe(
+            "Continued in a trimmed copy of the session (about 112k tokens instead of 431k): 180 older tool outputs cleared, every message and tool call kept.",
+        );
+        expect(handedOffLine({ mode: "summary", model: "claude-haiku-5-5", from: 431_000 })).toBe(
+            "Continued in a fresh session opened with a summary of the conversation written by claude-haiku-5-5.",
+        );
+        expect(handedOffLine({ mode: "carry", tokens: 431_000 })).toBe("Continued in the same session, re-reading all of it (about 431k tokens).");
+    });
+
+    it("says plainly when the way picked could not be built", () => {
+        expect(handedOffLine({ mode: "trim", fellBack: true })).toBe("Could not trim the session for the hand-off, so it was carried whole.");
+        expect(handedOffNotice({ mode: "summary", fellBack: true })).toStrictEqual({ code: "handedOff", params: { mode: "summary", fellBack: true } });
+    });
+});

package/src/schemas/providers/handoff.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { tokensLabel } from "../keep-warm.js";
+import type { SandboxNotice } from "../../events/sandbox-notice.js";
+
+// What a conversation hands the session that continues it after a spent usage allowance, when the prompt cache is cold
+// and continuing means reading the conversation again from scratch. Measured on real sessions before it was built
+// (sandbox/bench/handoff-bench.ts, 2026-10-09): context is ~94% tool output, and every call of the next turn re-reads
+// whatever the session starts from, so the starting size sets the cost of the whole turn, not just of its first call.
+//
+//   carry    resume the session as it is: the model keeps everything, and re-reads all of it
+//   trim     resume a copy of the session with older tool output cleared; every message and tool call stays
+//   summary  a fresh session opened with a smaller model's summary and the last exchanges word for word
+//
+// The sandbox suggests one by the conversation's size; the person picks, on the card or as a standing setting.
+
+export const HANDOFF_MODES = ["carry", "trim", "summary"] as const;
+export const HandoffModeSchema = z.enum(HANDOFF_MODES);
+export type HandoffMode = z.infer<typeof HandoffModeSchema>;
+
+// The standing answer: `suggested` follows the size-based suggestion, anything else names one mode, used wherever it
+// is available.
+export const LimitHandoffSchema = z.enum(["suggested", ...HANDOFF_MODES]);
+export type LimitHandoff = z.infer<typeof LimitHandoffSchema>;
+
+// How many of the newest tool results a trimmed session keeps whole.
+export const TRIM_KEEPS_RESULTS = 10;
+
+export const HandoffOfferSchema = z.object({
+    suggested: HandoffModeSchema.describe("The hand-off the sandbox would use unless told otherwise."),
+    basis: z
+        .enum(["size", "setting"])
+        .describe("Why that one: the conversation's size (the sandbox's suggestion), or the owner's standing setting naming it."),
+    carry: z
+        .object({
+            tokens: z.number().optional().describe("The context resuming the session re-reads. Absent where nothing measured it."),
+        })
+        .optional()
+        .describe("Present where the session can be resumed as it is."),
+    trim: z
+        .object({
+            tokens: z.number().describe("The estimated context a trimmed copy of the session starts from."),
+            cleared: z.number().describe("How many older tool outputs trimming clears."),
+        })
+        .optional()
+        .describe("Present where this runtime's session can be trimmed: a Claude Code session the sandbox holds."),
+    summary: z
+        .object({
+            tokens: z.number().describe("The estimated context a fresh session opened with the summary starts from."),
+            reads: z.number().optional().describe("The estimated tokens the summarising model reads once to write it."),
+        })
+        .optional()
+        .describe("Present where a model is set for hand-off summaries (Sandbox ▸ Agent ▸ Models)."),
+    chosen: HandoffModeSchema.optional().describe("The hand-off a person picked for this held turn, which every later send of it uses."),
+});
+export type HandoffOffer = z.infer<typeof HandoffOfferSchema>;
+
+export const ChooseHandoffSchema = z.object({
+    conversationId: z.string().min(1).describe("Which conversation's held turn."),
+    handoff: HandoffModeSchema.describe("How the next send of the held turn continues the conversation."),
+});
+export type ChooseHandoff = z.infer<typeof ChooseHandoffSchema>;
+
+export const handoffAvailable = (offer: HandoffOffer, mode: HandoffMode): boolean => offer[mode] !== undefined;
+
+// The sandbox's suggestion for a session of `tokens` context: carry a small one (trimming saves little), trim the
+// middle band (keeps almost everything at a fraction of the read), summarise a very large one (a trimmed copy still
+// holds every message and tool call, which past ~700k is itself large). Falls to whatever is available.
+export const suggestHandoff = (
+    tokens: number | undefined,
+    available: (mode: HandoffMode) => boolean,
+    thresholds: { readonly carryUnder: number; readonly summaryOver: number },
+): HandoffMode | undefined => {
+    const order: readonly HandoffMode[] =
+        tokens === undefined || tokens < thresholds.carryUnder
+            ? ["carry", "trim", "summary"]
+            : tokens >= thresholds.summaryOver
+              ? ["summary", "trim", "carry"]
+              : ["trim", "summary", "carry"];
+    return order.find((mode) => available(mode));
+};
+
+// How a held turn actually continued, told once as its re-run starts, which the transcript keeps as a row: what it
+// started from beside what carrying the session whole would have re-read. `fellBack` names a hand-off that was asked for
+// and could not be built (no session file to trim, no model answered for the summary), which went on with the short
+// record hand-off instead.
+export const HandedOffSchema = z.object({
+    mode: HandoffModeSchema,
+    tokens: z.number().optional().describe("The context the continuing session starts from, estimated."),
+    from: z.number().optional().describe("What carrying the session whole would have re-read."),
+    cleared: z.number().optional().describe("Older tool outputs a trimmed copy cleared."),
+    model: z.string().optional().describe("The model that wrote the summary."),
+    fellBack: z.boolean().optional(),
+});
+export type HandedOff = z.infer<typeof HandedOffSchema>;
+
+export const handedOffNotice = (event: HandedOff): Extract<SandboxNotice, { code: "handedOff" }> => ({
+    code: "handedOff",
+    params: {
+        mode: event.mode,
+        ...(event.tokens === undefined ? {} : { tokens: tokensLabel(event.tokens) }),
+        ...(event.from === undefined ? {} : { from: tokensLabel(event.from) }),
+        ...(event.cleared === undefined ? {} : { cleared: event.cleared }),
+        ...(event.model === undefined ? {} : { model: event.model }),
+        ...(event.fellBack === true ? { fellBack: true } : {}),
+    },
+});
+
+/** The transcript's line for how a held turn continued. */
+export const handedOffLine = (event: HandedOff): string => {
+    if (event.fellBack === true) {
+        return event.mode === "trim"
+            ? "Could not trim the session for the hand-off, so it was carried whole."
+            : "Could not write a summary for the hand-off, so the fresh session opened with the recent conversation and where the work stands instead.";
+    }
+    const tokens = event.tokens === undefined ? undefined : tokensLabel(event.tokens);
+    switch (event.mode) {
+        case "carry":
+            return `Continued in the same session, re-reading all of it${tokens === undefined ? "" : ` (about ${tokens} tokens)`}.`;
+        case "trim": {
+            const cleared = event.cleared ?? 0;
+            const size =
+                tokens === undefined ? "" : event.from === undefined ? ` (about ${tokens} tokens)` : ` (about ${tokens} tokens instead of ${tokensLabel(event.from)})`;
+            return `Continued in a trimmed copy of the session${size}: ${cleared} older tool output${cleared === 1 ? "" : "s"} cleared, every message and tool call kept.`;
+        }
+        case "summary":
+            return `Continued in a fresh session opened with a summary of the conversation${event.model === undefined ? "" : ` written by ${event.model}`}.`;
+    }
+};

package/src/schemas/providers/plan-limits.ts

@@ -3,6 +3,7 @@ import { ChildRunSchema, PAGE_VALUE_MAX } from "../../events/requests.js";
 import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../../models/provider-specs.js";
 import { AgentHarnessSchema, AgentProviderSchema, ConversationIdSchema, EditorContextSchema } from "../agent.js";
 import { MENTION_LIMIT } from "../../text/mentions.js";
+import { HandoffModeSchema } from "./handoff.js";
 // Headroom is one shape shared by every provider, not a Claude idea others imitate: a native account and a routed
 // subscription differ in who holds the credential, never in what a reading is. Every surface that draws a percentage
 // reads this one type.
@@ -23,6 +24,18 @@ export const UsageWindowSchema = z.object({
     utilization: z.number(), // 0-100
     resetsAt: z.number().optional(),
     gates: WindowGatesSchema,
+    rounded: z
+        .boolean()
+        .optional()
+        .describe(
+            "The provider rounds this figure to a whole percent (Anthropic does), so a reading of 100 may be 99.5 and the pool can still serve. Such a pool reads as at the line, not spent: only the provider's refusal proves it empty.",
+        ),
+    lapsedAt: z
+        .number()
+        .optional()
+        .describe(
+            "When the window this pool was last read in closed, in epoch seconds, while nothing has read the pool since. Its `utilization` is then 0, the floor every new window starts from, not a measurement, and `resetsAt` is absent because the next reset is unknown.",
+        ),
 });
 export type UsageWindow = z.infer<typeof UsageWindowSchema>;
 // A failed re-read, whatever the cause: a 429 park, a 403 asking for verification, a 5xx, a timeout. Recorded as the fact
@@ -59,7 +72,9 @@ export const AccountStateSchema = z.discriminatedUnion("kind", [
         kind: z.literal("ready"),
         room: z
             .number()
-            .describe("How much of the fullest pool that gates the turn is left, in percent (above 0, up to 100). Pickers take the most room."),
+            .describe(
+                "How much of the fullest pool that gates the turn is left, in percent (0 up to 100). Pickers take the most room. 0 is a rounded pool read at 100: at the line, tried after an unmeasured account, never a limit move's destination.",
+            ),
     }),
     z.object({
         kind: z.literal("spent"),
@@ -391,8 +406,11 @@ export const ResumeRoutingSchema = z.object({
         .boolean()
         .optional()
         .describe(
-            "When the account changes, keep the provider session (the model keeps everything, and re-reads all of it once on the other account) rather than opening a fresh one seeded from the record. Ignored when the provider changes, or when nothing changes.",
+            "When the account changes, keep the provider session (the model keeps everything, and re-reads all of it once on the other account) rather than opening a fresh one seeded from the record. Ignored when the provider changes, or when nothing changes. `handoff` says the same and more; it wins where both are given.",
         ),
+    handoff: HandoffModeSchema.optional().describe(
+        "How a turn a spent allowance held continues the conversation, on this account or another: `carry` resumes the session as it is, `trim` resumes a copy with older tool output cleared, `summary` opens a fresh session with a summary. Leave it out for the one a person picked on the held turn, else the sandbox's setting (`limitHandoff`). Only a spent allowance's held turn reads it.",
+    ),
 });
 export type ResumeRouting = z.infer<typeof ResumeRoutingSchema>;
 // Returns an ordinary `StartedTurn`; the caller attaches to it like any turn someone else started. A resume note on the
@@ -469,6 +487,9 @@ export const SwitchAccountSchema = z.object({
         .describe(
             "Keep the provider session across the move (the model keeps everything, and re-reads all of it once on the other account) rather than opening a fresh one seeded from the record.",
         ),
+    handoff: HandoffModeSchema.optional().describe(
+        "How the held turn continues the conversation on the new account: `carry`, `trim` or `summary` (see `limitHandoff`). Wins over `carry`. Leave it out for the held turn's own pick, else the sandbox's setting.",
+    ),
     run: z
         .boolean()
         .optional()

package/src/schemas/providers/usage.ts

@@ -23,10 +23,14 @@ export const UsageTurnSchema = z.object({
         .optional()
         .describe("The model that was asked for, when one was named. Differs from `model` when something resolved it."),
     harness: z.string().describe("Which agentic loop it ran on."),
-    // cancelled: the user pressed Stop, not a failure.
+    // cancelled: stopped before it finished, not a failure: the user pressed Stop, or a daemon restart cut it (then
+    // `errorCode` is `interrupted` and `errorMessage` says what became of it).
     // error: the provider or request killed the turn.
     // Absent means the row predates recording, not that the turn succeeded.
-    outcome: z.enum(["ok", "error", "cancelled"]).optional().describe("How it ended: finished, failed, or was stopped by the user."),
+    outcome: z
+        .enum(["ok", "error", "cancelled"])
+        .optional()
+        .describe("How it ended: finished, failed, or stopped before it finished (by the user, or by a restart, whose errorCode is `interrupted`)."),
     // The failing frame's code (e.g. rate_limit, provider-outage); absent even on error means unclassified.
     errorCode: z.string().optional().describe("The failure's code, when it had one."),
     // The failing frame's own sentence, capped at ERROR_MESSAGE_CHARS.
@@ -38,6 +42,11 @@ export const UsageTurnSchema = z.object({
         .describe(
             "Which conversation it belonged to, so spending can be traced to a card. Absent only for an internal one-off with no conversation at all.",
         ),
+    // The ids a turn is followed by elsewhere: its turn id (activity log, failure lines), the run its transcript rows are
+    // stamped with, and the provider session it ran in. Absent on rows written before they were recorded.
+    turnId: z.string().optional().describe("The turn's id in the activity log and the daemon's log lines."),
+    run: z.string().optional().describe("The run whose id the turn's transcript rows carry."),
+    sessionId: z.string().optional().describe("The provider session the turn ran in."),
     // The provider's own count for the request, since one exchange can be several; 1 when unreported.
     turns: z
         .number()
@@ -71,8 +80,8 @@ export const UsageTurnSchema = z.object({
     // Arm of the project-map experiment, stable per conversation; mapChars is the note's length when sent.
     mapArm: z.boolean().optional(),
     mapChars: z.number().optional(),
-    // Which comparison `mapArm` belongs to: absent on the map-or-none rows, "compact-vs-full" since 2026-10-06, when
-    // the arm became the compact map and the holdout the full one.
+    // Which comparison `mapArm` belongs to: absent on the first map-or-none rows; "compact-vs-full" from 2026-10-06 to
+    // 10-12, when the arm was the compact map and the holdout the full one; "map-vs-none" since, the map against none.
     mapCohort: z.string().optional(),
     // Arm of the field-notes experiment, stable per conversation; notesChars is what the budget let through.
     notesArm: z.boolean().optional(),
@@ -80,9 +89,6 @@ export const UsageTurnSchema = z.object({
     // Hash of the brief that was sent, recorded on control turns too. Load-bearing rather than decorative: the file is
     // rewritten monthly, so a 30-day window holds two different treatments and pooling them would measure neither.
     notesCohort: z.string().optional(),
-    // Arm of the tool-result clearing experiment, stable per conversation; true is a conversation whose old tool results
-    // the gateway drops. Native Claude turns only: no other runtime's requests pass a gateway that clears.
-    clearingArm: z.boolean().optional(),
     // What became of pre-turn retrieval on this turn, and how long it took. Assignment and DELIVERY are different
     // facts: the first version of this mechanism was assigned to every eligible turn and reached four in five of them,
     // which is the difference between a null result and a mechanism that never ran. Absent means the flag was off, so

package/src/schemas/run-targets.ts

@@ -1,3 +1,4 @@
+import { STATE_DIR } from "@intentic/constants";
 import { z } from "zod";
 import { ArtifactNameSchema } from "./device-artifacts.js";
 
@@ -21,14 +22,16 @@ import { ArtifactNameSchema } from "./device-artifacts.js";
 //     }]
 //   }
 
-export const RUN_TARGETS_FILE = ".intentic/run.json";
+export const RUN_TARGETS_FILE = `${STATE_DIR}/run.json`;
 
 const RepoPathSchema = z
     .string()
     .min(1)
     .max(500)
     .refine((path) => !path.startsWith("/") && !path.split(/[\\/]/).includes(".."), "a path inside the repository, relative to its root");
-const BundleNameSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9 ._()+-]{0,199}(\/[A-Za-z0-9][A-Za-z0-9 ._()+-]{0,199})*$/, "a relative name, folders by /");
+const BundleNameSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9][A-Za-z0-9 ._()+-]{0,199}(\/[A-Za-z0-9][A-Za-z0-9 ._()+-]{0,199})*$/, "a relative name, folders by /");
 
 export const RunTargetSchema = z
     .object({

package/src/schemas/settings-history.ts

@@ -1,5 +1,8 @@
 import { z } from "zod";
-import { at, drop, dropAll, fold, isJsonObject, mapValue, retype } from "../documents/conversions.js";
+import { at, drop, dropAll, fold, isJsonObject, type JsonObject, mapValue, retype, transform } from "../documents/conversions.js";
+import { type ModelRole, ModelRoleSchema } from "../models/model-roles.js";
+import { setupsFromRoleLists } from "../models/model-setups.js";
+import { ModelPinSchema, type ModelPin } from "./agent.js";
 import type { KeepWarmSettings, RuleSchema } from "./settings.js";
 
 // The conversions the settings shape has had, oldest first: what brings any earlier release's settings to
@@ -63,6 +66,41 @@ const keepWarmObject = fold("folds keepWarm, keepWarmHours, keepWarmMinTokens an
     },
 });
 
+// The Refactors job (2026-10-09): a refactor started from a repository's Health tab used to name no job and opened on
+// whatever model the composer last held. A file from before it inherits the Maintenance chores list, the job nearest in
+// kind, so the owner's choice for work they start carries over instead of the new job opening empty. Only while the key
+// is absent: an owner who later empties it stores [], which this leaves alone.
+type RolesWithChores = JsonObject & { readonly "maintenance-chore": readonly unknown[] };
+const holdsChoresWithoutRefactors = (roles: JsonObject): roles is RolesWithChores =>
+    !Object.hasOwn(roles, "refactor-run") && Array.isArray(roles["maintenance-chore"]) && roles["maintenance-chore"].length > 0;
+const refactorsFromChores = transform(
+    "gives the new Refactors job the Maintenance chores list",
+    holdsChoresWithoutRefactors,
+    (roles): JsonObject => ({ ...roles, "refactor-run": roles["maintenance-chore"] }),
+);
+
+// Setups (2026-10-12): a job no longer holds a model list of its own (`modelRoles`) beside one default list
+// (`modelDefault`); it runs on a named setup it shares with other jobs. Jobs that held the same list share one setup, a
+// list most of whose jobs are suggested a preset becomes that preset, and a job that held none, or an empty one, is on
+// none, which runs it exactly as before: not at all. A list that does not read (a role this version does not know, a malformed pin) is left out rather than refusing
+// the whole file, the same reading the schema gave it.
+const PinList = z.array(ModelPinSchema);
+const holdsRoleLists = (settings: JsonObject): settings is JsonObject => Object.hasOwn(settings, "modelRoles") || Object.hasOwn(settings, "modelDefault");
+const roleListsIntoSetups = transform("folds modelRoles and modelDefault into setups (modelSetups, roleSetups)", holdsRoleLists, (settings): JsonObject => {
+    const { modelRoles, modelDefault, ...rest } = settings;
+    const fallback = PinList.safeParse(modelDefault);
+    const lists: Partial<Record<ModelRole, ModelPin[]>> = {};
+    for (const role of ModelRoleSchema.options) {
+        const own = isJsonObject(modelRoles) ? PinList.safeParse(modelRoles[role]) : undefined;
+        const list = own?.success === true ? own.data : fallback.success && fallback.data.length > 0 ? fallback.data : undefined;
+        if (list !== undefined) {
+            lists[role] = list;
+        }
+    }
+    const { modelSetups, roleSetups } = setupsFromRoleLists(lists);
+    return { ...rest, modelSetups, roleSetups };
+});
+
 export const SETTINGS_HISTORY = [
     // Every setting a release since 2026-08-10 had and this one does not (read off the contract lock's history):
     // retired, so passthrough stops carrying them, a definition naming one still applies, and no later setting may
@@ -112,4 +150,8 @@ export const SETTINGS_HISTORY = [
     at("modelRoles", drop("pre-push-fix")),
     // The short guidance form (2026-10-06): it lost its A/B to the full one, which every turn now gets.
     ...dropAll(["leanGuidance", "leanGuidanceHoldout"]),
+    // Tool-result clearing (2026-10-12): it lost its A/B, rewriting more of the cache than it saved and failing more calls.
+    ...dropAll(["toolResultClearing", "toolResultClearingHoldout"]),
+    at("modelRoles", refactorsFromChores),
+    roleListsIntoSetups,
 ] as const;

package/src/schemas/settings.test.ts

@@ -1,4 +1,6 @@
 import { convertDocument } from "../documents/conversions.js";
+import type { ModelRole } from "../models/model-roles.js";
+import { rolePins } from "../models/model-setups.js";
 import { SETTINGS_HISTORY } from "./settings-history.js";
 import { RepoChecksFileSchema, RuleSchema, SandboxSettingsSchema, SandboxSettingsWriteSchema } from "./settings.js";
 
@@ -112,6 +114,20 @@ describe(`the folded keep-warm settings`, () => {
     });
 });
 
+// Tool-result clearing lost its A/B and was removed (2026-10-12); a file that still switches it on reads, without it.
+test(`a stored tool-result clearing switch is dropped, and the rest of the file kept`, () => {
+    const converted = convertDocument(SETTINGS_HISTORY, `object`, { iqSearch: true, toolResultClearing: true, toolResultClearingHoldout: 0.5 }, true);
+    expect(converted.value).toEqual({ iqSearch: true });
+    expect(SandboxSettingsSchema.parse(converted.value).iqSearch).toBe(true);
+});
+
+// What a job runs on, read the way every reader reads it, over a sandbox with nothing connected: the setups a stored
+// file converts into are judged by what they make each job run on, not by their shape.
+const runsOn = (stored: unknown, role: ModelRole): readonly unknown[] => {
+    const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
+    return rolePins(SandboxSettingsSchema.parse(converted.value), role, []);
+};
+
 // The pre-push fix's model list went with the fix a refused push used to offer (2026-09-28). A settings file that still
 // names it must read, since an unknown role refuses the whole file, and every other job's list stays as its owner set it.
 describe(`the retired pre-push fix role`, () => {
@@ -119,13 +135,75 @@ describe(`the retired pre-push fix role`, () => {
 
     test(`is dropped from a stored file, leaving every other job's list, and the file reads`, () => {
         const stored = { modelRoles: { "pipeline-fix": [pin], "pre-push-fix": [pin] } };
-        expect(SandboxSettingsSchema.safeParse(stored).success).toBe(false);
-        const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
-        expect(converted.value).toEqual({ modelRoles: { "pipeline-fix": [pin] } });
-        expect(SandboxSettingsSchema.parse(converted.value).modelRoles).toEqual({ "pipeline-fix": [pin] });
+        expect(SandboxSettingsSchema.safeParse({ roleSetups: { "pre-push-fix": `high` } }).success).toBe(false);
+        expect(runsOn(stored, `pipeline-fix`)).toEqual([pin]);
+    });
+});
+
+// The Refactors job arrived on 2026-10-09; a file from before it carries the owner's Maintenance chores list over, so a
+// refactor started from Health opens on a model they chose rather than on an empty job.
+describe(`the new Refactors job`, () => {
+    const opus = { provider: `claude`, model: `claude-opus-5-5` };
+    const sol = { provider: `codex`, model: `gpt-sol-6.1` };
+
+    test(`takes the Maintenance chores list in a file from before it, and every other list stays`, () => {
+        const stored = { modelRoles: { "maintenance-chore": [opus, sol], "pipeline-fix": [sol] } };
+        expect(runsOn(stored, `refactor-run`)).toEqual([opus, sol]);
+        expect(runsOn(stored, `pipeline-fix`)).toEqual([sol]);
+    });
+
+    test(`leaves a list the owner set, even an emptied one`, () => {
+        expect(runsOn({ modelRoles: { "maintenance-chore": [opus], "refactor-run": [sol] } }, `refactor-run`)).toEqual([sol]);
+        expect(runsOn({ modelRoles: { "maintenance-chore": [opus], "refactor-run": [] } }, `refactor-run`)).toEqual([]);
+    });
+});
+
+// Setups (2026-10-12): per-job lists and the default list become named setups that jobs share.
+describe(`per-job model lists`, () => {
+    const opus = { provider: `claude`, model: `claude-opus-5-5`, effort: `high` };
+    const haiku = { provider: `claude`, model: `claude-haiku-4-5` };
+    const sol = { provider: `codex`, model: `gpt-sol-6.1` };
+
+    test(`become setups that every job runs exactly as before on`, () => {
+        const cases = [
+            [`commit-message`, [haiku]],
+            [`session-title`, [haiku]],
+            [`pipeline-fix`, [opus, sol]],
+            [`refactor-run`, [opus, sol]],
+            [`handoff-summary`, [sol, haiku]],
+            [`safety-judge`, []],
+        ] as const satisfies readonly (readonly [ModelRole, readonly unknown[]])[];
+        for (const [role, pins] of cases) {
+            expect(runsOn({ modelRoles: Object.fromEntries(cases) }, role)).toEqual(pins);
+        }
+    });
+
+    test(`share a setup where they held one list, which becomes the preset most of them suit`, () => {
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: { "commit-message": [haiku], "session-title": [haiku], "pipeline-fix": [opus], "handoff-summary": [sol] } }, true);
+        expect(converted.value).toEqual({
+            modelSetups: [
+                { id: `low`, pins: [haiku] },
+                { id: `setup-1`, name: `Setup 1`, pins: [sol] },
+                { id: `high`, pins: [opus] },
+            ],
+            roleSetups: { "commit-message": `low`, "session-title": `low`, "handoff-summary": `setup-1`, "pipeline-fix": `high` },
+        });
+    });
+
+    test(`carry the default list to every job that had none of its own`, () => {
+        const stored = { modelDefault: [sol], modelRoles: { "pipeline-fix": [opus] } };
+        expect(runsOn(stored, `commit-message`)).toEqual([sol]);
+        expect(runsOn(stored, `loop-iteration`)).toEqual([sol]);
+        expect(runsOn(stored, `pipeline-fix`)).toEqual([opus]);
+    });
+
+    test(`leave a job that never had a list on none, running exactly as before`, () => {
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: {} }, true);
+        expect(converted.value).toEqual({ modelSetups: [], roleSetups: {} });
+        expect(runsOn({ modelRoles: {} }, `safety-judge`)).toEqual([]);
     });
 
-    test(`leaves a file without it alone`, () => {
-        expect(convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: { "pipeline-fix": [pin] } }, true).changes).toEqual([]);
+    test(`read once, and a file already in setups is left alone`, () => {
+        expect(convertDocument(SETTINGS_HISTORY, `object`, { modelSetups: [{ id: `low`, pins: [haiku] }], roleSetups: {} }, true).changes).toEqual([]);
     });
 });