@intentic/sandbox-contract 1.332.0 → 1.333.0

package/src/index.ts

@@ -164,6 +164,8 @@ export * from "./models/agent-catalog.js";
 export * from "./policy/capability-env.js";
 export * from "./policy/command-classes.js";
 export * from "./policy/command-run.js";
+export * from "./policy/device-programs.js";
+export * from "./policy/sandbox-power.js";
 export * from "./policy/safety-policy.js";
 export * from "./policy/reserved-servers.js";
 export * from "./policy/credential-material.js";
@@ -205,6 +207,7 @@ export * from "./policy/persona-home.js";
 export * from "./schemas/agents.js";
 export * from "./schemas/speaker.js";
 export * from "./schemas/speech.js";
+export * from "./schemas/voice.js";
 export * from "./schemas/approvals.js";
 export * from "./schemas/automations.js";
 export * from "./schemas/agents-list.js";
@@ -215,6 +218,7 @@ export * from "./schemas/providers/claude-gate.js";
 export * from "./schemas/codebase-health.js";
 export * from "./schemas/context-trim.js";
 export * from "./schemas/devices.js";
+export * from "./schemas/device-swaps.js";
 export * from "./schemas/project-delivery.js";
 export * from "./schemas/device-artifacts.js";
 export * from "./schemas/run-targets.js";
@@ -265,6 +269,7 @@ export * from "./schemas/short-codes.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
 export * from "./schemas/state-plan.js";
+export * from "./schemas/restart-intent.js";
 export * from "./schemas/updates.js";
 export * from "./schemas/terminal.js";
 export * from "./schemas/turn-break.js";
@@ -280,11 +285,13 @@ export * from "./schemas/workspace/workspace-repos.js";
 export * from "./schemas/workspace/workspace-search.js";
 export * from "./schemas/workspace/workspace-setup.js";
 export * from "./schemas/workspace/workspace-tree.js";
+export * from "./schemas/workspace/workspace-upload.js";
 export * from "./state/arrival.js";
 export * from "./state/definition.js";
 export * from "./policy/search-globs.js";
 export * from "./state/starter.js";
 export * from "./text/title.js";
+export * from "./state/update-probation.js";
 export * from "./state/versions.js";
 export * from "./text/model-answer.js";
 export * from "./text/shell-regions.js";

package/src/models/model-roles.ts

@@ -73,6 +73,16 @@ export const MODEL_ROLES = [
         icon: "align-left",
         setup: "low",
     },
+    {
+        // Reads one finished reply (and the ask it answered) and writes what a person hears in hands-free voice: a few
+        // short sentences, never markdown. A fast model matters more than a strong one, since the person is waiting.
+        id: "spoken-reply",
+        label: "Spoken replies",
+        blurb: "The few sentences you hear when you talk to the agent hands-free: what it did and what it needs from you, while the full reply stays on screen.",
+        kind: "helper",
+        icon: "volume-up",
+        setup: "low",
+    },
     {
         // One reading answering both halves of "what does this chat open on": an offered `provider:model` line with an
         // effort and an account, and a persona id, each a classification over a fixed list rather than free text. The

package/src/policy/control-scopes.ts

@@ -36,3 +36,30 @@ export const CONTROL_SCOPE_REACH: readonly ControlScopeReach[] = [
         note: "Separate because the usual arrangement is a program that works and a person who decides.",
     },
 ];
+
+// One control token as the roster lists it: everything but the secret, which the daemon keeps only as a hash.
+export const ControlTokenSummarySchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    scope: ControlScopeSchema,
+    createdAt: z.number(),
+    // The owner or maintainer who minted it, so the roster says whose decision each token was.
+    createdBy: z.string().optional(),
+    // Epoch ms after which the token is refused; absent means it lives until revoked.
+    expiresAt: z.number().optional(),
+    // Epoch ms of the last authorized request, coarse on purpose; absent means never used.
+    lastUsedAt: z.number().optional(),
+});
+export type ControlTokenSummary = z.infer<typeof ControlTokenSummarySchema>;
+export const ControlTokensListSchema = z.object({ tokens: z.array(ControlTokenSummarySchema) });
+
+// POST /system/control/tokens: scope is required, never defaulted; expiry is optional and absent means never.
+export const ControlTokenMintSchema = z.object({
+    scope: ControlScopeSchema,
+    label: z.string().optional(),
+    expiresAt: z.number().optional(),
+});
+export type ControlTokenMint = z.infer<typeof ControlTokenMintSchema>;
+// The raw token, shown exactly once.
+export const ControlTokenMintedSchema = z.object({ id: z.string(), token: z.string() });
+export type ControlTokenMinted = z.infer<typeof ControlTokenMintedSchema>;

