@intentic/sandbox-contract 1.245.0 → 1.246.1

package/src/schemas/{computers.ts → devices.ts}

@@ -1,4 +1,4 @@
-// computers: what ONE of the user's own machines is running
+// devices: what ONE of the user's own machines is running
 import { z } from "zod";
 import { HostFactsSchema } from "./hosts.js";
 // The one sentinel every non-release build carries, so a locally compiled agent is never told it is behind.
@@ -26,8 +26,47 @@ import { DEV_VERSION } from "../versions.js";
  * `mirror` enrollment, a collaborator's own laptop, drops `localDir` with it. So a member who mirrors one
  * dev-server port does not hand the sandbox's owner a map of their machine. */
 
+/* ONE SANDBOX'S SHARE OF ITS MACHINE, as docker enforces it right now: read off the container's HostConfig
+ * and env by the machine agent, never asked of the sandbox (which cannot see its own cgroup ceiling as a
+ * docker flag, only as a number in /sys/fs/cgroup).
+ *
+ * The two `*Runtime` lists are the same directive vocabulary the run contract allowlists
+ * (@intentic/sandbox-run RUNTIME_DIRECTIVES), split by WHO asked: `overlayRuntime` is what the approved
+ * environment demands (a view draws those locked — "required by the Docker capability"), `hostRuntime` is
+ * what the owner asked for on top and may withdraw. `privileged` and `gpu` are the docker-side truth of the
+ * union: what the container actually got, after a host without the nvidia runtime dropped the GPU. */
+export const SandboxResourcesSchema = z.object({
+    // The cgroup memory ceiling in bytes; absent when docker imposes none (the hosted shape).
+    memoryBytes: z.number().optional(),
+    // The CFS quota as whole cores; absent when the container may use every core (the default).
+    cpus: z.number().optional(),
+    privileged: z.boolean(),
+    gpu: z.boolean(),
+    hostRuntime: z.array(z.string()),
+    overlayRuntime: z.array(z.string()),
+});
+export type SandboxResources = z.infer<typeof SandboxResourcesSchema>;
+
+/* WHAT A RESHAPE ASKS FOR: the Resources dialog's answer, the `reshape` op's payload, and the shape the
+ * machine turns into `ic sandbox reshape` flags. Every key is "leave it" when absent; the two caps take
+ * `null` for "back to the default" (the machine-derived memory share; every core), which `ic` spells as
+ * `default` and the run contract as an empty seed. At least one key, because a reshape with nothing to change
+ * is a restart for nothing, and the machine refuses it before anything is spawned. */
+export const SandboxResourcesAskFieldsSchema = z.object({
+    memoryGib: z.int().positive().nullable().optional(),
+    cpus: z.int().positive().nullable().optional(),
+    privileged: z.boolean().optional(),
+    gpu: z.boolean().optional(),
+});
+// The fields alone are exported too, for a caller that composes them into a wider object (the machine's MCP
+// tool adds the slug beside them) and applies the at-least-one rule itself.
+export const SandboxResourcesAskSchema = SandboxResourcesAskFieldsSchema.refine((ask) => Object.values(ask).some((value) => value !== undefined), {
+    message: "a reshape must change at least one thing",
+});
+export type SandboxResourcesAsk = z.infer<typeof SandboxResourcesAskSchema>;
+
 // One sandbox container on the machine, the docker half, filled in by the reader, never by the sync agent.
