@intentic/sandbox-contract 1.344.0 → 1.346.0

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/conversation-links.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { CONVERSATION_ID } from "../ids/conversation-ids.js";
+
+// HOW ONE CONVERSATION RELATES TO ANOTHER at its birth, latched on its registry entry and carried on its card: the
+// conversation a fork was cut from, and the work a fresh session was opened on. Re-exported by agent.ts, whose turn
+// names them on a conversation's first turn.
+
+// agent.ts's ConversationIdSchema, spelled here rather than imported, since agent.ts re-exports this module.
+const ConversationIdSchema = z.string().regex(CONVERSATION_ID);
+
+// Where a conversation was cut from, the durable half of a fork, carried on the registry entry. `index` is the message
+// the cut sat above in the source, so its transcript can put the mark back.
+export const ForkedFromSchema = z.object({
+    conversationId: ConversationIdSchema,
+    index: z.number().int().nonnegative(),
+    // Which files this fork opened on; kept so the fork can still say it later, not only right after the click.
+    files: z.enum(["then", "now"]),
+});
+export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
+// A FRESH SESSION on another conversation's work: a code review, a test pass, or a person's own ask, started from that
+// conversation's work as it stands now and with none of its messages. A harness's own reviewer runs this way (Claude
+// Code's /code-review in a forked subagent, Codex's /review in a thread of its own) so it judges the diff rather than
+// the reasoning that produced it. Its first turn names the origin; the daemon then treats it as the origin's child: cut
+// from its current work, its edits going back into it, folded under its card. It is still a person's chat, never woken
+// for nor waking its origin: findings reach the origin only when a person sends them.
+export const FRESH_KINDS = ["review", "test", "ask"] as const;
+export const FreshKindSchema = z.enum(FRESH_KINDS);
+export type FreshKind = z.infer<typeof FreshKindSchema>;
+export const FreshOfSchema = z.object({
+    conversationId: ConversationIdSchema.describe("The conversation whose work this one starts from."),
+    kind: FreshKindSchema.describe("What it is opened for: a code review, a test pass, or the person's own ask."),
+});
+export type FreshOf = z.infer<typeof FreshOfSchema>;
+// The durable half, latched on the entry by the first turn and never cleared: the relationship, not a pending state.
+export const FreshSessionSchema = z.object({
+    of: ConversationIdSchema.describe("The conversation whose work it started from."),
+    kind: FreshKindSchema.describe("What it was opened for: a code review, a test pass, or the person's own ask."),
+    at: z.number().describe("When it started, in milliseconds. Work its origin changed after this is work it has not seen."),
+});
+export type FreshSession = z.infer<typeof FreshSessionSchema>;
+
+export const FRESH_OF_DESCRIPTION =
+    "Open this conversation on another conversation's work as it stands now, with none of that conversation's messages: for a review or a test that should judge the work, not the reasoning behind it. Its edits go back into that work. First turn only, and only on a private copy.";
+
+// The turn's own rules for `freshOf`: a new private copy of its own, never beside a fork's copy of a chat, never on itself.
+export const freshOfIssues = (
+    turn: { readonly freshOf?: FreshOf | undefined; readonly conversationId?: string | undefined; readonly isolated?: boolean | undefined; readonly forkOf?: unknown },
+    ctx: z.RefinementCtx,
+): void => {
+    if (turn.freshOf === undefined) {
+        return;
+    }
+    if (turn.conversationId === undefined || turn.isolated !== true) {
+        ctx.addIssue({ code: "custom", message: "freshOf requires an isolated conversationId" });
+    }
+    if (turn.forkOf !== undefined) {
+        ctx.addIssue({ code: "custom", message: "freshOf and forkOf are two different starts: a fork carries the conversation, a fresh session carries none of it" });
+    }
+    if (turn.freshOf.conversationId === turn.conversationId) {
+        ctx.addIssue({ code: "custom", message: "a conversation cannot start fresh on its own work" });
+    }
+};

package/src/schemas/data-protection.ts

@@ -4,7 +4,7 @@
 // behaviour except for restore points: that copy grows without bound on disk. Thirty days still covers recovering a
 // deleted file; zero remains available for people who want every snapshot. The public-office preset sets the rest.
 import { z } from "zod";
-import type { AdmissionRule } from "./agent.js";
+import type { AdmissionRule } from "./command-admission.js";
 
 export const AgentRetentionDaysSchema = z
     .number()

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`.
@@ -117,13 +118,13 @@ export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
 // One operation on one sandbox, streamed as lines ending in a `result` or `error` frame. `prepare` builds the pending
 // update without touching the container. `set-shape` sets its resources and privileges, now or for the next restart;
 // `forget-shape` drops a shape saved for the next restart. `start`/`restart` apply a saved shape (all through `ic`).
-// `reshape` is the older spelling of `set-shape`, kept one release for pages served by older sandboxes.
-// `runner-up`/`runner-remove` act on a runner (this sandbox's own container), not a person's sandbox; gated by the
-// `sandboxes` switch, not removal, since a runner holds no separate workspace to lose.
+// `reshape` is `set-shape`'s older spelling, kept one release. `runner-up`/`runner-remove` act on a runner (this
+// sandbox's own container); gated by the `sandboxes` switch, not removal, as a runner holds no workspace to lose.
 export const DeviceSandboxOpSchema = z.enum([
     "start",
     "stop",
     "restart",
+    "sleep",
     "prepare",
     // `prepare` under the unattended rules (`ic sandbox prepare --auto`): nobody pressed anything, so low disk is "not
     // now" and a pinned sandbox or the version it went back from is left alone. What the update card sends by itself
@@ -203,7 +204,7 @@ export const icShapeArgs = (slug: string, fields: SandboxShapeFields, when: Sand
 ];
 export const icForgetShapeArgs = (slug: string): string[] => ["sandbox", "shape", slug, "--forget"];
 // Power goes through ic too, so a Start or Restart from any door applies the shape saved for the next restart.
-export const icPowerArgs = (op: "start" | "stop" | "restart", slug: string): string[] => ["sandbox", op, slug];
+export const icPowerArgs = (op: "start" | "stop" | "restart" | "sleep", slug: string): string[] => ["sandbox", op, slug];
 // Adds the device id to the flow input; the daemon looks up machines by id. `resumeTurns` is the owner saying, as they
 // restart the sandbox relaying this, that the turns it cuts should run again once it is back; the daemon keeps it for
 // its next boot and never forwards it to the machine. A sandbox older than it ignores it, and the cut turns wait.
@@ -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.