@intentic/sandbox-contract 1.308.2 → 1.310.0

package/src/schemas/history.ts

@@ -25,7 +25,8 @@ export interface SnapshotTurn {
 }
 export const SnapshotsListSchema = z.object({ snapshots: z.array(SnapshotSchema).describe("Every point you can go back to, newest first.") });
 // Restores the workspace to that turn's checkpoint, drops every message after it, and forgets the provider session so
-// the next turn opens fresh.
+// the next turn opens fresh. `messageId` is what makes `index` safe to act on: a position is only as current as the
+// transcript it was read from.
 export const RewindTurnSchema = z.object({
     conversationId: z.string().min(1).describe("Which conversation to rewind."),
     index: z
@@ -35,6 +36,12 @@ export const RewindTurnSchema = z.object({
         .describe(
             "Which message to go back to, counting from the start. It is also how many messages survive: rewinding to the first keeps none of them and puts the files back to before it ran.",
         ),
+    messageId: z
+        .string()
+        .min(1)
+        .describe(
+            "The id of the message at that position, as its row names it. If that position now holds a different message, nothing is rewound: the transcript has moved since you read it.",
+        ),
 });
 export const RewindResultSchema = z.object({
     snapshot: z

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>;
 
@@ -105,3 +105,120 @@ export const SandboxMetricsSchema = z.object({
         .describe("Every process in the sandbox but the daemon, by what kind of work it is. A kind with nothing running is absent."),
 });
 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.
+
+// 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>;
+
+// 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",
+    // Each open conversation's own checkout of the repositories and the dependencies its turns installed; archiving the conversation frees it.
+    checkouts: "none",
+    // 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",
+    // 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",
+    // 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",
+    // 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<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."),
+    bytes: z.number().describe("Its size in bytes."),
+});
+export type StorageItem = z.infer<typeof StorageItemSchema>;
+
+export const StorageCategoryUsageSchema = z.object({
+    id: StorageCategoryIdSchema,
+    cleanability: StorageCleanabilitySchema.describe("Whether this category can be cleaned from here, and whether cleaning it asks first."),
+    bytes: z.number().describe("Its size in bytes."),
+    files: z.number().describe("How many files it holds."),
+    cleanableBytes: z
+        .number()
+        .optional()
+        .describe(
+            "What cleaning it would free right now: only what is old enough and not in use. Absent where nothing here may be cleaned, and for a package store, whose own tool decides what no project needs.",
+        ),
+    items: z.array(StorageItemSchema).describe("Its biggest parts, largest first, at most eight."),
+});
+export type StorageCategoryUsage = z.infer<typeof StorageCategoryUsageSchema>;
+
+export const StorageScanSchema = z.object({
+    startedAt: z.number().describe("When the scan began, in milliseconds."),
+    finishedAt: z.number().describe("When it ended, in milliseconds: the moment these sizes describe."),
+    outcome: z
+        .enum(["complete", "partial"])
+        .describe("`partial` when the scan hit its time limit first, so every size is at least what it says rather than exactly it."),
+    disk: z
+        .object({
+            usedBytes: z.number().describe("Space used on the volume the workspace lives on."),
+            totalBytes: z.number().describe("That volume's size."),
+        })
+        .optional()
+        .describe("The volume as a whole. Absent when the volume would not say."),
+    categories: z.array(StorageCategoryUsageSchema).describe("Every category that holds anything, largest first."),
+    unreadable: z.number().describe("Files and folders the scan could not read, and so did not count."),
+});
+export type StorageScan = z.infer<typeof StorageScanSchema>;
+
+export const StorageReportSchema = z.object({
+    scan: StorageScanSchema.optional().describe("The last scan that finished. Absent until one has, and again after the daemon restarts."),
+    scanning: z.boolean().describe("Whether a scan is running now."),
+});
+export type StorageReport = z.infer<typeof StorageReportSchema>;
+
+export const StorageCleanInputSchema = z.object({
+    category: StorageCategoryIdSchema.describe("The category to clean; one whose cleanability is `none` is refused."),
+});
+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.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/plan-limits.ts

@@ -214,6 +214,14 @@ export const SteerSchema = z
     .object({
         conversationId: z.string().min(1).describe("Which running conversation to interrupt."),
         text: z.string().max(20_000).describe("What to say to it. It arrives mid-turn without stopping the turn."),
+        messageId: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe(
+                "Your id for this message. Sending again under an id the sandbox already took is answered with what it did with it the first time, never a second delivery. Leave it out and the sandbox names the message itself.",
+            ),
         attachments: z
             .array(z.string().min(1))
             .max(20)
@@ -233,8 +241,42 @@ export const SteerSchema = z
     .refine((steer) => steer.text.trim().length > 0 || (steer.attachments?.length ?? 0) > 0, {
         message: "text or attachments required",
     });
-// True cancel, aborted daemon-side; unlike closing the /agent fetch, which sends no cancel frame.
-export const StopTurnSchema = z.object({ conversationId: z.string().min(1).describe("Which conversation's running turn to cancel.") });
+// True cancel, aborted daemon-side; unlike closing the /agent fetch, which sends no cancel frame. A stop names the run
+// it means, so one arriving after that run settled cannot cancel whatever the conversation started next.
+export const StopTurnSchema = z.union([
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        run: z
+            .string()
+            .min(1)
+            .describe(
+                "The run you mean to cancel, as starting or attaching to it named it. If another turn has started since, nothing is cancelled and the answer names the one running instead.",
+            ),
+    }),
+    // A send not yet answered has no run to name, only the id it gave its message.
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        messageId: z
+            .string()
+            .min(1)
+            .describe(
+                "The message you sent, while its run is not named yet: cancels the turn it is in. If none is, nothing is cancelled: the message has not become a turn, or its turn has already ended.",
+            ),
+    }),
+    // Only for a turn nobody can name: one the sandbox runs with no run to attach to (a scheduled automation's).
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        live: z
+            .literal(true)
+            .describe("Cancel whatever turn is running now, whichever that is. Only for a turn you cannot name: one that has no run to attach to."),
+    }),
+]);
+export type StopTurn = z.infer<typeof StopTurnSchema>;
+export const StopResultSchema = z.object({
+    stopped: z.boolean().describe("Whether a turn was cancelled."),
+    running: z.string().optional().describe("The run that is live instead of the one you named, left running. Absent when nothing else runs."),
+});
+export type StopResult = z.infer<typeof StopResultSchema>;
 // The press carries WHO serves the re-run; the daemon keeps WHAT the turn is (prompt, attachments, worktree) from its
 // own record, since re-deriving from a stripped client transcript would replay a different turn.
 export const ResumeRoutingSchema = z.object({
@@ -261,3 +303,26 @@ export const ResumeTurnSchema = z.object({
         "Who serves the re-run, when the conversation has been re-pointed since it was refused. Leave it out to run it on whatever the turn carried.",
     ),
 });
+// Names one queued message as it was read, so a change made against an older copy is refused rather than written over
+// somebody else's.
+export const QueuedMessageRefSchema = z.object({
+    conversationId: z.string().min(1).describe("Whose queue."),
+    id: z.string().min(1).describe("Which waiting message."),
+    revision: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("The message's revision as you read it. If it has been changed since, from this window or another, nothing happens."),
+});
+export type QueuedMessageRef = z.infer<typeof QueuedMessageRefSchema>;
+export const QueueEditSchema = QueuedMessageRefSchema.extend({
+    text: z.string().describe("What the message should say instead. It keeps its place in the queue."),
+});
+export type QueueEdit = z.infer<typeof QueueEditSchema>;
+export const QueueResumeSchema = z.object({
+    conversationId: z.string().min(1).describe("Whose queue to let go."),
+    routing: ResumeRoutingSchema.optional().describe(
+        "Who serves the turn the waiting messages start, when the conversation has been re-pointed since they were queued: the usual answer to a refusal that held them. Leave it out to send them as they were queued.",
+    ),
+});
+export type QueueResume = z.infer<typeof QueueResumeSchema>;

package/src/schemas/providers/usage.ts

@@ -72,6 +72,9 @@ 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 lean-guidance experiment, stable per conversation; true is the short form. The cohort hashes both forms.
+    guidanceArm: z.boolean().optional(),
+    guidanceCohort: z.string().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/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);
     });
 });