-export const MachineSandboxSchema = z.object({
+export const DeviceSandboxSchema = z.object({
     slug: z.string(),
     container: z.string(),
     // The display name, when the machine has one recorded. Docker knows only the container name.
@@ -37,9 +76,12 @@ export const MachineSandboxSchema = z.object({
     // Absent when the sandbox has no cloudflared sidecar AT ALL (reached over the user's own proxy), which is
     // not the same fact as a sidecar that is down, and must not render as one.
     tunnelRunning: z.boolean().optional(),
+    // Its share of the machine (above). Absent from a reader that did not inspect the container: the cheap
+    // `docker ps` listing the machine's own fleet reads use carries none of it.
+    resources: SandboxResourcesSchema.optional(),
 });
-export type MachineSandbox = z.infer<typeof MachineSandboxSchema>;
-/* ONE OPERATION ON ONE SANDBOX ON ONE MACHINE, the Computers view's buttons, and the only thing that changes a
+export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
+/* ONE OPERATION ON ONE SANDBOX ON ONE MACHINE, the Devices view's buttons, and the only thing that changes a
  * machine's fleet from a browser.
  *
  * All nine ops travel one route because they are one decision to the person clicking, however differently they
@@ -56,6 +98,11 @@ export type MachineSandbox = z.infer<typeof MachineSandboxSchema>;
  * same row as the others, on a container that may be too broken to answer any other way, and the stream shape
  * already carries "many lines, then an outcome" exactly as a log tail wants to arrive.
  *
+ * `reshape` is the one that changes the CONTAINER without changing its image: its share of the machine (memory
+ * and CPU caps) and its privileges (privileged, the host's GPU), recreated onto the same image so the values
+ * live on the container and outlive every later swap. It carries `resources`, the only op with a payload of
+ * its own besides `rebuild`'s hash.
+ *
  * 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. */
 /* `runner-up` / `runner-remove` are the same door for a container that belongs to THIS SANDBOX rather than to
@@ -64,7 +111,7 @@ export type MachineSandbox = z.infer<typeof MachineSandboxSchema>;
  * 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([
+export const DeviceSandboxOpSchema = z.enum([
     "start",
     "stop",
     "restart",
@@ -72,20 +119,23 @@ export const MachineSandboxOpSchema = z.enum([
     "update",
     "rebuild",
     "rollback",
+    "reshape",
     "remove",
     "logs",
     "runner-up",
     "runner-remove",
 ]);
-export type MachineSandboxOp = z.infer<typeof MachineSandboxOpSchema>;
-export const MachineSandboxFlowSchema = z.object({
-    op: MachineSandboxOpSchema,
+export type DeviceSandboxOp = z.infer<typeof DeviceSandboxOpSchema>;
+export const DeviceSandboxFlowSchema = z.object({
+    op: DeviceSandboxOpSchema,
     // 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(),
+    // What `reshape` should change, required by it and meaningless to the rest.
+    resources: SandboxResourcesAskSchema.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
@@ -105,29 +155,53 @@ export const MachineSandboxFlowSchema = z.object({
     overlay: z.string().optional(),
     overlayHash: z.string().optional(),
 });
-export type MachineSandboxFlow = z.infer<typeof MachineSandboxFlowSchema>;
+export type DeviceSandboxFlow = z.infer<typeof DeviceSandboxFlowSchema>;
 // The same input plus which machine it is for, the browser's half, since the daemon reaches the machine by id.
-export const MachineSandboxFlowInputSchema = MachineSandboxFlowSchema.extend({ id: z.string().min(1) });
-export type MachineSandboxFlowInput = z.infer<typeof MachineSandboxFlowInputSchema>;
+export const DeviceSandboxFlowInputSchema = DeviceSandboxFlowSchema.extend({ id: z.string().min(1) });
+export type DeviceSandboxFlowInput = z.infer<typeof DeviceSandboxFlowInputSchema>;
 /* What a running operation says, in the one line shape every streamed flow in this product already uses
  * (IntenticLineSchema, which the browser's reader parses): `line` as the machine prints it, then exactly one
  * terminal frame, `result` when it worked, `error` when it did not, carrying the machine's own words either
  * way rather than a code this side invented. */
-export const MachineFlowLineSchema = z.discriminatedUnion("kind", [
+export const DeviceFlowLineSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("line"), text: z.string() }),
     z.object({ kind: z.literal("result"), message: z.string() }),
     z.object({ kind: z.literal("error"), message: z.string() }),
 ]);
-export type MachineFlowLine = z.infer<typeof MachineFlowLineSchema>;
-/* RUNNING ONE OF THIS PRODUCT'S OWN CLIs ON A CONNECTED COMPUTER, FROM A BUTTON, with no agent in the loop.
+export type DeviceFlowLine = z.infer<typeof DeviceFlowLineSchema>;
+/* UPDATING OR RESTARTING THE AGENT ITSELF, from the row that reports its version.
+ *
+ * THE OPERATION THAT KILLS ITS OWN TRANSPORT, and that is the whole reason it is a flow of its own rather than
+ * another entry in the DeviceCommand set below. `run_command` runs as a child of the resident process, and both
+ * of these stop that process: `upgrade` calls stopResident() before it swaps the binary, and `run` stops before
+ * it starts. So the socket carrying the request dies mid-command, and the child's stdout pipe dies with it —
+ * an EPIPE on `process.stdout` is an uncaught exception in Node. An upgrade killed between
+ * `swap(agentPath, previous)` and `swap(staged, agentPath)` leaves a device with NO `intentic-machine` binary
+ * and a login entry pointing at a missing file, which is the one outcome worse than being out of date.
  *
- * A machine that is connected as a computer can already be told things: the ops above drive its docker, and an
+ * The agent therefore runs the work DETACHED (spawnDetached, exactly as it launches its own loop) and streams
+ * its log while it can. The stream ending with no terminal frame is the NORMAL case here, not a failure, and
+ * confirmation is the version moving on the view's next poll — which is also the only honest confirmation: the
+ * CLI's own `loop-behind` outcome exists because "a process came up" does not mean the new build is serving.
+ *
+ * `restart` needs no new CLI verb: bare `intentic-machine run` is a restart (reconcileResidency stops before it
+ * starts), and it is the remedy for both a stalled loop and one serving an older build than the file beside it. */
+export const DeviceAgentOpSchema = z.enum(["upgrade", "restart"]);
+export type DeviceAgentOp = z.infer<typeof DeviceAgentOpSchema>;
+export const DeviceAgentFlowSchema = z.object({ op: DeviceAgentOpSchema });
+export type DeviceAgentFlow = z.infer<typeof DeviceAgentFlowSchema>;
+// The same input plus which device it is for, the browser's half.
+export const DeviceAgentFlowInputSchema = DeviceAgentFlowSchema.extend({ id: z.string().min(1) });
+export type DeviceAgentFlowInput = z.infer<typeof DeviceAgentFlowInputSchema>;
+/* RUNNING ONE OF THIS PRODUCT'S OWN CLIs ON A CONNECTED DEVICE, FROM A BUTTON, with no agent in the loop.
+ *
+ * A machine that is connected as a device can already be told things: the ops above drive its docker, and an
  * agent with the `host` capability can run whatever it likes through `run_command`. What had no door was the
  * ordinary case in between — the user wants the thing the CLI on their machine already does, and the sandbox is
  * where they are looking. Their alternatives were to go and find a terminal, or to ask an agent to do it, which
  * spends a turn and a model's judgement on a decision that has none in it.
  *
- * So: a CLOSED SET OF NAMES, and the argv is built on the daemon from the name alone (hosts/machine-commands.ts).
+ * So: a CLOSED SET OF NAMES, and the argv is built on the daemon from the name alone (hosts/device-commands.ts).
  * The browser sends `mirror-off`, never a command line. That is the whole security property, and it is the
  * reason this is an enum rather than a string: the same socket carries `run_command`, so a route that forwarded
  * caller-supplied text would hand every browser session a shell on the user's laptop, which is a grant the
@@ -137,7 +211,7 @@ export type MachineFlowLine = z.infer<typeof MachineFlowLineSchema>;
  * own words, naming the control to flip — exactly as it does for the sandbox ops. */
 /* THE SET, and why the file-sync half of it is here beside the mirroring half.
  *
- * Both are the same gesture to the person clicking: something this computer is doing for this sandbox, turned
+ * Both are the same gesture to the person clicking: something this device is doing for this sandbox, turned
  * off or on from the row that describes it. They were split for a while by nothing but which one had been built
  * — mirroring had a button and pausing a file sync had a paragraph telling you to go and find a terminal — and
  * that is exactly the gap this door exists to close.
@@ -147,8 +221,8 @@ export type MachineFlowLine = z.infer<typeof MachineFlowLineSchema>;
  * pairing and self-revokes its enrollment on the way out, so the machine cleans up after itself rather than
  * leaving a sandbox to guess what it managed to do. Revoking from the SANDBOX side (an unreachable machine, a
  * laptop that is never coming back) is a different act and a different route, see the enrollment revoke. */
-export const MachineCommandSchema = z.enum(["mirror-off", "mirror-on", "sync-pause", "sync-resume", "sync-unpair"]);
-export type MachineCommand = z.infer<typeof MachineCommandSchema>;
+export const DeviceCommandSchema = z.enum(["mirror-off", "mirror-on", "sync-pause", "sync-resume", "sync-unpair"]);
+export type DeviceCommand = z.infer<typeof DeviceCommandSchema>;
 /* Which paired sandbox the command acts on: the machine's own id for it, as it appears in that machine's report,
  * so nothing here has to re-derive the sanitizing the agent applied. Absent means every sandbox that machine
  * pairs, which is what the CLI does when it is run bare.
@@ -156,42 +230,42 @@ export type MachineCommand = z.infer<typeof MachineCommandSchema>;
  * Pattern-bound because it becomes an argv token. It must start with an alphanumeric, not merely consist of id
  * characters: a value like `--takeover` is made only of legal id characters and is a FLAG by the time the CLI on
  * the machine parses it. Real ids are `sandbox-<hex>-<zone>`-shaped, so nothing legitimate leads with a dash. */
-export const MachineSandboxIdSchema = z
+export const DeviceSandboxIdSchema = z
     .string()
     .max(200)
     .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
-export const MachineCommandInputSchema = z.object({
+export const DeviceCommandInputSchema = z.object({
     id: z.string().min(1),
-    command: MachineCommandSchema,
-    sandboxId: MachineSandboxIdSchema.optional(),
+    command: DeviceCommandSchema,
+    sandboxId: DeviceSandboxIdSchema.optional(),
 });
-export type MachineCommandInput = z.infer<typeof MachineCommandInputSchema>;
+export type DeviceCommandInput = z.infer<typeof DeviceCommandInputSchema>;
 /* What came back. `ok` is the command's own exit status, not this route's: a machine that refused the call, or a
  * CLI that exited non-zero, is a real answer to show the person who clicked, not an exception to convert into
  * one. Only an unreachable machine throws, because then there is nothing to report at all.
  *
  * `output` is what the command printed, kept because the CLI's own sentences ("Port mirroring OFF for: …") are
  * better than anything this side would write over them. */
-export const MachineCommandResultSchema = z.object({
+export const DeviceCommandResultSchema = z.object({
     ok: z.boolean(),
     message: z.string(),
     output: z.string().optional(),
 });
-export type MachineCommandResult = z.infer<typeof MachineCommandResultSchema>;
+export type DeviceCommandResult = z.infer<typeof DeviceCommandResultSchema>;
 // One paired sandbox as the local agent holds it. `localDir` is the answer to the question the Desktop sync card
-// has never been able to answer: which folder on that computer this sandbox's /work actually is.
-export const MachinePairingSchema = z.object({
+// has never been able to answer: which folder on that device this sandbox's /work actually is.
+export const DevicePairingSchema = z.object({
     sandboxId: z.string(),
     mode: z.enum(["sync", "mirror"]),
     // Set only for mode "sync", and only for the sandbox being reported to, see the redaction note above.
     localDir: z.string().optional(),
-    /* Whether that computer is putting this sandbox's ports on its own localhost, which is a switch its owner
+    /* Whether that device is putting this sandbox's ports on its own localhost, which is a switch its owner
      * holds and not a state this sandbox can read off anything else. An empty port list means two opposite
      * things — nothing is listening in the sandbox, or the machine was told to keep them off — and only the
      * second is worth a word on screen or a button to undo.
      *
      * The MACHINE owns the flag (the agent's `sync mirror off`), because the localhost being written to is
-     * there: a computer told to keep ports off must keep them off while this sandbox is asleep, unreachable, or
+     * there: a device told to keep ports off must keep them off while this sandbox is asleep, unreachable, or
      * arguing. A browser asks for it by running that same command over the machine's `host` capability, so the
      * button and the CLI are one gesture rather than two mechanisms that can disagree.
      *
@@ -213,103 +287,107 @@ export const MachinePairingSchema = z.object({
      * running is only dangerous while nobody knows, so it gets its own word on the line. */
     backupStatus: z.string().optional(),
 });
-export type MachinePairing = z.infer<typeof MachinePairingSchema>;
+export type DevicePairing = z.infer<typeof DevicePairingSchema>;
 /* One sandbox port and what became of it on this machine's localhost. The rows that did NOT make it are the
- * reason this carries a state rather than being a list of live forwards: two sandboxes on one computer routinely
+ * reason this carries a state rather than being a list of live forwards: two sandboxes on one device routinely
  * serve the same dev-server port and only one can own localhost:6480, so the loser's port is simply missing from
  * localhost with nothing anywhere saying why. Today that fact exists only as a line in mirror.log. */
-export const MachinePortStateSchema = z.enum([
+export const DevicePortStateSchema = z.enum([
     // Forwarded: the sandbox's listener answers on this machine's localhost at the same number.
     "mirrored",
     // Another PAIRED SANDBOX got there first (first paired wins), `heldBy` names it, because "busy on this
     // machine" sends people hunting for a process that does not exist.
     "held-by-sandbox",
-    // Something else on this computer already binds the port, a local dev server, another tool. Not ours to
+    // Something else on this device already binds the port, a local dev server, another tool. Not ours to
     // name, and not ours to take.
     "busy",
 ]);
-export const MachinePortSchema = z.object({
+export const DevicePortSchema = z.object({
     port: z.number().int().min(1).max(65535),
     host: z.enum(["127.0.0.1", "::1"]),
     // The sandbox serving the port, whose /ports listed it, not whoever ended up holding the local bind.
     sandboxId: z.string(),
-    state: MachinePortStateSchema,
+    state: DevicePortStateSchema,
     // Set only for "held-by-sandbox": the sandbox id that owns the local bind instead.
     heldBy: z.string().optional(),
     // What is listening on the sandbox side ("node …/vite"), for a row the user has to recognise to act on.
     command: z.string().optional(),
 });
-export type MachinePort = z.infer<typeof MachinePortSchema>;
-/* The resident watcher's liveness. This is the field that decides whether everything ELSE in the report is still
- * true: a healthy session list under a dead watcher means new dev-server ports stop appearing on localhost and
- * commits stop arriving in the local clones, while every other row keeps reading exactly as it did. */
-export const MachineWatcherSchema = z.object({
+export type DevicePort = z.infer<typeof DevicePortSchema>;
+/* THE AGENT ON THIS DEVICE, AS ONE BLOCK, because it is one binary and one process.
+ *
+ * It used to be two: `agents: { sync, host }` up in the report, and a `watcher` beside it. That split was a
+ * fiction two merges out of date — `resident.ts` runs a SINGLE process serving the outbound socket per linked
+ * sandbox and the mirror watcher together, from a single `intentic-machine` on disk — and it cost the Devices
+ * view its version chip. The chip read `agents.sync` and labelled it with the ENROLLMENT MODE ("desktop sync
+ * 1.243.0", or the same number as "ports only 1.243.0" on a mirror), so one binary's version wore two product
+ * names and appeared on no row that had never been paired for sync. `agents.host` was never filled by the
+ * report at all: the daemon fills `Device.agentVersion` from the hello frame it already holds.
+ *
+ * So: one block, and every version question about a device is answered inside it.
+ *
+ * `running` also decides whether everything ELSE in the report is still true — a healthy session list under a
+ * dead loop means new dev-server ports stop appearing on localhost and commits stop arriving in the local
+ * clones, while every other row reads exactly as it did the moment before. */
+export const DeviceAgentSchema = z.object({
     running: z.boolean(),
     pid: z.number().int().optional(),
-    /* WHICH BUILD IS ACTUALLY SERVING, stamped into the pidfile by the loop that claimed it, which is the only
-     * place the fact exists: replacing the binary does not touch the running process, so a machine can hold a
-     * current agent and go on serving a months-old one indefinitely. `agents.sync` is the file, this is the
-     * process, and the two differing is a restart somebody is owed (see watcherBuildSkew). Absent when no loop
-     * is running, and when the one running predates the stamp. */
+    /* THE BUILD ON DISK: the file at `~/.intentic/bin/intentic-machine`, asked what it is rather than assumed
+     * (the agent's own installed.ts). Absent on a device with no installed agent at all — a dev run, an `npx`
+     * one, a binary somebody put elsewhere on their PATH — which is "not known", never a version. */
+    installed: z.string().optional(),
+    /* THE BUILD ACTUALLY SERVING, stamped into the pidfile by the loop that claimed it, which is the only place
+     * the fact exists: replacing the binary does not touch the running process, so a device can hold a current
+     * agent and go on serving a months-old one indefinitely. The two differing is a restart somebody is owed
+     * (see agentBuildSkew). Absent when no loop is running, and when the one running predates the stamp. */
     build: z.string().optional(),
-    /* When the watcher last FINISHED a pass, the field that makes `running` mean something. The agent holds its
+    /* When the loop last FINISHED a pass, the field that makes `running` mean something. The agent holds its
      * SSH transport listeners on its own event loop, so a failure that escapes the loop leaves a process that is
      * alive and a loop that is gone: pid present, unit "active", mirroring and the git bridge stopped. Absent
      * means the agent has not reported one (too old to stamp, or its first pass has not landed), which is not
      * the same as stalled, and readers must not treat it as either state. */
     lastTickAt: z.number().optional(),
 });
-export type MachineWatcher = z.infer<typeof MachineWatcherSchema>;
-/* How long a watcher may go without finishing a pass before "running" stops being the honest word for it. Its
- * loop polls every 5s and its slowest step is bounded by two 10s network timeouts per pairing, so a minute is
- * several passes of slack, the same yardstick the Computers view already ages a whole report by.
+export type DeviceAgent = z.infer<typeof DeviceAgentSchema>;
+/* How long the loop may go without finishing a pass before "running" stops being the honest word for it. It
+ * polls every 5s and its slowest step is bounded by two 10s network timeouts per pairing, so a minute is
+ * several passes of slack, the same yardstick the Devices view already ages a whole report by.
  *
  * The rule lives HERE, next to the field, because the terminal and the browser both answer this question and a
- * machine that is "running" in one and "stalled" in the other is worse than either answer alone. */
-export const WATCHER_STALL_AFTER_MS = 60_000;
-export const watcherStalled = (watcher: MachineWatcher, now: number): boolean =>
-    watcher.running && watcher.lastTickAt !== undefined && now - watcher.lastTickAt > WATCHER_STALL_AFTER_MS;
-export const MachineReportSchema = z.object({
+ * device that is "running" in one and "stalled" in the other is worse than either answer alone. */
+export const AGENT_STALL_AFTER_MS = 60_000;
+export const agentStalled = (agent: DeviceAgent, now: number): boolean =>
+    agent.running && agent.lastTickAt !== undefined && now - agent.lastTickAt > AGENT_STALL_AFTER_MS;
+export const DeviceReportSchema = z.object({
     /* The OS hostname, and the JOIN KEY. A machine can arrive here two ways at once, volunteered by its sync
      * agent, and read through its `host` capability, and those two know it by different names (the enrolled
      * key's comment vs. the capability id the user typed). The hostname is the one thing both can state about
      * the same box, so it is what dedupes them into a single row. */
     hostname: z.string(),
     os: z.string(),
-    /* Which agents this machine has, and at what version, so one on an old build is visible rather than
-     * mysteriously lacking a field. Same argument as HostSummary.version.
-     *
-     * `sync` is the agent INSTALLED here — the file on disk — and `watcher.build` beside it is the loop running
-     * from that file. It used to be neither: whichever process happened to build the report stamped its own
-     * version here, so the same machine answered its running build to a sandbox its loop posted to and its
-     * installed build to one that ran `status --json` over a host capability. One field, two meanings, and the
-     * gap between them — a machine updated but never restarted — invisible in both.
-     *
-     * `host` is what the live socket announced (so: what is running), filled by the daemon at merge time from
-     * the hello frame it already holds, never by the sync agent, which would have to go reading another agent's
-     * config to guess at it. */
-    agents: z.object({ sync: z.string().optional(), host: z.string().optional() }),
     // Filled by the READER, never the agent (see above). Empty is the resting state: no Docker on the machine,
     // or nothing has looked. Neither is an error, and neither means "no sandboxes exist".
-    sandboxes: z.array(MachineSandboxSchema),
-    pairings: z.array(MachinePairingSchema),
-    ports: z.array(MachinePortSchema),
-    watcher: MachineWatcherSchema,
+    sandboxes: z.array(DeviceSandboxSchema),
+    pairings: z.array(DevicePairingSchema),
+    ports: z.array(DevicePortSchema),
+    // The one agent this device runs, on disk and in flight, in one block (see DeviceAgentSchema for why it is
+    // one and not the `agents` map plus a `watcher` it replaced).
+    agent: DeviceAgentSchema,
     // When the machine took this reading. NOT when the daemon received it. A report is a snapshot from a box
     // that may since have gone to sleep, and the UI ages it against this rather than presenting it as now.
     capturedAt: z.number(),
 });
-export type MachineReport = z.infer<typeof MachineReportSchema>;
+export type DeviceReport = z.infer<typeof DeviceReportSchema>;
 
 /* THE AGENT THIS MACHINE INSTALLED AND THE ONE IT IS RUNNING, when they are not the same build — the whole of
  * "you updated the agent and nothing changed", as a value.
  *
- * It is one comparison, and it lives HERE for the same reason watcherStalled does: the terminal (`intentic-machine
- * status`) and the browser (the Computers row) both answer this question, and a machine that is behind in one and
+ * It is one comparison, and it lives HERE for the same reason agentStalled does: the terminal (`intentic-machine
+ * status`) and the browser (the Devices row) both answer this question, and a machine that is behind in one and
  * fine in the other is worse than either answer alone. The remedy is the same in both: restart the loop.
  *
  * AN UNSTAMPED LOOP IS THE LOUDEST CASE, not a missing one, and reading it as "nothing to say" is what let this
- * whole check miss the machines it was written for. `watcher.build` is stamped into the pidfile by the loop that
+ * whole check miss the machines it was written for. `agent.build` is stamped into the pidfile by the loop that
  * claimed it, so a loop old enough to predate the stamp reports none — and it is running, and something newer is
  * installed beside it, which is a skew by definition and a wider one than any it could have named. Every surface
  * therefore went quiet on precisely the machines furthest behind: upgrade, see the new number everywhere, watch
@@ -317,20 +395,19 @@ export type MachineReport = z.infer<typeof MachineReportSchema>;
  *
  * So the running build is OPTIONAL in the answer and the question is asked of the installed one. Still silent
  * whenever the honest answer is "no idea": a loop that is stopped (nothing is serving, and every surface already
- * says so in louder words), a machine with no installed agent to compare against, and a working-tree build, which
+ * says so in louder words), a device with no installed agent to compare against, and a working-tree build, which
  * is not a version and must not be told it is behind. */
-export const watcherBuildSkew = (report: MachineReport): { readonly running: string | undefined; readonly installed: string } | undefined => {
-    const running = report.watcher.build;
-    const installed = report.agents.sync;
-    if (!report.watcher.running || installed === undefined || installed === DEV_VERSION || running === installed) {
+export const agentBuildSkew = (agent: DeviceAgent): { readonly running: string | undefined; readonly installed: string } | undefined => {
+    const { build: running, installed } = agent;
+    if (!agent.running || installed === undefined || installed === DEV_VERSION || running === installed) {
         return undefined;
     }
     return { running, installed };
 };
 
-// Why a computer that is plainly THERE has no report to show. Each is a different errand for the reader, which is
+// Why a device that is plainly THERE has no report to show. Each is a different errand for the reader, which is
 // the whole reason they are not collapsed into one "unavailable".
-export const ComputerGapSchema = z.enum([
+export const DeviceGapSchema = z.enum([
     // A host capability that is enrolled but has no socket right now. Laptops sleep; this is not a fault.
     "offline",
     // Connected, but "Run commands" is switched off on its capability card, so the daemon may not ask it
@@ -342,8 +419,8 @@ export const ComputerGapSchema = z.enum([
     // machine reports. Distinct from "no-agent" because the agent IS there and the folders ARE syncing.
     "unreported",
 ]);
-export type ComputerGap = z.infer<typeof ComputerGapSchema>;
-/* ONE COMPUTER, however the sandbox happens to be able to see it, and it may be both ways at once.
+export type DeviceGap = z.infer<typeof DeviceGapSchema>;
+/* ONE DEVICE, however the sandbox happens to be able to see it, and it may be both ways at once.
  *
  * A machine reaches a sandbox through two independent doors: a desktop-sync enrollment (which volunteers its own
  * report) and a `host` capability (which the daemon can ask). They know the same box by different names, the
@@ -357,14 +434,14 @@ export type ComputerGap = z.infer<typeof ComputerGapSchema>;
  * ever used the enrollment, and how to name it when they want it gone. Those three lived on /system/sync
  * instead, as one machine's worth of `syncingFrom` plus a list of `mirroredBy` names, which is the sandbox-level
  * shape this view exists to stop being: one card claiming a sandbox has A desktop sync, over a list of the
- * several computers that actually do.
+ * several devices that actually do.
  *
  * `machine` is the enrollment's own name for the box (the ssh key's comment). It is what the reports are filed
  * under, and it is the id the revoke route takes — the same string, so a row can revoke exactly the enrollment
  * it is drawn from. Two machines that present the same comment share one enrollment identity throughout the
  * daemon (reports included); that is a pre-existing property of naming machines by their key comment, and this
  * field inherits it rather than inventing a second identity that would disagree with the first. */
-export const ComputerSyncSchema = z.object({
+export const DeviceSyncSchema = z.object({
     machine: z.string(),
     /* Which half. "sync" is files AND ports and is SINGLE-HOLDER for the sandbox; "mirror" is ports only and any
      * number of machines may hold one. The row says which, because "your laptop is paired" is read as the first
@@ -374,24 +451,24 @@ export const ComputerSyncSchema = z.object({
     // has, which is exactly what a setup that did not finish leaves behind, and must not read as healthy.
     seenAt: z.number().optional(),
 });
-export type ComputerSync = z.infer<typeof ComputerSyncSchema>;
-export const ComputerSchema = z.object({
+export type DeviceSync = z.infer<typeof DeviceSyncSchema>;
+export const DeviceSchema = z.object({
     // Stable row key: the reported hostname when either door produced one, else the name that door knows it by.
     key: z.string(),
     // What to call it on screen, the user's own name for the machine wherever one exists.
     label: z.string(),
-    // The desktop-sync enrollment this machine holds with this sandbox, absent when it has none (a computer
+    // The desktop-sync enrollment this machine holds with this sandbox, absent when it has none (a device
     // reached only through its `host` capability).
-    sync: ComputerSyncSchema.optional(),
-    // The host capability's id, when this machine is also a connected computer. Absent otherwise.
+    sync: DeviceSyncSchema.optional(),
+    // The host capability's id, when this machine is also a connected device. Absent otherwise.
     hostId: z.string().optional(),
     // Host-capability liveness. Absent when there is no host capability, which is NOT the same as offline.
     online: z.boolean().optional(),
-    /* WHAT THE COMPUTER IS, as distinct from how it is reachable, the half a row used to leave out entirely,
+    /* WHAT THE DEVICE IS, as distinct from how it is reachable, the half a row used to leave out entirely,
      * so a Windows laptop and a Linux desktop were two identical lines of text with different names on them.
      *
      * It is carried BESIDE the report rather than inside it because the rows that need it most are the ones with
-     * no report: a connected computer with no sync agent, or one that is asleep, still knows its own OS. Nothing
+     * no report: a connected device with no sync agent, or one that is asleep, still knows its own OS. Nothing
      * here depends on an agent being installed, and the daemon has held all of it since the machine connected.
      *
      * `platform` is the slug this side classifies the machine by, the host capability's own card ("windows",
@@ -399,24 +476,30 @@ export const ComputerSchema = z.object({
      * machine's connect-time description of ITSELF, which is what says which Windows and which shell. */
     platform: z.string().optional(),
     facts: HostFactsSchema.optional(),
-    // The host agent's version and when the machine last held a socket, how a connected computer AGES. An old
-    // agent explains a row that lacks something newer machines have, and "last seen" is the one honest thing an
-    // offline row can still say about itself.
-    hostAgent: z.string().optional(),
+    /* The agent version the socket ANNOUNCED at connect, and when the device last held one: how a connected
+     * device AGES. An old agent explains a row that lacks something newer devices have, and "last seen" is the
+     * one honest thing an offline row can still say about itself.
+     *
+     * It is the same number as `report.agent.build` whenever both are known — one resident process stamps its
+     * `MACHINE_VERSION` into the pidfile and sends it in the hello frame — and it is kept because it is the
+     * ONLY version a row with no report has: a device whose "Run commands" switch is off, or which has no
+     * agent to answer `status --json`, still told us what it was when it dialled. That is what stops the
+     * Devices view's agent chip going blank on exactly the rows that need explaining. */
+    agentVersion: z.string().optional(),
     lastSeen: z.number().optional(),
-    report: MachineReportSchema.optional(),
-    gap: ComputerGapSchema.optional(),
+    report: DeviceReportSchema.optional(),
+    gap: DeviceGapSchema.optional(),
 });
-export type Computer = z.infer<typeof ComputerSchema>;
-export const ComputersListSchema = z.object({ computers: z.array(ComputerSchema) });
+export type Device = z.infer<typeof DeviceSchema>;
+export const DevicesListSchema = z.object({ devices: z.array(DeviceSchema) });
 /* GET /system/sync: what desktop sync is doing for this sandbox, WITHOUT naming any one machine as the answer.
  *
  * It used to carry `syncingFrom` + `syncSeenAt` + `mirroredBy`, which is the enrollment list flattened into one
  * holder and a list of everybody else — the shape a card that believed a sandbox has A desktop sync needed, and
- * the reason that card kept restating facts the Computers list beside it already had per machine. Every one of
- * those now rides on the machine's own row (ComputerSync), where a reader can act on it.
+ * the reason that card kept restating facts the Devices list beside it already had per machine. Every one of
+ * those now rides on the machine's own row (DeviceSync), where a reader can act on it.
  *
- * What is left is what is genuinely about the SANDBOX rather than about any computer: whether sync is possible
+ * What is left is what is genuinely about the SANDBOX rather than about any device: whether sync is possible
  * here at all, whether anything at all is enrolled, and the raw reports, which is the cheap ambient read the
  * rail's badge lives on (it must never fan out to somebody's laptop just to decide whether to draw a chip). */
 export const SyncStatusSchema = z.object({
@@ -427,6 +510,6 @@ export const SyncStatusSchema = z.object({
      * surface now, so a sandbox that can answer this read can also sync. Kept as a field rather than assumed,
      * because the card branches on it and a daemon too old to say is one that should not be offered sync. */
     available: z.boolean().optional(),
-    machines: z.array(MachineReportSchema).optional(),
+    machines: z.array(DeviceReportSchema).optional(),
 });
 export type SyncStatus = z.infer<typeof SyncStatusSchema>;

package/src/schemas/hosts.ts

@@ -1,4 +1,4 @@
-// hosts: the user's own connected computers (the `host` capability's live half)
+// hosts: the user's own connected devices (the `host` capability's live half)
 import { z } from "zod";
 // 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
@@ -18,6 +18,10 @@ export const HostFactsSchema = z.object({
     home: z.string(),
     // Roots in force right now (the capability's `roots`, or [home]), the agent sees its own boundary.
     roots: z.array(z.string()),
+    /* The Docker ENGINE's size — the WSL guest on Windows, the Desktop VM on macOS, the host on Linux — which
+     * is the ceiling a sandbox's share is bounded by, and the number a Resources dialog draws its limits from.
+     * Absent when the machine has no docker to ask, which is a machine that runs no sandboxes anyway. */
+    engine: z.object({ memoryBytes: z.number(), cpus: z.number() }).optional(),
 });
 export type HostFacts = z.infer<typeof HostFactsSchema>;
 export const HostSummarySchema = z.object({

package/src/schemas/issues.ts

@@ -234,10 +234,6 @@ export const IssuePublicConfigSchema = z.object({
 });
 export type IssuePublicConfig = z.infer<typeof IssuePublicConfigSchema>;
 
-// The proof-of-work challenge, the same shape and the same solver as the Front Desk's.
-export const IssueChallengeSchema = z.object({ salt: z.string(), difficulty: z.number().int().positive() });
-export type IssueChallenge = z.infer<typeof IssueChallengeSchema>;
-
 /* What the intake answers with. A short reference the reporter can be shown ("we filed this as 4f3a…"), and
  * nothing else: whether this crash is new, how often it has happened and whether it woke anybody are the
  * owner's facts, and the caller is a stranger's browser. */

package/src/schemas/personas.ts

@@ -44,7 +44,7 @@ import { SkillDraftSchema, SkillNameSchema, SystemPromptModeSchema } from "./set
  * what it said after the SDK renames something.
  *
  * TWO STRENGTHS, AND THE DIFFERENCE IS VISIBLE FROM HERE. Everything capability-shaped (`connectors`,
- * `computers`, `mcp`, and the accounts in `capabilities`) is enforced by ABSENCE, the credential is never
+ * `devices`, `mcp`, and the accounts in `capabilities`) is enforced by ABSENCE, the credential is never
  * injected, the server never mounted, the browser never launched, which is the same mechanism the account
  * filter already uses and needs no cooperation from the model. The plain switches are enforced by taking the
  * tools out of the turn's context, which holds for every tool the harness owns and cannot reach a program the
@@ -99,7 +99,7 @@ export const PersonaPowersSchema = z.object({
      * whole reason these are optional rather than defaulted arrays, "all" and "none" are both real answers and
      * an empty default could only spell one of them. */
     connectors: z.array(entryId).max(100).optional(),
-    computers: z.array(entryId).max(50).optional(),
+    devices: z.array(entryId).max(50).optional(),
     mcp: z.array(entryId).max(50).optional(),
 });
 export type PersonaPowers = z.infer<typeof PersonaPowersSchema>;
@@ -155,6 +155,11 @@ export const PersonaSchema = z.object({
         "What a conversation wearing it may do. Absent means the full toolbox, so a card written before this existed behaves exactly as it did.",
     ),
     workspace: PersonaWorkspaceSchema.optional().describe("Where it works. Absent means the whole workspace."),
+    /* WHICH PART OF THE WORKSPACE A SESSION WEARING THIS CARD CARRIES, the id of a context shelf
+     * (schemas/context.ts). A different question from `workspace.folders`: that one fences what the file tools
+     * may TOUCH inside a tree that holds everything, this one decides what the tree HOLDS. Absent falls through to
+     * the sandbox's `contextShelf` setting, and from there to everything. */
+    context: entryId.optional().describe("Which context shelf a conversation wearing it opens on: the part of the workspace it carries. Absent follows the sandbox setting."),
     /* WHICH SYSTEM PROMPT A SESSION WEARING THIS CARD RUNS ON, the same three bases the sandbox chooses
      * between, asked per card. ABSENT is the fourth answer and the default: follow the sandbox, which is what
      * every card meant before this field existed and what almost every card will go on meaning.
@@ -218,7 +223,7 @@ export const personaBounds = (persona: Persona): string => {
         !resolved.delegate,
         !resolved.sandbox,
         resolved.connectors !== undefined,
-        resolved.computers !== undefined,
+        resolved.devices !== undefined,
         resolved.mcp !== undefined,
     ].filter(Boolean).length;
     return limits === 0 ? "Full powers" : `${limits} limit${limits === 1 ? "" : "s"}`;