@clawscarf/cli 0.1.0-alpha.1

package/scripts/deployment/prepare.js

@@ -0,0 +1,205 @@
+import { openshellGatewayImage, verifyRuntimeImage } from "./images.js";
+import { ensureOwnedVolume } from "./volumes.js";
+import { prepareModelGateway, prepareModelCredential, } from "./model-gateway.js";
+import { prepareBrowserNode, browserNodeName } from "./browser-node.js";
+import { withInitialServices } from "./initial-services.js";
+import { loadInitialConnections, prepareInitialConnections, readInitialConnectionToken, } from "./connections.js";
+import { prepareRelay } from "./relay.js";
+import { prepareRuntimePolicy } from "./policy.js";
+import { prepareBrowser, initializeBrowserVolume } from "./browser.js";
+import { readTeamMaterials, prepareTeamFiles } from "./team.js";
+import { readFile, lstat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { prepareInitialModels, withInitialModels, } from "./models.js";
+import { ensureLocalNetworks } from "./networks.js";
+import { nodeEntrypoint } from "./entrypoint.js";
+import { ensureCertificates } from "./certificates.js";
+import { z } from "zod";
+import { PostgresAccessStore } from "../../services/access/repo/postgres.js";
+import { parseLocalInput, generateLocalConfiguration, } from "./configuration.js";
+import { withPreparedDatabase } from "./database.js";
+import { initializeState, writePrivate, ensurePrivateFile, resourceNames, } from "./state.js";
+import { composeConfiguration } from "./compose.js";
+import { run, LocalSetupError } from "./process.js";
+import { verifyLocalExecutables, verifyLocalPorts } from "./preflight.js";
+import { requireNoUpgrade } from "./upgrade-state.js";
+/** Internal operation: the caller holds the installation lock for its full lifetime. */
+export async function prepareLocal(directoryInput, inputValue, capabilities) {
+    const directory = resolve(directoryInput);
+    const input = parseLocalInput(inputValue);
+    const connections = await loadInitialConnections(input.connections);
+    const teamMaterials = await readTeamMaterials(input.team);
+    if (process.platform !== "darwin" || process.arch !== "arm64")
+        throw new LocalSetupError("platform_unqualified", "This local assembly currently requires macOS arm64 with Docker Desktop; other platforms need qualification.");
+    for (const image of [
+        input.runtimeImage,
+        input.openshellClientImage,
+        openshellGatewayImage,
+        input.companionImage,
+        ...(input.modelGateway ? [input.modelGateway.image] : []),
+        ...(input.relayImage ? [input.relayImage] : []),
+        ...(input.browser
+            ? [
+                input.browser.image,
+                input.browser.egressImage,
+                input.browser.nodeImage,
+                input.browser.dnsImage,
+            ]
+            : []),
+    ])
+        await run("docker", ["image", "inspect", image]);
+    await verifyRuntimeImage(input.runtimeImage);
+    const state = await initializeState(directory, input);
+    try {
+        z.strictObject({
+            ownerId: z.literal(state.ownerId),
+            settingsCandidate: z.string().optional(),
+            settingsReapply: z.enum(["models", "connections"]).optional(),
+        }).parse(JSON.parse(await readFile(join(directory, "prepared.json"), "utf8")));
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw new LocalSetupError("configuration_changed", "A retained settings change is unconfirmed. Inspect it before preparing or starting this installation.");
+    }
+    await requireNoUpgrade(directory);
+    if (capabilities)
+        await ensurePrivateFile(join(directory, "inputs.sha256"), capabilities.inputFingerprint);
+    await verifyLocalExecutables(state);
+    await verifyLocalPorts(state);
+    const privateDirectory = join(directory, "private");
+    await ensureCertificates(privateDirectory);
+    const connectionsEndpoint = await prepareInitialConnections(directory, connections);
+    await prepareModelGateway(directory, state);
+    await ensureLocalNetworks(directory, state);
+    const browser = await prepareBrowser(directory, state);
+    const browserMachine = browser
+        ? await prepareBrowserNode(directory, state, browser.token)
+        : undefined;
+    await prepareRelay(directory, state);
+    const names = resourceNames(state);
+    await prepareTeamFiles(privateDirectory, teamMaterials);
+    await ensureOwnedVolume(names.databaseVolume, state.ownerId);
+    await ensureOwnedVolume(names.volume, state.ownerId);
+    if (input.modelGateway)
+        await ensureOwnedVolume(`${names.project}-models`, state.ownerId);
+    if (browser) {
+        await ensureOwnedVolume(names.browserVolume, state.ownerId);
+        await initializeBrowserVolume(state, browser.token);
+    }
+    await ensurePrivateFile(join(directory, "compose.json"), JSON.stringify(composeConfiguration(state, directory, browser?.address, browserMachine), null, 2));
+    await prepareModelCredential(directory, state);
+    const models = await prepareInitialModels(directory, input.models);
+    await prepareRuntimePolicy(directory, models, connectionsEndpoint);
+    await withPreparedDatabase(directory, state, async (pool, runtimeUrl) => {
+        const store = new PostgresAccessStore(pool, await readFile(join(privateDirectory, "encryption.key")), {
+            issuer: input.team.issuer,
+            subject: input.team.administratorSubject ?? "urn:clawscarf:unclaimed",
+            email: input.team.administratorEmail ?? "",
+            claimRequired: !input.team.administratorSubject,
+            name: input.administratorName,
+        });
+        const identity = await store.initialize();
+        const connectionCredential = capabilities?.connections && connectionsEndpoint
+            ? {
+                ...connectionsEndpoint,
+                token: await readInitialConnectionToken(capabilities.connections.credentialFile ?? ""),
+            }
+            : undefined;
+        const insideDatabase = new URL(runtimeUrl);
+        insideDatabase.hostname = "postgres";
+        insideDatabase.port = "5432";
+        const generated = generateLocalConfiguration({
+            input,
+            directory: privateDirectory,
+            encryptionKeyPath: join(privateDirectory, "encryption.key"),
+            managementCertificatePath: join(privateDirectory, "management-cert.pem"),
+            managementKeyPath: join(privateDirectory, "management-key.pem"),
+            runtimeDatabaseUrl: insideDatabase.toString(),
+            administratorIdentity: identity.administrator.identity,
+        });
+        // Native configuration is an initialization input; it is never re-applied on resume.
+        await ensurePrivateFile(join(privateDirectory, "access.json"), JSON.stringify(generated.access, null, 2));
+        await ensurePrivateFile(join(privateDirectory, "companion.json"), JSON.stringify(generated.companion, null, 2));
+        const configured = withInitialModels(generated.native, models);
+        const native = JSON.stringify(withInitialServices(configured, {
+            ...(connectionCredential
+                ? { connectionsBrokerUrl: connectionCredential.brokerUrl }
+                : {}),
+            ...(browser
+                ? {
+                    browserToken: browser.token,
+                    browserNode: browserNodeName(state),
+                }
+                : {}),
+        }), null, 2);
+        await initializeNativeVolume(state, native, identity.serverId, models?.credential, connectionCredential);
+        await writePrivate(join(directory, "identity.json"), JSON.stringify(identity, null, 2));
+    });
+    const controller = join(directory, "controller");
+    try {
+        await lstat(controller);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+        await run(process.execPath, [
+            ...nodeEntrypoint("../controller"),
+            "init",
+            "--directory",
+            controller,
+            "--gateway",
+            input.openshellGateway,
+            "--cli",
+            input.openshellCli,
+            "--name",
+            names.sandbox,
+            "--port",
+            String(input.ports.controller),
+        ]);
+    }
+    // The existing helper owns controller configuration; partial initialization must be explicit.
+    z.object({
+        name: z.literal(names.sandbox),
+        port: z.literal(input.ports.controller),
+        cli: z.literal(input.openshellCli),
+        gateway: z.literal(input.openshellGateway),
+    }).parse(JSON.parse(await readFile(join(controller, "controller.json"), "utf8")));
+    await writePrivate(join(directory, "prepared.json"), JSON.stringify({ ownerId: state.ownerId }));
+    return state;
+}
+async function initializeNativeVolume(state, configuration, serverId, modelCredential, connectionsCredential) {
+    await run("docker", [
+        "run",
+        "--rm",
+        "-i",
+        "--pull",
+        "never",
+        "--network",
+        "none",
+        "--user",
+        "root",
+        "--mount",
+        `type=volume,source=${resourceNames(state).volume},target=/home/node,volume-nocopy`,
+        "--entrypoint",
+        "node",
+        state.input.runtimeImage,
+        "/app/clawscarf/initialize-main.js",
+    ], {
+        input: JSON.stringify({
+            ownerId: state.ownerId,
+            serverId,
+            configuration,
+            ...(modelCredential ? { modelCredential } : {}),
+            ...(connectionsCredential
+                ? {
+                    connectionsCredential: {
+                        token: connectionsCredential.token,
+                        ...(connectionsCredential.ca
+                            ? { ca: connectionsCredential.ca }
+                            : {}),
+                    },
+                }
+                : {}),
+        }),
+    });
+}

package/scripts/deployment/process.js

@@ -0,0 +1,70 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { constants } from "node:os";
+const execute = promisify(execFile);
+export class LocalSetupError extends Error {
+    code;
+    commandFailure;
+    constructor(code, message, commandFailure) {
+        super(message);
+        this.code = code;
+        this.commandFailure = commandFailure;
+        this.name = "LocalSetupError";
+    }
+}
+function commandFailure(error) {
+    if (!(error instanceof Error))
+        return { reason: "unavailable" };
+    const code = "code" in error ? error.code : undefined;
+    if (code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER")
+        return { reason: "output_limit" };
+    if ("killed" in error && error.killed === true)
+        return { reason: "timeout" };
+    if (typeof code === "number" && Number.isSafeInteger(code))
+        return { reason: "exit", exitCode: code };
+    if ("signal" in error) {
+        for (const signal of Object.keys(constants.signals))
+            if (error.signal === signal)
+                return { reason: "signal", signal };
+    }
+    if (typeof code === "string" &&
+        [
+            "ENOENT",
+            "EACCES",
+            "ENOEXEC",
+            "ENOTDIR",
+            "EAGAIN",
+            "EMFILE",
+            "ENFILE",
+        ].includes(code))
+        return { reason: "spawn", systemCode: code };
+    return { reason: "unavailable" };
+}
+function failureDetail(failure) {
+    switch (failure.reason) {
+        case "exit":
+            return `exit ${String(failure.exitCode)}`;
+        case "signal":
+            return failure.signal;
+        case "spawn":
+            return failure.systemCode;
+        default:
+            return failure.reason;
+    }
+}
+/** Keep subprocess diagnostic payloads out of operator errors: they can contain secrets. */
+export async function run(executable, args, options = {}) {
+    try {
+        const child = execute(executable, [...args], {
+            timeout: options.timeout ?? 60_000,
+            maxBuffer: 4 * 1024 * 1024,
+            ...(options.env ? { env: options.env } : {}),
+        });
+        child.child.stdin?.end(options.input);
+        return (await child).stdout;
+    }
+    catch (error) {
+        const failure = commandFailure(error);
+        throw new LocalSetupError("command_failed", `An external command did not confirm success (${failureDetail(failure)}). Inspect this installation before retrying.`, failure);
+    }
+}

package/scripts/deployment/relay.js

@@ -0,0 +1,58 @@
+import { chmod, lstat, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { LocalSetupError } from "./process.js";
+export const runtimeRelayHost = "runtime.clawscarf.internal";
+/** Fixed browser TCP destination; authentication remains end-to-end. */
+export const browserRelayConfiguration = `global
+  maxconn 256
+  nbthread 1
+
+defaults
+  mode tcp
+  timeout connect 5s
+  timeout client 0
+  timeout server 0
+  option clitcpka
+  option srvtcpka
+
+resolvers docker
+  nameserver dns 127.0.0.11:53
+  resolve_retries 3
+  timeout resolve 1s
+  timeout retry 1s
+  hold valid 10s
+
+listen browser
+  bind :9223
+  server browser browser:9223 resolvers docker init-addr libc,none
+`;
+async function verifyFile(path, expected) {
+    const metadata = await lstat(path);
+    if (!metadata.isFile() ||
+        metadata.nlink !== 1 ||
+        metadata.uid !== process.getuid?.() ||
+        (metadata.mode & 0o777) !== 0o444 ||
+        (await readFile(path, "utf8")) !== expected)
+        throw new LocalSetupError("configuration_changed", "The prepared browser relay differs from its fixed destination.");
+}
+export async function prepareRelay(directory, state) {
+    if (!state.input.relayImage)
+        return undefined;
+    const path = join(directory, "private/browser-relay.cfg");
+    const content = browserRelayConfiguration;
+    try {
+        await verifyFile(path, content);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+        await writeFile(path, content, { flag: "wx", mode: 0o444 });
+        await chmod(path, 0o444);
+    }
+}
+/** Starting a deployment observes its policy; it never repairs changed configuration. */
+export async function verifyRelayConfiguration(directory, state) {
+    if (!state.input.relayImage)
+        return;
+    await verifyFile(join(directory, "private/browser-relay.cfg"), browserRelayConfiguration);
+}

package/scripts/deployment/runtime-binding.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { resourceNames } from "./state.js";
+import { LocalSetupError, run } from "./process.js";
+const imageId = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const containerId = z.string().regex(/^[a-f0-9]{64}$/);
+/** Read actual Docker-driver identity/image/storage before admitting application access. */
+export async function verifyRuntimeBinding(state, target, command = run) {
+    const names = resourceNames(state);
+    if (target.name !== names.sandbox || !z.uuid().safeParse(target.id).success)
+        throw new LocalSetupError("runtime_binding_changed", "The selected runtime does not belong to this installation.");
+    try {
+        const ids = (await command("docker", [
+            "container",
+            "ls",
+            "--all",
+            "--quiet",
+            "--no-trunc",
+            "--filter",
+            `label=openshell.ai/sandbox-id=${target.id}`,
+        ]))
+            .trim()
+            .split("\n")
+            .filter(Boolean);
+        const parsed = z.array(containerId).parse(ids);
+        if (parsed.length !== 1)
+            changed();
+        const id = parsed[0];
+        if (!id)
+            changed();
+        const actual = z
+            .object({
+            Id: containerId,
+            Image: imageId,
+            Labels: z.record(z.string(), z.string()),
+            Mounts: z.array(z.object({
+                Type: z.string(),
+                Name: z.string().optional(),
+                Destination: z.string(),
+                RW: z.boolean(),
+            })),
+        })
+            .parse(JSON.parse(await command("docker", [
+            "container",
+            "inspect",
+            "--format",
+            '{"Id":{{json .Id}},"Image":{{json .Image}},"Labels":{{json .Config.Labels}},"Mounts":{{json .Mounts}}}',
+            id,
+        ])));
+        const expectedImage = imageId.parse((await command("docker", [
+            "image",
+            "inspect",
+            "--format",
+            "{{.Id}}",
+            state.input.runtimeImage,
+        ])).trim());
+        const labels = {
+            "openshell.ai/managed-by": "openshell",
+            "openshell.ai/sandbox-id": target.id,
+            "openshell.ai/sandbox-name": target.name,
+            "openshell.ai/sandbox-namespace": names.sandbox,
+            "openshell.ai/sandbox-workspace": "default",
+        };
+        const homes = actual.Mounts.filter((mount) => mount.Destination === "/home/node");
+        const home = homes[0];
+        if (actual.Id !== id ||
+            actual.Image !== expectedImage ||
+            Object.entries(labels).some(([key, value]) => actual.Labels[key] !== value) ||
+            homes.length !== 1 ||
+            actual.Mounts.some((mount) => mount.Destination.startsWith("/home/node/")) ||
+            home?.Type !== "volume" ||
+            home.Name !== names.volume ||
+            !home.RW)
+            changed();
+        const volume = z
+            .object({
+            Name: z.string(),
+            Labels: z.record(z.string(), z.string()).nullable(),
+        })
+            .parse(JSON.parse(await command("docker", [
+            "volume",
+            "inspect",
+            "--format",
+            '{"Name":{{json .Name}},"Labels":{{json .Labels}}}',
+            names.volume,
+        ])));
+        if (volume.Name !== names.volume ||
+            volume.Labels?.["clawscarf.installation"] !== state.ownerId)
+            changed();
+        return { containerId: actual.Id, imageId: actual.Image };
+    }
+    catch (error) {
+        if (error instanceof LocalSetupError &&
+            error.code === "runtime_binding_changed")
+            throw error;
+        throw new LocalSetupError("runtime_binding_unavailable", "The runtime image and storage could not be verified. Inspect Docker before continuing.");
+    }
+}
+function changed() {
+    throw new LocalSetupError("runtime_binding_changed", "The runtime container, image or home volume differs from this installation. Inspect its ownership before continuing.");
+}

package/scripts/deployment/runtime.js

@@ -0,0 +1,232 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { run, LocalSetupError } from "./process.js";
+import { ensurePrivateFile, writePrivate, resourceNames, } from "./state.js";
+const targetSchema = z.object({
+    id: z.uuid(),
+    name: z.string(),
+    phase: z.string(),
+    workspace: z.literal("default"),
+    labels: z.record(z.string(), z.string()),
+});
+const intentSchema = z.strictObject({
+    ownerId: z.uuid(),
+    name: z.string(),
+    image: z.string(),
+});
+const receiptSchema = intentSchema.extend({ id: z.uuid() });
+async function readOptional(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function uncertain() {
+    throw new LocalSetupError("runtime_outcome_unknown", "Runtime creation was attempted but its owned target is absent. Inspect this installation; setup will not create another runtime automatically.");
+}
+function changed() {
+    throw new LocalSetupError("runtime_identity_changed", "The runtime identity or ownership differs from this installation. No further runtime command was sent.");
+}
+export function runtimeManager(directory, state, env, command) {
+    const name = resourceNames(state).sandbox;
+    const intent = {
+        ownerId: state.ownerId,
+        name,
+        image: state.input.runtimeImage,
+    };
+    const receiptPath = join(directory, "runtime.json");
+    const intentPath = join(directory, "runtime-create.json");
+    const shell = (args) => command(state.input.openshellCli, [
+        ...args,
+        "--gateway",
+        resourceNames(state).sandbox,
+        "--workspace",
+        "default",
+    ], { env, timeout: 120000 });
+    async function observe() {
+        const matching = [];
+        const seen = new Set();
+        const limit = 100;
+        for (let offset = 0;; offset += limit) {
+            if (offset > 0xffffffff - limit)
+                throw new LocalSetupError("runtime_lookup_incomplete", "Runtime lookup did not complete. No absence or creation decision was made.");
+            const rows = z
+                .array(targetSchema)
+                .max(limit)
+                .parse(JSON.parse(await shell([
+                "sandbox",
+                "list",
+                "--limit",
+                String(limit),
+                "--offset",
+                String(offset),
+                "-o",
+                "json",
+            ])));
+            for (const row of rows) {
+                if (seen.has(row.id))
+                    throw new LocalSetupError("runtime_lookup_incomplete", "The runtime list changed or repeated while loading. Retry observation before making changes.");
+                seen.add(row.id);
+                if (row.name === name)
+                    matching.push(row);
+            }
+            if (rows.length < limit)
+                break;
+        }
+        if (matching.length > 1)
+            changed();
+        const row = matching[0];
+        if (!row)
+            return undefined;
+        if (row.labels["clawscarf.installation"] !== state.ownerId)
+            changed();
+        const current = targetSchema.parse(JSON.parse(await shell(["sandbox", "get", name, "-o", "json"])));
+        if (current.name !== name ||
+            current.id !== row.id ||
+            current.labels["clawscarf.installation"] !== state.ownerId)
+            changed();
+        return current;
+    }
+    async function recorded() {
+        const pending = await readOptional(intentPath);
+        if (pending !== undefined) {
+            const value = intentSchema.parse(pending);
+            if (value.ownerId !== intent.ownerId ||
+                value.name !== name ||
+                value.image !== intent.image)
+                changed();
+        }
+        const raw = await readOptional(receiptPath);
+        const receipt = raw === undefined ? undefined : receiptSchema.parse(raw);
+        if (receipt &&
+            (receipt.ownerId !== intent.ownerId ||
+                receipt.name !== name ||
+                receipt.image !== intent.image))
+            changed();
+        if (receipt && pending === undefined)
+            changed();
+        return { pending: pending !== undefined, receipt };
+    }
+    async function confirm(id) {
+        const result = await observe();
+        if (!result || result.id !== id)
+            changed();
+        return result;
+    }
+    return {
+        name,
+        intent,
+        intentPath,
+        receiptPath,
+        shell,
+        observe,
+        recorded,
+        confirm,
+    };
+}
+/** Caller holds the installation lock. A persisted create intent is never blindly replayed. */
+export async function ensureRuntime(directory, state, env, command = run) {
+    const control = runtimeManager(directory, state, env, command);
+    const record = await control.recorded();
+    let target = await control.observe();
+    if (record.receipt && target?.id !== record.receipt.id)
+        changed();
+    if (!target) {
+        if (record.pending)
+            uncertain();
+        await ensurePrivateFile(control.intentPath, JSON.stringify(control.intent) + "\n");
+        const args = [
+            "sandbox",
+            "create",
+            "--name",
+            control.name,
+            "--from",
+            state.input.runtimeImage,
+            "--policy",
+            join(directory, "private/runtime-policy.json"),
+            "--cpu",
+            state.input.cpu,
+            "--memory",
+            state.input.memory,
+            "--driver-config-json",
+            JSON.stringify({
+                docker: {
+                    mounts: [
+                        {
+                            type: "volume",
+                            source: resourceNames(state).volume,
+                            target: "/home/node",
+                            read_only: false,
+                        },
+                    ],
+                },
+            }),
+            "--label",
+            `clawscarf.installation=${state.ownerId}`,
+            "--no-auto-providers",
+            "--detach",
+            "--no-tty",
+            "--gateway",
+            resourceNames(state).sandbox,
+            "--workspace",
+            "default",
+            "--",
+            "/app/clawscarf/bin/openclaw",
+            "gateway",
+        ];
+        // A failed response may follow successful allocation: reconcile observed identity only.
+        try {
+            await command(state.input.openshellCli, args, { env, timeout: 180000 });
+        }
+        catch {
+            target = await control.observe();
+            if (!target)
+                uncertain();
+        }
+        target ??= await control.observe();
+        if (!target)
+            uncertain();
+    }
+    else if (!record.pending) {
+        changed();
+    }
+    if (!record.receipt)
+        await writePrivate(control.receiptPath, JSON.stringify({ ...control.intent, id: target.id }) + "\n");
+    if (target.phase === "Error")
+        throw new LocalSetupError("runtime_failed", "The owned runtime is in Error. Inspect it before retrying; setup will not replace it.");
+    if (target.phase === "Stopped") {
+        await control.confirm(target.id);
+        await control.shell(["sandbox", "start", target.name]);
+        target = await control.confirm(target.id);
+        if (target.phase === "Error" || target.phase === "Stopped")
+            throw new LocalSetupError("runtime_start_failed", "The owned runtime did not confirm startup. Inspect it before retrying.");
+    }
+    return { id: target.id, name: target.name, phase: target.phase };
+}
+/** Native start/stop resolve names; identity checks detect replacement, not an atomic UUID precondition. */
+export async function stopRuntime(directory, state, env, command = run) {
+    const control = runtimeManager(directory, state, env, command);
+    const record = await control.recorded();
+    const target = await control.observe();
+    if (!target) {
+        if (record.pending || record.receipt)
+            uncertain();
+        return;
+    }
+    if (!record.receipt || record.receipt.id !== target.id)
+        changed();
+    if (target.phase === "Stopped")
+        return;
+    if (target.phase === "Error")
+        throw new LocalSetupError("runtime_failed", "The owned runtime is in Error. Inspect it before continuing.");
+    await control.confirm(target.id);
+    await control.shell(["sandbox", "stop", target.name]);
+    const stopped = await control.confirm(target.id);
+    if (stopped.phase !== "Stopped")
+        throw new LocalSetupError("runtime_stop_pending", "The runtime has not confirmed Stopped. Keep its controller running and inspect its state.");
+}