package/src/schemas/settings.ts

@@ -13,39 +13,28 @@ export const SystemPromptModeSchema = z.enum(["intentic", "claude", "custom"]);
 export type SystemPromptMode = z.infer<typeof SystemPromptModeSchema>;
 // Excludes "custom": there is nothing to fetch, it's whatever the owner already typed into the settings field.
 export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"]) });
-// Rules: "at this moment, if this is true, do this" — one table replacing three settings that were the same idea built
-// three ways; a fourth is now a row here, not a release. Moments are named to match `WorkspaceEventKind`, so folding
-// chores in later won't rename what users wrote.
-
-// Five places the daemon already stops to decide something; this names those decisions rather than inventing new ones.
+// Rules: "at this moment, if this is true, do this". The owner's rules decide (land, hold, version) and switch the
+// daemon's built-in reviews; every command a moment runs is a repository's own check (`<repo>/.intentic/checks.json`),
+// compiled into this same table by the daemon, so no command lives in settings.
 export const RuleMomentSchema = z.enum([
     // A command here runs on the just-written file (`{file}` is its path); the cheapest moment to catch a defect.
     "file.edited",
     // The assistant is about to stop. A rule here can send it back to work, which is the only moment that can.
     "turn.ending",
-    // Code is about to leave the machine. A rule here gates the push on its own exit code.
-    "push.starting",
     // An agent's turn is over and its delta is sitting on its branch. A rule here decides whether it lands.
     "agent.finished",
     // An agent's delta has just reached the main tree. A rule here decides what becomes of it there.
     "agent.landed",
 ]);
 export type RuleMoment = z.infer<typeof RuleMomentSchema>;
