@intentic/sandbox-contract 1.309.0 → 1.311.0

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.test.ts

@@ -1,4 +1,3 @@
-import { test, expect } from "bun:test";
 import { isScratch } from "./git.js";
 
 test("a scratch directory entry covers everything under it, and a file entry only itself", () => {

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

@@ -59,9 +59,7 @@ export const SandboxUsageSchema = z.object({
         .optional()
         .describe("CPU the whole sandbox used over the window, as a percentage of all it may use (`cores`). Absent on a first reading."),
     cores: z.number().describe("How many cores the sandbox may use: its CPU quota, or every core it is allowed to run on when it has none."),
-    memoryBytes: z
-        .number()
-        .describe("Memory in use, less the file cache the kernel takes back on demand: the figure that runs into the limit."),
+    memoryBytes: z.number().describe("Memory in use, less the file cache the kernel takes back on demand: the figure that runs into the limit."),
     memoryLimitBytes: z.number().describe("The memory limit: the container's own, or the machine's memory when the container has none."),
     swapBytes: z.number().optional().describe("Memory pushed out to swap. Absent where the sandbox cannot see its own swap."),
     diskBytes: z.number().optional().describe("Space used on the volume the workspace lives on. Absent when the volume would not say."),
@@ -70,7 +68,9 @@ export const SandboxUsageSchema = z.object({
         .tuple([z.number(), z.number(), z.number()])
         .describe("The load average over 1, 5 and 15 minutes. It is the machine's, so other sandboxes on it count too."),
     processes: z.number().describe("How many processes are running in the sandbox."),
-    pressure: PressureMetricsSchema.optional().describe("How much work waited on CPU, memory or disk lately. Absent where the kernel does not report it."),
+    pressure: PressureMetricsSchema.optional().describe(
+        "How much work waited on CPU, memory or disk lately. Absent where the kernel does not report it.",
+    ),
 });
 export type SandboxUsage = z.infer<typeof SandboxUsageSchema>;
 
@@ -109,89 +109,58 @@ export type SandboxMetrics = z.infer<typeof SandboxMetricsSchema>;
 // What is filling the sandbox's disk, by what it is for (GET /system/storage). Sizes are apparent bytes, and a file
 // with several hard links counts once, toward the first place the scan met it.
 
-// Every category a byte on the sandbox's volumes can belong to; STORAGE_CLEANABILITY below says which may be cleaned.
-export const STORAGE_CATEGORIES = [
-    // The workspace's own files: repositories, their dependencies, anything the owner or an agent put there.
-    "workspace",
-    // Transcripts, runtime session stores, attachments and loop memory of every conversation, archived ones included.
-    "conversations",
-    // Each open conversation's own checkout of the repositories, and the dependencies its turns installed over them.
-    "checkouts",
-    // The minute-by-minute and per-turn snapshots the History timeline restores from.
-    "restorePoints",
-    // The repositories' own git data: every commit and branch, pushed or not.
-    "repositories",
-    // Installed versions of the agent runtimes: the one turns use and the one kept for Revert.
-    "engines",
-    // Search indexes and caches the sandbox keeps up to date by itself while it runs.
-    "indexes",
-    // Installed extensions and their scratch.
-    "extensions",
-    // The sandbox's own Docker: images, containers, volumes.
-    "docker",
-    // Settings, credentials, sign-ins and the ledgers of what was spent and done.
-    "state",
-    // Anything no part of the sandbox claims.
-    "other",
-    // Git data and checkouts of repositories deleted from the workspace.
-    "trash",
-    // Copies of the sandbox packed for download.
-    "exports",
-    // Files agents produced: generated images, reports, harness output.
-    "artifacts",
-    // Screenshots and page snapshots the agent's browser took.
-    "browserCaptures",
-    // The agent browser's profiles, with the sites it is signed in to.
-    "browserProfiles",
-    // Weights downloaded for local models.
-    "modelWeights",
-    // The sandbox's own logs and terminal captures.
-    "logs",
-    // Scratch space agents and checks leave behind.
-    "scratch",
-    // Package managers' content stores, which the next install refills.
-    "packageStores",
-    // Build tools' output caches.
-    "buildCaches",
-] as const;
-export const StorageCategoryIdSchema = z.enum(STORAGE_CATEGORIES);
-export type StorageCategoryId = z.infer<typeof StorageCategoryIdSchema>;
-
 // none: never removed from here; safe: comes back by itself, removed without asking; confirm: removed only once the
 // owner has read what it costs.
 export const StorageCleanabilitySchema = z.enum(["none", "safe", "confirm"]);
 export type StorageCleanability = z.infer<typeof StorageCleanabilitySchema>;
 
-// Which categories may be cleaned, and which ask first: the daemon's cleaner refuses by it, the editor words its
-// confirm by it. State, credentials and live work are `none`; what regenerates is `safe`; the owner's own data asks.
+// Every category a byte on the volumes can belong to, and its cleanability: the cleaner refuses by it, the editor words its confirm by it.
 export const STORAGE_CLEANABILITY = {
+    // The workspace's own files: repositories, their dependencies, anything the owner or an agent put there.
     workspace: "none",
+    // Transcripts, runtime session stores, attachments and loop memory of every conversation, archived ones included.
     conversations: "none",
-    // A live conversation's working copy; archiving the conversation is what frees it.
+    // Each open conversation's own checkout of the repositories and the dependencies its turns installed; archiving the conversation frees it.
     checkouts: "none",
-    // No compaction is safe to offer: `git gc --auto` already runs after every snapshot, and every object is reachable.
+    // Per-turn and minute-by-minute snapshots History restores from; no compaction to offer: `git gc --auto` runs after each, all is reachable.
     restorePoints: "none",
+    // The repositories' own git data: every commit and branch, pushed or not.
     repositories: "none",
-    // The Engines card keeps two versions and owns which is which; removing one here would strand its Revert.
+    // Installed agent runtimes, the one turns use and the one kept for Revert; the Engines card owns which is which, so removing one strands it.
     engines: "none",
-    // Held open by what maintains them: removing a file frees nothing until they close it.
+    // Search indexes and caches the sandbox keeps up to date while it runs, held open by it: removing a file frees nothing until it closes.
     indexes: "none",
+    // Installed extensions and their scratch.
     extensions: "none",
+    // The sandbox's own Docker: images, containers, volumes.
     docker: "none",
+    // Settings, credentials, sign-ins and the ledgers of what was spent and done.
     state: "none",
+    // Anything no part of the sandbox claims.
     other: "none",
-    // Nothing reads it again, but it may hold commits never pushed anywhere.
+    // Git data and checkouts of repositories deleted from the workspace; nothing reads it again, but it may hold commits never pushed.
     trash: "confirm",
+    // Copies of the sandbox packed for download.
     exports: "confirm",
+    // Files agents produced: generated images, reports, harness output.
     artifacts: "confirm",
+    // Screenshots and page snapshots the agent's browser took.
     browserCaptures: "confirm",
+    // The agent browser's profiles, with the sites it is signed in to.
     browserProfiles: "confirm",
+    // Weights downloaded for local models.
     modelWeights: "confirm",
+    // The sandbox's own logs and terminal captures.
     logs: "safe",
+    // Scratch space agents and checks leave behind.
     scratch: "safe",
+    // Package managers' content stores, which the next install refills.
     packageStores: "safe",
+    // Build tools' output caches.
     buildCaches: "safe",
-} as const satisfies Record<StorageCategoryId, StorageCleanability>;
+} as const satisfies Record<string, StorageCleanability>;
+export type StorageCategoryId = keyof typeof STORAGE_CLEANABILITY;
+export const StorageCategoryIdSchema = z.enum(Object.keys(STORAGE_CLEANABILITY) as StorageCategoryId[]);
 
 export const StorageItemSchema = z.object({
     path: z.string().describe("Where it is, as an absolute path inside the sandbox."),
@@ -245,11 +214,11 @@ export type StorageCleanInput = z.infer<typeof StorageCleanInputSchema>;
 
 export const StorageCleanResultSchema = z.object({
     category: StorageCategoryIdSchema,
-    freedBytes: z.number().describe("Space the removals gave back, in bytes. A file that is still linked elsewhere frees nothing and is not counted."),
-    removed: z.number().describe("How many items were removed."),
-    kept: z
+    freedBytes: z
         .number()
-        .describe("How many were left in place: changed too recently, in use by a running program, or no longer this category's."),
+        .describe("Space the removals gave back, in bytes. A file that is still linked elsewhere frees nothing and is not counted."),
+    removed: z.number().describe("How many items were removed."),
+    kept: z.number().describe("How many were left in place: changed too recently, in use by a running program, or no longer this category's."),
     failed: z.number().describe("How many removals the filesystem refused."),
 });
 export type StorageCleanResult = z.infer<typeof StorageCleanResultSchema>;

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.test.ts

@@ -1,5 +1,4 @@
-import { describe, test, expect } from "bun:test";
-import { RuleSchema } from "./settings.js";
+import { RepoChecksFileSchema, RuleSchema, SandboxSettingsSchema } from "./settings.js";
 
 // A rule that saves cleanly and silently does nothing is the failure this schema exists to refuse: an action, and a
 // built-in's name, are checked against the moment they are written at.
@@ -12,14 +11,49 @@ describe(`which built-in stands at which moment`, () => {
         expect(rule(`turn.ending`, { kind: `builtin`, name: `version-landed` }).success).toBe(false);
     });
 
-    test(`the verifiers stand at the turn's end and not at the landing`, () => {
-        expect(rule(`turn.ending`, { kind: `builtin`, name: `verify-edits` }).success).toBe(true);
-        expect(rule(`agent.landed`, { kind: `builtin`, name: `verify-edits` }).success).toBe(false);
+    test(`the look stands at the turn's end and not at the landing`, () => {
+        expect(rule(`turn.ending`, { kind: `builtin`, name: `verify-ui-edits` }).success).toBe(true);
+        expect(rule(`agent.landed`, { kind: `builtin`, name: `verify-ui-edits` }).success).toBe(false);
     });
 
-    test(`the landed moment takes no verdict, command or instruction: the work is already in the tree`, () => {
+    test(`the landed moment takes no verdict and no command: the work is already in the tree`, () => {
         expect(rule(`agent.landed`, { kind: `verdict`, verdict: `allow` }).success).toBe(false);
         expect(rule(`agent.landed`, { kind: `command`, command: `pnpm test` }).success).toBe(false);
-        expect(rule(`agent.landed`, { kind: `instruct`, text: `well done` }).success).toBe(false);
+    });
+
+    test(`there is no push moment: the repository's own pre-push hook gates a push`, () => {
+        expect(rule(`push.starting`, { kind: `command`, command: `pnpm test` }).success).toBe(false);
+    });
+});
+
+describe(`where a command lives`, () => {
+    test(`settings refuse a command rule, since it belongs to the repository it checks`, () => {
+        const command = { id: `lint`, label: `lint`, moment: `file.edited`, action: { kind: `command`, command: `oxlint {file}` } };
+        expect(SandboxSettingsSchema.safeParse({ rules: [command] }).success).toBe(false);
+        const land = { id: `auto-land`, label: `land`, moment: `agent.finished`, action: { kind: `verdict`, verdict: `allow` } };
+        expect(SandboxSettingsSchema.safeParse({ rules: [land] }).success).toBe(true);
+    });
+
+    test(`a repository declares edit, turn and land checks, and no push check`, () => {
+        const file = (checks: unknown[]) => RepoChecksFileSchema.safeParse({ checks }).success;
+        expect(
+            file([
+                { when: `edit`, run: `lint {file}` },
+                { when: `turn`, run: `pnpm verify:turn` },
+                { when: `land`, run: `pnpm verify` },
+            ]),
+        ).toBe(true);
+        expect(file([{ when: `push`, run: `pnpm verify:push` }])).toBe(false);
+    });
+
+    test(`a land check is one per repository and narrows by no path`, () => {
+        const file = (checks: unknown[]) => RepoChecksFileSchema.safeParse({ checks }).success;
+        expect(
+            file([
+                { when: `land`, run: `pnpm verify` },
+                { when: `land`, run: `pnpm test` },
+            ]),
+        ).toBe(false);
+        expect(file([{ when: `land`, run: `pnpm verify`, paths: [`src/**`] }])).toBe(false);
     });
 });