@intentic/sandbox-contract 1.230.3 → 1.232.0

package/src/schemas.ts

@@ -3,6 +3,7 @@ import { ExtensionManifestSchema } from "@intentic/extension-manifest";
 import { RegistryEntrySchema } from "@intentic/registry";
 import { z } from "zod";
 import { OutputFieldsSchema } from "./output-fields.js";
+import { AgentPlacementSchema } from "./runner-protocol.js";
 
 // All request/response wire schemas for the sandbox daemon. Inputs that carry a `{param}` in their route path
 // (repo / id / name) merge the path param into the same flat object, oRPC fills the path placeholder from the
@@ -253,6 +254,13 @@ export const AgentTurnSchema = z
             .describe(
                 "Work in this conversation's own private copy of the repos rather than the shared tree, so several agents can work at once. Needs a conversation id.",
             ),
+        /* WHERE the conversation executes, decided like `isolated` directly above: the request's choice on the
+         * first turn, the registry entry's on every turn after. `runner` implies isolation (the branch is what
+         * moves between machines) and needs a conversation id for the same reason `isolated` does. Absent =
+         * local. Design: docs/remote-runners-plan.md; refused until runners ship. */
+        placement: AgentPlacementSchema.optional().describe(
+            "Where this conversation runs: this sandbox (leave it out), or a paired runner by id. Decided on the first turn; later turns follow the conversation.",
+        ),
         /* Pin a NEW isolated conversation's worktree composition to these repository commits. Daemon-owned:
          * ordinary chats omit it and keep rebasing onto the current workspace; a workflow supplies the one
          * snapshot all of its candidates must share. Repeated iterations carry it too, which suppresses the
@@ -1929,6 +1937,23 @@ export const SteerSchema = z
 // /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.") });
 
+/* RUN THE HELD TURN AGAIN, and it carries a conversation id and NOTHING else, which is the entire point of it
+ * existing as its own route rather than as a flag on a turn.
+ *
+ * A spent allowance leaves a turn stranded that the daemon still holds in full: the prompt, the attachments, the
+ * model, the effort, the mode, the worktree, the session that holds whatever it managed to do. Every one of
+ * those is on the turn the daemon already has, and a client that re-derived them from its own transcript would
+ * be re-deriving them from the STRIPPED copy it renders (no preamble notes, no attachment note, no model), which
+ * is how a re-send comes to run a different turn from the one it claims to repeat.
+ *
+ * So the caller says only WHICH conversation, and the daemon re-runs the turn it kept. What comes back is an
+ * ordinary StartedTurn, and the caller then attaches to it exactly as it would to a turn somebody else started
+ * (the resume note on the prompt is what tells an attaching window to reuse the bubble that is already there
+ * instead of drawing the same message twice). */
+export const ResumeTurnSchema = z.object({
+    conversationId: z.string().min(1).describe("Which conversation's held turn to run again."),
+});
+
 // ---- claude rate-limit gate ----
 // The GATE signal: whether the provider is letting turns through right now, and, when it is refusing, which
 // window is binding and when it lifts. This is the SDK's rate_limit_event, mapped one-to-one, and it is only
