@intentic/sandbox-contract 1.332.0 → 1.333.1

package/src/policy/sandbox-power.ts

@@ -0,0 +1,247 @@
+import { inertRegions, isLive } from "../text/shell-regions.js";
+import type { CommandSpan } from "./command-classes.js";
+
+// A SHELL COMMAND THAT STARTS, STOPS OR REPLACES A SANDBOX CONTAINER (2026-10-12). `ic sandbox restart work` and
+// `docker stop intentic-sandbox-work` end the same turns the device tools manage_sandbox and swap_sandbox end, but they
+// arrive as text in run_command, where no tool name says what they are. This reads that text once, for both ends that
+// have to answer it: the daemon, which asks the owner before an agent cuts the sandbox it runs in while others are
+// working (hosts/host-restart-guard.ts), and the device agent, whose "Manage sandboxes" switch decides whether anything
+// may do this at all (the machine's tools/shell.ts). The same verbs and the same wording, so a command and the tool
+// that does the same job cannot drift apart.
+
+/** The sandbox operations a command can name, in the words `ic sandbox` spells them. */
+export type SandboxPowerOp =
+    | "start"
+    | "stop"
+    | "restart"
+    | "sleep"
+    | "remove"
+    | "update"
+    | "prepare"
+    | "rebuild"
+    | "rollback"
+    | "dev"
+    | "resize"
+    | "restore"
+    | "connect";
+
+/** The owner's own word for an operation, as a card or a refusal says it ("<doing> this sandbox now?"). */
+export const SANDBOX_POWER_DOING = {
+    start: "Start",
+    stop: "Stop",
+    restart: "Restart",
+    sleep: "Stop",
+    remove: "Remove",
+    update: "Update",
+    prepare: "Prepare an update for",
+    rebuild: "Rebuild",
+    rollback: "Roll back",
+    dev: "Update",
+    resize: "Restart with new resources",
+    restore: "Restore a backup over",
+    connect: "Reinstall",
+} as const satisfies Record<SandboxPowerOp, string>;
+
+/** One command that manages a sandbox container, and what it aims at. */
+export interface SandboxPowerCommand {
+    readonly via: "ic" | "docker";
+    readonly op: SandboxPowerOp;
+    /** Whether it ends the turns of a sandbox that is running; false for a start, a download, a resource ask saved for later. */
+    readonly stops: boolean;
+    /** The slugs (`ic`) or container names (`docker`) it names, as written; an expansion (`$x`, `$(…)`, `*`) stays as typed. */
+    readonly targets: readonly string[];
+    /** Names none: `ic sandbox restart` alone (the only sandbox the device runs), `remove --all`, `docker stop` fed from a pipe. */
+    readonly unnamed: boolean;
+    /** The fragment, so a card can point at it. */
+    readonly span: CommandSpan;
+    /** Whether a shell would run it, as against a quoted argument of echo or a comment. */
+    readonly live: boolean;
+}
+
+// `ic sandbox <verb>`: the program may be a full path, `ic.exe`, or quoted (`& 'C:\…\ic.exe' sandbox restart work`).
+const IC_INVOCATION = /(?<![\w.$-])ic(?:\.exe)?["']?\s+sandbox\s+([a-z][a-z-]*)(?![\w-])/gi;
+// `docker stop`, `docker container rm`, podman alike. A global option between the program and the verb
+// (`docker -H host stop x`) is not read: the verb then follows an option, and the command is left unrecognised.
+const DOCKER_INVOCATION = /(?<![\w.$-])(?:docker|podman)(?:\.exe)?["']?\s+(?:container\s+)?(stop|restart|rm|remove|kill)(?![\w-])/gi;
+
+const IC_VERBS = new Map<string, SandboxPowerOp>([
+    ["start", "start"],
+    ["stop", "stop"],
+    ["restart", "restart"],
+    ["sleep", "sleep"],
+    ["remove", "remove"],
+    ["rm", "remove"],
+    ["update", "update"],
+    ["prepare", "prepare"],
+    ["rebuild", "rebuild"],
+    ["rollback", "rollback"],
+    ["dev", "dev"],
+    ["reshape", "resize"],
+    ["shape", "resize"],
+    ["backup-restore", "restore"],
+    ["connect", "connect"],
+]);
+
+const DOCKER_VERBS = new Map<string, SandboxPowerOp>([
+    ["stop", "stop"],
+    ["kill", "stop"],
+    ["restart", "restart"],
+    ["rm", "remove"],
+    ["remove", "remove"],
+]);
+
+// The flags of each program that take their value as the next word, so the value is not read as a slug.
+const IC_VALUE_FLAGS: ReadonlySet<string> = new Set([
+    "--channel",
+    "--to",
+    "--set",
+    "--when",
+    "--memory",
+    "--cpus",
+    "--privileged",
+    "--gpus",
+    "--idle",
+    "--source",
+    "--code",
+    "--snapshot",
+    "--into",
+    "--confirm",
+    "--accept",
+    "--tail",
+]);
+const DOCKER_VALUE_FLAGS: ReadonlySet<string> = new Set(["-t", "--time", "-s", "--signal"]);
+
+// The simple command that starts the text: up to the first `|`, `;`, `&` or newline outside quotes. A `&` right after
+// `>` or `<` is a redirection (`2>&1`), which ends nothing.
+const SIMPLE_COMMAND = /^(?:[^|;&\n\r"']|(?<=[<>])&|"[^"]*"?|'[^']*'?)*/;
+// One word, quoted pieces included. Backslashes stay as written: they are Windows path separators as often as escapes,
+// and a slug has neither.
+const WORD = /(?:[^\s"']|"[^"]*"?|'[^']*'?)+/g;
+const REDIRECTION = /^\d*(?:>>?|<)/;
+const BARE_REDIRECTION = /^\d*(?:>>?|<)$/;
+
+const wordsOf = (text: string): string[] => [...(SIMPLE_COMMAND.exec(text)?.[0] ?? "").matchAll(WORD)].map((word) => word[0].replace(/["']/g, ""));
+
+// A redirection (`2>&1`, `> log`, `>>out`) is not an operand; a bare `>` takes the word after it with it.
+const withoutRedirections = (words: readonly string[]): string[] => {
+    const kept: string[] = [];
+    let skipNext = false;
+    for (const word of words) {
+        if (skipNext) {
+            skipNext = false;
+        } else if (BARE_REDIRECTION.test(word)) {
+            skipNext = true;
+        } else if (!REDIRECTION.test(word)) {
+            kept.push(word);
+        }
+    }
+    return kept;
+};
+
+interface Operands {
+    readonly positionals: readonly string[];
+    /** Flags as written, `--flag=value` split: name → value (undefined for a switch). */
+    readonly flags: ReadonlyMap<string, string | undefined>;
+}
+
+const operandsOf = (words: readonly string[], valueFlags: ReadonlySet<string>): Operands => {
+    const positionals: string[] = [];
+    const flags = new Map<string, string | undefined>();
+    const list = withoutRedirections(words);
+    for (const [index, word] of list.entries()) {
+        const equals = word.indexOf("=");
+        if (!word.startsWith("-") || word === "-") {
+            // The word after a flag that takes a value is that value, not an operand.
+            if (!valueFlags.has(list[index - 1] ?? "")) {
+                positionals.push(word);
+            }
+        } else if (word.startsWith("--") && equals !== -1) {
+            flags.set(word.slice(0, equals), word.slice(equals + 1));
+        } else {
+            flags.set(word, valueFlags.has(word) ? list[index + 1] : undefined);
+        }
+    }
+    return { positionals, flags };
+};
+
+interface Aim {
+    readonly stops: boolean;
+    readonly targets: readonly string[];
+    readonly all: boolean;
+}
+
+// What `ic sandbox <op>` with these operands does to a running sandbox, and which sandboxes it aims at. The verbs that
+// restart nothing say so: a start, a download, a resource ask saved for the next restart, a backup restored to a folder.
+const icAim = (op: SandboxPowerOp, { positionals, flags }: Operands): Aim => {
+    const all = flags.has("--all") || flags.has("-a");
+    if (op === "start" || op === "prepare") {
+        return { stops: false, targets: positionals, all };
+    }
+    if (op === "resize") {
+        // `reshape --later` and `--forget` save an ask and restart nothing; `shape` restarts only with `--when now`.
+        const when = flags.get("--when");
+        const saves = flags.has("--later") || flags.has("--forget") || (when !== undefined && when !== "now");
+        return { stops: !saves, targets: positionals, all };
+    }
+    if (op === "restore") {
+        // A backup restored into a folder touches no sandbox; `--into <slug>` stops that one to write its volumes.
+        const into = flags.get("--into");
+        return into === undefined ? { stops: false, targets: [], all: false } : { stops: true, targets: [into], all: false };
+    }
+    if (op === "connect") {
+        return { stops: flags.has("--replace"), targets: [], all: false };
+    }
+    return { stops: true, targets: positionals, all };
+};
+
+/**
+ * Every command in `command` that starts, stops or replaces a sandbox container, through `ic sandbox` or `docker`.
+ * A scan for the programs by name, not a shell parse: it is meant to over-include, since a caller that mistakes
+ * a mention for a command asks the owner once, and one that misses a command cuts a fleet's turns unasked.
+ */
+export const sandboxPowerCommands = (command: string): SandboxPowerCommand[] => {
+    const regions = inertRegions(command);
+    const found: SandboxPowerCommand[] = [];
+    for (const invocation of command.matchAll(IC_INVOCATION)) {
+        const op = IC_VERBS.get((invocation[1] ?? "").toLowerCase());
+        if (op !== undefined) {
+            const span = { start: invocation.index, end: invocation.index + invocation[0].length };
+            const aim = icAim(op, operandsOf(wordsOf(command.slice(span.end)), IC_VALUE_FLAGS));
+            found.push({ via: "ic", op, stops: aim.stops, targets: aim.targets, unnamed: aim.targets.length === 0 || aim.all, span, live: isLive(span, regions) });
+        }
+    }
+    for (const invocation of command.matchAll(DOCKER_INVOCATION)) {
+        const op = DOCKER_VERBS.get((invocation[1] ?? "").toLowerCase());
+        if (op !== undefined) {
+            const span = { start: invocation.index, end: invocation.index + invocation[0].length };
+            const { positionals } = operandsOf(wordsOf(command.slice(span.end)), DOCKER_VALUE_FLAGS);
+            found.push({ via: "docker", op, stops: true, targets: positionals, unnamed: positionals.length === 0, span, live: isLive(span, regions) });
+        }
+    }
+    return found.toSorted((left, right) => left.span.start - right.span.start);
+};
+
+// A word whose value exists only when the shell runs it: `$(docker ps -q)`, `$NAME`, `*`, PowerShell's `(…)` and `%X%`.
+const isExpansion = (word: string): boolean => /[$`*?%]|^\(/.test(word);
+
+/** The sandbox a caller means to protect: its slug, and the container name docker knows it by. */
+export interface OwnSandbox {
+    readonly slug: string;
+    readonly container: string;
+}
+
+/**
+ * Whether `hit` may stop `own`. Deliberately generous: it names it, names none (the device's only sandbox, `--all`, a
+ * pipe), or names something that is only worked out when the command runs. A target spelled as the bare slug counts for
+ * `docker` too, which knows the container by a longer name.
+ */
+export const mayReachSandbox = (hit: SandboxPowerCommand, own: OwnSandbox): boolean =>
+    hit.unnamed || hit.targets.some((target) => target === own.slug || target === own.container || isExpansion(target));
+
+/**
+ * Whether `hit` manages a sandbox that a device's "Manage sandboxes" switch covers, whichever sandbox it is: any
+ * `ic sandbox` verb here, and a `docker` verb aimed at a container whose name starts with `containerPrefix` (a sandbox's
+ * own, or its tunnel's). A docker target worked out at run time is not read: the device cannot know what it will be.
+ */
+export const managesSandbox = (hit: SandboxPowerCommand, containerPrefix: string): boolean =>
+    hit.via === "ic" || hit.targets.some((target) => target.startsWith(containerPrefix));

package/src/policy/tests/device-programs.test.ts

@@ -0,0 +1,107 @@
+import { commandLineOf, DEVICE_PROGRAM_TOOLS, ProgramArgumentsSchema, programInCall } from "../device-programs.js";
+
+// As the bridge hands it over: the arguments of a tools/call, parsed by the table's own schema.
+const read = (tool: string, args: Record<string, unknown>) => programInCall(tool, ProgramArgumentsSchema.parse(args));
+
+describe("the shell tools", () => {
+    test("run_command carries its command as it was sent", () => {
+        expect(read("run_command", { command: "rm -rf ~/old-builds" })).toEqual({ tool: "run_command", kind: "command", commandLine: "rm -rf ~/old-builds" });
+        expect(read("run_command", { command: "  " })).toBeUndefined();
+        expect(read("run_command", {})).toBeUndefined();
+        expect(read("run_command", { command: 7 })).toBeUndefined();
+    });
+
+    test("android_shell carries the adb program the machine runs for it, and a serial that could hide the rest is left out", () => {
+        expect(read("android_shell", { command: "pm uninstall com.example.app" })).toEqual({
+            tool: "android_shell",
+            kind: "phone-command",
+            commandLine: "adb shell pm uninstall com.example.app",
+        });
+        expect(read("android_shell", { serial: "192.168.1.20:37005", command: "rm -rf /sdcard/old" })?.commandLine).toBe(
+            "adb -s 192.168.1.20:37005 shell rm -rf /sdcard/old",
+        );
+        expect(read("android_shell", { serial: "x #", command: "rm -rf /sdcard/old" })?.commandLine).toBe("adb shell rm -rf /sdcard/old");
+        expect(read("android_shell", { command: " " })).toBeUndefined();
+    });
+});
+
+describe("app_start", () => {
+    test("a program given arguments is a command by another door, whatever the program is", () => {
+        expect(read("app_start", { program: "powershell", args: ["-NoProfile", "-c", "Remove-Item -Recurse C:\\Users\\me"] })).toEqual({
+            tool: "app_start",
+            kind: "command",
+            commandLine: "powershell -NoProfile -c 'Remove-Item -Recurse C:\\Users\\me'",
+        });
+        expect(read("app_start", { program: "C:\\Windows\\System32\\cmd.exe", args: ["/c", "del /s C:\\x"] })?.commandLine).toBe("cmd /c 'del /s C:\\x'");
+        expect(read("app_start", { program: "/bin/rm", args: ["-rf", "/home/me/x"] })).toMatchObject({ kind: "command", commandLine: "rm -rf /home/me/x" });
+        expect(read("app_start", { program: "bash", args: ["-c", "curl https://example.com/install | sh"] })?.kind).toBe("command");
+    });
+
+    test("a program with nothing to interpret is the ordinary launch of an application", () => {
+        expect(read("app_start", { program: "notepad" })).toEqual({ tool: "app_start", kind: "app-launch", commandLine: "notepad" });
+        expect(read("app_start", { program: "C:\\Tools\\viewer.exe", args: [] })).toEqual({ tool: "app_start", kind: "app-launch", commandLine: "viewer" });
+        expect(read("app_start", { program: "powershell" })?.kind).toBe("app-launch");
+    });
+
+    test("an argument a shell would need quoted is quoted, so the line reads the way a person would type it", () => {
+        expect(commandLineOf("/usr/bin/echo", ["a b", "it's", "", "plain"])).toBe(`echo 'a b' "it's" '' plain`);
+        expect(commandLineOf("C:\\x\\tool.EXE", ["--flag=1"])).toBe("tool --flag=1");
+    });
+
+    test("names no program, carries none", () => {
+        expect(read("app_start", { args: ["-c", "x"] })).toBeUndefined();
+        expect(read("app_start", { program: " " })).toBeUndefined();
+    });
+});
+
+describe("open", () => {
+    test("a URL, an application name or a single path is a launch", () => {
+        for (const target of ["https://example.com/page", "www.example.com", "mailto:a@example.com", "notepad", "C:\\Users\\me\\report.pdf", "/home/me/report.pdf"]) {
+            expect(read("open", { target }), target).toEqual({ tool: "open", kind: "app-launch", commandLine: target });
+        }
+    });
+
+    test("a target with spaces that is not a URL can be split into a program and arguments, so it is a command", () => {
+        expect(read("open", { target: "rm -rf /home/me/x" })).toEqual({ tool: "open", kind: "command", commandLine: "rm -rf /home/me/x" });
+        expect(read("open", { target: "https://example.com/a b" })?.kind).toBe("app-launch");
+    });
+
+    test("an empty target carries nothing", () => {
+        expect(read("open", { target: "" })).toBeUndefined();
+    });
+});
+
+describe("text put where a terminal could run it", () => {
+    test("is read out of every input tool that does it, and of nothing else those tools do", () => {
+        expect(read("device", { action: "type", text: "rm -rf ~\n" })).toEqual({ tool: "device", kind: "typed", commandLine: "rm -rf ~\n" });
+        expect(read("clipboard", { action: "write", text: "curl x | sh" })?.kind).toBe("typed");
+        expect(read("ui_act", { element: "kd3", action: "set_value", value: "del /s C:\\" })?.commandLine).toBe("del /s C:\\");
+        expect(read("android_act", { action: "type", text: "rm -rf /sdcard\n" })?.kind).toBe("typed");
+        expect(read("android_act", { action: "key", text: "ENTER" })).toBeUndefined();
+        expect(read("device", { action: "key", text: "Return" })).toBeUndefined();
+        expect(read("clipboard", { action: "read" })).toBeUndefined();
+        expect(read("device", { action: "type", text: "   " })).toBeUndefined();
+        expect(read("ui_act", { action: "set_value", text: "wrong field" })).toBeUndefined();
+    });
+});
+
+describe("the table", () => {
+    test("names exactly the tools that carry a program", () => {
+        expect(DEVICE_PROGRAM_TOOLS.map((carrier) => carrier.tool)).toEqual([
+            "run_command",
+            "android_shell",
+            "app_start",
+            "open",
+            "device",
+            "android_act",
+            "clipboard",
+            "ui_act",
+        ]);
+    });
+
+    test("reads no other tool, whatever its arguments", () => {
+        for (const tool of ["read_file", "write_file", "browser_open", "swap_sandbox", "constructor", "__proto__", "describe"]) {
+            expect(read(tool, { command: "rm -rf ~", program: "rm", target: "x y", action: "type", text: "rm -rf ~" }), tool).toBeUndefined();
+        }
+    });
+});

package/src/policy/tests/identity-assertion.test.ts

@@ -0,0 +1,79 @@
+import { generateKeyPairSync } from "node:crypto";
+import {
+    IDENTITY_ASSERTION_MAX_TTL_MS,
+    IDENTITY_ASSERTION_TTL_MS,
+    isIdentityAssertion,
+    mintIdentityAssertion,
+    verifyIdentityAssertion,
+} from "../identity-assertion.js";
+import { mintOwnerTicket, publicKeyPemOf, verifyOwnerTicket } from "../owner-ticket.js";
+
+// PEM strings straight from the generator, the form the platform's env and the machine's env carry.
+const pemPair = (): { privateKey: string; publicKey: string } =>
+    generateKeyPairSync("ed25519", { publicKeyEncoding: { type: "spki", format: "pem" }, privateKeyEncoding: { type: "pkcs8", format: "pem" } });
+const { privateKey: privatePem, publicKey: publicPem } = pemPair();
+const NOW = 1_800_000_000_000;
+const SANDBOX = "0123456789ab";
+
+const mint = (overrides: Partial<Parameters<typeof mintIdentityAssertion>[1]> = {}): string =>
+    mintIdentityAssertion(privatePem, { sandboxId: SANDBOX, email: "Ada@Example.org", method: "email", issuedAtMs: NOW, ...overrides });
+
+describe("identity assertion", () => {
+    it("round-trips the claim, lowercased, and expires when it says", () => {
+        const assertion = mint();
+        expect(isIdentityAssertion(assertion)).toBe(true);
+        expect(verifyIdentityAssertion(publicPem, assertion, NOW + 1_000)).toEqual({
+            sandboxId: SANDBOX,
+            email: "ada@example.org",
+            method: "email",
+            issuedAt: NOW / 1000,
+            expiresAt: (NOW + IDENTITY_ASSERTION_TTL_MS) / 1000,
+            nonce: expect.stringMatching(/^[A-Za-z0-9_-]{22}$/),
+        });
+        expect(verifyIdentityAssertion(publicPem, assertion, NOW + IDENTITY_ASSERTION_TTL_MS)).toBeUndefined();
+    });
+
+    it("gives every mint its own nonce, so a daemon can spend each once", () => {
+        const first = verifyIdentityAssertion(publicPem, mint(), NOW);
+        const second = verifyIdentityAssertion(publicPem, mint(), NOW);
+        expect(first?.nonce).not.toBe(second?.nonce);
+    });
+
+    it("verifies against the public half derived from the platform's private key", () => {
+        expect(verifyIdentityAssertion(publicKeyPemOf(privatePem), mint({ method: "google" }), NOW)).toMatchObject({ method: "google" });
+    });
+
+    it("refuses another key's signature, a tampered claim, and garbage", () => {
+        const other = pemPair().publicKey;
+        const assertion = mint();
+        expect(verifyIdentityAssertion(other, assertion, NOW)).toBeUndefined();
+        const [prefix, , signature] = assertion.split(".");
+        const forged = Buffer.from(
+            JSON.stringify({ v: 1, sub: SANDBOX, email: "eve@example.org", amr: "email", iat: NOW / 1000, exp: NOW / 1000 + 60, jti: "x".repeat(22) }),
+        ).toString("base64url");
+        expect(verifyIdentityAssertion(publicPem, `${prefix}.${forged}.${signature}`, NOW)).toBeUndefined();
+        expect(verifyIdentityAssertion(publicPem, "pa1.not.base64", NOW)).toBeUndefined();
+        expect(verifyIdentityAssertion(publicPem, `${assertion}.extra`, NOW)).toBeUndefined();
+        expect(isIdentityAssertion("ot1.x.y")).toBe(false);
+    });
+
+    it("refuses a claim issued more than a minute ahead of the daemon's clock", () => {
+        expect(verifyIdentityAssertion(publicPem, mint({ issuedAtMs: NOW + 61_000 }), NOW)).toBeUndefined();
+        expect(verifyIdentityAssertion(publicPem, mint({ issuedAtMs: NOW + 59_000 }), NOW)).toMatchObject({ email: "ada@example.org" });
+    });
+
+    /* One key could sign tickets and assertions if an operator reused it; neither may pass as the other. */
+    it("is never an owner ticket, and an owner ticket is never an assertion", () => {
+        const ticket = mintOwnerTicket(privatePem, { sandboxId: SANDBOX, email: "ada@example.org", issuedAtMs: NOW });
+        expect(verifyIdentityAssertion(publicPem, ticket, NOW)).toBeUndefined();
+        expect(verifyIdentityAssertion(publicPem, `pa1.${ticket.slice("ot1.".length)}`, NOW)).toBeUndefined();
+        expect(verifyOwnerTicket(publicPem, mint(), NOW)).toBeUndefined();
+    });
+
+    it("refuses to mint for anything but a real sandbox id, an address, and a short life", () => {
+        expect(() => mint({ sandboxId: "nope" })).toThrow("12-hex sandbox id");
+        expect(() => mint({ email: " " })).toThrow("names an address");
+        expect(() => mint({ ttlMs: IDENTITY_ASSERTION_MAX_TTL_MS + 1 })).toThrow("lives at most");
+        expect(() => mint({ ttlMs: 0 })).toThrow("lives at most");
+    });
+});

package/src/policy/tests/sandbox-power.test.ts

@@ -0,0 +1,181 @@
+import { managesSandbox, mayReachSandbox, SANDBOX_POWER_DOING, type SandboxPowerCommand, sandboxPowerCommands } from "../sandbox-power.js";
+
+const OWN = { slug: "work", container: "intentic-sandbox-work" };
+const PREFIX = "intentic-sandbox-";
+
+// What a command aims at, without the spans: the verb, whether it ends a running sandbox's turns, and who it names.
+const aimOf = (hit: SandboxPowerCommand | undefined) => hit && { via: hit.via, op: hit.op, stops: hit.stops, targets: hit.targets, unnamed: hit.unnamed };
+const first = (command: string) => aimOf(sandboxPowerCommands(command)[0]);
+
+describe("ic sandbox", () => {
+    test("reads every verb that ends a running sandbox's turns, with the slug it names", () => {
+        expect(first("ic sandbox restart work")).toEqual({ via: "ic", op: "restart", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox stop work")).toEqual({ via: "ic", op: "stop", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox rm work")).toEqual({ via: "ic", op: "remove", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox remove work -y")).toEqual({ via: "ic", op: "remove", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox rebuild work 3f2a")).toEqual({ via: "ic", op: "rebuild", stops: true, targets: ["work", "3f2a"], unnamed: false });
+        expect(first("ic sandbox update work --no-resume")).toEqual({ via: "ic", op: "update", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox rollback work --to 1.315.0")).toEqual({ via: "ic", op: "rollback", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox sleep work")).toEqual({ via: "ic", op: "sleep", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox dev work")).toEqual({ via: "ic", op: "dev", stops: true, targets: ["work"], unnamed: false });
+    });
+
+    test("a start, a download and a resource ask saved for later are managing the sandbox but ending nothing", () => {
+        expect(first("ic sandbox start work")).toEqual({ via: "ic", op: "start", stops: false, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox prepare work --auto")).toEqual({ via: "ic", op: "prepare", stops: false, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox reshape work --memory 12g --later")?.stops).toBe(false);
+        expect(first("ic sandbox reshape work --forget")?.stops).toBe(false);
+        expect(first("ic sandbox shape work --set cpus=4 --when next-restart")?.stops).toBe(false);
+        expect(first("ic sandbox shape work --set cpus=4 --when nextRestart")?.stops).toBe(false);
+    });
+
+    test("a resource change applied now restarts, and so does a bare reshape, which applies what was saved", () => {
+        expect(first("ic sandbox reshape work --memory 12g")).toEqual({ via: "ic", op: "resize", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox reshape work")?.stops).toBe(true);
+        expect(first("ic sandbox shape work --set cpus=4 --when now")).toEqual({ via: "ic", op: "resize", stops: true, targets: ["work"], unnamed: false });
+        expect(first("ic sandbox shape work --when=now --set cpus=4")?.stops).toBe(true);
+    });
+
+    test("a flag's value is not a slug, so a command naming no sandbox reads as naming none", () => {
+        expect(first("ic sandbox update --channel stable")).toEqual({ via: "ic", op: "update", stops: true, targets: [], unnamed: true });
+        expect(first("ic sandbox rollback --to 1.315.0")).toEqual({ via: "ic", op: "rollback", stops: true, targets: [], unnamed: true });
+        expect(first("ic sandbox restart")).toEqual({ via: "ic", op: "restart", stops: true, targets: [], unnamed: true });
+        expect(first("ic sandbox restart 2>&1")?.unnamed).toBe(true);
+        expect(first("ic sandbox remove --all -y")?.unnamed).toBe(true);
+    });
+
+    test("a backup restored into a sandbox stops it; restored to a folder it touches none", () => {
+        expect(first("ic sandbox backup-restore work --snapshot latest --into work -y")).toEqual({
+            via: "ic",
+            op: "restore",
+            stops: true,
+            targets: ["work"],
+            unnamed: false,
+        });
+        expect(first("ic sandbox backup-restore work --snapshot latest --into other")?.targets).toEqual(["other"]);
+        expect(first("ic sandbox backup-restore work --snapshot latest --to /tmp/look")?.stops).toBe(false);
+    });
+
+    test("reinstalling over a sandbox ends it, and names no slug the command line shows", () => {
+        expect(first("ic sandbox connect --replace -y abc123")).toEqual({ via: "ic", op: "connect", stops: true, targets: [], unnamed: true });
+        expect(first("ic sandbox connect -y abc123")?.stops).toBe(false);
+    });
+
+    test("reads the program however a shell is told to find it", () => {
+        for (const command of [
+            "ic.exe sandbox restart work",
+            "& 'C:\\Users\\radar\\.intentic\\bin\\ic.exe' sandbox restart work",
+            '& "C:\\Users\\radar\\.intentic\\bin\\ic.exe" sandbox restart work',
+            "~/.intentic/bin/ic sandbox restart work",
+            "sudo ic sandbox restart work",
+            "cd /tmp && ic sandbox restart work",
+            "wsl -d archlinux -- ic sandbox restart work",
+            "IC SANDBOX RESTART work",
+        ]) {
+            expect(first(command), command).toMatchObject({ via: "ic", op: "restart", targets: ["work"] });
+        }
+    });
+
+    test("leaves alone what only reads, and words that merely end in ic", () => {
+        for (const command of [
+            "ic sandbox list --json",
+            "ic sandbox logs work --tail 50",
+            "ic sandbox doctor work",
+            "ic sandbox versions work",
+            "intentic sandbox restart work",
+            "magic sandbox restart work",
+            "ic runner remove build",
+            "git commit -m 'document how ic works'",
+        ]) {
+            expect(sandboxPowerCommands(command), command).toEqual([]);
+        }
+    });
+
+    test("stops reading at the end of the simple command, so a later command's words are not this one's operands", () => {
+        expect(first("ic sandbox restart work; echo done")?.targets).toEqual(["work"]);
+        expect(first("ic sandbox restart | tee log")?.unnamed).toBe(true);
+        expect(first("ic sandbox restart work && ic sandbox start other")?.targets).toEqual(["work"]);
+        expect(sandboxPowerCommands("ic sandbox restart work && ic sandbox start other").map((hit) => hit.targets)).toEqual([["work"], ["other"]]);
+    });
+
+    test("marks a command that only appears as text as not live", () => {
+        expect(sandboxPowerCommands("echo 'ic sandbox restart work'")[0]?.live).toBe(false);
+        expect(sandboxPowerCommands("# ic sandbox restart work")[0]?.live).toBe(false);
+        expect(sandboxPowerCommands("ic sandbox restart work")[0]?.live).toBe(true);
+        expect(sandboxPowerCommands("ic sandbox restart work")[0]?.span).toEqual({ start: 0, end: "ic sandbox restart".length });
+    });
+});
+
+describe("docker", () => {
+    test("reads a stop, kill, restart or remove of a container, with the names it gives", () => {
+        expect(first("docker stop intentic-sandbox-work")).toEqual({ via: "docker", op: "stop", stops: true, targets: ["intentic-sandbox-work"], unnamed: false });
+        expect(first("docker kill intentic-sandbox-work")?.op).toBe("stop");
+        expect(first("docker restart intentic-sandbox-work")?.op).toBe("restart");
+        expect(first("docker rm -f intentic-sandbox-work")).toEqual({ via: "docker", op: "remove", stops: true, targets: ["intentic-sandbox-work"], unnamed: false });
+        expect(first("docker container stop -t 60 a b")).toEqual({ via: "docker", op: "stop", stops: true, targets: ["a", "b"], unnamed: false });
+        expect(first("docker.exe stop a")?.targets).toEqual(["a"]);
+        expect(first("podman rm a")?.via).toBe("docker");
+    });
+
+    test("leaves alone docker that stops nothing", () => {
+        for (const command of ["docker ps", "docker logs intentic-sandbox-work", "docker start intentic-sandbox-work", "docker exec c kill -9 1", "docker compose stop"]) {
+            expect(sandboxPowerCommands(command), command).toEqual([]);
+        }
+    });
+
+    test("a stop fed from a pipe names nothing", () => {
+        expect(first("docker ps -q | xargs docker stop")).toEqual({ via: "docker", op: "stop", stops: true, targets: [], unnamed: true });
+    });
+});
+
+describe("whether a command may reach this sandbox", () => {
+    const reaches = (command: string): boolean => sandboxPowerCommands(command).some((hit) => mayReachSandbox(hit, OWN));
+
+    test("names it by slug or by container", () => {
+        expect(reaches("ic sandbox restart work")).toBe(true);
+        expect(reaches("docker stop intentic-sandbox-work")).toBe(true);
+        // docker knows no such container, but a card for a mistaken match costs less than a fleet cut unasked
+        expect(reaches("docker stop work")).toBe(true);
+    });
+
+    test("names none, or something that is only worked out when it runs", () => {
+        expect(reaches("ic sandbox update")).toBe(true);
+        expect(reaches("ic sandbox remove --all")).toBe(true);
+        expect(reaches("docker stop $(docker ps -q)")).toBe(true);
+        expect(reaches('docker stop "$SANDBOX"')).toBe(true);
+        expect(reaches("docker stop (docker ps -q)")).toBe(true);
+        expect(reaches("docker rm intentic-sandbox-*")).toBe(true);
+        expect(reaches("ic sandbox restart %NAME%")).toBe(true);
+    });
+
+    test("names another sandbox, or another container", () => {
+        expect(reaches("ic sandbox restart other")).toBe(false);
+        expect(reaches("ic sandbox rebuild other 3f2a")).toBe(false);
+        expect(reaches("docker stop intentic-sandbox-other")).toBe(false);
+        expect(reaches("docker restart postgres")).toBe(false);
+        expect(reaches("ic sandbox update --channel stable other")).toBe(false);
+    });
+});
+
+describe("whether a command manages a sandbox the switch covers", () => {
+    const manages = (command: string): boolean => sandboxPowerCommands(command).some((hit) => managesSandbox(hit, PREFIX));
+
+    test("any ic sandbox verb, whichever sandbox it names", () => {
+        expect(manages("ic sandbox restart other")).toBe(true);
+        expect(manages("ic sandbox start other")).toBe(true);
+        expect(manages("ic sandbox update")).toBe(true);
+    });
+
+    test("docker only for a container that is a sandbox's, since the device cannot know a name worked out at run time", () => {
+        expect(manages("docker stop intentic-sandbox-other")).toBe(true);
+        expect(manages("docker rm -f intentic-sandbox-tunnel-abc")).toBe(true);
+        expect(manages("docker restart postgres")).toBe(false);
+        expect(manages("docker stop $(docker ps -q)")).toBe(false);
+    });
+});
+
+test("every operation has the owner's word for it", () => {
+    expect(SANDBOX_POWER_DOING.restart).toBe("Restart");
+    expect(SANDBOX_POWER_DOING.resize).toBe("Restart with new resources");
+    expect(SANDBOX_POWER_DOING.rollback).toBe("Roll back");
+});

package/src/protocol/doors/runner-protocol.ts

@@ -154,6 +154,13 @@ export const RunnerSummarySchema = z.object({
     drift: z.array(NeedsActionSchema).optional(),
 });
 export type RunnerSummary = z.infer<typeof RunnerSummarySchema>;
+// GET /system/runners: every enrolled runner, the one list the Devices view, the placement picker and the Access tab read.
+export const RunnersListSchema = z.object({ runners: z.array(RunnerSummarySchema) });
+export type RunnersList = z.infer<typeof RunnersListSchema>;
+// What a runner answers when it takes a definition (`applyDefinition`), and POST /system/runners/{id}/definition/sync
+// relays: the settings it now runs.
+export const RunnerDefinitionAppliedSchema = z.object({ settings: z.array(z.string()) });
+export type RunnerDefinitionApplied = z.infer<typeof RunnerDefinitionAppliedSchema>;
 
 // A workspace sync, narrated line by line as it happens (first contact clones whole repos). `op`: `pull` brings the
 // runner's checkout current before a turn, `push` returns the branch after; `repos` is the parent's own record, since