@intentic/sandbox-contract 1.345.0 → 1.347.0

package/src/schemas/agents.ts

@@ -1,5 +1,6 @@
 // agents: the conversation fleet
 import { LandingDeliverySchema } from "./project-delivery.js";
+import { AgentNextSchema } from "./agent-next.js";
 import { z } from "zod";
 import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema, FreshSessionSchema } from "./agent.js";
 import { LoopStateSchema } from "./loops.js";
@@ -294,21 +295,27 @@ export const AgentSummarySchema = z.object({
         .describe(
             "Which kind of failure it was, as the turn's own error frame coded it. Absent for a failure nothing could classify, which reads as the plain red line it is.",
         ),
-    // Epoch seconds the spent allowance reopens; absent means genuinely unknown (Grok, Cursor) — never guess one.
-    limitResetsAt: z.number().optional().describe("When the spent allowance reopens, in epoch seconds. Absent when the provider publishes no instant."),
-    limitHeld: z.boolean().optional().describe("Whether the refused turn is held whole, so sending again re-runs it instead of appending to it."),
-    // Whether the daemon has already booked a retry at the reset; the one thing that keeps a stranded card out of the Attention lane.
-    limitScheduled: z.boolean().optional().describe("Whether the held turn is already booked to go again at the reset, so nobody has to press anything."),
-    // Account a booked move is sending the held turn to; set alongside `limitScheduled`, cleared by the move's own turn.
-    limitMoving: z.string().optional().describe("The account the held turn is being moved to by the owner's policy, while that move is booked."),
-    // The resume pass's own instant for the booked re-run, the one it fires by (limit-due.ts), so a card states when it
-    // goes rather than inferring it from the reset: they differ once the account it goes on is still spent at the reset.
-    limitNextAt: z
-        .number()
+    // Who worded `failure`, as the turn's error frame said (its `own`): a card leads with those words only when they are
+    // the sandbox's own sentence, as the chat's notice does (failureView), and with its kind's line otherwise.
+    failureOwn: z
+        .boolean()
         .optional()
         .describe(
-            "When the held turn goes again by itself, in epoch seconds, while it is booked to (limitScheduled): later than the reset where the account it goes on is still spent, and already past for a booked move, which goes on the next pass. Absent while only a press sends it.",
+            "Whether `failure` is the sandbox's own sentence rather than the provider's or the harness's words. Absent for theirs, and for an ending recorded before it was said.",
         ),
+    // Epoch seconds the spent allowance reopens; absent means genuinely unknown (Grok, Cursor) — never guess one.
+    limitResetsAt: z.number().optional().describe("When the spent allowance reopens, in epoch seconds. Absent when the provider publishes no instant."),
+    limitHeld: z.boolean().optional().describe("Whether the refused turn is held whole, so sending again re-runs it instead of appending to it."),
+    // What a sandbox older than `next` (before 1.343.0) said in its place, read so the editor can derive `next` from it
+    // (agentStatus-standing.ts, withNext): the hosted editor meets such a sandbox for as long as it stays off the release
+    // that dropped them, which carried a Breaking-Note and so is never taken by itself. No sandbox sends them since.
+    limitScheduled: z.boolean().optional().describe("Sent only by sandboxes older than `next`: whether the held turn was booked to go again by itself."),
+    limitMoving: z.string().optional().describe("Sent only by sandboxes older than `next`: the account a booked move was taking the held turn to."),
+    limitNextAt: z.number().optional().describe("Sent only by sandboxes older than `next`: when the booked re-run went, in epoch seconds."),
+    // The one answer to "does it go by itself, and when" (agent-next.ts), derived from what it holds every time it is read.
+    next: AgentNextSchema.optional().describe(
+        "What carries it on next with nobody pressing anything, and when: a held turn re-run, a message held for memory, or messages booked for later. Absent when only a press moves it.",
+    ),
     provider: AgentProviderSchema.describe("Which model provider it runs on."),
     harness: AgentHarnessSchema.describe("Which agentic loop it runs on."),
     // Latched with the conversation, so the card can say where work runs without asking anything else.
@@ -475,7 +482,8 @@ export const AgentSummarySchema = z.object({
         .describe(
             "When somebody last opened it, in milliseconds. Newer activity than this is what makes it unread. Kept by the sandbox rather than by a browser, so clearing site data or picking up a phone does not resurrect every badge.",
         ),
-    // Browser-side words the daemon cannot read, reported so the unattended archive sweep never files them away.
+    // Derived from the drafts the sandbox holds (composer-drafts.ts), or reported by a client that keeps its own, so the
+    // unattended archive sweep never files away a conversation somebody is still writing to.
     unsentAt: z
         .number()
         .optional()
@@ -512,10 +520,10 @@ export const AgentSummarySchema = z.object({
         .describe(
             "The last attempt to bring its work into the workspace failed, and why. Cleared by the next land that goes through. Absent when nothing failed, and from a sandbox older than it.",
         ),
-    // The land's own last word on the owner's folder, for a project attached to this computer's sandbox: written there,
+    // The land's own last word on the owner's folder, for a sandbox made for one folder: written there,
     // partly kept out, waiting for the computer, or refused (schemas/project-delivery.ts).
     delivery: LandingDeliverySchema.optional().describe(
-        "What became of its last land in the folder on the owner's computer, for a project folder attached to this computer's sandbox. Absent for any other land, and from a sandbox older than it.",
+        "What became of its last land in the folder on the owner's computer, for a sandbox made for one folder. Absent for any other land, and from a sandbox older than it.",
     ),
     // Only the causes that still hold, re-read live (conversations/land/standing.ts), never the stored report's own list: a
     // blocker the user has since cleared is not something to offer them an action about.
@@ -809,53 +817,6 @@ export const AgentsRemovedSchema = z.object({
         ),
 });
 export type AgentsRemoved = z.infer<typeof AgentsRemovedSchema>;
-// Searches only speech, both sides of the conversation, never thinking, tool output or protocol text, which would
-// otherwise match nearly the whole board. Two-char minimum; `caseSensitive` off means case-insensitive, matching
-// workspace search's own switch.
-export const AgentSearchQuerySchema = z.object({
-    query: z
-        .string()
-        .trim()
-        .min(2)
-        .describe(
-            "What to look for. Searched against what was said, both sides of the conversation, and nothing else: not the thinking, not the tool output, which between them name nearly every identifier in the workspace and would return most of the board.",
-        ),
-    caseSensitive: z.stringbool().optional().describe("Whether capitals matter."),
-});
-// Why a row survived the filter: the matched line, windowed, and who said it. `speaker` rides with the text since agent
-// prose alone can read as something the user typed.
-export const SpeakerSchema = z.enum(["user", "agent"]);
-export type Speaker = z.infer<typeof SpeakerSchema>;
-export const MatchSnippetSchema = z.object({
-    text: z.string().describe("The matching line, with a little either side of it."),
-    speaker: SpeakerSchema.describe(
-        "Who said it. Carried with the words rather than beside them, because a line of the agent's prose under a card reads as something you typed until the row says otherwise.",
-    ),
-});
-export type MatchSnippet = z.infer<typeof MatchSnippetSchema>;
-// One matching agent and its evidence; `snippet` is absent for a title match, which the card already shows.
-export const AgentMatchSchema = z.object({
-    id: z.string().describe("Which conversation matched."),
-    snippet: MatchSnippetSchema.optional().describe(
-        "Why, in its own words. Absent when the title was the match, which the card already shows: repeating it underneath is noise where evidence was wanted.",
-    ),
-});
-export type AgentMatch = z.infer<typeof AgentMatchSchema>;
-// How many agents were actually read, so the board can say a search saw less than the whole fleet.
-export const AgentSearchResultSchema = z.object({
-    matches: z.array(AgentMatchSchema).describe("What matched, from the live fleet and the archive together."),
-    scanned: z
-        .number()
-        .describe(
-            "How many conversations were actually read, so a screen can say when a search saw less than everything rather than implying it saw all of it.",
-        ),
-    indexing: z
-        .boolean()
-        .describe(
-            "Whether what was said is still being read in the background. True means this answer can still grow, so a screen must say it is incomplete rather than presenting it as the whole list.",
-        ),
-});
-export type AgentSearchResult = z.infer<typeof AgentSearchResultSchema>;
 // The user-chosen display title, bounded like sanitizeTitle's own cap.
 export const AgentRenameSchema = z.object({
     id: z.string().min(1).describe("Which conversation."),
@@ -890,7 +851,7 @@ export const AgentAutoLandSchema = z.object({
             "Whether its work merges automatically when a turn finishes. Null clears the override and goes back to following the sandbox-wide setting, so a conversation does not sit holding a frozen copy of a default it has quietly stopped following.",
         ),
 });
-// A composer's unsent words, reported by the editor that holds them: the words themselves stay in the browser.
+// A composer's unsent words, reported by a client that keeps them to itself rather than writing them as a draft.
 export const AgentUnsentSchema = z.object({
     id: z.string().min(1).describe("Which conversation."),
     at: z

package/src/schemas/compose-overlay.test.ts

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { ComposedOverlayLineSchema } from "./compose-overlay.js";
+
+// The lines a target image's composer prints, as examples: golden/compose-overlay.json, which ic's reader is held to
+// (_sandbox/ic/src/sandbox/composition.rs). This is the TS half: each is a line the contract reads, its hash its overlay's.
+
+interface ComposeCase {
+    readonly name: string;
+    readonly base: string;
+    readonly line: unknown;
+}
+
+// SAFETY: the golden is this package's own file; the assertions below fail on any field it lacks.
+const GOLDEN = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "golden", "compose-overlay.json"), "utf8")) as { readonly cases: readonly ComposeCase[] };
+
+test("every golden line is a composer's line, its hash the overlay's own and its FROM the base it was asked for", () => {
+    expect(GOLDEN.cases.length).toBeGreaterThan(2);
+    for (const { base, line } of GOLDEN.cases) {
+        const read = ComposedOverlayLineSchema.parse(line);
+        expect(line).toEqual(read);
+        if (read.overlay === null) {
+            expect(read.hash).toBeUndefined();
+            continue;
+        }
+        expect(read.hash).toBe(createHash("sha256").update(read.overlay).digest("hex"));
+        expect(read.overlay).toContain(`\nFROM ${base}\n`);
+    }
+});
+
+test("a line in another format is not one this contract reads", () => {
+    expect(ComposedOverlayLineSchema.safeParse({ compose: 2, overlay: null }).success).toBe(false);
+});

package/src/schemas/compose-overlay.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+// WHAT A TARGET IMAGE COMPOSES FOR A SANDBOX, as the host reads it: the one line the image's own composer prints
+// (`node /opt/sandbox/dist/environment/compose-overlay.js --base <image>`, _sandbox/sandbox/src/environment/compose-overlay.ts) over read-only
+// mounts of the sandbox's volumes before a swap onto it, which `ic` builds instead of the overlay the running daemon
+// composed (_sandbox/ic/src/sandbox/composition.rs). golden/compose-overlay.json holds examples the Rust test reads.
+
+// The one format `ic` reads; any other, or none, sends it back to the running daemon's overlay.
+export const COMPOSE_OVERLAY_FORMAT = 1;
+
+export const ComposedOverlayLineSchema = z.object({
+    compose: z.literal(COMPOSE_OVERLAY_FORMAT).describe("The format of this line. A reader takes no other."),
+    overlay: z
+        .string()
+        .nullable()
+        .describe("The Dockerfile the image's daemon composes on its first boot, byte for byte; null when the sandbox wants no overlay on it."),
+    hash: z.string().optional().describe("sha256 of `overlay`, what the new container is stamped with (SANDBOX_ENVIRONMENT_HASH). Absent with no overlay."),
+});
+export type ComposedOverlayLine = z.infer<typeof ComposedOverlayLineSchema>;

package/src/schemas/composer-drafts.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { ATTACHMENT_LIMIT, ConversationIdSchema, ForkOfSchema, FreshOfSchema, QueuedServingSchema } from "./agent.js";
+
+// A PERSON'S UNSENT WORDS FOR ONE CONVERSATION, held by the sandbox. Until 2026-10-20 a composer's words lived only in the
+// browser: in each window's tab snapshot, moved into a per-browser "closed drafts" set when the tab closed and back out
+// when it reopened, and broadcast between windows as previews. Every move was a chance to lose or duplicate them: a
+// popped-out chat and the board each held a copy for a round trip, two windows wrote the same chat's words over each
+// other, and another device never saw them at all. Now the sandbox holds the one record, per person and conversation, and
+// a browser keeps only an optimistic copy of it. A draft never goes by itself (AgentSummary.next never names one), and it
+// is not egress: no model reads it until the person sends it, when it becomes the message the privacy shield judges.
+
+// The words as the composer holds them: what the message will say, its files, and who it will go to when it opens a
+// conversation (the pick a draft for a conversation the sandbox has never seen has nowhere else to live).
+const draftWords = {
+    text: z.string().max(200_000).describe("The words, exactly as typed."),
+    attachments: z
+        .array(z.string().min(1))
+        .max(ATTACHMENT_LIMIT)
+        .optional()
+        .describe("Files staged with it, as workspace paths already uploaded."),
+    serves: QueuedServingSchema.optional().describe(
+        "Who the message is to go to: the provider, loop, model, effort and account picked in the composer. Absent when nothing was picked.",
+    ),
+    forkOf: ForkOfSchema.optional().describe("Where the conversation this draft opens is cut from, when it is a fork no turn has started yet."),
+    freshOf: FreshOfSchema.optional().describe("The work a fresh session this draft opens starts from, when no turn has started it yet."),
+};
+
+export const ComposerDraftSchema = z.object({
+    conversationId: ConversationIdSchema.describe("The conversation the words are for. It may not exist yet: a new chat's words are a draft before its first turn."),
+    ...draftWords,
+    since: z.number().describe("When the composer first held these words unsent, in milliseconds."),
+    revision: z
+        .number()
+        .int()
+        .positive()
+        .describe("Moves with every write of any of your drafts. A write or a clear naming an older one is answered with the newer draft instead."),
+});
+export type ComposerDraft = z.infer<typeof ComposerDraftSchema>;
+
+export const ComposerDraftsSchema = z.object({
+    drafts: z.array(ComposerDraftSchema).describe("Every draft you hold in this sandbox, newest first. Only your own: another member's unsent words are theirs."),
+    revision: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe(
+            "The newest revision handed out when this list was read. A draft you hold at a revision past it was written after the read, so its absence here says nothing about it.",
+        ),
+});
+export type ComposerDrafts = z.infer<typeof ComposerDraftsSchema>;
+
+export const DraftWriteSchema = z.object({
+    id: ConversationIdSchema.describe("The conversation the words are for."),
+    ...draftWords,
+    since: z.number().optional().describe("When the words were first held unsent. Leave it out to keep the draft's own, or to start it now."),
+    base: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(
+            "The draft's revision these words were edited from. When the draft has been written since (another window, another device), nothing is written and the newer draft comes back with `conflict`, so no one's words are overwritten unseen. Leave it out to write a draft you have never read.",
+        ),
+});
+export type DraftWrite = z.infer<typeof DraftWriteSchema>;
+
+export const DraftWrittenSchema = z.object({
+    draft: ComposerDraftSchema.optional().describe("The draft as it now stands. Absent when there is none: it was cleared, or sent, before this write arrived."),
+    conflict: z
+        .literal(true)
+        .optional()
+        .describe("Nothing was written: the draft had moved past `base`. Merge your words into this one and write again from its revision."),
+});
+export type DraftWritten = z.infer<typeof DraftWrittenSchema>;
+
+export const DraftClearSchema = z.object({
+    id: ConversationIdSchema.describe("The conversation whose draft to clear."),
+    revision: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Clear it only while it is still this revision, so words written since in another window survive. Leave it out to clear whatever is there."),
+});
+export type DraftClear = z.infer<typeof DraftClearSchema>;

package/src/schemas/device-commands.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+// Closed set of command names; the daemon builds argv from the name alone (hosts/device-commands.ts). Never a free-text
+// command: the same socket carries `run_command`, which would grant a shell on the user's machine.
+// `sync-unpair` runs the machine's own `sync uninstall --sandbox` (terminates both Mutagen sessions, drops the pairing,
+// self-revokes enrollment); revoking from the sandbox side is a different route.
+// `dev-restart`, `dev-rebuild` and `sync-install` are the three whose argv the daemon fills from what only it knows — the
+// dev checkout on that machine, a freshly minted pairing token — which is also why none takes a path or a token from the
+// caller. The two dev commands are also why a machine-side op is the wrong shape for them: this door carries a COMMAND
+// STRING to a tool every released agent already has, so a sandbox can drive a machine whose agent predates the feature.
+// `dev-rebuild-log` is the read side of `dev-rebuild`: the build is detached out there, so its log is the only place its
+// progress exists, and polling this is what turns a fired-and-forgotten command into something with a progress bar.
+// `sync-clean` removes the build output left in directories the sandbox has deleted, which is what stops those
+// deletions from ever landing. It deletes only content the session already ignores, so it is the one command here whose
+// worst outcome is a rebuild — which is why it is a button and not a turn.
+// `mirror-ignore`/`mirror-unignore` are `mirror-off`'s per-port form, and the reason they exist: a port number that is
+// permanently taken on one machine's localhost has no answer in an all-or-nothing switch, so the choice lives where the
+// conflict does — one port, one device, durable — instead of muting every port the pairing serves.
+export const DeviceCommandSchema = z.enum([
+    "mirror-off",
+    "mirror-on",
+    "mirror-ignore",
+    "mirror-unignore",
+    "sync-pause",
+    "sync-resume",
+    "sync-unpair",
+    "sync-clean",
+    "dev-restart",
+    "dev-rebuild",
+    "dev-rebuild-log",
+    "sync-install",
+]);
+export type DeviceCommand = z.infer<typeof DeviceCommandSchema>;
+// The reversible sync switches: the subset a device's own row drives with a pair of buttons, as opposed to the two
+// commands a card elsewhere issues once. Its own type so those button tables stay total without carrying entries for
+// commands they can never send.
+export const DeviceSyncSwitchSchema = DeviceCommandSchema.exclude(["dev-restart", "dev-rebuild", "dev-rebuild-log", "sync-install", "sync-clean"]);
+export type DeviceSyncSwitch = z.infer<typeof DeviceSyncSwitchSchema>;
+
+// Where a detached rebuild reports itself, and the reader of that report (dev-rebuild-log.ts).
+export { DEV_REBUILD_EXIT_MARK, DEV_REBUILD_QUIET_MARK, type DevRebuildLog, devRebuildLogPath, readDevRebuildLog } from "./dev-rebuild-log.js";
+
+// Machine's sandbox id (absent = every paired sandbox); must start alphanumeric, else it parses as a CLI flag.
+export const DeviceSandboxIdSchema = z
+    .string()
+    .max(200)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+// A folder on the DEVICE for `sync-install` to keep in step. The only caller-supplied string that reaches a command
+// line, so its shape is the guard: `~`, an absolute POSIX path or a drive letter, and none of the characters that would
+// end the argument it sits in. `~` is expanded by the daemon, which is why `$` is not allowed to arrive here. The line
+// may be PowerShell, which reads the typographic quotes “ ” „ as double quotes and ‘ ’ ‚ ‛ as single quotes beside the
+// ASCII ones, so those are refused too: the daemon quotes the folder, and this keeps a second guard where one quoter
+// misses a character.
+export const DeviceLocalDirSchema = z
+    .string()
+    .min(1)
+    .max(4096)
+    // The curly quotes as escapes: bun's transpiler rewrites a literal one in a regex to its escape and tsgo keeps it,
+    // so spelled literally the pattern reads differently from source and from dist, and contract.lock.json can match
+    // only one of them.
+    .regex(/^(?:~|\/|[A-Za-z]:[\\/])[^"'`$;|&\n\r\u201C\u201D\u201E\u2018\u2019\u201A\u201B]*$/);
+// A TCP port number, the one value a caller supplies that reaches a command line as a number rather than a string.
+export const PortNumberSchema = z.number().int().min(1).max(65535);
+export const DeviceCommandInputSchema = z.object({
+    id: z.string().min(1),
+    command: DeviceCommandSchema,
+    sandboxId: DeviceSandboxIdSchema.optional(),
+    // `sync-install` only: which half to enroll (a member's "sync" still comes back mirror, decided daemon-side) and,
+    // for file sync, the folder on that device. The pairing token is minted by the daemon; no caller ever carries one.
+    mode: z.enum(["sync", "mirror"]).optional(),
+    localDir: DeviceLocalDirSchema.optional(),
+    // The two per-port mirror switches only. A number rather than a string, so nothing a caller sends can widen the
+    // command line it lands in.
+    port: PortNumberSchema.optional(),
+});
+export type DeviceCommandInput = z.infer<typeof DeviceCommandInputSchema>;
+// `ok` is the command's own exit status, not this route's: a refusal or non-zero exit is a real answer, not a thrown
+// error. Only an unreachable machine throws. `output` is the command's own printed text.
+export const DeviceCommandResultSchema = z.object({
+    ok: z.boolean(),
+    message: z.string(),
+    output: z.string().optional(),
+    // WHICH KIND OF `ok: false` THIS IS, because a caller that repeats itself needs to tell them apart: the device
+    // turning the command away (a switch of its own is off, the path is out of its reach) will turn it away again,
+    // whereas a command it accepted and then killed at its deadline says nothing except that this attempt was too slow.
+    refused: z.boolean(),
+});
+export type DeviceCommandResult = z.infer<typeof DeviceCommandResultSchema>;
+

package/src/schemas/device-folder.ts

@@ -33,6 +33,15 @@ export type DeviceConflict = z.infer<typeof DeviceConflictSchema>;
 export const clearableOnDevice = (conflict: DeviceConflict): boolean =>
     conflict.nature === "derived-leftover" && conflict.local === "untracked" && conflict.sandbox === "deleted";
 
+// WHY A FOLDER'S FILE SYNC IS HELD STILL, AND BY WHOM (2026-10-20). The machine agent reads each off a fact it keeps
+// on the pairing and makes Mutagen agree every pass (its sync/holds.ts), so a pause never outlives its reason and a
+// resume never undoes somebody else's. `owner` is a person's Pause, the only one a person lifts; every other is the
+// agent's own and lifts by itself once its reason ends. `transfer` (2026-10-21) is a bring-back, a restore or a delivery
+// of landed work writing into the folder. Strings on the wire, so a reason a newer agent adds still reads as held to an
+// older page.
+export const DeviceSyncHoldSchema = z.enum(["owner", "gone", "container-missing", "container-trashed", "swap", "unreachable", "low-disk", "transfer"]);
+export type DeviceSyncHold = z.infer<typeof DeviceSyncHoldSchema>;
+
 // The drive reading that paused a pairing for want of room: when (epoch ms), and how much was free of how much.
 export const DeviceLowDiskSchema = z.object({
     since: z.number(),

package/src/schemas/devices.ts

@@ -1,7 +1,8 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
+import { PortNumberSchema } from "./device-commands.js";
 import { DeviceBridgeHoldSchema, DeviceConflictSchema, DeviceLowDiskSchema } from "./device-folder.js";
-import { parseHostConnection, type DeviceFacts, DeviceFactsSchema, MachineIdSchema, userDistrosOf, WslEnvironmentSchema } from "./hosts.js";
+import { parseHostConnection, type DeviceFacts, DeviceFactsSchema, MachineIdentitySchema, MachineIdSchema, userDistrosOf, WslEnvironmentSchema } from "./hosts.js";
 import { RollbackTargetSchema, UpdateOutcomeSchema } from "./updates.js";
 import { DEV_VERSION } from "../state/versions.js";
 // Desktop-sync report shape shared by the agent, daemon and browser, produced only by the agent's own `deviceReport`.
@@ -230,92 +231,7 @@ export type DeviceAgentFlow = z.infer<typeof DeviceAgentFlowSchema>;
 // Adds the device id to the flow input.
 export const DeviceAgentFlowInputSchema = DeviceAgentFlowSchema.extend({ id: z.string().min(1) });
 export type DeviceAgentFlowInput = z.infer<typeof DeviceAgentFlowInputSchema>;
-// Closed set of command names; the daemon builds argv from the name alone (hosts/device-commands.ts). Never a free-text
-// command: the same socket carries `run_command`, which would grant a shell on the user's machine.
-// `sync-unpair` runs the machine's own `sync uninstall --sandbox` (terminates both Mutagen sessions, drops the pairing,
-// self-revokes enrollment); revoking from the sandbox side is a different route.
-// `dev-restart`, `dev-rebuild` and `sync-install` are the three whose argv the daemon fills from what only it knows — the
-// dev checkout on that machine, a freshly minted pairing token — which is also why none takes a path or a token from the
-// caller. The two dev commands are also why a machine-side op is the wrong shape for them: this door carries a COMMAND
-// STRING to a tool every released agent already has, so a sandbox can drive a machine whose agent predates the feature.
-// `dev-rebuild-log` is the read side of `dev-rebuild`: the build is detached out there, so its log is the only place its
-// progress exists, and polling this is what turns a fired-and-forgotten command into something with a progress bar.
-// `sync-clean` removes the build output left in directories the sandbox has deleted, which is what stops those
-// deletions from ever landing. It deletes only content the session already ignores, so it is the one command here whose
-// worst outcome is a rebuild — which is why it is a button and not a turn.
-// `mirror-ignore`/`mirror-unignore` are `mirror-off`'s per-port form, and the reason they exist: a port number that is
-// permanently taken on one machine's localhost has no answer in an all-or-nothing switch, so the choice lives where the
-// conflict does — one port, one device, durable — instead of muting every port the pairing serves.
-export const DeviceCommandSchema = z.enum([
-    "mirror-off",
-    "mirror-on",
-    "mirror-ignore",
-    "mirror-unignore",
-    "sync-pause",
-    "sync-resume",
-    "sync-unpair",
-    "sync-clean",
-    "dev-restart",
-    "dev-rebuild",
-    "dev-rebuild-log",
-    "sync-install",
-]);
-export type DeviceCommand = z.infer<typeof DeviceCommandSchema>;
-// The reversible sync switches: the subset a device's own row drives with a pair of buttons, as opposed to the two
-// commands a card elsewhere issues once. Its own type so those button tables stay total without carrying entries for
-// commands they can never send.
-export const DeviceSyncSwitchSchema = DeviceCommandSchema.exclude(["dev-restart", "dev-rebuild", "dev-rebuild-log", "sync-install", "sync-clean"]);
-export type DeviceSyncSwitch = z.infer<typeof DeviceSyncSwitchSchema>;
-
-// Where a detached rebuild reports itself, and the reader of that report (dev-rebuild-log.ts).
-export { DEV_REBUILD_EXIT_MARK, DEV_REBUILD_QUIET_MARK, type DevRebuildLog, devRebuildLogPath, readDevRebuildLog } from "./dev-rebuild-log.js";
-
-// Machine's sandbox id (absent = every paired sandbox); must start alphanumeric, else it parses as a CLI flag.
-export const DeviceSandboxIdSchema = z
-    .string()
-    .max(200)
-    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
-// A folder on the DEVICE for `sync-install` to keep in step. The only caller-supplied string that reaches a command
-// line, so its shape is the guard: `~`, an absolute POSIX path or a drive letter, and none of the characters that would
-// end the argument it sits in. `~` is expanded by the daemon, which is why `$` is not allowed to arrive here. The line
-// may be PowerShell, which reads the typographic quotes “ ” „ as double quotes and ‘ ’ ‚ ‛ as single quotes beside the
-// ASCII ones, so those are refused too: the daemon quotes the folder, and this keeps a second guard where one quoter
-// misses a character.
-export const DeviceLocalDirSchema = z
-    .string()
-    .min(1)
-    .max(4096)
-    // The curly quotes as escapes: bun's transpiler rewrites a literal one in a regex to its escape and tsgo keeps it,
-    // so spelled literally the pattern reads differently from source and from dist, and contract.lock.json can match
-    // only one of them.
-    .regex(/^(?:~|\/|[A-Za-z]:[\\/])[^"'`$;|&\n\r\u201C\u201D\u201E\u2018\u2019\u201A\u201B]*$/);
-// A TCP port number, the one value a caller supplies that reaches a command line as a number rather than a string.
-export const PortNumberSchema = z.number().int().min(1).max(65535);
-export const DeviceCommandInputSchema = z.object({
-    id: z.string().min(1),
-    command: DeviceCommandSchema,
-    sandboxId: DeviceSandboxIdSchema.optional(),
-    // `sync-install` only: which half to enroll (a member's "sync" still comes back mirror, decided daemon-side) and,
-    // for file sync, the folder on that device. The pairing token is minted by the daemon; no caller ever carries one.
-    mode: z.enum(["sync", "mirror"]).optional(),
-    localDir: DeviceLocalDirSchema.optional(),
-    // The two per-port mirror switches only. A number rather than a string, so nothing a caller sends can widen the
-    // command line it lands in.
-    port: PortNumberSchema.optional(),
-});
-export type DeviceCommandInput = z.infer<typeof DeviceCommandInputSchema>;
-// `ok` is the command's own exit status, not this route's: a refusal or non-zero exit is a real answer, not a thrown
-// error. Only an unreachable machine throws. `output` is the command's own printed text.
-export const DeviceCommandResultSchema = z.object({
-    ok: z.boolean(),
-    message: z.string(),
-    output: z.string().optional(),
-    // WHICH KIND OF `ok: false` THIS IS, because a caller that repeats itself needs to tell them apart: the device
-    // turning the command away (a switch of its own is off, the path is out of its reach) will turn it away again,
-    // whereas a command it accepted and then killed at its deadline says nothing except that this attempt was too slow.
-    refused: z.boolean(),
-});
-export type DeviceCommandResult = z.infer<typeof DeviceCommandResultSchema>;
+export * from "./device-commands.js";
 
 // What a synced folder reports beyond Mutagen's word, its conflicts and what the device holds back (device-folder.ts).
 export * from "./device-folder.js";
@@ -323,8 +239,7 @@ export * from "./device-folder.js";
 // One paired sandbox as the local agent holds it; `localDir` is which folder on that device holds this sandbox's /work.
 export const DevicePairingSchema = z.object({
     sandboxId: z.string(),
-    // The account's name for the sandbox, stamped by the editor that reads the report (withSandboxNames), as a
-    // container's `name` is. A machine never sends one: all it knows is the folder, named once at setup.
+    // The account's name for the sandbox, stamped by the editor that reads the report (withSandboxNames); never a machine's.
     name: z.string().optional(),
     mode: z.enum(["sync", "mirror"]),
     // Set only for mode "sync", and only for the sandbox being reported to.
@@ -332,12 +247,13 @@ export const DevicePairingSchema = z.object({
     // Which sandbox folder `localDir` holds when it is not /work itself: a project pairing's `/work/<name>`, the
     // owner's own folder, which carries no state backup and no git bridge. Absent means /work.
     remoteDir: z.string().optional(),
-    // The folderless pairing that holds this machine's sync token for its own local sandbox, which project folders
-    // attach to (`intentic-machine sync attach`). Absent on every other pairing.
-    projectsHost: z.boolean().optional(),
-    // Whether landed work in this project folder is delivered to `localDir` by itself (`deliverProject`). Only a
-    // folder attached to the machine's own sandbox says "auto"; absent means Bring back by hand, as before.
+    // Whether landed work in this project folder is delivered to `localDir` by itself (`deliverProject`). A project
+    // sandbox's folder says "auto"; absent means Bring back by hand, as before. (2026-10-21) The folderless
+    // `projectsHost` pairing of the desktop app's one sandbox per computer went with that sandbox; an older agent's report
+    // that still carries it parses, the key dropped.
     deliver: z.enum(["auto", "off"]).optional(),
+    // (2026-10-20) The slug this machine's ic knows the sandbox by: how the desktop app starts or forgets a folder's sandbox.
+    slug: z.string().optional(),
     // Machine-owned switch (agent's own `sync mirror off`); absent reads as "on", not merely unknown.
     mirroring: z.enum(["on", "off"]).optional(),
     // Mutagen's own status word, kept verbatim rather than reduced to a traffic light.
@@ -346,7 +262,9 @@ export const DevicePairingSchema = z.object({
     conflicts: z.number().int().nonnegative().optional(),
     // Conflicted paths, capped at `CONFLICT_PATHS_MAX`; `conflicts` above is the true, uncapped count.
     conflictedPaths: z.array(DeviceConflictSchema).optional(),
+    // Mutagen's word, and why the agent holds it still, owner first (DeviceSyncHoldSchema); agreeing by its next pass.
     paused: z.boolean().optional(),
+    heldBy: z.array(z.string()).optional(),
     // Second session's status (the state-dir backup mirror), reported separately: the two fail independently.
     backupStatus: z.string().optional(),
     // (2026-10-18) While the drive holding `localDir` is nearly full, the reading that paused its sync and git bridge; and the
@@ -488,12 +406,11 @@ export const SshHostKeySchema = z
 
 // POST /system/authorized-key: a machine's agent enrolling its SSH key for desktop sync, redeeming a pairing token.
 // Every field past `key` is optional: an older agent sends none of them and is still enrolled.
-export const SyncEnrollmentRequestSchema = z.object({
+// The key, and the computer and environment enrolling it (the same identity a device redeem sends), so the
+// enrollment joins that machine's card.
+export const SyncEnrollmentRequestSchema = MachineIdentitySchema.extend({
     // One authorized_keys line; its comment is the name the enrollment goes by (`DeviceSync.machine`).
     key: z.string(),
-    // The computer and the environment on it that are enrolling, so the enrollment joins that machine's card.
-    machineId: MachineIdSchema.optional(),
-    environment: z.string().min(1).optional(),
 });
 export type SyncEnrollmentRequest = z.infer<typeof SyncEnrollmentRequestSchema>;
 
@@ -546,6 +463,10 @@ export const DeviceSchema = z.object({
     // (a switch that is off, an `ic` too old to list). Absent when it listed, or when nothing answered at all. What a
     // card falling back to a command says instead of "connect the computer": that computer IS connected (2026-10-07).
     sandboxesUnread: z.string().optional(),
+    // Whether its card's "Manage sandboxes on this device" switch is on (HostSummary.manages). Not the same fact as
+    // `sandboxes`: "Run commands" alone lists the containers, and only this switch lets one be made, started or removed,
+    // so a screen offering such a press asks here first. Absent on a sync-only row and from a daemon older than it.
+    manages: z.boolean().optional(),
     gap: DeviceGapSchema.optional(),
 });
 export type Device = z.infer<typeof DeviceSchema>;
@@ -659,14 +580,11 @@ const doorsRunningSandbox = (devices: readonly Device[], slug: string | undefine
         ? []
         : devices.filter((device) => device.hostId !== undefined && device.online === true && (device.sandboxes ?? []).some((box) => box.slug === slug));
 
-// The connected, online device whose docker reports a given sandbox slug: the machine that sandbox RUNS ON, as opposed
-// to any machine merely paired with it. Answers the question every "run it there instead of asking the owner to type
-// it" path starts from, and is `undefined` for a sync-only agent, which reports no containers at all.
-// Reads the row's own container list, not the report's: a card that grants sandbox management without "Run commands"
-// can run every swap this answer leads to while refusing to describe itself, and judging it on the report would print
-// a terminal command for a machine one click could have done it on.
-// Answers with a door, and a container verb may take any door of the machine; a command written for a PATH may not
-// (`hostHoldingPath`).
+// The connected, online device whose docker reports a given sandbox slug: the machine that sandbox RUNS ON, not any
+// machine merely paired with it, and `undefined` for a sync-only agent, which reports no containers. Read off the row's
+// own container list, not the report's: a card granting sandbox management without "Run commands" refuses to describe
+// itself yet runs every swap this answer leads to, so judging it on the report printed a command one click could do.
+// Answers with a door, any of which a container verb may take; a command written for a PATH may not (`hostHoldingPath`).
 export const hostRunningSandbox = (devices: readonly Device[], slug: string | undefined): string | undefined =>
     doorsRunningSandbox(devices, slug)[0]?.hostId;
 

package/src/schemas/environment.ts

@@ -1,9 +1,8 @@
 // environment: the overlay Dockerfile extending the sandbox image
 import { z } from "zod";
-// The approved file is daemon-composed (pinned FROM + capability fragments + the owner-approved custom section). Status
-// is derived, never stored:
-// applied: sha256(approved) === appliedHash.
-// pending rebuild: approved present but hashes differ.
+// The approved overlay is daemon-composed (pinned FROM + capability fragments + the owner-approved custom section) from its
+// inputs on every read. Status is derived, never stored:
+// pending rebuild: rebuildPending(approved.hash, appliedHash) (state/sandbox-build.ts); applied otherwise.
 // proposed: proposal present with a hash different from custom's.
 
 const environmentFileSchema = z.object({ content: z.string(), hash: z.string() });
@@ -45,10 +44,10 @@ export type RuntimeInstall = z.infer<typeof RuntimeInstallSchema>;
 // (`environment propose`) clears its tool's entries.
 export const SettledDraftSchema = z.object({ tool: z.string(), hash: z.string(), at: z.number() });
 export type SettledDraft = z.infer<typeof SettledDraftSchema>;
-// One overlay the daemon composed, by the hash a rebuild is stamped with, and the custom-section blocks it carried (each
-// by name and the hash of its trimmed steps). Kept so "is this tool in the image" is answered against the overlay the
-// running container was actually built from, which is rarely the newest one composed: every approval, capability change
-// and daemon update composes again, and a rebuild builds whatever was newest when it started.
+// One overlay the daemon composed, by the hash a rebuild is stamped with, and the sections it carried, each by the hash
+// of its trimmed steps: capability fragments unnamed, custom-section blocks by name. Kept so "is this in the image" is
+// answered against the overlay the running container was actually built from, which is rarely the newest one composed:
+// every approval, capability change and daemon update composes again, and a rebuild builds whatever was newest then.
 export const EnvironmentCompositionSchema = z.object({
     hash: z.string(),
     at: z.number(),
@@ -196,7 +195,7 @@ export type EnvironmentRemove = z.infer<typeof EnvironmentRemoveSchema>;
 export const EnvironmentContentsSchema = z.object({ items: z.array(EnvironmentItemSchema) });
 export type EnvironmentContents = z.infer<typeof EnvironmentContentsSchema>;
 // A sandbox is four stores: /work, /history, the container, and the AI-provider credential root. A bundle carries only
-// the first two (WORKSPACE_STATE_FILES/HISTORY_STATE_FILES); it cannot rebuild the container or credentials, so
+// the first two (WORKSPACE_STATE_FILES here, the daemon's HISTORY_STATE_FILES); it cannot rebuild the container or credentials, so
 // importing one is a report, not a claim of equivalence. Only the outbound half is here; inbound is one of arrival.ts's
 // four sources.