@intentic/sandbox-contract 1.338.0 → 1.340.0

package/src/protocol/doors/phone-links.ts

@@ -18,6 +18,10 @@ const PAIRING_PREFIX = "ixp1_";
 // that offers it. The code rides the fragment, which no server ever receives, so no access log holds a live pairing.
 export const PHONE_PAIR_LINK = "https://intentic.dev/phone/pair";
 
+// A watch has no camera to scan with, so its code is scanned by the phone beside it: this link opens Intentic Device on
+// that phone, which sends the code on to the watch instead of pairing itself. The code inside is the same.
+export const WATCH_PAIR_LINK = "https://intentic.dev/watch/pair";
+
 const base64url = (value: string): string => btoa(value).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
 
 export const phonePairingCode = (pairing: { readonly url: string; readonly token: string }): string =>
@@ -26,12 +30,17 @@ export const phonePairingCode = (pairing: { readonly url: string; readonly token
 export const phonePairingLink = (pairing: { readonly url: string; readonly token: string }): string =>
     `${PHONE_PAIR_LINK}#${phonePairingCode(pairing)}`;
 
+export const watchPairingLink = (pairing: { readonly url: string; readonly token: string }): string =>
+    `${WATCH_PAIR_LINK}#${phonePairingCode(pairing)}`;
+
 // The phone's side, and the editor's for a pasted code; undefined for anything not one of ours. Accepts the bare code
-// or the whole link, since a person may paste either.
+// or the whole link (a phone's or a watch's), since a person may paste either.
 export const parsePhonePairingCode = (input: string): { readonly url: string; readonly token: string } | undefined => {
     const trimmed = input.trim();
     // The site serves the page with a trailing slash, so a link copied out of the browser may carry one.
-    const linked = [`${PHONE_PAIR_LINK}#`, `${PHONE_PAIR_LINK}/#`].find((prefix) => trimmed.startsWith(prefix));
+    const linked = [`${PHONE_PAIR_LINK}#`, `${PHONE_PAIR_LINK}/#`, `${WATCH_PAIR_LINK}#`, `${WATCH_PAIR_LINK}/#`].find((prefix) =>
+        trimmed.startsWith(prefix),
+    );
     const code = linked === undefined ? trimmed : trimmed.slice(linked.length);
     if (!code.startsWith(PAIRING_PREFIX)) {
         return undefined;

package/src/protocol/doors/phone-protocol.test.ts

@@ -4,7 +4,7 @@ import { packageRoot } from "@intentic/constants/node";
 import { OkSchema } from "../../schemas/shared.js";
 import { PhoneFactsSchema, PhoneScopesSchema } from "../../schemas/phone.js";
 import { PHONE_ERROR, PhoneHelloSchema, PhoneRequestSchema, PhoneResponseSchema } from "./phone-protocol.js";
-import { parsePhonePairingCode, phoneConnectUrl, phoneEnrollUrl, phonePairingCode, phonePairingLink } from "./phone-links.js";
+import { parsePhonePairingCode, phoneConnectUrl, phoneEnrollUrl, phonePairingCode, phonePairingLink, watchPairingLink } from "./phone-links.js";
 
 // The phone door's wire as examples, spelled once here: golden/phone-wire.json is this file's `wire` as JSON, and both
 // far ends test against it — the daemon's JSON-RPC link (_sandbox/sandbox/src/phones/json-rpc-link.test.ts) sends
@@ -123,6 +123,13 @@ test("a pairing round-trips as a code and as the link the QR carries", () => {
     expect(parsePhonePairingCode(phonePairingLink(pairing).replace("/pair#", "/pair/#"))).toEqual(pairing);
 });
 
+test("a watch's link carries the same code, under the path its phone hands on", () => {
+    const pairing = { url: "https://sandbox-abc.sbx.intentic.dev", token: "one-time" };
+    expect(watchPairingLink(pairing)).toBe(`https://intentic.dev/watch/pair#${phonePairingCode(pairing)}`);
+    expect(parsePhonePairingCode(watchPairingLink(pairing))).toEqual(pairing);
+    expect(parsePhonePairingCode(watchPairingLink(pairing).replace("/pair#", "/pair/#"))).toEqual(pairing);
+});
+
 test("a code that is not ours, or carries no usable url or token, is refused rather than attempted", () => {
     expect(parsePhonePairingCode("ixb1_abc")).toBeUndefined();
     expect(parsePhonePairingCode("ixp1_not-base64!")).toBeUndefined();

package/src/schemas/agents-list.ts

@@ -22,3 +22,16 @@ export const AgentsListSchema = z.object({
         ),
 });
 export type AgentsList = z.infer<typeof AgentsListSchema>;
+
+// What the fleet owes its owner, counted by the board's own rules (models/agent-lanes.ts `fleetAttention`): what the
+// desktop app's status bar and `ic sandbox attention` read over the loopback port, so neither has to fetch the whole
+// roster and fold it the way the board does.
+export const AgentsAttentionSchema = z.object({
+    needsYou: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("How many cards the board's Attention lane draws (a child agent counted through its family's one card), plus the automations waiting for a yes."),
+    working: z.number().int().nonnegative().describe("How many conversations are producing something right now."),
+});
+export type AgentsAttention = z.infer<typeof AgentsAttentionSchema>;

package/src/schemas/devices.ts

@@ -104,6 +104,13 @@ export const DeviceSandboxSchema = z.object({
     // (2026-10-10) Stopped by the machine's keeper after a stretch nobody needed it (`ic sandbox sleep`), and started
     // again by itself when somebody opens it. `running` is false while this is true.
     asleep: z.boolean().optional(),
+    // (2026-10-16) How this machine reaches it with no network (ic's sandbox/loopback.rs): its 12-hex id from its connect
+    // token (null without one), the host port its loopback listener is published on (null when it publishes none), and
+    // the platform's own id for its row as its last announce said (null before one did). Absent from an older ic, and
+    // from a row whose container docker would not inspect.
+    sandboxId: z.string().nullable().optional(),
+    localPort: z.number().int().nullable().optional(),
+    platformId: z.string().nullable().optional(),
 });
 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

package/src/schemas/intentic-os.test.ts

@@ -3,7 +3,39 @@ import { join } from "node:path";
 import { packageRoot } from "@intentic/constants/node";
 import { DeviceFactsSchema } from "./hosts.js";
 import {
+    displayModeArg,
+    IC_OS_DRIVE_NO_ROOM_EXIT,
+    IC_OS_NO_SCREEN_EXIT,
+    IC_OS_NOT_INTENTIC_OS_EXIT,
+    IC_OS_WIFI_PASSWORD_EXIT,
     icOsChannelArgs,
+    icOsDisplayListArgs,
+    icOsDisplaySetArgs,
+    icOsDriveEjectArgs,
+    icOsDriveImportArgs,
+    icOsDrivesListArgs,
+    icOsKeyboardLayoutsArgs,
+    icOsKeyboardSetArgs,
+    icOsKeyboardStatusArgs,
+    icOsNetworkStatusArgs,
+    icOsSoundOutputArgs,
+    icOsSoundOutputsArgs,
+    icOsSoundSetArgs,
+    icOsSoundStatusArgs,
+    icOsWifiConnectArgs,
+    icOsWifiForgetArgs,
+    icOsWifiListArgs,
+    icOsWifiRadioArgs,
+    IntenticOsDisplayListSchema,
+    IntenticOsDriveImportProgressSchema,
+    IntenticOsDriveImportSchema,
+    IntenticOsDrivesSchema,
+    IntenticOsKeyboardLayoutsSchema,
+    IntenticOsKeyboardStatusSchema,
+    IntenticOsNetworkStatusSchema,
+    IntenticOsSoundOutputsSchema,
+    IntenticOsSoundStatusSchema,
+    IntenticOsWifiListSchema,
     icOsRebootArgs,
     icOsRollbackArgs,
     icOsStatusArgs,
@@ -25,6 +57,7 @@ const GOLDEN = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "golde
     readonly release: unknown;
     readonly status: readonly Readonly<Record<string, unknown>>[];
     readonly updateCheck: readonly Readonly<Record<string, unknown>>[];
+    readonly [settings: string]: unknown;
 };
 
 test("every status and update check in the golden reads back field for field", () => {
@@ -84,3 +117,118 @@ test("a channel ic does not have never reaches it, even past the type", () => {
         expect(() => icOsChannelArgs(channel as IntenticOsChannel), channel).toThrow();
     }
 });
+
+/* THE MACHINE'S SETTINGS: the network, sound, screens, keyboard and drives, as ic's settings verbs print them. */
+
+test("every settings answer in the golden reads back field for field", () => {
+    const readers = {
+        networkStatus: IntenticOsNetworkStatusSchema,
+        wifiList: IntenticOsWifiListSchema,
+        soundStatus: IntenticOsSoundStatusSchema,
+        soundOutputs: IntenticOsSoundOutputsSchema,
+        displayList: IntenticOsDisplayListSchema,
+        keyboardStatus: IntenticOsKeyboardStatusSchema,
+        keyboardLayouts: IntenticOsKeyboardLayoutsSchema,
+        drives: IntenticOsDrivesSchema,
+        driveImportProgress: IntenticOsDriveImportProgressSchema,
+        driveImport: IntenticOsDriveImportSchema,
+    } as const;
+    for (const [key, schema] of Object.entries(readers)) {
+        const examples = GOLDEN[key];
+        expect(Array.isArray(examples), key).toBe(true);
+        // SAFETY: checked to be an array just above.
+        for (const example of examples as unknown[]) {
+            const read: unknown = schema.parse(example);
+            expect(read, key).toEqual(example);
+        }
+    }
+});
+
+test("the status bar's two shapes are exactly what it reads, and nothing looser", () => {
+    expect(IntenticOsNetworkStatusSchema.safeParse({ connected: true, kind: "wifi", name: "x", signal: 101 }).success).toBe(false);
+    expect(IntenticOsNetworkStatusSchema.safeParse({ connected: true, kind: "cellular", name: "x", signal: null }).success).toBe(false);
+    expect(IntenticOsSoundStatusSchema.safeParse({ volume: -1, muted: false, output: null }).success).toBe(false);
+    expect(IntenticOsSoundStatusSchema.safeParse({ volume: 40.5, muted: false, output: null }).success).toBe(false);
+});
+
+test("the exit codes a caller tells apart are distinct", () => {
+    const codes = [IC_OS_NOT_INTENTIC_OS_EXIT, IC_OS_NO_SCREEN_EXIT, IC_OS_WIFI_PASSWORD_EXIT, IC_OS_DRIVE_NO_ROOM_EXIT];
+    expect(new Set(codes).size).toBe(codes.length);
+    expect(codes).not.toContain(0);
+    expect(codes).not.toContain(1);
+});
+
+test("the settings argv is ic's own verbs, and a password never rides on it", () => {
+    expect(icOsNetworkStatusArgs()).toEqual(["os", "network", "status", "--json"]);
+    expect(icOsWifiListArgs()).toEqual(["os", "network", "wifi", "list", "--json"]);
+    expect(icOsWifiConnectArgs("Home Fiber", false)).toEqual(["os", "network", "wifi", "connect", "--", "Home Fiber"]);
+    expect(icOsWifiConnectArgs("-guest", true)).toEqual(["os", "network", "wifi", "connect", "--password-stdin", "--", "-guest"]);
+    expect(icOsWifiForgetArgs("Office")).toEqual(["os", "network", "wifi", "forget", "--", "Office"]);
+    expect(icOsWifiRadioArgs(false)).toEqual(["os", "network", "wifi", "off"]);
+    expect(icOsWifiRadioArgs(true)).toEqual(["os", "network", "wifi", "on"]);
+    expect(icOsSoundStatusArgs()).toEqual(["os", "sound", "status", "--json"]);
+    expect(icOsSoundSetArgs({ volume: 40 })).toEqual(["os", "sound", "set", "--volume", "40", "--json"]);
+    expect(icOsSoundSetArgs({ volume: 39.6, muted: false })).toEqual(["os", "sound", "set", "--volume", "40", "--unmute", "--json"]);
+    expect(icOsSoundSetArgs({ muted: true })).toEqual(["os", "sound", "set", "--mute", "--json"]);
+    expect(icOsSoundOutputsArgs()).toEqual(["os", "sound", "outputs", "--json"]);
+    expect(icOsSoundOutputArgs(58)).toEqual(["os", "sound", "output", "58"]);
+    expect(icOsDisplayListArgs()).toEqual(["os", "display", "list", "--json"]);
+    expect(icOsDisplaySetArgs("DP-2", { mode: { width: 1920, height: 1080, refresh: 59.94 } })).toEqual([
+        "os",
+        "display",
+        "set",
+        "DP-2",
+        "--mode",
+        "1920x1080@59.94",
+    ]);
+    expect(icOsDisplaySetArgs("eDP-1", { scale: 1.25 })).toEqual(["os", "display", "set", "eDP-1", "--scale", "1.25"]);
+    expect(displayModeArg({ width: 2256, height: 1504, refresh: 59.9994 })).toBe("2256x1504@59.999");
+    expect(displayModeArg({ width: 3840, height: 2160, refresh: 60 })).toBe("3840x2160@60");
+    expect(icOsKeyboardStatusArgs()).toEqual(["os", "keyboard", "status", "--json"]);
+    expect(icOsKeyboardLayoutsArgs()).toEqual(["os", "keyboard", "layouts", "--json"]);
+    expect(icOsKeyboardSetArgs("de", "nodeadkeys")).toEqual(["os", "keyboard", "set", "de", "--variant", "nodeadkeys"]);
+    expect(icOsKeyboardSetArgs("us")).toEqual(["os", "keyboard", "set", "us"]);
+    expect(icOsDrivesListArgs()).toEqual(["os", "drives", "list", "--json"]);
+    expect(icOsDriveImportArgs("/dev/sda1", "work")).toEqual(["os", "drives", "import", "/dev/sda1", "--to", "work", "--json"]);
+    expect(icOsDriveImportArgs("/dev/sda1", "work", "Photos/2026")).toEqual([
+        "os",
+        "drives",
+        "import",
+        "/dev/sda1",
+        "--to",
+        "work",
+        "--path",
+        "Photos/2026",
+        "--json",
+    ]);
+    expect(icOsDriveEjectArgs("/dev/sdb1")).toEqual(["os", "drives", "eject", "/dev/sdb1"]);
+});
+
+test("a value that would reach ic as a flag, a path out, or nothing to change never does", () => {
+    const refused: (() => readonly string[])[] = [
+        () => icOsWifiConnectArgs("", false),
+        () => icOsWifiConnectArgs("x".repeat(33), false),
+        // 11 two-byte letters is 22 characters' worth of bytes past 32, though only 17 characters.
+        () => icOsWifiForgetArgs("ü".repeat(17)),
+        () => icOsSoundSetArgs({}),
+        () => icOsSoundSetArgs({ volume: 101 }),
+        () => icOsSoundOutputArgs(-1),
+        () => icOsDisplaySetArgs("--all", { scale: 1 }),
+        () => icOsDisplaySetArgs("DP-2", {}),
+        () => icOsDisplaySetArgs("DP-2", { scale: 9 }),
+        () => icOsKeyboardSetArgs("-de"),
+        () => icOsKeyboardSetArgs("de", "x y"),
+        () => icOsDriveImportArgs("/etc/passwd", "work"),
+        () => icOsDriveImportArgs("/dev/../etc", "work"),
+        () => icOsDriveImportArgs("/dev/sda1", "--rm"),
+        () => icOsDriveImportArgs("/dev/sda1", "a..b"),
+        () => icOsDriveImportArgs("/dev/sda1", "work", "../history"),
+        () => icOsDriveImportArgs("/dev/sda1", "work", "/etc"),
+        () => icOsDriveImportArgs("/dev/sda1", "work", "a//b"),
+        () => icOsDriveEjectArgs("sda"),
+    ];
+    for (const [index, call] of refused.entries()) {
+        expect(call, String(index)).toThrow();
+    }
+    expect(icOsWifiForgetArgs("ü".repeat(16))).toHaveLength(6);
+});

package/src/schemas/intentic-os.ts

@@ -128,3 +128,262 @@ export const icOsRebootArgs = (): string[] => ["os", "reboot"];
 // Checked here too, not only by a caller's schema: a channel is a positional, and one beginning with a hyphen would
 // reach ic as a flag.
 export const icOsChannelArgs = (channel: IntenticOsChannel): string[] => ["os", "channel", IntenticOsChannelSchema.parse(channel)];
+
+// THE MACHINE'S OWN SETTINGS (2026-10-16): the network, the sound, the screen, the keyboard and the drives a person plugs
+// in, each a verb of `ic os` (_os/README.md, "Settings"). The desktop app's This computer cards, its status bar and the
+// machine agent's tools all read these shapes, so a person and the agent in the machine's own sandbox change the same
+// things the same way ("connect to the guest Wi-Fi"). ic reads NetworkManager, WirePlumber, sway and udisks for them:
+// nothing that calls ic speaks to those.
+
+/** Exit code of the screen verbs (display, keyboard) on an edition with no screen (the server edition). */
+export const IC_OS_NO_SCREEN_EXIT = 4;
+
+/** Exit code of `ic os network wifi connect` when the network needs a password it was not given, or refused the one it
+ *  was: ask the person for it and try again with `--password-stdin`. */
+export const IC_OS_WIFI_PASSWORD_EXIT = 5;
+
+/** Exit code of `ic os drives import` when what is on the drive would not fit in the sandbox: nothing was copied. */
+export const IC_OS_DRIVE_NO_ROOM_EXIT = 6;
+
+// `ic os network status --json`: how this machine is online right now. `name` is the Wi-Fi network's name or the wired
+// connection's, `signal` the Wi-Fi strength 0-100 (null on a wire and offline). The status bar reads exactly this.
+export const IntenticOsNetworkKindSchema = z.enum(["wifi", "ethernet", "none"]);
+export type IntenticOsNetworkKind = z.infer<typeof IntenticOsNetworkKindSchema>;
+
+const percent = z.number().int().min(0).max(100);
+
+export const IntenticOsNetworkStatusSchema = z.object({
+    connected: z.boolean(),
+    kind: IntenticOsNetworkKindSchema,
+    name: z.string().nullable(),
+    signal: percent.nullable(),
+});
+export type IntenticOsNetworkStatus = z.infer<typeof IntenticOsNetworkStatusSchema>;
+
+// One Wi-Fi network in reach, once however many access points broadcast it: the strongest signal, `secured` when it
+// asks for a password, `known` when this machine has joined it before (it rejoins without asking), `active` when it is
+// the one in use.
+export const IntenticOsWifiNetworkSchema = z.object({
+    ssid: z.string(),
+    signal: percent,
+    secured: z.boolean(),
+    known: z.boolean(),
+    active: z.boolean(),
+});
+export type IntenticOsWifiNetwork = z.infer<typeof IntenticOsWifiNetworkSchema>;
+
+// `ic os network wifi list --json`: `adapter` false on a machine with no Wi-Fi, `enabled` false while Wi-Fi is turned
+// off (then `networks` is empty), the networks strongest first.
+export const IntenticOsWifiListSchema = z.object({
+    adapter: z.boolean(),
+    enabled: z.boolean(),
+    networks: z.array(IntenticOsWifiNetworkSchema),
+});
+export type IntenticOsWifiList = z.infer<typeof IntenticOsWifiListSchema>;
+
+// `ic os sound status --json`: the volume of what plays now, 0-100, whether it is muted, and the speaker or headphones it
+// plays on (null when this machine has none). The status bar reads exactly this.
+export const IntenticOsSoundStatusSchema = z.object({
+    volume: percent,
+    muted: z.boolean(),
+    output: z.string().nullable(),
+});
+export type IntenticOsSoundStatus = z.infer<typeof IntenticOsSoundStatusSchema>;
+
+// `ic os sound outputs --json`: every speaker, headphone and screen that plays sound, `default` on the one in use.
+// `id` is what `ic os sound output <id>` takes; it can change when a device is plugged in again.
+export const IntenticOsSoundOutputSchema = z.object({
+    id: z.number().int().nonnegative(),
+    name: z.string(),
+    default: z.boolean(),
+});
+export type IntenticOsSoundOutput = z.infer<typeof IntenticOsSoundOutputSchema>;
+export const IntenticOsSoundOutputsSchema = z.object({ outputs: z.array(IntenticOsSoundOutputSchema) });
+export type IntenticOsSoundOutputs = z.infer<typeof IntenticOsSoundOutputsSchema>;
+
+// A screen's mode: pixels across and down, and how many times a second it redraws (Hz, to three decimals).
+export const IntenticOsDisplayModeSchema = z.object({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    refresh: z.number().nonnegative(),
+});
+export type IntenticOsDisplayMode = z.infer<typeof IntenticOsDisplayModeSchema>;
+
+// One screen as `ic os display list --json` says it: `name` is the connector (`HDMI-A-1`, `eDP-1`) every other verb
+// names it by, `make` and `model` what the screen says it is (null where it does not), `current` the mode it shows now
+// (null while it is off), `modes` every mode it offers, `scale` how much bigger everything is drawn (null while off).
+export const IntenticOsDisplaySchema = z.object({
+    name: z.string(),
+    make: z.string().nullable(),
+    model: z.string().nullable(),
+    enabled: z.boolean(),
+    current: IntenticOsDisplayModeSchema.nullable(),
+    modes: z.array(IntenticOsDisplayModeSchema),
+    scale: z.number().positive().nullable(),
+});
+export type IntenticOsDisplay = z.infer<typeof IntenticOsDisplaySchema>;
+export const IntenticOsDisplayListSchema = z.object({ outputs: z.array(IntenticOsDisplaySchema) });
+export type IntenticOsDisplayList = z.infer<typeof IntenticOsDisplayListSchema>;
+
+// `ic os keyboard status --json`: the layout in use as xkb names it (`us`, `de`), its variant (`nodeadkeys`, null for
+// the layout's own), and its name for a person ("German (no dead keys)"), null when xkb has none for it.
+export const IntenticOsKeyboardStatusSchema = z.object({
+    layout: z.string(),
+    variant: z.string().nullable(),
+    name: z.string().nullable(),
+});
+export type IntenticOsKeyboardStatus = z.infer<typeof IntenticOsKeyboardStatusSchema>;
+
+export const IntenticOsKeyboardVariantSchema = z.object({ variant: z.string(), name: z.string() });
+export const IntenticOsKeyboardLayoutSchema = z.object({
+    layout: z.string(),
+    name: z.string(),
+    variants: z.array(IntenticOsKeyboardVariantSchema),
+});
+export type IntenticOsKeyboardLayout = z.infer<typeof IntenticOsKeyboardLayoutSchema>;
+// `ic os keyboard layouts --json`: every layout xkb knows, in its own order, each with its variants.
+export const IntenticOsKeyboardLayoutsSchema = z.object({ layouts: z.array(IntenticOsKeyboardLayoutSchema) });
+export type IntenticOsKeyboardLayouts = z.infer<typeof IntenticOsKeyboardLayoutsSchema>;
+
+// What kind of removable drive: a USB stick or disk, or a memory card in a card reader.
+export const IntenticOsDriveKindSchema = z.enum(["usb", "card", "other"]);
+export type IntenticOsDriveKind = z.infer<typeof IntenticOsDriveKindSchema>;
+
+// One removable drive's filesystem (a partition, or the whole stick when it has none) as `ic os drives list --json`
+// says it: `device` is what the other drive verbs take, `label` the name it was given (null for none), `size` in bytes,
+// `filesystem` as Linux names it (`vfat`, `exfat`, `ntfs`, `ext4`), `mountedAt` where it is open (null while it is
+// not), `model` what the drive says it is. The machine's own disks are never listed.
+export const IntenticOsDriveSchema = z.object({
+    device: z.string(),
+    label: z.string().nullable(),
+    size: z.number().int().nonnegative(),
+    filesystem: z.string().nullable(),
+    mountedAt: z.string().nullable(),
+    readOnly: z.boolean(),
+    model: z.string().nullable(),
+    kind: IntenticOsDriveKindSchema,
+});
+export type IntenticOsDrive = z.infer<typeof IntenticOsDriveSchema>;
+export const IntenticOsDrivesSchema = z.object({ drives: z.array(IntenticOsDriveSchema) });
+export type IntenticOsDrives = z.infer<typeof IntenticOsDrivesSchema>;
+
+// `ic os drives import … --json` prints one of these every few seconds while it copies, then the result last.
+export const IntenticOsDriveImportProgressSchema = z.object({
+    progress: z.object({ bytes: z.number().int().nonnegative(), total: z.number().int().nonnegative() }),
+});
+export type IntenticOsDriveImportProgress = z.infer<typeof IntenticOsDriveImportProgressSchema>;
+
+// What was copied: from which drive, into which sandbox, the folder inside it (`/work/Imports/<label>-<date>`), and how
+// many bytes in how many files.
+export const IntenticOsDriveImportSchema = z.object({
+    device: z.string(),
+    sandbox: z.string(),
+    path: z.string(),
+    bytes: z.number().int().nonnegative(),
+    files: z.number().int().nonnegative(),
+});
+export type IntenticOsDriveImport = z.infer<typeof IntenticOsDriveImportSchema>;
+
+// The pieces a caller hands ic as positionals and flag values, checked here before they reach its command line: none may
+// begin with a hyphen (it would be a flag), and none is a path out of where it belongs. An SSID is anything a network
+// broadcasts, so it goes after `--` instead.
+const OUTPUT_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+const XKB_NAME = /^[A-Za-z0-9][A-Za-z0-9_+-]{0,63}$/;
+const BLOCK_DEVICE = /^\/dev\/[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SANDBOX_SLUG = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+
+// An SSID is at most 32 bytes, in whatever characters the network broadcasts.
+export const IntenticOsSsidSchema = z
+    .string()
+    .min(1)
+    .refine((ssid) => new TextEncoder().encode(ssid).length <= 32, "a Wi-Fi network's name, at most 32 bytes");
+export const IntenticOsDisplayNameSchema = z.string().regex(OUTPUT_NAME, "a screen's connector name, like HDMI-A-1");
+export const IntenticOsXkbNameSchema = z.string().regex(XKB_NAME, "an xkb layout or variant name, like de or nodeadkeys");
+export const IntenticOsBlockDeviceSchema = z.string().regex(BLOCK_DEVICE, "a drive's device, like /dev/sdb1");
+export const IntenticOsSandboxSlugSchema = z.string().regex(SANDBOX_SLUG, "a sandbox's slug").refine((slug) => !slug.includes(".."), "a sandbox's slug");
+// A folder inside the sandbox's /work: relative, no `..`, no leading slash or hyphen.
+export const IntenticOsImportPathSchema = z
+    .string()
+    .min(1)
+    .max(255)
+    .refine(
+        (path) => !path.startsWith("/") && !path.startsWith("-") && path.split("/").every((part) => part !== ".." && part !== "." && part !== ""),
+        "a folder inside the sandbox's /work, like Photos/2026",
+    );
+export const IntenticOsScaleSchema = z.number().min(0.5).max(4);
+
+/** A mode the way `ic os display set --mode` takes it: `1920x1080@60`, the rate to three decimals at most. */
+export const displayModeArg = (mode: IntenticOsDisplayMode): string => `${mode.width}x${mode.height}@${Number(mode.refresh.toFixed(3))}`;
+
+export const icOsNetworkStatusArgs = (): string[] => ["os", "network", "status", "--json"];
+export const icOsWifiListArgs = (): string[] => ["os", "network", "wifi", "list", "--json"];
+// The password never: it goes on ic's stdin with `--password-stdin`, since a command line is readable by anyone on the
+// machine (`ps`). Without one, ic joins a known network or one that asks for none, and exits IC_OS_WIFI_PASSWORD_EXIT
+// for one that needs a password.
+export const icOsWifiConnectArgs = (ssid: string, withPassword: boolean): string[] => [
+    "os",
+    "network",
+    "wifi",
+    "connect",
+    ...(withPassword ? ["--password-stdin"] : []),
+    "--",
+    IntenticOsSsidSchema.parse(ssid),
+];
+export const icOsWifiForgetArgs = (ssid: string): string[] => ["os", "network", "wifi", "forget", "--", IntenticOsSsidSchema.parse(ssid)];
+export const icOsWifiRadioArgs = (on: boolean): string[] => ["os", "network", "wifi", on ? "on" : "off"];
+
+export const icOsSoundStatusArgs = (): string[] => ["os", "sound", "status", "--json"];
+// At least one of the two: a volume 0-100, and muted or not. Answers with the status after (`--json`).
+export const icOsSoundSetArgs = (change: { readonly volume?: number; readonly muted?: boolean }): string[] => {
+    const args = ["os", "sound", "set"];
+    if (change.volume !== undefined) {
+        args.push("--volume", String(percent.parse(Math.round(change.volume))));
+    }
+    if (change.muted !== undefined) {
+        args.push(change.muted ? "--mute" : "--unmute");
+    }
+    if (args.length === 3) {
+        throw new Error("a sound change names a volume, muted, or both");
+    }
+    return [...args, "--json"];
+};
+export const icOsSoundOutputsArgs = (): string[] => ["os", "sound", "outputs", "--json"];
+export const icOsSoundOutputArgs = (id: number): string[] => ["os", "sound", "output", String(z.number().int().nonnegative().parse(id))];
+
+export const icOsDisplayListArgs = (): string[] => ["os", "display", "list", "--json"];
+export const icOsDisplaySetArgs = (output: string, change: { readonly mode?: IntenticOsDisplayMode; readonly scale?: number }): string[] => {
+    const args = ["os", "display", "set", IntenticOsDisplayNameSchema.parse(output)];
+    if (change.mode !== undefined) {
+        args.push("--mode", displayModeArg(IntenticOsDisplayModeSchema.parse(change.mode)));
+    }
+    if (change.scale !== undefined) {
+        args.push("--scale", String(IntenticOsScaleSchema.parse(change.scale)));
+    }
+    if (args.length === 4) {
+        throw new Error("a display change names a mode, a scale, or both");
+    }
+    return args;
+};
+
+export const icOsKeyboardStatusArgs = (): string[] => ["os", "keyboard", "status", "--json"];
+export const icOsKeyboardLayoutsArgs = (): string[] => ["os", "keyboard", "layouts", "--json"];
+export const icOsKeyboardSetArgs = (layout: string, variant?: string): string[] => [
+    "os",
+    "keyboard",
+    "set",
+    IntenticOsXkbNameSchema.parse(layout),
+    ...(variant === undefined ? [] : ["--variant", IntenticOsXkbNameSchema.parse(variant)]),
+];
+
+export const icOsDrivesListArgs = (): string[] => ["os", "drives", "list", "--json"];
+export const icOsDriveImportArgs = (device: string, sandbox: string, path?: string): string[] => [
+    "os",
+    "drives",
+    "import",
+    IntenticOsBlockDeviceSchema.parse(device),
+    "--to",
+    IntenticOsSandboxSlugSchema.parse(sandbox),
+    ...(path === undefined ? [] : ["--path", IntenticOsImportPathSchema.parse(path)]),
+    "--json",
+];
+export const icOsDriveEjectArgs = (device: string): string[] => ["os", "drives", "eject", IntenticOsBlockDeviceSchema.parse(device)];

package/src/schemas/phone.ts

@@ -62,6 +62,9 @@ export const PhoneFactsSchema = z.object({
     sdk: z.number().int(),
     // "direct" (downloaded from intentic.dev, can touch and type) or "play" (the store build, which cannot).
     build: z.string(),
+    // What kind of Android device answered: "watch" for Wear OS, which has no folders and no notification access to
+    // give; absent from an app older than this field, which is a phone. A string, so a newer app's "tablet" still reads.
+    form: z.string().optional(),
     // The pause tile on the phone; true means every tool refuses and says the person paused it.
     paused: z.boolean(),
     // What the person has switched on in Android's own settings for this app.

package/src/schemas/system.ts

@@ -208,8 +208,11 @@ export type DaemonSession = z.infer<typeof DaemonSessionSchema>;
 // How a session's identity was proven. A session carries the set it was minted from; the require-passkey policy reads
 // it on every request, so a session minted before the switch stops working on its next call. `email` is the platform's
 // signed word that the person controls the address (policy/identity-assertion.ts), accepted only where the owner opted
-// that person in, and on hosted machines.
-export const ProofMethodSchema = z.enum(["google", "ticket", "passkey", "recovery", "email"]);
+// that person in, and on hosted machines. `host` is the machine that runs the sandbox: a session `ic sandbox session`
+// minted through `docker exec` for the bound owner, so the desktop app and Intentic OS reach their own sandboxes with no
+// network (the daemon's auth/host/host-session.ts). It is never a sign-in a browser can offer, so no daemon lists it in
+// `signIn.proofs`.
+export const ProofMethodSchema = z.enum(["google", "ticket", "passkey", "recovery", "email", "host"]);
 export type ProofMethod = z.infer<typeof ProofMethodSchema>;
 
 // The `reason` a daemon's refusal of an identity assertion carries beside its `error`, so the editor can say what to do:

package/src/state/history-state.ts

@@ -172,6 +172,9 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
 
     // Signs every browser session cookie; carrying it would let the holder mint sessions against the target.
     { path: "session-secret", portability: "identity", note: "Sign in again, the target signs its own sessions." },
+    // The platform's id for this sandbox's row, as its announce last said (system/boot/platform-row.ts): the target is
+    // its own row, and learns its own id at its first announce.
+    { path: "platform-row.json", portability: "identity", note: "The target learns its own platform id when it first announces." },
     // Who owns this sandbox, who else may reach it and at what tier, and the hashed control tokens programs present:
     // the daemon's to decide, so kept off the workspace every turn writes (auth/members/identity-off-workspace.ts moved
     // them from `.intentic/identity/` on 2026-10-06). An access list that traveled would let a source sandbox hand