@@ -2778,7 +2803,13 @@ export const SandboxSettingsSchema = z.object({
      * `<provider>.<type>` ("discord.message.send") with `<provider>.*` as the per-provider wildcard; exact key
      * wins. An action with no rule is allowed, the empty default wires no hook at all, so an unconfigured
      * workspace pays nothing. "hold" cannot park a running turn (nobody may be there to answer); it refuses the
-     * live call and points the agent at the drafts outbox, which IS the held form of a send. */
+     * live call and points the agent at the drafts outbox, which IS the held form of a send.
+     *
+     * The CHILD-AGENT surface reads the same book: `agents.spawn` covers starting, steering and answering
+     * child agents on every provider, `agents.spawn.<provider>` singles one out (the specific key wins), and
+     * the daemon's own taint floor holds a spawn from a turn that has taken in outside content unless the
+     * owner wrote an explicit allow (guard/actions.ts childSpawn). "hold" refuses with the owner named, the
+     * same translation a send gets. */
     actionRules: z
         .record(z.string(), AdmissionRuleSchema)
         .default({})
@@ -3812,13 +3843,43 @@ export const SnapshotFileDiffQuerySchema = z.object({
     scope: z.string().min(1).describe("Which part of the workspace the path belongs to."),
     path: z.string().min(1).describe("The file, relative to that scope."),
 });
+/* WHAT A FILE TOO BIG TO SEND WHOLE ANSWERS WITH INSTEAD, and why that is not simply "no".
+ *
+ * Both whole sides of a half-megabyte file are a megabyte of JSON per click, so above the cap they are not
+ * sent, which used to be the end of it: the response said "too large" and every review surface printed one
+ * sentence over an empty pane. That is the wrong trade, because the thing a reader wants out of a big file is
+ * almost never the file: it is the handful of lines that MOVED, and those are small however big the file is.
+ *
+ * So the daemon diffs it and sends the CHANGED REGIONS as a unified patch, at the same three lines of context
+ * a collapsed region keeps elsewhere. A 40 KB patch stands in for a 60 MB pair, and the reader gets the actual
+ * review rather than a refusal. `patch` carries the `@@` sections only, the file headers git prints above them
+ * name rev-specs no one can apply anyway.
+ *
+ * An added or deleted file has no counterpart to diff against, so its patch IS the file, one region of pure
+ * +/− lines. That is still the right answer: cut to the budget, it is the head of the file, which is the peek
+ * the reader came for.
+ *
+ * `patch` is absent only when there was nothing to make one from: a change too large even to render as a
+ * patch, or a git that refused. The sizes are still there, so a surface can at least say how big the thing it
+ * is not showing is. */
+export const PartialFileDiffSchema = z.object({
+    beforeBytes: z.number().int().nonnegative().optional().describe("How big the before side is, in bytes. Absent when the file did not exist yet."),
+    afterBytes: z.number().int().nonnegative().optional().describe("How big the after side is, in bytes. Absent when the file was deleted."),
+    patch: z
+        .string()
+        .optional()
+        .describe("The changed regions as unified-diff hunks (`@@` sections only). Absent when the change was too large to render even as a patch."),
+    more: z.boolean().optional().describe("There were more changed regions than fit; the patch stops at a region boundary."),
+});
+export type PartialFileDiff = z.infer<typeof PartialFileDiffSchema>;
+
 // Both sides of a file diff, a snapshot vs its parent, or a working tree vs HEAD; an absent side means the
-// file was added/deleted. Binary or oversized content is flagged instead of shipped.
+// file was added/deleted. Binary content is flagged instead of shipped; oversized content arrives as `partial`.
 export const FileDiffSchema = z.object({
-    before: z.string().optional().describe("The whole file as it was. Absent when it did not exist yet."),
-    after: z.string().optional().describe("The whole file as it is now. Absent when it was deleted."),
+    before: z.string().optional().describe("The whole file as it was. Absent when it did not exist yet, or when `partial` is set."),
+    after: z.string().optional().describe("The whole file as it is now. Absent when it was deleted, or when `partial` is set."),
     binary: z.boolean().optional().describe("The file is not text, so neither side is sent."),
-    truncated: z.boolean().optional().describe("The file was too large to send whole, so what you have is the start of it."),
+    partial: PartialFileDiffSchema.optional().describe("Set when the file was too large to send whole: what is sent instead of the two sides."),
 });
 export type FileDiff = z.infer<typeof FileDiffSchema>;
 
@@ -5617,6 +5678,26 @@ export const CapabilityOtpSchema = z.object({
         .describe("How long it lasts. Its expiring is what makes handing one to an agent safe, since the seed behind it is never revealed."),
 });
 
+/* POST /capabilities/probe response: did these settings actually reach the thing, asked BEFORE they are saved.
+ *
+ * The answer is a sentence rather than a status code because the reader is standing in front of a form: what
+ * they need is either the service's own confirmation ("Reached GitHub, authenticated as ada") or the exact
+ * refusal ("GitHub answered 401: the token is not valid"), in the place where the box they would fix still is.
+ * That is also the whole point of doing it here: every one of these failures is otherwise discovered after the
+ * add, on a card that says "not connected" with nothing about which of six answers was wrong.
+ *
+ * `ok: false` is a REPORTED failure, not a transport error: the probe ran and the service said no. A card whose
+ * settings cannot be checked from here at all answers `checked: false`, which is a different thing from a
+ * failure and must never be drawn as one. */
+export const CapabilityProbeSchema = z.object({
+    checked: z.boolean().describe("Whether this connection can be tested from here at all. False is not a failure: it is 'no test exists'."),
+    ok: z.boolean().describe("Whether the service answered as itself."),
+    message: z
+        .string()
+        .describe("What happened, in the words a person standing in front of the form needs: the service's own answer, or its refusal."),
+});
+export type CapabilityProbe = z.infer<typeof CapabilityProbeSchema>;
+
 // ---- hosts: the user's own connected computers (the `host` capability's live half) ----
 // The manifest says which machines the user INTENDS to have connected; this says which are actually holding a
 // socket right now. Nothing here is remembered across a daemon restart except the enrollment itself: a machine
@@ -7625,6 +7706,9 @@ export const PanelSummarySchema = z.object({
     servers: z
         .array(
             z.object({
+                // The port itself, not just the URL it appears in: forwarding one is how a repo answering on
+                // several ports becomes previewable at all, and that call takes a number.
+                port: z.number().describe("The port it is listening on, which is what forwarding it takes."),
                 url: z.string().describe("Where it answers, with the right scheme: a server on its own certificate is served over https."),
                 dir: z
                     .string()
@@ -7641,8 +7725,15 @@ export const PanelSummarySchema = z.object({
             }),
         )
         .describe("Every server this repository is really serving, found by looking at what is listening. Empty when nothing answers."),
-    // https://preview-<repo>-<sandboxId>.<zone>; absent when the sandbox has no zone or connect token (loopback/tests).
-    previewUrl: z.string().optional().describe("Where to open it from outside. Absent on a sandbox with no outside address."),
+    /* https://preview-<repo>-<sandboxId>.<zone>, and ONLY where that address actually serves this repo: absent
+     * on a sandbox with no zone or connect token (loopback/tests), and absent whenever the preview proxy has
+     * nothing to route it to — nothing running, still starting, or (the ordinary monorepo) several dev servers
+     * on ports of their own, none of which one hostname can stand for. Present ⇒ safe to open or frame, which
+     * is what stops a surface from showing a 502 as if it were the app. */
+    previewUrl: z
+        .string()
+        .optional()
+        .describe("Where to open it from outside, present only while that address really serves it. Absent on a sandbox with no outside address."),
     // The workspace role this repo dir occupies (the three fixed dirs); absent for extra clones.
     role: z
         .enum(["intent", "desired-state", "app"])
@@ -7816,15 +7907,41 @@ export type MachineSandbox = z.infer<typeof MachineSandboxSchema>;
  *
  * The machine enforces which of them it will do: `sandboxes` covers everything but removal, which takes its own
  * switch, and a refusal comes back as the machine's own sentence naming the control to flip. */
-export const MachineSandboxOpSchema = z.enum(["start", "stop", "restart", "prepare", "update", "rebuild", "rollback", "remove", "logs"]);
+/* `runner-up` / `runner-remove` are the same door for a container that belongs to THIS SANDBOX rather than to
+ * a person: a runner (runners/, docs/remote-runners-plan.md at the workspace root). They ride here because to
+ * the machine they are the same act it already does, run and remove a sandbox container, and to the person
+ * clicking they are the same row of buttons. Both take the `sandboxes` switch and neither takes the removal
+ * one: a runner holds no workspace of its own, only a mirror of the parent's git, so removing it destroys
+ * nothing the parent does not still have. */
+export const MachineSandboxOpSchema = z.enum([
+    "start",
+    "stop",
+    "restart",
+    "prepare",
+    "update",
+    "rebuild",
+    "rollback",
+    "remove",
+    "logs",
+    "runner-up",
+    "runner-remove",
+]);
 export type MachineSandboxOp = z.infer<typeof MachineSandboxOpSchema>;
 
 export const MachineSandboxFlowSchema = z.object({
     op: MachineSandboxOpSchema,
+    // Which sandbox, or, for the two runner ops, which RUNNER: the name it is known by at both ends, the
+    // parent's `/system/runners` list and the machine's `ic runner list`.
     slug: z.string().min(1),
     // The approved overlay's sha256, required by `rebuild` and meaningless to the rest. It is the trust anchor:
     // only content that still hashes to what the owner reviewed is ever built.
     hash: z.string().optional(),
+    /* `runner-up` only, and both are filled in by the DAEMON, never by the caller: where the runner dials
+     * (this sandbox's public URL) and the single-use pairing it redeems there. The browser asks for a runner
+     * on a machine; it never holds the credential that makes one, which is what keeps a pairing out of every
+     * surface between here and that machine. */
+    parentUrl: z.string().optional(),
+    pair: z.string().optional().meta({ secret: true }),
 });
 export type MachineSandboxFlow = z.infer<typeof MachineSandboxFlowSchema>;
 
@@ -8323,28 +8440,28 @@ export const BrowserNameParamSchema = z.object({ name: z.string().describe("Whic
  * (another agent, working, that you did not start):
  *   • `subagent`, the SDK's Agent/Task tool. The daemon learns of it from the SubagentStart/SubagentStop hooks
  *     and the task_* stream messages, joined on `toolUseId`.
- *   • `codex` / `grok`, a CLI the agent drove from its own Bash (agent/delegation.ts). Detected in the Bash
- *     PreToolUse hook, bound to its thread/session id from the command's output.
- *
- * `id` IS THE SPAWNING TOOL CALL'S id, the Agent card's, or the Bash card's for a delegation. It is the one key
- * every source already carries (the SDK's subagent meta, its task_* messages, and the `parentToolUseId` the
- * client nests inner frames under), so nothing has to be correlated: a card links to its subagent with the id it
- * already has, and the subagent points back at the card the same way. The ids the transcripts are actually READ
- * with, the SDK's agent id, a Codex thread, an OpenCode session, stay daemon-side, because no surface asks a
- * question they answer.
- *
- * WHAT A KIND CHANGES, and it is only ever the live view: a subagent has no process of its own to look at, so
- * watching it means reading its transcript. A delegation runs in a tmux window, so it has both, `terminal`
- * names it, and the card keeps its existing "Watch in terminal" beside the transcript door. */
-export const SubagentKindSchema = z.enum(["subagent", "codex", "grok"]);
+ *   • `spawned`, a full agent the turn started through the daemon's own spawn door (children/children.ts), on
+ *     ANY connected provider, Cursor's Composer, Codex, Gemini, another Claude. The daemon runs the child
+ *     itself, so its whole life is reported by direct calls rather than reconstructed from hooks or stdout.
+ *
+ * `id` IS THE SPAWNING TOOL CALL'S id for an SDK child (the one key its meta file, its task messages and the
+ * client's `parentToolUseId` nesting all carry), and the child's own conversation id for a `spawned` one (the
+ * spawn door returns it, so both sides hold it). A card links to its subagent with the id it has, and the
+ * subagent points back at the card the same way. The ids the transcripts are actually READ with, the SDK's
+ * agent id, stay daemon-side, because no surface asks a question they answer.
+ *
+ * WHAT A KIND CHANGES, and it is only ever the live view: an SDK subagent has no process of its own to look
+ * at, so watching it means reading its transcript; a spawned child is a conversation of its own, so its live
+ * view is that conversation's stream. */
+export const SubagentKindSchema = z.enum(["subagent", "spawned"]);
 export type SubagentKind = z.infer<typeof SubagentKindSchema>;
 
 // running/pending/blocked are live; the rest are terminal. Deliberately the SDK's own task vocabulary
 // (SDKTaskUpdatedMessage.patch.status) rather than AgentStatus: this is not a fleet card's lifecycle (no
 // draft/landed/conflict), and mapping the two would invent states neither side reports. `blocked` is the one
-// addition the SDK never says: it comes from a delegated CLI's own signals (a Codex PermissionRequest hook, an
-// OpenCode permission ask, agent/delegation-signals.ts), and it exists because "the child needs an answer" is
-// the one live state a parent or an operator acts on differently from "the child is working".
+// addition the SDK never says: a spawned child's own question/permission/plan card raises it
+// (children/children.ts), and it exists because "the child needs an answer" is the one live state a parent or
+// an operator acts on differently from "the child is working".
 export const SubagentStatusSchema = z.enum(["pending", "running", "blocked", "completed", "failed", "killed", "paused"]);
 export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
 
@@ -8352,20 +8469,23 @@ export const SubagentSessionSchema = z.object({
     id: z
         .string()
         .describe(
-            "The id of the tool call that started it, which every side already holds, so a card links to its helper with the id it has and the helper points back the same way.",
+            "The id of the tool call that started it (an SDK child) or the child's own conversation id (a spawned one); either way both sides already hold it, so a card links to its helper with the id it has and the helper points back the same way.",
         ),
     kind: SubagentKindSchema.describe(
-        "What sort of helper: one the runtime spawned, or a separate tool the agent drove from a shell. It changes only how you watch it.",
+        "What sort of helper: one the runtime's own Task tool spawned in-process, or a full agent the daemon started for the turn. It changes only how you watch it.",
     ),
     // The conversation whose turn spawned this, what the area groups its rows by, and the way back to the chat
     // the card lives in.
     conversationId: z.string().describe("The conversation whose turn started it, and the way back to the chat it belongs to."),
-    // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or the delegated
-    // provider's model, and the caller's one-line description. The area's row and the card's title read as
-    // `Explore · Locate claimIndexer definition`.
+    // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or a spawned
+    // child's provider label, and the caller's one-line description. The area's row and the card's title read
+    // as `Explore · Locate claimIndexer definition`.
     agentType: z.string().optional().describe("What kind of helper it is."),
     description: z.string().optional().describe("What it was asked to do, in one line."),
     model: z.string().optional().describe("Which model it runs on."),
+    // Which provider serves a `spawned` child (its AgentProvider id), so the row can wear the right logo. An
+    // SDK subagent implies its own: it runs on its parent's provider.
+    provider: z.string().optional().describe("Which provider serves it, for a helper spawned across providers."),
     // How deep in the spawn tree (1 = spawned by the turn itself). From the SDK's meta.json; a subagent may
     // itself delegate, and a flat list that cannot say so reads as though the turn started all of them.
     spawnDepth: z
@@ -8403,14 +8523,6 @@ export const SubagentSessionSchema = z.object({
         .optional()
         .describe("Its report: what it concluded, without opening its record. The question a finished helper gets read for."),
     error: z.string().optional().describe("Why it failed, when it did."),
-    // A delegation's live view: the tmux session its command runs in. Absent for an SDK subagent, which has no
-    // process of its own to attach to.
-    terminal: z
-        .string()
-        .optional()
-        .describe(
-            "The terminal its command runs in, when there is one. Absent for a helper with no process of its own, which is watched by reading its record instead.",
-        ),
 });
 export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
 export const SubagentsListSchema = z.object({
@@ -8431,6 +8543,73 @@ export const SubagentIdParamSchema = z.object({ id: z.string() });
 // proposal present with a hash different from custom's.
 
 const environmentFileSchema = z.object({ content: z.string(), hash: z.string() });
+
+/* ---- environment DRIFT: what the live container has that the image did not put there ----
+ *
+ * Anything installed outside /work dies with the container, and transcript mining showed the same tools being
+ * reinstalled session after session (cargo-xwin six times, a Windows rustup target eight) before anyone thought
+ * to bake them. Drift is the daemon OBSERVING that gap rather than trusting the model to report it: apt installs
+ * read from dpkg's own log, everything else from system paths newer than the container itself. Two channels
+ * because they are disjoint by construction — dpkg unpacks files with their archive mtimes, so an mtime sweep
+ * cannot see apt, and nothing apt does lands under the swept prefixes' hand-installed corners. */
+export const EnvironmentDriftSchema = z.object({
+    // When this container was created (PID 1's start). A snapshot whose bornAt is not the running container's
+    // describes a container that no longer exists, and every reader must treat it as no drift at all.
+    bornAt: z.number(),
+    // When the probe ran.
+    at: z.number(),
+    // Debian packages installed since the container was born, from /var/log/dpkg.log.
+    apt: z.array(z.string()),
+    // System paths (outside /work) newer than the container, collapsed so a browser download is one entry.
+    paths: z.array(z.string()),
+});
+export type EnvironmentDrift = z.infer<typeof EnvironmentDriftSchema>;
+
+// How a runtime install was made, which decides whether the daemon can draft a Dockerfile step for it
+// mechanically (apt/cargo/npm/rustup-target) or only surface it for a person to route (pip belongs in a venv or
+// a Debian package, "other" is a curl|sh whose replay could embed anything).
+export const RuntimeInstallKindSchema = z.enum(["apt", "pip", "cargo", "npm", "rustup-target", "playwright", "gem", "pipx", "go", "other"]);
+export type RuntimeInstallKind = z.infer<typeof RuntimeInstallKindSchema>;
+
+/* One tool's runtime-install history across sessions: the ledger entry behind the recurrence signal. Sessions
+ * are the unit of recurrence — a session that retries an install five times needed it once — and the entry
+ * survives container recreates (the file lives under /work), which is exactly what makes "installed again in a
+ * fresh container" observable at all. */
+export const RuntimeInstallSchema = z.object({
+    tool: z.string(),
+    kind: RuntimeInstallKindSchema,
+    // Distinct conversation ids that installed it, capped; length is the recurrence count that gates drafting.
+    sessions: z.array(z.string()),
+    // The most recent install commands, capped, secrets already masked to references by the harness.
+    commands: z.array(z.string()),
+    firstAt: z.number(),
+    lastAt: z.number(),
+    count: z.number(),
+    // The owner rejected an auto-drafted step for this tool: never propose it again until this is cleared.
+    declinedAt: z.number().optional(),
+});
+export type RuntimeInstall = z.infer<typeof RuntimeInstallSchema>;
+
+export const RuntimeInstallsFileSchema = z.object({
+    installs: z.array(RuntimeInstallSchema),
+    // The last drift snapshot, persisted so a daemon restart does not blank the card until the next sweep.
+    drift: EnvironmentDriftSchema.optional(),
+});
+export type RuntimeInstallsFile = z.infer<typeof RuntimeInstallsFileSchema>;
+
+// A ledger entry as the Environment card shows it: recurrence joined with whether the install is present in the
+// LIVE container (drift-corroborated), already drafted for approval, or previously declined.
+export const EnvironmentRecurringSchema = z.object({
+    tool: z.string(),
+    kind: RuntimeInstallKindSchema,
+    sessions: z.number(),
+    lastAt: z.number(),
+    live: z.boolean(),
+    drafted: z.boolean().optional(),
+    declined: z.boolean().optional(),
+});
+export type EnvironmentRecurring = z.infer<typeof EnvironmentRecurringSchema>;
+
 export const EnvironmentSchema = z.object({
     proposal: environmentFileSchema.optional(),
     // The owner-approved agent-written custom section (.intentic/config/environment.custom.Dockerfile).
@@ -8440,6 +8619,10 @@ export const EnvironmentSchema = z.object({
     appliedHash: z.string().optional(),
     // config.sandbox.name, the UI derives the rebuild one-liner's slug from it.
     container: z.string().optional(),
+    // What the live container has that the image did not put there; absent until the first sweep of this container.
+    drift: EnvironmentDriftSchema.optional(),
+    // Runtime installs worth the owner's attention: recurring across sessions, or present-and-doomed right now.
+    recurring: z.array(EnvironmentRecurringSchema).optional(),
 });
 export type Environment = z.infer<typeof EnvironmentSchema>;
 export const EnvironmentApproveSchema = z.object({ hash: z.string().min(1) });
@@ -8508,33 +8691,10 @@ export type EnvironmentContents = z.infer<typeof EnvironmentContentsSchema>;
  * by entry in WORKSPACE_STATE_FILES / HISTORY_STATE_FILES. It cannot carry the other two, and the honest
  * consequence is that an import ends in a REPORT rather than a claim of equivalence, the container has no
  * docker socket, so only the host can rebuild the image the overlay describes.
- */
-
-// What the bundle says about itself, written as its first tar entry so a reader learns the shape before the
-// bytes. `secrets` is the owner's export-time choice; the restorer re-derives every decision from the manifests
-// rather than trusting this, and uses it only to explain what is missing.
-export const BundleManifestSchema = z.object({
-    // Bumped when the layout changes in a way an older daemon would misread. Refused rather than guessed at.
-    version: z.literal(1),
-    // Where it came from, for the report's first line. Never used to authorize anything.
-    sandbox: z.object({ name: z.string() }).optional(),
-    createdAt: z.number(),
-    secrets: z.boolean(),
-    /* The environment the target has to reproduce, carried as FACTS rather than as the composed file (which the
-     * target recomposes against its OWN base image on first boot). `customDockerfile` is the owner-approved
-     * source section; `capabilities` names what contributed the remaining fragments, so the report can list what
-     * to re-add when the configs themselves did not travel. */
-    environment: z.object({
-        customDockerfile: z.string().optional(),
-        baseImage: z.string().optional(),
-        approvedHash: z.string().optional(),
-        capabilities: z.array(z.object({ id: z.string(), kind: z.string() })),
-    }),
-    // Every path class the bundle deliberately left out, with the manifest's own note where it has one. This is
-    // what turns "the export skipped things" from a silence into a list the owner can act on.
-    excluded: z.array(z.object({ path: z.string(), portability: z.string(), note: z.string().optional() })),
-});
-export type BundleManifest = z.infer<typeof BundleManifestSchema>;
+ *
+ * The bundle's manifest (BundleManifestSchema) lives in definition.ts beside the sandbox DEFINITION it embeds:
+ * a bundle is definition + state, and keeping the two schemas together is what keeps the two export doors from
+ * drifting into different answers about what an environment is. */
 
 // What a restore actually did. `needsAction` is the part that matters: the environment rebuild command, the
 // credentials to re-enter, the logins to redo, each one a thing the target cannot do for itself.

package/src/workspace-state.test.ts

@@ -343,6 +343,10 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             // The owner's per-extension update posture (notify / agent / auto): a standing decision about
             // what may run unattended, which is exactly the kind of edit worth a line in `git log`.
             `.intentic/config/extension-update-policy.json`,
+            // Which commands are heavy enough to take turns, and how many may run at once. Tracked because
+            // raising that limit is a decision about every session sharing the box, and `git log` is the only
+            // thing that answers "since when have we been allowing four of these at a time".
+            `.intentic/config/heavy-commands.json`,
             `.intentic/config/loop-designs.json`,
             `.intentic/config/personas.json`,
             // A persona's own kit: the prompt it runs on and the skills only its turns reach. Tracked for the

package/src/workspace-state.ts

@@ -221,6 +221,18 @@ const STATE_FILES = [
     },
 
     { path: ".intentic/config/settings.json", invalidates: ["settings", "manifests"], portability: "carry", versioned: true },
+    /* Which agent commands are heavy enough to take turns, and how many may run at once (the daemon reads it
+     * per Bash command: platform/heavy-commands.ts).
+     *
+     * `carry`, because the answer is a property of the WORKSPACE rather than of this machine: `pnpm test` fans
+     * out to the same 74 packages wherever the repo is cloned, so a fresh sandbox should arrive already knowing
+     * which commands to queue rather than rediscovering it by freezing once.
+     *
+     * `versioned` for the reason the config slice generally is (personas.json's entry argues it): the file
+     * changes at human speed, it holds no secret, and a change to it is exactly the kind a reviewer should see
+     * — raising the limit is a decision about everyone's sessions on that box, and `git log` is the only thing
+     * that answers "since when have we allowed four of these at once". */
+    { path: ".intentic/config/heavy-commands.json", invalidates: ["settings"], portability: "carry", versioned: true },
     // The rule table's last-fired stamps, beside the rules themselves. `derived` rather than `carry`: it is a
     // record of what happened in THIS sandbox, and carrying it to a fresh one would date every rule to work
     // that machine never did.
@@ -230,6 +242,13 @@ const STATE_FILES = [
         portability: "derived",
         note: "Stamps of when each rule last did something; the new sandbox starts its own record.",
     },
+    /* The runtime-install ledger: which tools sessions installed into the container at runtime, how often, and
+     * the last drift snapshot (environment/runtime-installs.ts). `carry` where rule-firings chose `derived`,
+     * because the two record different subjects: a firing is about what THIS machine did, while the ledger is
+     * about what this WORKSPACE's tasks keep needing — a workspace moved to a fresh sandbox will hit the same
+     * missing tools, and arriving with the recurrence memory is the whole reason it is kept. The drift snapshot
+     * inside is machine-scoped, and self-expires on the move: its bornAt can never match the new container. */
+    { path: ".intentic/records/runtime-installs.json", invalidates: ["environment"], portability: "carry" },
     /* Written by the AGENT's file tools (the drafts skill), read by the owner's approval inbox, the one entry
      * here whose whole point is that a change arrives from outside the browser that renders it. `authored`:
      * a draft is text somebody wrote, and "find the reddit draft about X" is an ordinary search.