@intentic/sandbox-contract 1.310.0 → 1.312.0

package/src/schemas/agents.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema } from "./agent.js";
 import { LoopStateSchema } from "./loops.js";
 import { LimitPolicySchema, RetryPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
+import { KeepWarmSchema } from "./keep-warm.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
@@ -82,10 +83,30 @@ export const UnfinishedWorkSchema = z.object({
         })
         .optional()
         .describe("The agent's own checklist where that turn left it. Absent for a conversation that kept no list."),
-    // Name of the `turn.ending` check still red when the turn ended, after its two repair rounds ran out.
-    check: z.string().optional().describe("The end-of-turn check that was still failing when the turn ended, by name."),
+    // Name of the `turn.ending` check still red when the turn ended. Retired with that check: nothing writes it now, and
+    // it stays so entries written before still read.
+    check: z
+        .string()
+        .optional()
+        .describe("The end-of-turn check that was still failing when the turn ended, by name. No longer written: checks run after work lands."),
 });
 export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
+// What the last turn showed of its own work, read off its tool calls and never asked of the model: the record a card
+// badges instead of sending the turn back to prove anything. Checks run after the work lands (mainline.ts).
+export const TurnProofSchema = z.object({
+    at: z.number().describe("When the turn that left this ended, in milliseconds."),
+    verification: z
+        .enum(["verified", "unproven", "failing", "no-code"])
+        .describe(
+            "Verified: a check it ran passed after its last edit to code. Failing: the last one it ran failed. Unproven: it changed code and ran nothing that checked it. No-code: it changed nothing a check could speak to.",
+        ),
+    check: z.string().optional().describe("The command that spoke, when one did, so a targeted test is never read as the whole suite."),
+    unviewed: z
+        .number()
+        .optional()
+        .describe("How many rendered files it changed (pages, components, styles) without looking at the result afterwards. Absent when none."),
+});
+export type TurnProof = z.infer<typeof TurnProofSchema>;
 // A landing's commit message: subject plus the two trailer sentences a changelog repo gets. One schema, not three
 // duplicated fields, since both the live roster and the review carrier must read the same shape and can't disagree.
 export const LandedMessageSchema = z.object({
@@ -329,11 +350,24 @@ export const AgentSummarySchema = z.object({
         .object({
             at: z.number().describe("When its last request touched the provider's prompt cache, in milliseconds."),
             ttlMs: z.number().describe("How long that entry lives from `at`, in milliseconds."),
+            rollsAt: z
+                .number()
+                .optional()
+                .describe(
+                    "When the date written into the agent's prompt next changes, in milliseconds (midnight where the agent runs). Past it the next turn sends a different prompt, so nothing kept before it is read again.",
+                ),
+            keepable: z
+                .boolean()
+                .optional()
+                .describe("Whether this sandbox can keep this cache warm: it holds the last turn's exact request to replay, on a Claude subscription account."),
         })
         .optional()
         .describe(
             "When this conversation's prompt cache was last kept alive and how long it lasts, which together say when picking the conversation up stops being cheap. Absent when the provider publishes nothing to ground it on.",
         ),
+    keepWarm: KeepWarmSchema.optional().describe(
+        "Whether the sandbox is keeping this conversation's prompt cache warm while it sits idle, how that is going, or why it stopped. Absent when nobody asked for it.",
+    ),
     activity: AgentActivitySchema.optional().describe("What it is doing at this moment."),
     // Beside `activity` because both answer "where is it", one in a sentence and one as a fraction. Live while a turn
     // runs, and left standing after it, so a settled card still says how far the work got.
@@ -382,7 +416,11 @@ export const AgentSummarySchema = z.object({
     // Beside `attention` since a reader asks both at a glance, but opposite in shape: a turn gone, not one still parked
     // and waiting.
     unfinished: UnfinishedWorkSchema.optional().describe(
-        "What its last turn left open: steps it never completed, a check still failing. Absent for a turn that finished what it started.",
+        "What its last turn left open: steps it never completed. Absent for a turn that finished what it started.",
+    ),
+    // Written by the turn's own settle from its tool calls; nothing is asked of the model to earn or clear it.
+    proof: TurnProofSchema.optional().describe(
+        "What its last turn showed of its work: whether a check it ran passed after its last edit, and whether it looked at interface files it changed. Absent until a turn that edited or checked anything has ended.",
     ),
     // Completed turns and lifetime tool calls, the card's msgs/tools counters.
     turns: z.number().optional().describe("Turns it has finished."),
@@ -470,6 +508,27 @@ export const AgentSummarySchema = z.object({
                 startedAt: z.number().describe("When it started, in milliseconds."),
                 endedAt: z.number().optional().describe("When the command exited, in milliseconds. Absent while it runs."),
                 exitCode: z.number().int().optional().describe("The code it exited with. Absent while it runs, or when its exit left none."),
+                // What the turn that left it running decided about it (agent/tools/job-fates.ts): one of these, or none
+                // while its turn is still going.
+                watch: z
+                    .string()
+                    .optional()
+                    .describe(
+                        "The watch its exit wakes this conversation through. Present once the turn that left it running has ended and the conversation is waiting on it.",
+                    ),
+                handed: z
+                    .boolean()
+                    .optional()
+                    .describe(
+                        "Left running for the person: the turn's reply gave its address, so it outlives the turn, wakes nothing and is theirs to stop.",
+                    ),
+                ports: z.array(z.number().int()).optional().describe("The ports it was listening on when its turn ended."),
+                stoppedBy: z
+                    .enum(["turn", "person", "agent"])
+                    .optional()
+                    .describe(
+                        "Who stopped it: the sandbox, when the turn that used it ended without handing it over; a person; or the agent itself. Present from the moment the stop is asked. Absent for a job that exited by itself.",
+                    ),
             }),
         )
         .optional()
@@ -500,6 +559,10 @@ export const AgentStopWatchingSchema = AgentIdSchema.extend({
     watchId: z.string().optional().describe("Which watch to disarm. Absent disarms every watch this conversation is parked on."),
 });
 
+export const AgentStopJobSchema = AgentIdSchema.extend({
+    jobId: z.string().min(1).describe("Which of its background jobs, by the id its card and transcript row carry."),
+});
+
 // Pages a transcript: a read returns its most recent turns and where they start (`from`); handing that back as `before`
 // asks for the page above. A stale cursor (a rewind, a fork) is clamped, never refused.
 export const AgentTranscriptQuerySchema = AgentIdSchema.extend({
@@ -517,13 +580,6 @@ export const AgentToolChildrenQuerySchema = AgentIdSchema.extend({
     toolId: z.string().min(1).describe("Which tool call, by the id its card carries."),
 });
 // Absent `ids` archives every archivable finished agent (the lane's "Clear"); unarchive always names its own ids.
-export const AgentArchiveSchema = z.object({
-    ids: z
-        .array(z.string().min(1))
-        .max(500)
-        .optional()
-        .describe("Which conversations to put away. Leave it out for every finished one that can be archived right now."),
-});
 export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).max(500).describe("Which conversations.") });
 // What actually moved, not the roster afterward: two archives finishing at once would otherwise let a slower snapshot
 // resurrect what a faster one just filed away. Whole summaries, since the receiving surfaces (archive list, detail

package/src/schemas/capabilities.ts

@@ -354,6 +354,12 @@ export const CapabilityStatusSchema = z.object({
     state: CapabilityStateSchema.describe("Whether it is live, still coming up, broken, or switched off."),
     detail: z.string().optional().describe("What is wrong, in words a person can act on."),
     code: z.string().optional().describe("A short marker for that reason, for anything deciding what to do about it."),
+    settling: z
+        .boolean()
+        .optional()
+        .describe(
+            "True while something under way will move this on its own: a start, a download, a pairing code waiting to be typed. Absent when only a person can move it, or a pushed change will say when it moved.",
+        ),
 });
 export type CapabilityStatus = z.infer<typeof CapabilityStatusSchema>;
 // The list row: manifest entry plus live status, secrets never returned. `secrets` names which config keys hold a

package/src/schemas/devices.ts

@@ -9,6 +9,14 @@ import { DEV_VERSION } from "../state/versions.js";
 // One sandbox's resource share as docker currently enforces it, read off the container by the machine agent.
 // `overlayRuntime` is the environment's locked demand; `hostRuntime` is the owner's addition; `privileged`/`gpu` are
 // docker's enforced truth.
+// Reshape request, turned into `ic sandbox reshape` flags: absent means leave it, `null` on the two caps means back to
+// the default; at least one key must be set.
+export const SandboxResourcesAskFieldsSchema = z.object({
+    memoryGib: z.int().positive().nullable().optional(),
+    cpus: z.int().positive().nullable().optional(),
+    privileged: z.boolean().optional(),
+    gpu: z.boolean().optional(),
+});
 export const SandboxResourcesSchema = z.object({
     // The cgroup memory ceiling in bytes; absent when docker imposes none (the hosted shape).
     memoryBytes: z.number().optional(),
@@ -18,17 +26,12 @@ export const SandboxResourcesSchema = z.object({
     gpu: z.boolean(),
     hostRuntime: z.array(z.string()),
     overlayRuntime: z.array(z.string()),
+    // A reshape saved for the sandbox's next restart (`ic sandbox reshape --later`) and not yet in force: the next
+    // update, rollback, rebuild, reshape or Restart applies it. Absent when nothing is saved.
+    saved: SandboxResourcesAskFieldsSchema.optional(),
 });
 export type SandboxResources = z.infer<typeof SandboxResourcesSchema>;
 
-// Reshape request, turned into `ic sandbox reshape` flags: absent means leave it, `null` on the two caps means back to
-// the default; at least one key must be set.
-export const SandboxResourcesAskFieldsSchema = z.object({
-    memoryGib: z.int().positive().nullable().optional(),
-    cpus: z.int().positive().nullable().optional(),
-    privileged: z.boolean().optional(),
-    gpu: z.boolean().optional(),
-});
 // Fields also exported separately for callers that compose them and enforce the at-least-one rule themselves.
 export const SandboxResourcesAskSchema = SandboxResourcesAskFieldsSchema.refine((ask) => Object.values(ask).some((value) => value !== undefined), {
     message: "a reshape must change at least one thing",
@@ -81,8 +84,12 @@ export const DeviceSandboxFlowSchema = z.object({
     slug: z.string().min(1),
     // Approved overlay's sha256, required only by `rebuild`; only content matching it is ever built.
     hash: z.string().optional(),
-    // What `reshape` should change, required by it and meaningless to the rest.
+    // What `reshape` should change, meaningless to the rest. Absent on a reshape applies what is saved for the next
+    // restart now; absent with `later` forgets what is saved.
     resources: SandboxResourcesAskSchema.optional(),
+    // `reshape` only: save `resources` for the sandbox's next restart instead of restarting it now, replacing
+    // whatever was saved before (`ic sandbox reshape --later`).
+    later: z.boolean().optional(),
     // `runner-up` only, daemon-filled, never by the caller: the browser never holds the pairing credential.
     parentUrl: z.string().optional(),
     pair: z.string().optional().meta({ secret: true }),

package/src/schemas/git/git.ts

@@ -450,6 +450,11 @@ export const AgentChangesSchema = z.object({
 });
 export type AgentChanges = z.infer<typeof AgentChangesSchema>;
 
+// The review's `conflicts` alone, re-derived the same way. The whole review also takes a code-only line count per
+// file, and on a branch of hundreds of files that count, not the conflict check, is what takes seconds.
+export const AgentConflictsSchema = AgentChangesSchema.pick({ conflicts: true });
+export type AgentConflicts = z.infer<typeof AgentConflictsSchema>;
+
 // Names scratch exactly as `AgentChanges.scratch` lists it; anything else is refused, so a stale list cannot reach a
 // file that was never scratch.
 export const AgentScratchSchema = z.object({

package/src/schemas/hosts.ts

@@ -35,9 +35,17 @@ export const DeviceFactsSchema = z.object({
     // the rest are other sandboxes' addresses, and a sandbox has no business learning its siblings'. Absent from an
     // agent older than this field, which is why "none unreachable" is not the same value as "did not say".
     links: z.object({ total: z.number(), unreachable: z.number(), unreachableSince: z.number().optional() }).optional(),
+    // What this agent understands beyond the ops every agent has, so a caller can refuse up front rather than send a
+    // field an older agent drops without a word. Absent from an agent older than this field: it supports none of them.
+    features: z.array(z.string()).optional(),
 });
 export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 
+// `reshape` with `later`: save the change for the next restart. An agent without it strips `later` from the request and
+// reshapes NOW, restarting the sandbox and interrupting everyone in it, which is why a later-reshape is never sent to one.
+export const DEVICE_FEATURE_RESHAPE_LATER = "reshape-later";
+export const deviceSupports = (facts: Pick<DeviceFacts, "features"> | undefined, feature: string): boolean => facts?.features?.includes(feature) === true;
+
 // Docker Desktop's own distros: `wsl -l -q` lists them like any other, and none ever runs an agent or holds a checkout.
 export const WSL_SYSTEM_DISTROS: ReadonlySet<string> = new Set(["docker-desktop", "docker-desktop-data"]);
 

package/src/schemas/keep-warm.test.ts

@@ -0,0 +1,68 @@
+import { TranscriptFold } from "../text/transcript-fold.js";
+import {
+    changedParts,
+    keepWarmCap,
+    keepWarmDueAt,
+    keepWarmHorizon,
+    keepWarmLeadMs,
+    keepWarmMaxRefreshes,
+    keepWarmRefreshes,
+    keptWarmLine,
+} from "./keep-warm.js";
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+
+// The arithmetic both the daemon and every press read, so the price shown before a press is the price the daemon keeps.
+describe("keep-warm economics", () => {
+    test("refreshes a fifth of an entry's life early, never under a minute or over ten", () => {
+        expect(keepWarmLeadMs(HOUR)).toBe(10 * MINUTE);
+        expect(keepWarmLeadMs(5 * MINUTE)).toBe(MINUTE);
+    });
+
+    test("spends at most half of what a cold resume would rewrite", () => {
+        // A 1h rewrite costs 2x base input and a read 0.1x: nineteen reads break even, so nine.
+        expect(keepWarmMaxRefreshes(HOUR)).toBe(9);
+        // A 5m rewrite costs 1.25x: eleven reads break even, so five.
+        expect(keepWarmMaxRefreshes(5 * MINUTE)).toBe(5);
+    });
+
+    test("counts the refreshes that keep an entry alive through the deadline", () => {
+        const cache = { at: 0, ttlMs: HOUR };
+        expect(keepWarmRefreshes(cache, HOUR)).toBe(0);
+        expect(keepWarmRefreshes(cache, 4 * HOUR)).toBe(4);
+        expect(keepWarmDueAt(cache)).toBe(50 * MINUTE);
+    });
+
+    test("reaches no further than the horizon, or the date change when that comes first", () => {
+        const cache = { at: 0, ttlMs: HOUR };
+        expect(keepWarmHorizon(cache)).toBe(HOUR + 9 * 50 * MINUTE);
+        expect(keepWarmCap(cache, 3 * HOUR)).toBe(3 * HOUR);
+        expect(keepWarmCap({ at: 0, ttlMs: 5 * MINUTE }, undefined)).toBe(5 * MINUTE + 5 * 4 * MINUTE);
+    });
+
+    test("names the parts two fingerprints disagree on", () => {
+        const before = { hash: "a", parts: { version: "1", model: "m", day: "d1" } };
+        expect(changedParts(before, { hash: "b", parts: { version: "2", model: "m", day: "d2" } })).toEqual(["day", "version"]);
+        expect(changedParts(before, before)).toEqual([]);
+    });
+});
+
+describe("the receipt a kept conversation's turn leaves", () => {
+    test("says it picked up warm, and for how long it was kept", () => {
+        expect(keptWarmLine({ readTokens: 251_000, writtenTokens: 3_000, kept: { forMs: 3 * HOUR + 12 * MINUTE, refreshes: 4 } })).toBe(
+            "Picked up warm: 251k tokens read from the cache, kept warm for 3h 12m with 4 refreshes.",
+        );
+    });
+
+    test("says so plainly when the turn went cold anyway", () => {
+        expect(keptWarmLine({ readTokens: 0, writtenTokens: 250_000, kept: { forMs: 40 * MINUTE, refreshes: 1 } })).toContain("Picked up cold");
+    });
+
+    test("is a notice row in the transcript, and nothing for a turn nobody kept", () => {
+        const fold = new TranscriptFold([]);
+        expect(fold.apply({ kind: "prompt_cache", readTokens: 10, writtenTokens: 200_000 })).toEqual([]);
+        fold.apply({ kind: "prompt_cache", readTokens: 251_000, writtenTokens: 3_000, kept: { forMs: HOUR, refreshes: 1 } });
+        expect(fold.rows.at(-1)).toMatchObject({ role: "notice", text: expect.stringContaining("Picked up warm") });
+    });
+});

package/src/schemas/keep-warm.ts

@@ -0,0 +1,124 @@
+// keep-warm: holding an idle conversation's prompt cache open by re-reading it shortly before it expires.
+
+import { z } from "zod";
+
+const HOUR_MS = 3_600_000;
+
+// Anthropic's price multipliers on base input: a read costs 0.1x, a write 2x under the 1h TTL and 1.25x under 5m.
+const READ_COST = 0.1;
+const writeCost = (ttlMs: number): number => (ttlMs >= HOUR_MS ? 2 : 1.25);
+
+// A cache clock as the daemon publishes it: the last request that touched the entry, and the entry's lifetime.
+export interface CacheClock {
+    readonly at: number;
+    readonly ttlMs: number;
+}
+
+/** How long before expiry a refresh starts: a fifth of the entry's life, never under a minute or over ten. */
+export const keepWarmLeadMs = (ttlMs: number): number => Math.min(10 * 60_000, Math.max(60_000, Math.round(ttlMs / 5)));
+
+/** Refreshes one hold may spend: half of what a cold resume rewrites, the other half left for each refresh's own tail. */
+export const keepWarmMaxRefreshes = (ttlMs: number): number => Math.floor((writeCost(ttlMs) - READ_COST) / READ_COST / 2);
+
+/** How many refreshes keep an entry alive through `until`. */
+export const keepWarmRefreshes = (cache: CacheClock, until: number): number => {
+    const beyond = until - (cache.at + cache.ttlMs);
+    return beyond <= 0 ? 0 : Math.ceil(beyond / (cache.ttlMs - keepWarmLeadMs(cache.ttlMs)));
+};
+
+/** The latest instant a hold may reach, given the refreshes it already spent: past it, refreshing costs more than the cold resume it saves. */
+export const keepWarmHorizon = (cache: CacheClock, spent = 0): number =>
+    cache.at + cache.ttlMs + Math.max(0, keepWarmMaxRefreshes(cache.ttlMs) - spent) * (cache.ttlMs - keepWarmLeadMs(cache.ttlMs));
+
+/** When the next refresh is due for an entry last touched at `cache.at`. */
+export const keepWarmDueAt = (cache: CacheClock): number => cache.at + cache.ttlMs - keepWarmLeadMs(cache.ttlMs);
+
+/** The furthest `until` a hold can honestly promise: the economic horizon, or the date change, whichever comes first. */
+export const keepWarmCap = (cache: CacheClock, rollsAt: number | undefined, spent = 0): number =>
+    rollsAt === undefined ? keepWarmHorizon(cache, spent) : Math.min(keepWarmHorizon(cache, spent), rollsAt);
+
+// Why a hold ended before anyone picked the conversation up. `elapsed` is the one ending that is not a problem.
+export const KeepWarmEndSchema = z.enum(["elapsed", "allowance", "limited", "changed", "rewrote", "cold", "failed", "midnight", "moved"]);
+export type KeepWarmEnd = z.infer<typeof KeepWarmEndSchema>;
+
+export const KeepWarmSchema = z.object({
+    since: z.number().describe("When keeping it warm started, in milliseconds."),
+    until: z
+        .number()
+        .describe(
+            "When it stops by itself, in milliseconds: the time asked for, shortened to what the sandbox can honestly keep, which is never past the point where refreshing costs more than re-reading, nor past the date change that rewrites the prompt.",
+        ),
+    auto: z.boolean().optional().describe("Started by the sandbox-wide setting after a turn, rather than by a press on this conversation."),
+    refreshes: z.number().int().min(0).describe("Refreshes sent so far."),
+    readTokens: z
+        .number()
+        .optional()
+        .describe("How much the last refresh read back from the provider's cache, in tokens: the proof the cache was still there."),
+    ended: z
+        .object({
+            at: z.number().describe("When it stopped, in milliseconds."),
+            reason: KeepWarmEndSchema.describe(
+                "Why: `elapsed` the time asked for ran out; `allowance` the account reached the reserve kept for real work; `limited` the provider refused a refresh; `changed` what the next turn would send no longer matches the cache; `rewrote` a refresh found the cache already gone; `cold` it expired before a refresh could run; `failed` a refresh failed; `midnight` the date in the prompt changed; `moved` the conversation's session or account changed.",
+            ),
+            detail: z.string().optional().describe("The specifics, when there are any: which parts of the prompt changed, or the failure's own words."),
+        })
+        .optional()
+        .describe("Why keeping it warm stopped before anyone picked the conversation up. Absent while it is still being kept."),
+});
+export type KeepWarm = z.infer<typeof KeepWarmSchema>;
+
+export const AgentKeepWarmSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    until: z
+        .number()
+        .nullable()
+        .describe(
+            "Keep its prompt cache warm until this instant, in milliseconds; shortened to what the sandbox can honestly keep. Null stops keeping it warm.",
+        ),
+});
+export type AgentKeepWarm = z.infer<typeof AgentKeepWarmSchema>;
+
+// What a turn's first request found in the cache, and how long it had been kept warm for it when it was.
+export const PromptCacheOpeningSchema = z.object({
+    readTokens: z.number().describe("Tokens the turn's first request read from the provider's cache."),
+    writtenTokens: z.number().describe("Tokens it wrote to the cache, which is what it paid full price for."),
+    kept: z
+        .object({
+            forMs: z.number().describe("How long the cache had been kept warm for this turn, in milliseconds."),
+            refreshes: z.number().int().min(0).describe("How many refreshes that took."),
+        })
+        .optional()
+        .describe("Present when this turn picked up a conversation the sandbox had been keeping warm."),
+});
+export type PromptCacheOpening = z.infer<typeof PromptCacheOpeningSchema>;
+
+const tokensLabel = (tokens: number): string => (tokens >= 1_000 ? `${Math.round(tokens / 1_000)}k` : String(tokens));
+
+const spanLabel = (ms: number): string => {
+    const minutes = Math.max(1, Math.round(ms / 60_000));
+    const hours = Math.floor(minutes / 60);
+    return hours === 0 ? `${minutes}m` : `${hours}h ${minutes % 60}m`;
+};
+
+/** The transcript's line for a turn that picked up a conversation kept warm for it; undefined for any other turn. */
+export const keptWarmLine = (opening: PromptCacheOpening): string | undefined => {
+    const { kept } = opening;
+    if (kept === undefined) {
+        return undefined;
+    }
+    const held = `kept warm for ${spanLabel(kept.forMs)} with ${kept.refreshes} ${kept.refreshes === 1 ? "refresh" : "refreshes"}`;
+    return opening.readTokens >= opening.writtenTokens
+        ? `Picked up warm: ${tokensLabel(opening.readTokens)} tokens read from the cache, ${held}.`
+        : `Picked up cold despite being ${held}: ${tokensLabel(opening.writtenTokens)} tokens sent again, because this turn's prompt no longer matched the cache.`;
+};
+
+// A turn's prefix, part by part, so two turns that should share a cache can say which part stopped matching.
+export const PromptFingerprintSchema = z.object({
+    hash: z.string().describe("One short hash over every part."),
+    parts: z.record(z.string(), z.string()).describe("Each part's own short hash or value, by name."),
+});
+export type PromptFingerprint = z.infer<typeof PromptFingerprintSchema>;
+
+/** Which parts differ between two fingerprints, by name; empty when they match. */
+export const changedParts = (before: PromptFingerprint, after: PromptFingerprint): string[] =>
+    [...new Set([...Object.keys(before.parts), ...Object.keys(after.parts)])].filter((name) => before.parts[name] !== after.parts[name]).toSorted();

package/src/schemas/metrics.ts

@@ -140,6 +140,8 @@ export const STORAGE_CLEANABILITY = {
     other: "none",
     // Git data and checkouts of repositories deleted from the workspace; nothing reads it again, but it may hold commits never pushed.
     trash: "confirm",
+    // Transcripts as they were before the sandbox converted them to its current format; nothing reads them again.
+    backups: "confirm",
     // Copies of the sandbox packed for download.
     exports: "confirm",
     // Files agents produced: generated images, reports, harness output.

package/src/schemas/offload.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { RunnerCommandFrameSchema, RunnerCommandSchema } from "../protocol/runner-protocol.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.
+
+// Whether a runner can take a line right now, asked before the tree is snapshotted, so a machine that is asleep costs
+// nothing. `name` is the machine the runner sits on, the word the owner picked it by.
+export const OffloadTargetSchema = z.object({
+    runner: z.string().min(1),
+    name: z.string().min(1),
+    ready: z.boolean(),
+    // Why not, in the words the command prints before it runs the line here instead.
+    why: z.string().optional(),
+});
+export type OffloadTarget = z.infer<typeof OffloadTargetSchema>;
+
+export const OffloadRunSchema = RunnerCommandSchema.extend({ runner: z.string().min(1) });
+export type OffloadRun = z.infer<typeof OffloadRunSchema>;
+
+// What a run streams back: the runner's own frames, or one refusal when the runner could not take it after all (it went
+// offline between the question and the run, or it predates offloading), which sends the line back here.
+export const OffloadFrameSchema = z.union([...RunnerCommandFrameSchema.options, z.object({ kind: z.literal("refused"), why: z.string() })]);
+export type OffloadFrame = z.infer<typeof OffloadFrameSchema>;
+
+// One offloaded run as the runner card lists it: the recent ones, kept in memory, newest first.
+export const OffloadRecordSchema = z.object({
+    runId: z.string(),
+    runner: z.string(),
+    name: z.string(),
+    label: z.string(),
+    // The line, cut to a readable length.
+    command: z.string(),
+    startedAt: z.number(),
+    endedAt: z.number().optional(),
+    code: z.number().int().optional(),
+    failure: z.string().optional(),
+});
+export type OffloadRecord = z.infer<typeof OffloadRecordSchema>;
+
+// One kind of heavy work the owner can send elsewhere: a heavy-command rule this sandbox queues (its id, as settings
+// `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>;

package/src/schemas/personas.ts

@@ -125,9 +125,9 @@ export const TURN_BRIEFING_NOTES: readonly TurnBriefingNote[] = [
     },
     {
         id: "checks",
-        label: "Automatic end-of-turn checks",
-        when: "First message, and again after a compaction, when you have rules that run at the end of a turn.",
-        cost: "Your checks still run; the agent just does not know they are coming, so a failure arrives as a surprise it has to re-read the turn to understand.",
+        label: "Checks after landing",
+        when: "First message and after a compaction, and again whenever the main tree's own check turns red or back to green: what runs after its work lands, and which failures the main tree already has.",
+        cost: "The agent does not know which failures are the main tree's own and not its doing, so it may spend a turn chasing one somebody else is already fixing.",
     },
     {
         id: "dependencies",

package/src/schemas/ports.ts

@@ -45,6 +45,16 @@ export const PortSummarySchema = z.object({
         .describe(
             'The terminal it came from, to watch it in or stop it from. Absent when nothing in its ancestry is one, which is the honest "you cannot reach this from here".',
         ),
+    // A job an agent's turn left running for the person (AgentSummary.jobs[].handed); ports listed anywhere else stay
+    // unclaimed by any conversation.
+    job: z
+        .object({
+            conversationId: z.string().describe("The conversation whose turn left it running."),
+            jobId: z.string().describe("The job, as that conversation's card names it; stopping it stops this port."),
+            label: z.string().describe("What the job is, in the agent's own words when it gave any."),
+        })
+        .optional()
+        .describe("The background job an agent left running for you on this port, when that is what answers here."),
     forwarded: z.boolean().describe("Whether it is currently reachable from outside."),
     // `https://port-<slot>-<sandboxId>.<zone>`.
     previewUrl: z.string().optional().describe("Where to open it. Present only while forwarded, and only on a sandbox that has an outside address."),

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

@@ -24,11 +24,24 @@ export const UsageWindowSchema = z.object({
     gates: WindowGatesSchema,
 });
 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
+// "the last attempt failed", never inferred from a list of known failure kinds, so a surface that dates readings by
+// age can leave out every reading that cannot move, including one whose failure nobody has seen before.
+export const UsageUnreadSchema = z.object({
+    since: z.number().describe("When re-reading this account first failed, in milliseconds. It has failed on every attempt since."),
+    reason: z
+        .string()
+        .describe("Why, in the provider's own words where it gave some (\"Verify your account to continue.\"). Short enough to print; never a pasted response body."),
+});
+export type UsageUnread = z.infer<typeof UsageUnreadSchema>;
 // Every window kept, not just the binding one, since which pool binds changes between turns. Utilization only climbs
 // within a window, so a stale reading is still a valid floor. `measuredAt` is epoch ms — windows are seconds.
 export const AccountUsageSchema = z.object({
     windows: z.array(UsageWindowSchema),
     measuredAt: z.number(),
+    unread: UsageUnreadSchema.optional().describe(
+        "Present while re-reading this account keeps failing: these windows are the last reading that succeeded, and `measuredAt` will not move until a read succeeds again.",
+    ),
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
 // Anthropic's once-a-week reset of the session window only; the weekly allowance is untouched. The answer is entirely

package/src/schemas/providers/provider-oauth.ts

@@ -22,6 +22,12 @@ export const OauthAccountSchema = z.object({
         .optional()
         .describe("Its stored credential can no longer be renewed and somebody has to sign in again. Absent means healthy, or not checked yet."),
     detail: z.string().optional().describe("Why, in words a person can act on."),
+    seatRefusal: z
+        .string()
+        .optional()
+        .describe(
+            "Its organisation has switched it off for this harness (no seat): it still signs in and its plan limits may still read, but no turn can run on it until an admin gives access back. The provider's own sentence; cleared by the next turn that runs on it. Absent means no refusal is on file.",
+        ),
     usage: AccountUsageSchema.optional().describe(
         "How full its plan limits were when last measured, so a picker can show what is left before committing work to it. Absent until a reading exists, which reads as unknown rather than as nothing left.",
     ),

package/src/schemas/providers/usage.ts

@@ -103,6 +103,13 @@ export const UsageTurnSchema = z.object({
     compactions: z.number().optional(),
     contextTokens: z.number().optional(),
     contextWindow: z.number().optional(),
+    // Absent is a turn; `keep-warm` is a cache refresh sent while the conversation sat idle, billed but not a turn.
+    purpose: z.enum(["keep-warm"]).optional().describe("What the row is when it is not a turn: `keep-warm` is a cache refresh sent while the conversation sat idle."),
+    // The first request alone: a warm resume reads nearly the whole context here, a cold one writes it.
+    openingCacheReadTokens: z.number().optional().describe("Tokens the turn's first request read from the provider's cache."),
+    openingCacheCreationTokens: z.number().optional().describe("Tokens the turn's first request wrote to the provider's cache."),
+    // Equal on two turns means the prefix both sent was assembled from the same parts (PromptFingerprintSchema).
+    promptFingerprint: z.string().optional().describe("A short hash over the parts of the prompt a cache is keyed on; a change between two turns names why the second could not reuse the first's cache."),
     // This turn's model was chosen by the Auto judge reading the conversation's opening message, not picked by hand.
     // Marked on that one turn only; a later row of the same conversation naming a different model is the user
     // overruling it, which is the escalation rate this feature has to be able to answer for.

package/src/schemas/settings-history.ts

@@ -0,0 +1,61 @@
+import type { z } from "zod";
+import { dropAll, isJsonObject, mapValue, retype } from "../documents/conversions.js";
+import type { RuleSchema } from "./settings.js";
+
+// The conversions the settings shape has had, oldest first: what brings any earlier release's settings to
+// SandboxSettingsSchema. Two documents carry this shape, the daemon's settings.json and a sandbox.toml's [settings]
+// table, and both read through this one list; it sits beside the schema so that neither reader has to reach into the
+// other for it. A name retired here stays retired: no later setting may take it to mean something else.
+
+// Rules at a moment or with an action a later version withdrew (the `push.starting` moment, `instruct` actions, three
+// built-in checks) can never run, and one of them made the whole file unreadable, every setting in it with it.
+const RETIRED_MOMENTS: ReadonlySet<unknown> = new Set(["push.starting"]);
+const RETIRED_ACTIONS: ReadonlySet<unknown> = new Set(["instruct"]);
+const RETIRED_BUILTINS: ReadonlySet<unknown> = new Set(["verify-edits", "verify-removals", "verify-tests"]);
+
+const isRetiredRule = (rule: unknown): boolean => {
+    if (!isJsonObject(rule)) {
+        return false;
+    }
+    const action = isJsonObject(rule["action"]) ? rule["action"] : {};
+    return RETIRED_MOMENTS.has(rule["moment"]) || RETIRED_ACTIONS.has(action["kind"]) || (action["kind"] === "builtin" && RETIRED_BUILTINS.has(action["name"]));
+};
+
+const holdsRetiredRule = (value: unknown): value is readonly unknown[] => Array.isArray(value) && value.some(isRetiredRule);
+
+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
+    // take one of these names to mean something else.
+    ...dropAll([
+        "agentRunEffort",
+        "agentRunModel",
+        "agentRunModels",
+        "autoFastModels",
+        "autoTier",
+        "autoTierEagerness",
+        "commandJudgeModels",
+        "commandRules",
+        "contextShelf",
+        "dependencyFreshness",
+        "explainCommands",
+        "iqContext",
+        "iqContextHoldout",
+        "moveAfterLimit",
+        "quickModel",
+        "resumeAfterLimit",
+        "resumeAfterOutage",
+        "terseHoldout",
+        "terseOutput",
+        "testFaultDetection",
+    ]),
+    retype(
+        "rules",
+        holdsRetiredRule,
+        // What survives the filter is every rule this version can read; the parse after the chain says so.
+        (rules) => rules.filter((rule) => !isRetiredRule(rule)) as z.input<typeof RuleSchema>[],
+        "drops rules at a withdrawn moment or with a withdrawn action (push.starting, instruct, three built-in checks)",
+    ),
+    // suggest, the old default, becomes the new default: routing on.
+    mapValue("personaRouting", { off: false, suggest: true, auto: true }),
+] as const;