@intentic/sandbox-contract 1.331.0 → 1.332.0

package/src/schemas/offload.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { RunnerCommandFrameSchema, RunnerCommandSchema } from "../protocol/doors/runner-protocol.js";
+import { AgentHarnessSchema, AgentProviderSchema } from "./agent.js";
 
 // OFFLOADED WORK, as the in-sandbox `offload-run` command and the editor see it (settings `offload`): a heavy line this
 // sandbox hands a runner on one of the owner's machines instead of running it itself.
@@ -42,3 +43,78 @@ export type OffloadRecord = z.infer<typeof OffloadRecordSchema>;
 // `offload.commands` keys it) and the pattern that sorts a line into it.
 export const OffloadKindSchema = z.object({ id: z.string().min(1), pattern: z.string() });
 export type OffloadKind = z.infer<typeof OffloadKindSchema>;
+
+// NEW SESSIONS ACROSS THE OWNER'S MACHINES (settings `offload.sessions`, GET /offload/placement). One measure for every
+// machine, this sandbox and each runner alike, and one judgement over it (runners/fleet-advice.ts), so the composer's
+// suggestion, the placement menu and an automatic placement can never disagree about which machine has room.
+
+// What happens to a new session while this machine is busy and another has room: `suggest` says so above the
+// composer, `auto` starts it there unless the person keeps it here, `off` says nothing.
+export const SessionsPlacementSchema = z.enum(["suggest", "auto", "off"]);
+export type SessionsPlacement = z.infer<typeof SessionsPlacementSchema>;
+
+// `calm` takes another agent without anyone noticing; `busy` takes one at a cost to the agents already running; `full`
+// would hold or warn a person's next turn (the turn door's own figure).
+export const MachineStandingSchema = z.enum(["calm", "busy", "full"]);
+export type MachineStanding = z.infer<typeof MachineStandingSchema>;
+
+// What made a machine busy or full: memory short of what an agent needs, memory stalling, CPUs saturated, or as many
+// agents running as it has slots for.
+export const MachineStrainSchema = z.enum(["memory", "memory-stall", "cpu", "agents"]);
+export type MachineStrain = z.infer<typeof MachineStrainSchema>;
+
+export const MachineLoadSchema = z.object({
+    standing: MachineStandingSchema,
+    // Why it is not calm, strongest first; empty when it is.
+    strain: z.array(MachineStrainSchema),
+    cpus: z.number().int().positive(),
+    // The one-minute load average over the cores: 1 is every core busy.
+    load: z.number().nonnegative(),
+    // What its resource budget has free, and the limit that is measured against; absent where nothing measures it.
+    memoryFreeMb: z.number().int().nonnegative().optional(),
+    memoryLimitMb: z.number().int().positive().optional(),
+    // Conversations running a turn there now, and how many it holds at once (the fan-out scheduler's own slots).
+    agents: z.number().int().nonnegative(),
+    slots: z.number().int().positive(),
+    // The share of the machine still free by its tightest measure (slots, memory, CPU), so two machines of different
+    // sizes compare: 0 is none, 1 is idle.
+    headroom: z.number().min(0).max(1),
+});
+export type MachineLoad = z.infer<typeof MachineLoadSchema>;
+
+// Why a new session could not start on a runner right now: the machine is asleep, it has never said how big it is, the
+// draft's model signs in with a credential that does not travel, the privacy shield keeps it here, or the person is
+// limited to areas a runner cannot fence.
+export const FleetUnfitSchema = z.enum(["offline", "unmeasured", "credentials", "privacy", "areas"]);
+export type FleetUnfit = z.infer<typeof FleetUnfitSchema>;
+
+export const FleetMachineSchema = z.object({
+    runner: z.string().min(1),
+    // The machine the runner sits on, the word the owner knows it by.
+    name: z.string().min(1),
+    online: z.boolean(),
+    // Absent while it is offline or has never been measured.
+    load: MachineLoadSchema.optional(),
+    // Absent when a new session could start there now.
+    unfit: FleetUnfitSchema.optional(),
+});
+export type FleetMachine = z.infer<typeof FleetMachineSchema>;
+
+export const FleetAdviceInputSchema = z.object({
+    // The draft's provider and harness, which decide whether its credential can reach a runner; absent reads as the
+    // sandbox's defaults.
+    agent: AgentProviderSchema.optional(),
+    harness: AgentHarnessSchema.optional(),
+    // The draft's conversation, which the privacy shield may trust on its own.
+    conversationId: z.string().min(1).optional(),
+});
+export type FleetAdviceInput = z.infer<typeof FleetAdviceInputSchema>;
+
+export const FleetAdviceSchema = z.object({
+    mode: SessionsPlacementSchema,
+    here: MachineLoadSchema,
+    machines: z.array(FleetMachineSchema),
+    // Where a new session should start instead of here: absent while here is calm, or when no machine is better off.
+    suggestion: z.object({ runner: z.string().min(1), name: z.string().min(1) }).optional(),
+});
+export type FleetAdvice = z.infer<typeof FleetAdviceSchema>;

package/src/schemas/privacy.ts