package/src/policy/device-programs.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+
+// WHICH DEVICE TOOLS CARRY A PROGRAM (2026-10-12). A command on somebody's own computer arrives by more doors than
+// `run_command`: `app_start` starts a program with arguments, `open` starts whatever its target names (on Linux a
+// target with spaces is split into a program and arguments and spawned), `android_shell` hands a line to a phone's
+// shell, and the input tools put text where a terminal could run it. The daemon's gate used to know two of those by
+// name, the machine's own checks a different few, and `app_start program=powershell args=[…]` slipped past the judge, the
+// card and the unattended refusal. This is the one table both ends read: the tool, and how to lift the command line
+// out of its arguments. A device tool that carries a program is added here, or the machine's test says it is missing.
+
+/**
+ * What a call's program is, which decides how it is read:
+ * - `command`: a command line for the machine's own shell, or a program started with arguments; judged as `run_command`.
+ * - `phone-command`: a line for an attached phone's shell, judged as the `adb shell` program the machine runs for it.
+ * - `app-launch`: an application, URL or document started with nothing to interpret; the ordinary GUI launch, low risk.
+ * - `typed`: text put where a terminal could run it (typed, pasted, set into a field).
+ */
+export type ProgramKind = "command" | "phone-command" | "app-launch" | "typed";
+
+/** The program a tool call carries, as the classifier and the judge read it. */
+export interface ProgramReading {
+    readonly tool: string;
+    readonly kind: ProgramKind;
+    /** The command line as a shell would read it. */
+    readonly commandLine: string;
+}
+
+// The fields of every tool in the table below. One that is the wrong type reads as absent rather than failing the
+// parse: such a call never runs, since the device checks its input against its own schema before anything else.
+export const ProgramArgumentsSchema = z.looseObject({
+    command: z.string().optional().catch(undefined),
+    serial: z.string().optional().catch(undefined),
+    program: z.string().optional().catch(undefined),
+    args: z.array(z.string()).optional().catch(undefined),
+    target: z.string().optional().catch(undefined),
+    action: z.string().optional().catch(undefined),
+    text: z.string().optional().catch(undefined),
+    value: z.string().optional().catch(undefined),
+});
+export type ProgramArguments = z.infer<typeof ProgramArgumentsSchema>;
+
+interface ProgramCarrier {
+    readonly tool: string;
+    /** In words: where the program is in the arguments. */
+    readonly carries: string;
+    readonly read: (args: ProgramArguments) => Omit<ProgramReading, "tool"> | undefined;
+}
+
+const present = (value: string | undefined): string | undefined => (value === undefined || value.trim() === "" ? undefined : value);
+
+// A program by the name it is known by (`rm`, `powershell`), not the path or the `.exe` it was started through.
+const programName = (program: string): string => (program.split(/[/\\]/).at(-1) ?? program).replace(/\.exe$/i, "");
+
+/**
+ * The program and its arguments as the one command line they amount to: the program by its name, each argument quoted
+ * only where a shell would need it, so the line reads the way a person would type it.
+ */
+export const commandLineOf = (program: string, args: readonly string[]): string =>
+    [
+        programName(program),
+        ...args.map((arg) => (arg === "" || /[\s'"|;&<>()$`\\]/.test(arg) ? (arg.includes("'") ? `"${arg}"` : `'${arg}'`) : arg)),
+    ].join(" ");
+
+// A phone's serial as adb prints one (a USB serial, `ip:port`, an mDNS name), and nothing else: a serial is spliced into
+// the program judged below, where a `#` or a quote in it could make the command after it read as inert.
+const ADB_SERIAL = /^[\w.:-]+$/;
+
+// A URL, or `www.`/`mailto:` which the machine opens the same way (desktop-automation's looksLikeUrl).
+const URL_TARGET = /^(?:[a-z][a-z0-9+.-]*:\/\/|www\.|mailto:)/i;
+
+const typedBy = (tool: string, action: string, field: "text" | "value"): ProgramCarrier => ({
+    tool,
+    carries: `${field}, when action is ${action}`,
+    read: (args) => {
+        const typed = args.action === action ? present(args[field]) : undefined;
+        return typed === undefined ? undefined : { kind: "typed", commandLine: typed };
+    },
+});
+
+/** Every device tool that carries a program. */
+export const DEVICE_PROGRAM_TOOLS: readonly ProgramCarrier[] = [
+    {
+        tool: "run_command",
+        carries: "command",
+        read: ({ command }) => {
+            const line = present(command);
+            return line === undefined ? undefined : { kind: "command", commandLine: line };
+        },
+    },
+    {
+        tool: "android_shell",
+        carries: "command, run as `adb [-s serial] shell <command>`",
+        read: ({ command, serial }) => {
+            const line = present(command);
+            if (line === undefined) {
+                return undefined;
+            }
+            return { kind: "phone-command", commandLine: `adb ${serial !== undefined && ADB_SERIAL.test(serial) ? `-s ${serial} ` : ""}shell ${line}` };
+        },
+    },
+    {
+        tool: "app_start",
+        carries: "program and args",
+        read: ({ program, args }) => {
+            const started = present(program);
+            if (started === undefined) {
+                return undefined;
+            }
+            // With nothing to interpret it is a launch; with arguments it is a command by another door, whatever the
+            // program is: `rm -rf ~`, `curl … | sh` and `powershell -c …` read the same here as in run_command.
+            return { kind: args === undefined || args.length === 0 ? "app-launch" : "command", commandLine: commandLineOf(started, args ?? []) };
+        },
+    },
+    {
+        tool: "open",
+        carries: "target",
+        read: ({ target }) => {
+            const opened = present(target);
+            if (opened === undefined) {
+                return undefined;
+            }
+            // A URL or a single word (an application name, a file path) is opened. A target with spaces that is not a URL
+            // can be split into a program and arguments and spawned, so it is read as the command it may be.
+            return { kind: URL_TARGET.test(opened) || !/\s/.test(opened.trim()) ? "app-launch" : "command", commandLine: opened };
+        },
+    },
+    typedBy("device", "type", "text"),
+    typedBy("android_act", "type", "text"),
+    typedBy("clipboard", "write", "text"),
+    typedBy("ui_act", "set_value", "value"),
+];
+
+/** The program a `tools/call` of `tool` carries, or undefined for a tool that carries none or a call with nothing in the place the table looks. */
+export const programInCall = (tool: string, args: ProgramArguments): ProgramReading | undefined => {
+    const read = DEVICE_PROGRAM_TOOLS.find((carrier) => carrier.tool === tool)?.read(args);
+    return read === undefined ? undefined : { tool, ...read };
+};

package/src/policy/identity-assertion.ts

@@ -0,0 +1,130 @@
+import { createPrivateKey, createPublicKey, randomBytes, sign as edSign, verify as edVerify } from "node:crypto";
+import { z } from "zod";
+import { SANDBOX_ID } from "../ids/tunnel-ids.js";
+
+// The platform's signed word that a signed-in person controls an email address, spent on one sandbox's daemon. It is how
+// an address no identity provider vouches for (a custom domain on Fastmail, Proton, a company's own mail server) reaches
+// a sandbox: the platform confirmed the address by mailing it a code, and nobody else could. The daemon accepts it only
+// where its owner opted in for that person (the owner record or the member row says `emailSignIn`), and on hosted
+// machines, where the platform already holds the machine. Signed with a key of its own (IDENTITY_SIGNING_KEY), never the
+// ingress key, so neither credential can stand in for the other.
+
+const ASSERTION_PREFIX = "pa1";
+
+// One round trip to the daemon and a retry; a lifted assertion is dead before anyone reads the log it sat in.
+export const IDENTITY_ASSERTION_TTL_MS = 2 * 60_000;
+// The longest life a daemon accepts whatever the claim says, so a platform minting with a wrong clock or a wrong ttl
+// still cannot hand out a credential that outlives a replay window the daemon can hold in memory.
+export const IDENTITY_ASSERTION_MAX_TTL_MS = 5 * 60_000;
+
+// The env var that carries the platform's identity key on a hosted machine, which boots before its first announce. A
+// sandbox on its owner's own machine learns the same key from the announce answer (`AnnounceAcceptedSchema`).
+export const ENV_PLATFORM_IDENTITY_KEY = "PLATFORM_IDENTITY_KEY";
+
+// How the platform confirmed the address it vouches for: a code it mailed, or a Google sign-in it verified.
+export const IdentityAssertionMethodSchema = z.enum(["email", "google"]);
+export type IdentityAssertionMethod = z.infer<typeof IdentityAssertionMethodSchema>;
+
+// The signed claim, times in seconds like the owner ticket's. `nonce` is unique per mint: the daemon spends each once.
+export interface IdentityAssertion {
+    readonly sandboxId: string;
+    readonly email: string;
+    readonly method: IdentityAssertionMethod;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly nonce: string;
+}
+
+const base64url = (bytes: Buffer): string => bytes.toString("base64url");
+
+// The prefix is part of what is signed, so an assertion is never a valid signature over anything else the same key
+// might one day sign, and an owner ticket or a grant (which sign their bare payload) is never an assertion.
+const signedBytes = (payload: Buffer): Buffer => Buffer.concat([Buffer.from(`${ASSERTION_PREFIX}.`, "utf8"), payload]);
+
+export const isIdentityAssertion = (bearer: string): boolean => bearer.startsWith(`${ASSERTION_PREFIX}.`);
+
+export const mintIdentityAssertion = (
+    privateKeyPem: string,
+    claim: {
+        readonly sandboxId: string;
+        readonly email: string;
+        readonly method: IdentityAssertionMethod;
+        readonly issuedAtMs: number;
+        readonly ttlMs?: number;
+    },
+): string => {
+    if (!SANDBOX_ID.test(claim.sandboxId)) {
+        throw new Error(`an identity assertion names a 12-hex sandbox id, got "${claim.sandboxId}"`);
+    }
+    if (claim.email.trim() === "") {
+        throw new Error("an identity assertion names an address");
+    }
+    const ttlMs = claim.ttlMs ?? IDENTITY_ASSERTION_TTL_MS;
+    if (ttlMs <= 0 || ttlMs > IDENTITY_ASSERTION_MAX_TTL_MS) {
+        throw new Error(`an identity assertion lives at most ${IDENTITY_ASSERTION_MAX_TTL_MS} ms`);
+    }
+    const iat = Math.floor(claim.issuedAtMs / 1000);
+    const exp = Math.floor((claim.issuedAtMs + ttlMs) / 1000);
+    const payload = Buffer.from(
+        JSON.stringify({
+            v: 1,
+            sub: claim.sandboxId,
+            email: claim.email.trim().toLowerCase(),
+            amr: claim.method,
+            iat,
+            exp,
+            jti: base64url(randomBytes(16)),
+        }),
+        "utf8",
+    );
+    const signature = edSign(null, signedBytes(payload), createPrivateKey(privateKeyPem));
+    return `${ASSERTION_PREFIX}.${base64url(payload)}.${base64url(signature)}`;
+};
+
+// What the signed payload must be, read only after the signature checked out.
+const AssertionPayloadSchema = z.object({
+    v: z.literal(1),
+    sub: z.string().regex(SANDBOX_ID),
+    email: z.string().min(1),
+    amr: IdentityAssertionMethodSchema,
+    iat: z.number(),
+    exp: z.number(),
+    jti: z.string().min(16),
+});
+
+const parsePayload = (payload: Buffer): z.infer<typeof AssertionPayloadSchema> | undefined => {
+    try {
+        return AssertionPayloadSchema.safeParse(JSON.parse(payload.toString("utf8"))).data;
+    } catch {
+        // allow(silent-catch): a payload that is not JSON is an invalid assertion, which undefined is how this says.
+        return undefined;
+    }
+};
+
+// Verifies an assertion against the platform's public key at nowMs; undefined for any way of being invalid (wrong
+// prefix, bad signature, malformed claim, expired, issued in the future, living longer than the daemon allows). The
+// caller checks sandboxId against its own id and spends the nonce.
+export const verifyIdentityAssertion = (publicKeyPem: string, token: string, nowMs: number): IdentityAssertion | undefined => {
+    const [prefix, encodedPayload, encodedSignature, ...rest] = token.split(".");
+    if (prefix !== ASSERTION_PREFIX || encodedPayload === undefined || encodedSignature === undefined || rest.length > 0) {
+        return undefined;
+    }
+    const payload = Buffer.from(encodedPayload, "base64url");
+    try {
+        if (!edVerify(null, signedBytes(payload), createPublicKey(publicKeyPem), Buffer.from(encodedSignature, "base64url"))) {
+            return undefined;
+        }
+    } catch {
+        // allow(silent-catch): a key or signature that does not parse verifies nothing: the assertion is invalid, said as undefined.
+        return undefined;
+    }
+    const claim = parsePayload(payload);
+    if (claim === undefined) {
+        return undefined;
+    }
+    // A minute of clock skew either way, as the daemon allows Google's tokens; never a claim from further ahead.
+    if (claim.exp * 1000 <= nowMs || claim.iat * 1000 > nowMs + 60_000 || (claim.exp - claim.iat) * 1000 > IDENTITY_ASSERTION_MAX_TTL_MS) {
+        return undefined;
+    }
+    return { sandboxId: claim.sub, email: claim.email, method: claim.amr, issuedAt: claim.iat, expiresAt: claim.exp, nonce: claim.jti };
+};

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));