@intentic/sandbox-contract 1.310.0 → 1.312.0

package/src/schemas/settings.ts

@@ -13,13 +13,15 @@ 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". 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.
+// Rules: "at this moment, if this is true, do this". The owner's rules decide (land, hold, version); 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. Nothing verifies inside a turn: the whole-tree check runs after work lands and never
+// holds anything (schemas/workspace/mainline.ts).
 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.
+    // Retired: the assistant stopping. Nothing runs here any more and nothing sends a turn back to work; the value stays
+    // so settings written before it went still read, and a rule standing here is inert.
     "turn.ending",
     // An agent's turn is over and its delta is sitting on its branch. A rule here decides whether it lands.
     "agent.finished",
@@ -30,7 +32,8 @@ export type RuleMoment = z.infer<typeof RuleMomentSchema>;
 // 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-ui-edits: retired with `turn.ending`, read only so older settings parse; whether a turn looked at the surfaces it
+// changed is recorded on its card instead (AgentSummary.proof), never asked of the model.
 // 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.
@@ -47,8 +50,8 @@ export const RuleActionSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("builtin"), name: RuleBuiltinSchema }),
 ]);
 export type RuleAction = z.infer<typeof RuleActionSchema>;
-// `checks-failed` is a clean turn whose `turn.ending` check went red on the tree about to land; unlike the others, it
-// defaults to HELD unless a rule explicitly allows it.
+// `checks-failed` was a clean turn whose `turn.ending` check went red. Nothing produces it now that no check runs inside a
+// turn, and a check never holds work; it stays so older rules naming it still read.
 export const RuleOutcomeSchema = z.enum(["clean", "error", "conflict", "checks-failed"]);
 export type RuleOutcome = z.infer<typeof RuleOutcomeSchema>;
 // Every key absent means the rule always matches.
@@ -57,9 +60,10 @@ export const RuleConditionSchema = z.object({
     repo: z.string().min(1).optional(),
     // Globs the change has to touch for the rule to fire. Absent/empty ⇒ any.
     paths: z.array(z.string().min(1)).max(20).optional(),
-    // How the turn ended. Absent/empty ⇒ any, except that `checks-failed` never lands by omission.
+    // How the turn ended. Absent/empty ⇒ any.
     outcome: z.array(RuleOutcomeSchema).optional(),
-    // The fraction of occasions a rule fires on, at moments that draw one (turn.ending); absent ⇒ every occasion.
+    // The fraction of occasions a rule fires on, at a moment that draws one; absent ⇒ every occasion. No moment draws
+    // now that `turn.ending` is retired, so a sampled rule fires every time.
     sample: z.number().gt(0).lt(1).optional(),
 });
 export type RuleCondition = z.infer<typeof RuleConditionSchema>;
@@ -182,7 +186,8 @@ export type SkillSwitch = z.infer<typeof SkillSwitchSchema>;
 // Opt-in settings the /settings routes edit and streamAgent reads, defaulting off so each can be A/B tested (`skills`
 // defaults on for the baked tools worth having, since a skill file is the only thing that tells the agent a baked
 // binary exists). Every default lives in the schema, so an older settings file still parses and keeps the owner's other
-// picks rather than failing whole.
+// picks rather than failing whole. A setting removed or reshaped here gets its conversion in settings-history.ts, which
+// also names every retired setting, none of whose names may come back.
 
 export const SandboxSettingsSchema = z.object({
     // The zone every WALL-CLOCK RULE in this sandbox is meant in — an automation's cron, and anything else that says
@@ -387,16 +392,62 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "When a spent usage limit moves a turn to another account, carry the provider session (the model keeps everything, and re-reads all of it once on the other account) while the conversation's context is under this many tokens; at or above it, start a fresh session with the sandbox's measured brief instead. Zero always starts fresh.",
         ),
+    // Off by default: every refresh spends the account's own allowance on a conversation nobody is using yet.
+    keepWarm: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Keep a Claude conversation's prompt cache warm after each turn a person asked for, so coming back to it hours later costs a cache read instead of re-sending everything. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation. Any one conversation can be kept warm or let cool by hand either way.",
+        ),
+    keepWarmHours: z
+        .number()
+        .min(1)
+        .max(8)
+        .default(4)
+        .describe(
+            "How long an idle conversation is kept warm after its last turn, in hours. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
+        ),
+    keepWarmMinTokens: z
+        .number()
+        .int()
+        .min(0)
+        .default(100_000)
+        .describe("Only conversations at least this large, in tokens, are kept warm by themselves: a small one is cheap to re-read anyway."),
+    keepWarmReserve: z
+        .number()
+        .int()
+        .min(0)
+        .max(90)
+        .default(15)
+        .describe(
+            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
+        ),
     // Worth it since the container is recreated on every update or environment approval — otherwise approving a
     // Dockerfile change costs the run that asked for it.