-// What a rule does; the split is functional since the three settings this table replaces each needed a different shape.
-// command: runs a shell command; its exit code is the verdict.
-// instruct: says something to the assistant before it finishes.
-// verdict: allows or holds what is about to happen (a pass with nothing to run, told which way to go).
-// builtin: invokes a named daemon behaviour the table has no business expressing itself.
-// Each reads a record only the daemon keeps, which is what makes it a built-in rather than a command.
-// verify-edits: what a turn edited, against what it ran.
-// verify-removals: what a turn deleted, against the repo's own history (a `git log` question, not a shell one-liner).
+// command: a repository's check; its exit code is the verdict.
+// verdict: allows or holds what is about to happen.
+// builtin: a daemon behaviour that reads a record only the daemon keeps.
 // verify-ui-edits: rendered surfaces a turn changed, against whether it ever looked at one.
-// verify-tests: whether a touched test's assertions got weaker than at HEAD, or would have passed before its own
-// change.
 // version-landed: commits what a land brought, in the main tree, under the subject drafted for it, and the tree's own
 // remainder before the next isolated turn starts; the only way a person who never commits keeps every agent seeing
 // the latest tree, since worktrees are cut from HEAD.
-export const RuleBuiltinSchema = z.enum(["verify-edits", "verify-removals", "verify-ui-edits", "verify-tests", "version-landed"]);
+export const RuleBuiltinSchema = z.enum(["verify-ui-edits", "version-landed"]);
 export type RuleBuiltin = z.infer<typeof RuleBuiltinSchema>;
 export const RuleActionSchema = z.discriminatedUnion("kind", [
     z.object({
@@ -54,7 +43,6 @@ export const RuleActionSchema = z.discriminatedUnion("kind", [
         // Past this, the process group is killed and the run is `failed`, never a silent pass.
         timeoutMs: z.number().min(60_000).max(3_600_000).default(900_000),
     }),
-    z.object({ kind: z.literal("instruct"), text: z.string().min(1).max(4000) }),
     z.object({ kind: z.literal("verdict"), verdict: z.enum(["allow", "hold"]) }),
     z.object({ kind: z.literal("builtin"), name: RuleBuiltinSchema }),
 ]);
@@ -63,8 +51,7 @@ export type RuleAction = z.infer<typeof RuleActionSchema>;
 // defaults to HELD unless a rule explicitly allows it.
 export const RuleOutcomeSchema = z.enum(["clean", "error", "conflict", "checks-failed"]);
 export type RuleOutcome = z.infer<typeof RuleOutcomeSchema>;
-// Three keys covering "only this repo" and "skip docs-only changes" without a query language; every key absent means
-// the rule always matches.
+// Every key absent means the rule always matches.
 export const RuleConditionSchema = z.object({
     // A workspace repo id, or "root". Absent ⇒ any.
     repo: z.string().min(1).optional(),
@@ -80,15 +67,13 @@ export type RuleCondition = z.infer<typeof RuleConditionSchema>;
 // validated here, not left to the consumer — the alternative is a rule that saves cleanly and silently does nothing.
 const MOMENT_ACTIONS: Record<RuleMoment, readonly RuleAction["kind"][]> = {
     "file.edited": ["command"],
-    "turn.ending": ["builtin", "instruct", "command"],
-    "push.starting": ["command"],
+    "turn.ending": ["builtin", "command"],
     "agent.finished": ["verdict"],
     "agent.landed": ["builtin"],
 };
-// A built-in reads a record only one moment keeps, so it stands at that moment alone: the verifiers read a turn's
-// ledgers, the versioner reads a landing's claim.
+// A built-in reads a record only one moment keeps, so it stands at that moment alone.
 const MOMENT_BUILTINS: Partial<Record<RuleMoment, readonly RuleBuiltin[]>> = {
-    "turn.ending": ["verify-edits", "verify-removals", "verify-ui-edits", "verify-tests"],
+    "turn.ending": ["verify-ui-edits"],
     "agent.landed": ["version-landed"],
 };
 export const RuleSchema = z
@@ -254,6 +239,21 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Your own instructions, used only when the mode above says custom. Then it is the whole of them: both built-in bases go, and so does everything this product would otherwise add, including the guidance the chat's own cards are driven by. That is the price of total control.",
         ),
+    // Measured by the `guidance` experiment against the full set; the full set stays the default until that says otherwise.
+    leanGuidance: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Send this product's own guidance in its short form: only what the agent cannot find out by looking, instead of a paragraph for every habit it was once caught in. Off by default, because the long form is the one the product was tuned on.",
+        ),
+    leanGuidanceHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe(
+            "What share of conversations to keep on the long form, so the two can be compared. Whole conversations rather than individual turns, because the guidance sits in the prompt for the whole session.",
+        ),
     iqSearch: z
         .boolean()
         .default(false)
@@ -414,14 +414,17 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Which repositories may run the checks they declare for themselves, and exactly which version of those checks you agreed to. A repository's declaration does nothing until it appears here, the same rule git keeps for hooks, which are never cloned; and a declaration that changes afterwards is held until you look at it again.",
         ),
-    // Lives in the owner's own settings, not the workspace: a rule can hold work and gate a push, so it answers to the
-    // sandbox owner alone. A repository may declare a COMMAND of its own (see `adoptedChecks`), never a verdict.
+    // The owner's alone, since a rule can hold work. A command is refused here: it belongs to the repository it checks,
+    // in that repository's `.intentic/checks.json`, never in settings.
     rules: z
         .array(RuleSchema)
         .max(50)
         .default([])
+        .refine((rules) => rules.every((rule) => rule.action.kind !== "command"), {
+            message: "a command belongs in the repository's own .intentic/checks.json, not in settings",
+        })
         .describe(
-            "Standing instructions you give the sandbox about its own work: ask for proof before a turn ends, run something before a push, hold or release finished work. Empty is the default and is exactly the behaviour of a fresh sandbox, because each of those defaults is what no rule matched means at its own moment.",
+            "Standing decisions about the sandbox's own work: land or hold finished work, save a version of what landed, ask the assistant to look at an interface it changed. Empty is the default and is exactly the behaviour of a fresh sandbox, because each of those defaults is what no rule matched means at its own moment. A command to run is a repository's own check, declared in its .intentic/checks.json.",
         ),
     automationFailureLimit: z
         .number()
@@ -578,6 +581,7 @@ export const SavingsReportSchema = z.object({
     // Same absence rule as `search`: not measured, never zero.
     map: TurnExperimentSchema.optional(),
     notes: TurnExperimentSchema.optional(),
+    guidance: TurnExperimentSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 
@@ -592,27 +596,23 @@ export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 // spelling for the daemon that reads it, the screen that names it and the demo that mimics it.
 export const REPO_CHECKS_FILE = `${STATE_DIR}/checks.json`;
 
-// Named for the occasion as a repository would say it, not for the daemon's wire moment: `edit` is `file.edited`,
-// `turn` is `turn.ending` and `push` is `push.starting` (rules/repo-checks.ts maps them). Three, because these are the
-// occasions whose command a repository actually owns; a verdict moment has nothing here to express.
-//
-// `edit` is the cheapest of the three and the only one that reaches the model while it still holds the line it wrote:
-// the command runs on that one file (`{file}`), and its output rides back in the edit's own response. A repository
-// that declares a whole-tree command here pays it per edit, so the command has to take the file.
-export const RepoCheckMomentSchema = z.enum(["edit", "turn", "push"]);
+// Named for the occasion as a repository would say it: `edit` is `file.edited`, `turn` is `turn.ending`, and `land` is
+// the daemon's run over the main tree after an install a land caused (rules/repo-checks.ts maps them). A push is gated by
+// the repository's own git pre-push hook, which every push runs, the app's included.
+// `edit` runs on one file (`{file}`) and its output rides back in the edit's own response, so a command declared there is
+// paid per edit and has to take the file.
+export const RepoCheckMomentSchema = z.enum(["edit", "turn", "land"]);
 export type RepoCheckMoment = z.infer<typeof RepoCheckMomentSchema>;
 
 export const RepoCheckSchema = z.object({
     when: RepoCheckMomentSchema.describe(
-        "When to run it: `edit` on each file as it is written (`{file}` is its path), `turn` before the assistant finishes, `push` before code leaves the machine.",
+        "When to run it: `edit` on each file as it is written (`{file}` is its path), `turn` before the assistant finishes, `land` on the main tree after finished work lands (absent, the package's own verify or test script runs there).",
     ),
     run: z.string().min(1).max(500).describe("The command, run in this repository's own directory, so it reads as it would in a terminal there."),
     label: z.string().min(1).max(80).optional().describe("What to call it on screen. Absent names it after the command."),
-    // Same ceiling as a rule's own command; past it the process group is killed and the run is a failure, never a
-    // silent pass.
+    // Same ceiling as a rule's own command; past it the process group is killed and the run is a failure.
     timeoutMs: z.number().min(60_000).max(3_600_000).optional().describe("How long it may take before it is killed and counted as failed."),
-    // Repo-relative, as anybody reading this file would write them; the daemon prefixes the repo id before matching,
-    // since a rule's globs are workspace-relative.
+    // Repo-relative; the daemon prefixes the repo id before matching, since a rule's globs are workspace-relative.
     paths: z
         .array(z.string().min(1))
         .max(20)
@@ -622,7 +622,16 @@ export const RepoCheckSchema = z.object({
 export type RepoCheck = z.infer<typeof RepoCheckSchema>;
 
 // The file itself. One key, so a second concern can be added later without breaking a file anyone has written.
-export const RepoChecksFileSchema = z.object({ checks: z.array(RepoCheckSchema).max(10).default([]) });
+export const RepoChecksFileSchema = z.object({
+    checks: z
+        .array(RepoCheckSchema)
+        .max(10)
+        .default([])
+        // One land check per repository: it is THE verdict on the main tree the push hook replays, not one of several.
+        .refine((checks) => checks.filter((check) => check.when === "land").length <= 1, { message: "a repository declares at most one land check" })
+        // A land checks the whole tree an install settled, not a change, so there is nothing for a glob to narrow.
+        .refine((checks) => checks.every((check) => check.when !== "land" || check.paths === undefined), { message: "a land check takes no paths" }),
+});
 export type RepoChecksFile = z.infer<typeof RepoChecksFileSchema>;
 
 // One repository, as a screen reads it: what it declares, and where that stands with the owner.
@@ -630,6 +639,11 @@ export const RepoChecksSummarySchema = z.object({
     repo: z.string().describe('Which repository, by its workspace id ("root" is the workspace itself).'),
     path: z.string().describe("Where the declaration lives, relative to the workspace, whether or not the file exists yet."),
     checks: z.array(RepoCheckSchema).describe("What it declares, in the order the file lists them."),
+    fired: z
+        .array(z.number().nullable())
+        .describe(
+            "When each declared check last reported something, in the file's order, as epoch milliseconds; null for one that never has, or for the land check, whose verdict the activity feed records instead.",
+        ),
     adopted: z
         .boolean()
         .describe("Whether these are running. False means declared and inert: nothing a repository writes runs until the owner switches it on."),
@@ -639,10 +653,16 @@ export const RepoChecksSummarySchema = z.object({
             "Whether the declaration changed since it was adopted, which holds it until the owner looks again. True only for a repository that was adopted before.",
         ),
     error: z.string().optional().describe("Why the file could not be read, when it exists but does not parse. The checks list is empty in that case."),
+    landDefault: z
+        .string()
+        .optional()
+        .describe(
+            "What runs on the main tree after a land when the file declares no `land` check: the package's own verify or test script. Absent when the repository has neither.",
+        ),
 });
 export type RepoChecksSummary = z.infer<typeof RepoChecksSummarySchema>;
 export const RepoChecksListSchema = z.object({
-    repos: z.array(RepoChecksSummarySchema).describe("Every repository that declares checks, plus any the owner has adopted before, sorted by id."),
+    repos: z.array(RepoChecksSummarySchema).describe("Every repository that declares checks or has a package check that runs after a land, in id order."),
 });
 export type RepoChecksList = z.infer<typeof RepoChecksListSchema>;
 export const RepoChecksAdoptSchema = z.object({

package/src/schemas/turn-break.ts

@@ -47,3 +47,11 @@ export const RETRY_LADDER_TRIES = RETRY_LADDER_MS.length;
 
 /** The wait before the next rung, or undefined once the ladder is spent. */
 export const retryLadderDelay = (triesWithoutProgress: number): number | undefined => RETRY_LADDER_MS[triesWithoutProgress];
+
+// Where an automatic re-run ladder stands, whichever wall climbs it (an outage's breaker, a stopped turn's rungs).
+// `made` equal to `max` is a spent ladder: nothing more goes unasked.
+export const RetryLadderSchema = z.object({
+    made: z.number().int().min(0).describe("Automatic re-runs already sent for this turn."),
+    max: z.number().int().min(1).describe("How many the ladder may send before it stands down."),
+});
+export type RetryLadder = z.infer<typeof RetryLadderSchema>;

package/src/schemas/version-seam.test.ts

@@ -1,4 +1,3 @@
-import { test, expect } from "bun:test";
 import { CapabilitiesListSchema } from "./capabilities.js";
 import { SandboxSettingsSchema } from "./settings.js";
 import { SmbNetdiskConfigSchema } from "./netdisk.js";

package/src/state/contract-lock.test.ts

@@ -1,7 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { packageRoot } from "@intentic/constants/node";
-import { test, expect } from "bun:test";
 import { currentLock } from "./contract-lock.js";
 
 // contract.lock.json must match the exported schemas; the git-aware half of this check lives in contract-shrink.mjs.

package/src/state/fix-attempt-plan.test.ts

@@ -1,4 +1,3 @@
-import { test, expect } from "bun:test";
 import { ciFixConversationId, fixAttemptId } from "../ids/conversation-ids.js";
 import type { AgentSummary } from "../schemas/agents.js";
 import { planFixAttempt } from "./fix-attempt-plan.js";

package/src/state/fix-stance.test.ts

@@ -1,4 +1,3 @@
-import { test, expect } from "bun:test";
 import { fixStance } from "./fix-stance.js";
 import type { AgentSummary } from "../schemas/agents.js";
 

package/src/state/history-state.ts

@@ -113,5 +113,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "runner-pair-consumed.json", portability: "identity" },
     // This container's own identity and reconnect token; elsewhere it would dial the parent as this runner.
     { path: "runner-identity.json", portability: "identity" },
+    // The owner's yes to a workspace's hooks, pinned to their bytes: a trust decision the target's owner makes again.
+    { path: "hook-approvals.json", portability: "identity", note: "Approve the workspace's Claude Code hooks again from Approvals." },
+    // The hook sets waiting for that yes; the next turn that finds them lists them again.
+    { path: "hook-requests.json", portability: "derived" },
+    // The owner's yes to each workspace extension's declared powers, decided again by the target's owner.
+    { path: "extension-approvals.json", portability: "identity", note: "Approve the extensions written in this workspace again from Extensions." },
     { path: "local-cert/", portability: "identity" },
 ];

package/src/state/landed-commit.test.ts

@@ -1,4 +1,3 @@
-import { expect, test } from "bun:test";
 import { declaredTestNote, landedCommitMessage } from "./landed-commit.js";
 
 // The push gate reads a weakening's declaration off the commit (assertion-ratchet.mjs), so the trailer must survive

package/src/state/runtime-state.test.ts

@@ -1,4 +1,3 @@
-import { describe, it, expect } from "bun:test";
 import { RUNTIME_DOMAIN_BINDINGS, staleRuntimeQueryKeys } from "./runtime-state.js";
 
 describe(`staleRuntimeQueryKeys`, () => {

package/src/state/versions.test.ts

@@ -1,4 +1,3 @@
-import { test, expect } from "bun:test";
 import { DEV_VERSION, isBehind, isNewer } from "./versions.js";
 
 test("isNewer compares dotted numeric versions", () => {