@@ -87,7 +87,8 @@ export const trustedInConversation = (
     policy: Pick<PrivacyShieldPolicy, "conversations">,
     provider: string,
     conversationId: string | undefined,
-): boolean => conversationId !== undefined && policy.conversations.some((entry) => entry.conversationId === conversationId && entry.provider === provider);
+): boolean =>
+    conversationId !== undefined && policy.conversations.some((entry) => entry.conversationId === conversationId && entry.provider === provider);
 
 // The policy with that grant made or taken back. A full list drops its oldest grant to make room, since the newest is
 // the one somebody is waiting on.
@@ -104,7 +105,11 @@ export const DEFAULT_PRIVACY_SHIELD: PrivacyShieldPolicy = PrivacyShieldPolicySc
 export const PrivacyProviderSchema = z.object({
     id: z.string().describe("Provider id, as the trusted list names it."),
     label: z.string(),
-    shieldable: z.boolean().describe("The shield can read what its runtime sends by content (through the gateway or the runtime's hooks); one it cannot is refused while the shield is on, unless trusted."),
+    shieldable: z
+        .boolean()
+        .describe(
+            "The shield can read what its runtime sends by content (through the gateway or the runtime's hooks); one it cannot is refused while the shield is on, unless trusted.",
+        ),
     local: z.boolean().describe("It runs on this machine, so it is trusted whatever the list says."),
 });
 export type PrivacyProvider = z.infer<typeof PrivacyProviderSchema>;
@@ -140,6 +145,10 @@ export const PrivacyReplacementSchema = z.object({
         .string()
         .describe("The masked text around the token as it left this machine (watching: as it would have). Tokens only, never a value."),
     image: z.boolean().optional().describe("Found in an image's text, so the token was painted over the picture rather than written."),
+    imageId: z
+        .string()
+        .optional()
+        .describe("The image it was painted over, as privacy.image reads it back: the picture before and after masking, while it is still kept."),
 });
 export type PrivacyReplacement = z.infer<typeof PrivacyReplacementSchema>;
 
@@ -162,6 +171,17 @@ export const PrivacyLedgerEntrySchema = z.object({
 });
 export type PrivacyLedgerEntry = z.infer<typeof PrivacyLedgerEntrySchema>;
 
+// One image the shield painted over, as it was and as it left: the owner peeking at what the provider saw. The picture
+// before holds the personal data, so it is kept beside the vault, off the workspace, and only the owner may read it.
+export const PRIVACY_IMAGE_ID = /^[A-Za-z0-9_-]{16,64}$/u;
+export const PrivacyImageSchema = z.object({ mediaType: z.string(), data: z.string().describe("Base64.") });
+export const PrivacyImagePairSchema = z.object({
+    at: z.string().describe("When it was first painted, as an ISO timestamp."),
+    before: PrivacyImageSchema,
+    after: PrivacyImageSchema,
+});
+export type PrivacyImagePair = z.infer<typeof PrivacyImagePairSchema>;
+
 // Tokens read back to their values, for the owner checking what the shield masked; a token this vault never gave out is
 // left out of the answer.
 export const PRIVACY_REVEAL_MAX = 100;
@@ -205,7 +225,11 @@ export const PrivacyNameWordSchema = z.object({
     firstName: z.boolean().describe("A listed first name, in this form or as an inflection of one."),
     surname: z.boolean().describe("A listed surname, in this form or as an inflection of one."),
     surnameForm: z.boolean().describe("Shaped like a Polish surname (-ski, -cki, -wicz…), listed or not."),
-    ambiguous: z.boolean().describe("Also an ordinary word in some language, so found only beside other evidence (a title, a name field) and no surname to pair a first name with."),
+    ambiguous: z
+        .boolean()
+        .describe(
+            "Also an ordinary word in some language, so found only beside other evidence (a title, a name field) and no surname to pair a first name with.",
+        ),
     never: z.boolean().describe("Never taken as part of a name (a title, an institution, a function word)."),
 });
 export type PrivacyNameWord = z.infer<typeof PrivacyNameWordSchema>;

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

@@ -0,0 +1,15 @@
+import { type ProjectAnswer, ProjectAnswerSchema } from "./project-bring-back.js";
+
+test("reads the agent's change listing as the desktop app relays it", () => {
+    const detail: ProjectAnswer = {
+        kind: "changes",
+        result: { ok: true, pairing: "p1", direction: "to-sandbox", changes: [{ path: "a.ts", kind: "modified", size: 3, conflict: true }], truncated: true },
+    };
+    expect(ProjectAnswerSchema.parse(detail)).toEqual(detail);
+});
+
+test("a restore's skipped entries are held to their shape, and a failure carries the agent's sentence", () => {
+    expect(ProjectAnswerSchema.parse({ kind: "restored", result: { ok: true, restored: 2, skipped: [{ path: "x", reason: "changed" }] } })).toMatchObject({ result: { restored: 2 } });
+    expect(ProjectAnswerSchema.parse({ kind: "brought-back", result: { ok: false, error: "conflict" } })).toEqual({ kind: "brought-back", result: { ok: false, error: "conflict" } });
+    expect(ProjectAnswerSchema.safeParse({ kind: "changes", result: { note: "x" } }).success).toBe(false);
+});

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.
@@ -29,6 +30,12 @@ export const UsageWindowSchema = z.object({
         .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
@@ -399,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
@@ -477,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, 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
@@ -76,6 +79,28 @@ const refactorsFromChores = transform(
     (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
@@ -125,5 +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;