-    // What happens to breakage found after the work that caused it has left the turn: a land that turns the main tree's own
-    // check red is sent back to the conversation that landed it, and main's CI staying red on one failure gets a fix agent
-    // once pushes go quiet, with a fleet failure re-run instead. Off, both are only reported.
+    // What happens to breakage found after the work that caused it has left the turn. A land that turns the main tree's own
+    // check red waits for the lands queued behind it to be checked too, then goes back to the conversation that landed it
+    // while that one still has it in mind, or to a fresh conversation when nobody can be named or the one named has gone
+    // cold; main's CI staying red on one failure gets a fix agent once pushes go quiet, with a fleet failure re-run instead.
+    // Off, all of it is only reported.
     autoRepair: z
         .boolean()
         .default(true)
         .describe(
-            "Whether breakage found after the work left its turn is repaired without asking: a land that turns the main tree's check red goes back to the conversation that landed it, and main's CI staying red on the same failure gets a fix agent once pushes go quiet. A failure on the CI fleet itself is re-run once instead. Off, both are only reported.",
+            "Whether breakage found after the work left its turn is repaired without asking. A land that turns the main tree's check red is repaired once the work queued behind it has been checked too: by the conversation that landed it while it still has the work in mind, otherwise by a fresh conversation handed the failures and the suspects' changes. Main's CI staying red on the same failure gets a fix agent once pushes go quiet, and a failure on the CI fleet itself is re-run once instead. Off, all of it is only reported.",
+        ),
+    // Where heavy work runs: a runner (the same image, on one of the owner's machines) instead of this sandbox. Keyed by
+    // the heavy-command rule an agent's command matched (platform/resources/heavy-commands.ts), and one entry for the
+    // check after landing, each naming a runner id. A runner that is offline, outdated or full hands the work back here,
+    // which the command's output says. Never pushed to a runner itself (portability/definition.ts), which must not pass
+    // work on again.
+    offload: z
+        .object({
+            commands: z.record(z.string().min(1), z.string().min(1)).default({}),
+            landCheck: z.string().min(1).optional(),
+        })
+        .default({ commands: {} })
+        .describe(
+            "Which heavy work runs on a runner on one of your machines instead of this sandbox: agents' commands by the kind the heavy-command rules sort them into (tests, typechecks, verify…), and the check after landing. The code travels as it stands, uncommitted work included; the output streams back, and any file the command changed comes back with it. A machine that is offline, outdated or busy hands the work back to this sandbox, and the output says so.",
         ),
     autoResumeOnRestart: z
         .boolean()
@@ -424,7 +475,7 @@ export const SandboxSettingsSchema = z.object({
             message: "a command belongs in the repository's own .intentic/checks.json, not in settings",
         })
         .describe(
-            "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.",
+            "Standing decisions about the sandbox's own work: land or hold finished work, save a version of what landed. 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()
@@ -596,9 +647,9 @@ 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: `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.
+// Named for the occasion as a repository would say it: `edit` is `file.edited`, and `land` is the daemon's run over the
+// main tree after every land (rules/repo-checks.ts maps them). `turn` is retired: nothing runs when a turn ends any more,
+// and a declaration naming it still reads but runs nothing. No check refuses a land, a commit or a push.
 // `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"]);
@@ -606,7 +657,7 @@ 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, `land` on the main tree after finished work lands (absent, the package's own verify or test script runs there).",
+        "When to run it: `edit` on each file as it is written (`{file}` is its path), `land` on the main tree after finished work lands (absent, the package's own verify or test script runs there). `turn` is retired and runs nothing: checks no longer run while a conversation works.",
     ),
     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."),

package/src/schemas/system.ts

@@ -27,6 +27,23 @@ export const StagedUpdateSchema = z.object({
         ),
     // Epoch ms the download finished; used to check this is still the update being offered.
     at: z.number().describe("When the download finished, in milliseconds, which answers whether this is still the update being offered."),
+    // The staged build's state pre-flight (the daemon's state-plan.ts, run by `ic sandbox prepare` over read-only mounts
+    // of this sandbox's volumes): what its first boot converts, before anyone accepts the update.
+    plan: z
+        .object({
+            ok: z.boolean().describe("False when a conversion would fail on this sandbox's files, which refuses the update before anything is touched."),
+            downgrade: z.boolean().optional().describe("The staged build is older than the one that converted these files; it opens them read-only."),
+            steps: z
+                .array(z.object({ document: z.string(), change: z.string() }))
+                .optional()
+                .describe("Each stored file the first boot converts, and how."),
+            failures: z
+                .array(z.object({ document: z.string(), detail: z.string() }))
+                .optional()
+                .describe("Each conversion that would fail, and why."),
+        })
+        .optional()
+        .describe("What the downloaded build's first boot would convert in this sandbox's stored files. Absent when no plan could be had, which says nothing either way."),
 });
 export type StagedUpdate = z.infer<typeof StagedUpdateSchema>;
 export const InfoSchema = z.object({

package/src/schemas/workspace/mainline.ts

@@ -0,0 +1,201 @@
+// main-line checks: the whole-tree check the daemon runs after work lands, and what became of what it found
+import { z } from "zod";
+import { pushFixConversationId } from "../../ids/conversation-ids.js";
+import { AgentRunPickSchema } from "../agent.js";
+
+// Nothing is verified inside a conversation any more: a turn ends when the model says it is done, its work lands, and
+// the main tree's own check runs afterwards, off everyone's clock, one project at a time. This is that check as the
+// editor reads it: what is being measured, what is waiting, what the last run said, and who is working on a red one.
+
+export const MainlineLandSchema = z.object({
+    conversationId: z.string().describe("The conversation whose work landed."),
+    title: z.string().optional().describe("Its title when it landed."),
+    at: z.number().describe("When the land asked for the check, in milliseconds."),
+});
+export type MainlineLand = z.infer<typeof MainlineLandSchema>;
+
+// What happened to a red verdict's failures, decided once the lands behind it had their own check.
+export const MainlineRoutingKindSchema = z.enum([
+    // More work landed while this ran; the check that measures it decides, so nobody is sent after a failure it may fix.
+    "waiting",
+    // A conversation still working touches what failed; nobody else is started until it stops.
+    "held",
+    // Sent back to the conversation that landed it, which still had the work in mind.
+    "original",
+    // A fresh conversation was started on it with the failures, the suspects' changes and where to read their sessions.
+    "fix-up",
+    // Nobody was sent: repairs are switched off, or no conversation could take it. An automation may.
+    "reported",
+    // Gone at the next check, before anybody was sent.
+    "resolved",
+    // The sends and fresh attempts a red streak allows are used up; it waits for a person.
+    "spent",
+]);
+export type MainlineRoutingKind = z.infer<typeof MainlineRoutingKindSchema>;
+
+export const MainlineRoutingSchema = z.object({
+    kind: MainlineRoutingKindSchema.describe("What became of the failures."),
+    conversationId: z
+        .string()
+        .optional()
+        .describe("The conversation working on them (the original or a fresh one), or the one still working that the repair waits for."),
+    at: z.number().describe("When that was decided, in milliseconds."),
+    detail: z.string().optional().describe("One sentence on why, in the sandbox's words."),
+});
+export type MainlineRouting = z.infer<typeof MainlineRoutingSchema>;
+
+// The first failures a run names; the whole list stays in its terminal.
+export const MAINLINE_FAILURES_KEPT = 30;
+
+export const MainlineRunSchema = z.object({
+    project: z.string().describe("Which project, by folder relative to the workspace. Empty is the workspace root."),
+    command: z.string().describe("What ran."),
+    status: z.enum(["green", "red"]).describe("How it ended."),
+    startedAt: z.number().describe("When it started, in milliseconds."),
+    at: z.number().describe("When it ended, in milliseconds."),
+    lands: z.array(MainlineLandSchema).describe("The lands it answered for, oldest first. Empty for a run no land asked for."),
+    failures: z.array(z.string()).describe(`The first failures it named, at most ${MAINLINE_FAILURES_KEPT}.`),
+    failureCount: z.number().describe("How many failures it named in all. Zero on a red run that wrote no list."),
+    attempt: z.number().describe("How many red runs in a row this is for the project; zero when green."),
+    suspects: z
+        .array(z.string())
+        .optional()
+        .describe("The conversations whose lands these failures were laid at, when any could be named."),
+    routing: MainlineRoutingSchema.optional().describe("What became of a red run's failures. Absent on green, and until it is decided."),
+});
+export type MainlineRun = z.infer<typeof MainlineRunSchema>;
+
+export const MainlineProjectSchema = z.object({
+    project: z.string().describe("Which project, by folder relative to the workspace. Empty is the workspace root."),
+    running: z
+        .object({
+            command: z.string().describe("What is running."),
+            startedAt: z.number().describe("When it started, in milliseconds."),
+            lands: z.array(MainlineLandSchema).describe("The lands it answers for."),
+            on: z.string().optional().describe("The runner it was sent to, on one of your machines. Absent when it runs in this sandbox."),
+        })
+        .optional()
+        .describe("The check running on it now, if any."),
+    queued: z.array(MainlineLandSchema).describe("Lands waiting for the next check, which will measure them together."),
+    last: MainlineRunSchema.optional().describe("Its most recent settled check."),
+    redSince: z.number().optional().describe("When its checks went red and stayed so, in milliseconds. Absent while green."),
+});
+export type MainlineProject = z.infer<typeof MainlineProjectSchema>;
+
+
+// WHAT A PUSH LEFT BEHIND. The pre-push hook never refuses (verify-push.mjs, `--advisory`): it measures, reports, and the
+// push goes. What it found used to vanish with the terminal it printed to. It now leaves a report in the repository's
+// git dir, the daemon files it here once the push has actually reached the remote, and each finding waits until a later
+// measurement no longer prints it or somebody dismisses it. Nobody is sent after one: acting on it is the owner's call.
+
+// What measured a finding: one of the repository's checks (by id), the linter, the assertion ratchet, the
+// manifest/lockfile lockstep, or rustfmt. Only a check's or the linter's finding can be measured again; the other three
+// are about the pushed commits themselves, so they end only when dismissed.
+export const PushFindingKindSchema = z.enum(["check", "lint", "ratchet", "lockstep", "rustfmt"]);
+export type PushFindingKind = z.infer<typeof PushFindingKindSchema>;
+
+export const PushFindingStateSchema = z.enum([
+    // Still printed at the last measurement, and nobody has dismissed it.
+    "open",
+    // A later push, recheck or land check measured it and it was gone.
+    "resolved",
+    // Somebody decided it will not be fixed.
+    "dismissed",
+]);
+export type PushFindingState = z.infer<typeof PushFindingStateSchema>;
+
+export const PushFindingSchema = z.object({
+    id: z.string().describe("Stable across pushes: the same problem found again is the same id."),
+    kind: PushFindingKindSchema.describe("What measured it."),
+    check: z.string().optional().describe("The check's own id, for a check's finding."),
+    gate: z
+        .enum(["code", "tidy"])
+        .optional()
+        .describe("For a check's finding: `code` means the tree fails the check whoever caused it; `tidy` means the push added this line."),
+    text: z.string().describe("The finding as the check printed it."),
+    command: z.string().optional().describe("The command that shows it again."),
+    commit: z
+        .object({ sha: z.string(), subject: z.string() })
+        .optional()
+        .describe("The newest pushed commit that touched the path the finding names, when it names one."),
+    state: PushFindingStateSchema,
+    settledAt: z.number().optional().describe("When it was resolved or dismissed, in milliseconds."),
+});
+export type PushFinding = z.infer<typeof PushFindingSchema>;
+
+export const MainlinePushSchema = z.object({
+    project: z.string().describe("Which project, by folder relative to the workspace. Empty is the workspace root."),
+    id: z.string().describe("The report's own id."),
+    at: z.number().describe("When the push check ran, in milliseconds."),
+    remote: z.string().optional().describe("The remote it was pushed to."),
+    branch: z.string().optional().describe("The branch it was pushed to."),
+    base: z.string().optional().describe("The commit the pushed range starts from; absent when the remote had nothing to compare with."),
+    head: z.string().describe("The commit that was pushed."),
+    commits: z.number().describe("How many commits the push carried."),
+    findings: z.array(PushFindingSchema).describe("What it found that this push brought in, open or not. Empty for a clean push."),
+    measuredAt: z.number().optional().describe("When its findings were last measured again, in milliseconds."),
+});
+export type MainlinePush = z.infer<typeof MainlinePushSchema>;
+
+export const MainlineStatusSchema = z.object({
+    projects: z.array(MainlineProjectSchema).describe("Every project a land has been checked in, or is waiting to be."),
+    recent: z.array(MainlineRunSchema).describe("The latest settled checks across every project, newest first."),
+    pushes: z
+        .array(MainlinePushSchema)
+        .optional()
+        .describe("The latest push checks across every project, newest first, with what each left behind. Absent from a daemon that records none."),
+});
+export type MainlineStatus = z.infer<typeof MainlineStatusSchema>;
+
+export const MainlinePushDismissSchema = z.object({
+    project: z.string().describe("Which project, by folder relative to the workspace."),
+    ids: z.array(z.string()).optional().describe("Which findings. Leave it out for every open one in the project."),
+    restore: z.boolean().optional().describe("Undo: open the named dismissed findings again."),
+});
+export type MainlinePushDismiss = z.infer<typeof MainlinePushDismissSchema>;
+
+export const MainlinePushDismissResultSchema = z.object({
+    changed: z.number().describe("How many findings changed state."),
+});
+
+export const MainlinePushRecheckSchema = z.object({
+    project: z.string().describe("Which project, by folder relative to the workspace."),
+});
+
+export const MainlinePushRecheckResultSchema = z.object({
+    measured: z.boolean().describe("Whether the project could be measured at all; false leaves every finding as it was."),
+    resolved: z.number().describe("How many findings the measurement no longer saw."),
+    open: z.number().describe("How many are still open."),
+});
+export type MainlinePushRecheckResult = z.infer<typeof MainlinePushRecheckResultSchema>;
+
+export const MainlinePushFixSchema = z.object({
+    project: z.string().describe("Which project's open push findings to hand over, by folder relative to the workspace."),
+    pick: AgentRunPickSchema.describe(
+        "Which model to open the conversation on, when somebody chose one. Leave it out for the sandbox's own choice.",
+    ),
+    mode: z
+        .enum(["continue", "start-over"])
+        .optional()
+        .describe(
+            "What to do about an attempt already made at these findings: `continue` carries on in it, `start-over` files it away and opens the next attempt. Leave it out for the plain press.",
+        ),
+});
+export type MainlinePushFix = z.infer<typeof MainlinePushFixSchema>;
+
+export const MainlinePushFixResultSchema = z.object({
+    conversationId: z.string().describe("The conversation holding the findings. Open it to watch."),
+});
+
+// The oldest push in `project` that still has an open finding: what a hand-over is keyed by, so pressing again while
+// any of its findings stand continues the same attempt, and a backlog that starts after everything was handled starts
+// a fresh one.
+export const oldestOpenPush = (pushes: readonly MainlinePush[], project: string): MainlinePush | undefined =>
+    pushes.findLast((push) => push.project === project && push.findings.some((finding) => finding.state === "open"));
+
+// The conversation id a hand-over of `project`'s open push findings wears (attempt 1), derived so the editor and the
+// daemon agree on whether an agent is already on them; undefined when nothing is open.
+export const pushFindingsFixBase = (pushes: readonly MainlinePush[], project: string): string | undefined => {
+    const oldest = oldestOpenPush(pushes, project);
+    return oldest === undefined ? undefined : pushFixConversationId(project === "" ? "workspace" : project, `left:${oldest.head}`);
+};

package/src/schemas/workspace/workspace-tree.ts

@@ -72,8 +72,33 @@ export const WorkspaceTreeSchema = z.object({
         .describe(
             "Folders whose whole contents are empty folders, and nothing else. Complete for the workspace, however much of the tree above was listed, and ordered like the tree, so a parent comes before the branch below it.",
         ),
+    generation: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe(
+            "Which state of the shared tree this is; the changes that follow count from it. Absent for a conversation's own checkout, which is listed when asked and followed by no changes.",
+        ),
 });
 export type WorkspaceTree = z.infer<typeof WorkspaceTreeSchema>;
+// What moved in the shared tree between two generations: every folder whose own entries changed, parents first.
+export const WorkspaceTreeDeltaSchema = z.object({
+    from: z.number().int().nonnegative().describe("The generation this applies on top of. A reader holding any other fetches the tree afresh instead."),
+    generation: z.number().int().nonnegative().describe("The generation it leaves the tree at."),
+    dirs: z
+        .array(
+            z.object({
+                path: z.string().describe("The folder, as a workspace path; empty for the workspace root."),
+                entries: z
+                    .array(WorkspaceTreeEntrySchema)
+                    .describe("Its entries now, without their contents: a folder whose own entries also changed comes as an item of its own."),
+            }),
+        )
+        .describe("Each folder that changed, parents before the folders inside them."),
+    barren: z.array(z.string()).optional().describe("The barren folders now, present only when that list moved."),
+});
+export type WorkspaceTreeDelta = z.infer<typeof WorkspaceTreeDeltaSchema>;
 // Lazy-loads one directory's children past the tree walk's budget; depth reads several levels into one flat `entries`
 // list instead of one request per directory.
 export const WorkspaceChildrenQuerySchema = WorkspaceScopeSchema.extend({
@@ -253,6 +278,28 @@ export const WorkspaceExtractSchema = z.object({
         ),
 });
 export type WorkspaceExtract = z.infer<typeof WorkspaceExtractSchema>;
+// A delete moves the entry into the daemon's trash rather than erasing it, so the gesture can be taken back.
+export const WorkspaceDeletedSchema = z.object({
+    ok: z.literal(true).describe("Always true: the entry is gone from where it was, or was never there."),
+    trashed: z
+        .string()
+        .optional()
+        .describe(
+            "The trash id that brings it back through the restore call, for a day. Absent when there was nothing at that path to delete.",
+        ),
+});
+export type WorkspaceDeleted = z.infer<typeof WorkspaceDeletedSchema>;
+export const WorkspaceRestoreSchema = z.object({
+    trashed: z.string().min(1).describe("The trash id a delete answered with."),
+});
+export const WorkspaceRestoredSchema = z.object({
+    path: z
+        .string()
+        .describe(
+            "Where it came back, as a workspace path: where it was deleted from, or beside that under a `(restored)` name when something new has taken the name since.",
+        ),
+});
+export type WorkspaceRestored = z.infer<typeof WorkspaceRestoredSchema>;
 // Deterministic, no-LLM classification into coarse buckets, read-only, applied via /workspace/move. reason is the
 // winning signal: magic:<mime>, ext:<ext>, repository:<marker>, text-content, or unknown.
 export const WorkspaceBucketSchema = z.enum(["repositories", "documents", "media", "archives", "other"]);

package/src/state/definition.ts

@@ -48,9 +48,10 @@ const bareField = (field: z.ZodType): z.ZodType => {
     return inner;
 };
 
-const definitionSettings = (): z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>> => {
+// Typed as the prefault it is, so the static input type says what the runtime does: an absent table is accepted.
+const definitionSettings = (): z.ZodPrefault<z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>>> => {
     const shape = Object.fromEntries(Object.entries(SandboxSettingsSchema.shape).map(([key, field]) => [key, bareField(field).optional()]));
-    return z.strictObject(shape).prefault({}) as unknown as z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>>;
+    return z.strictObject(shape).prefault({}) as unknown as z.ZodPrefault<z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>>>;
 };
 
 export const SandboxDefinitionSchema = z.strictObject({

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

@@ -45,6 +45,20 @@ test("held work reads as a fix to review, whether the fleet called it ready or l
     expect(fixStance(agent({ status: `idle`, diff: { files: 4, insertions: 120, deletions: 8 } })).kind).toBe(`ready`);
 });
 
+test.each([
+    ["holding work", { files: 4, insertions: 120, deletions: 8 }],
+    ["holding nothing yet", undefined],
+] as const)("a turn that ended waiting on its own watch, %s, is still working", (_case, diff) => {
+    const watches = [{ id: `watch-a1b2`, note: `CI on the pushed branch`, intervalSeconds: 60, deadlineAt: 9_000 }];
+    expect(fixStance(agent({ status: `idle`, watches, ...(diff === undefined ? {} : { diff }) }))).toStrictEqual({
+        kind: `working`,
+        ongoing: true,
+        retry: false,
+        label: `Agent working`,
+        hint: `An agent is already working on this failure. Open the conversation to watch it.`,
+    });
+});
+
 // Diff present doesn't change a failed status to ready; it only earns a mention in the hint.
 test("an agent that failed after writing files still reads as failed", () => {
     const stance = fixStance(agent({ status: `error`, diff: { files: 2, insertions: 34, deletions: 6 } }));

package/src/state/fix-stance.ts

@@ -130,6 +130,8 @@ const RULES: readonly ((agent: AgentSummary) => FixStance | undefined)[] = [
             ? needsYou("Needs you", "The fix agent has stopped and is waiting on you.")
             : undefined,
     (agent) => (IN_FLIGHT.has(agent.status) ? WORKING : undefined),
+    // An armed watch wakes it again by itself, so neither what it holds nor holding nothing is its last word yet.
+    (agent) => ((agent.watches?.length ?? 0) > 0 ? WORKING : undefined),
     (agent) => (holdingWork(agent) ? READY : undefined),
     (agent) => (agent.status === "landed" ? LANDED : undefined),
 ];

package/src/state/history-state.ts

@@ -22,6 +22,9 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // conversation's own runtime session store (what `.intentic/records/sessions/claude/` holds for every other).
     // Carried whole, like the conversation it is.
     { path: "conversations/", portability: "carry" },
+    // The long tool outputs those transcripts name rather than hold, stored once by content for every record naming
+    // them; a transcript without them keeps only each output's start.
+    { path: "blobs/", portability: "carry" },
     // Index of published-page conversations; the pages travel with /work anyway, this makes one withdrawable.
     { path: "shares.json", portability: "carry" },
     { path: "activity.jsonl", portability: "carry" },
@@ -67,6 +70,8 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: ".isolation-probe", portability: "derived" },
     // Finished bundles, excluded so an export doesn't pack every prior export in; kept off /work, unwatched.
     { path: "exports/", portability: "derived" },
+    // Each transcript as it was before this format converted it, zstd-compressed: a local way back, never read here.
+    { path: "backups/", portability: "derived" },
     // Bundles being taken in, mid-review; excluded as someone else's. Deleted on apply/abandon, swept after a crash.
     { path: "arrivals/", portability: "derived" },
 
@@ -120,4 +125,14 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // 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" },
+
+    /* ---- the state engine's own bookkeeping (the daemon's store/evolution/state-journal.ts) ---- */
+
+    // Pre-images of the history files an update's conversions changed; `secret` since identity files are among them.
+    { path: "converting/", portability: "secret", note: "An update's undo record stays with the sandbox it happened on." },
+    // Which conversion episodes are open or recently committed, and earlier addresses awaiting removal.
+    { path: "state-journal.json", portability: "derived" },
+    // Every conversation the import of the pre-1.308 layout settled (the daemon's agents/registry/pre-1308-import.ts),
+    // so one deleted after its import is not brought back from the old files still on disk. About this volume only.
+    { path: "pre-1308-import.json", portability: "derived" },
 ];

package/src/state/runtime-state.ts

@@ -27,6 +27,10 @@ const RUNTIME_DOMAINS = [
     // The agent's Chromiums and open pages, daemon-held, minted from its own browser tool-call hooks.
     { domain: "browsers", invalidates: [["browsers"]] },
 
+    // A connection's status as its last probe found it: pushed when a probe behind a served answer finds another one, and
+    // when a browser sign-in is saved or cleared, which is what moves an account's card off "log in".
+    { domain: "capabilities", invalidates: [["capabilities"]] },
+
     // Daemon-held; changes continuously (tokens, tool uses), so it's rate-limited rather than pushed per mutation.
     { domain: "subagents", invalidates: [["subagents"]] },
 
@@ -54,6 +58,10 @@ const RUNTIME_DOMAINS = [
 
     // The audit log grew or a gateway's status moved or aged out; the log lives outside /work, so no file push carries it.
     { domain: "activity", invalidates: [["activity"], ["activity-status"]] },
+
+    // The main tree's own check after a land: queued, started, settled, or its red handed to somebody. Held in the
+    // daemon's memory as much as in a file, so a push is the only way a watcher hears it move.
+    { domain: "mainline", invalidates: [["mainline"]] },
 ] as const satisfies readonly RuntimeDomainBinding[];
 
 export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;

package/src/state/workspace-state.ts

@@ -267,6 +267,14 @@ const STATE_FILES = [
     // Per-extension update/advisory/health findings, written by the periodic check and by update/revert. Pushed live
     // so an auto-disabling advisory doesn't wait for a reload.
     { path: ".intentic/records/extension-updates.json", invalidates: ["extensions"], portability: "carry" },
+    // Every conversion an update ran over this workspace's files, newest last and capped (the daemon's
+    // state-convergence.ts). `carry`: what happened to the owner's files is their history, wherever it goes next.
+    {
+        path: ".intentic/records/conversions.json",
+        invalidates: [],
+        why: "Written once per update that converted something, at boot before any browser is connected; the update card reads the plan from the new image instead.",
+        portability: "carry",
+    },
     // Owner's per-extension update posture (notify/agent/auto, advisory opt-out). `carry`: a decision about the
     // extension, not the machine.
     { path: ".intentic/config/extension-update-policy.json", invalidates: ["extensions"], portability: "carry", versioned: true },
@@ -348,6 +356,14 @@ const STATE_FILES = [
         why: "Scratch that agents and tools leave behind (build logs, demo checkouts); nothing reads it after the turn that wrote it. The state janitor empties it at boot.",
         portability: "derived",
     },
+    // What the file view deleted, one folder per delete, kept so Undo can put it back. A day is longer than any undo
+    // stack lives in a browser tab; the hourly janitor sweep drops what's older.
+    {
+        path: ".intentic/local/trash/",
+        invalidates: [],
+        why: "Entries deleted from the file view, held for a day so Undo can restore them; nothing renders it, and the janitor expires it.",
+        portability: "derived",
+    },
     // Account for the pnpm store even though pnpm creates it, not the daemon.
     {
         path: ".intentic/local/.pnpm-store/",
@@ -366,7 +382,13 @@ const STATE_FILES = [
     {
         path: ".intentic/records/verify.json",
         invalidates: [],
-        why: "The dependency verifier's verdict memory; nothing renders it directly, outcomes reach the owner as activity entries and workspace events.",
+        why: "The main-line check's memory: each project's last verdict and red streak, and the latest runs with what became of each red one. Read through GET /workspace/mainline, which the daemon pushes itself (the `mainline` runtime domain), so no file watch is needed.",
+        portability: "carry",
+    },
+    {
+        path: ".intentic/records/push-checks.json",
+        invalidates: [],
+        why: "What each push check found and let through, per project, and what became of every finding: still open, measured gone, or dismissed. Filed from the report the pre-push hook leaves in the repository's git dir; read through GET /workspace/mainline, which the daemon pushes itself (the `mainline` runtime domain).",
         portability: "carry",
     },
     {
@@ -375,6 +397,16 @@ const STATE_FILES = [
         why: "A running check's wrapper artifacts (log + exit status), read once by the daemon when the panel finishes.",
         portability: "derived",
     },
+    // What an update converted before it booted all the way (the sandbox daemon's state-journal.ts): a copy of every
+    // file the new version changed, kept until it commits and for a grace window after. `secret` whatever the source
+    // was, since a vault's copy is a vault; locked below for the same reason.
+    {
+        path: ".intentic/secrets/converting/",
+        invalidates: [],
+        why: "Pre-images of the files an update's conversions changed; only the boot step reads them, to put a rolled-back version's files back.",
+        portability: "secret",
+        note: "An export does not carry an update's undo record; the target converts its own files.",
+    },
     {
         path: ".intentic/secrets/ci.json",
         invalidates: [],
@@ -588,6 +620,8 @@ export const LOCKED_STATE_ENTRIES: ReadonlySet<string> = new Set([
     "secrets/ci.json",
     "secrets/doors.json",
     "secrets/auth",
+    // An update's pre-images: copies of whatever it converted, vaults included.
+    "secrets/converting",
     "records/sessions",
     "local/browser",
     // The provider CLI's own home, undeclared in the table above and so without a group; stays at the state dir root.