@miosa/cli 1.0.9 → 1.0.11

package/dist/commands/sandbox.js

@@ -1,16 +1,18 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createServer } from "node:net";
 import chalk from "chalk";
 import WebSocket from "ws";
+import { detectFramework } from "../framework-detector.js";
 import { addDataOption, client, apiPath, deleteAndPrint, enc, getAndPrint, postAndPrint, printValue, runAction, unwrap, } from "./enterprise-util.js";
 import { loadConfig } from "../config.js";
 import { handleError } from "./util.js";
 import { renderTable } from "../ui/table.js";
 import { formatDuration, hintBlock, icon, kvPanel, printBanner, printElapsed, } from "../ui/render.js";
 import { formatBytes } from "../ui/progress.js";
+import { UserError } from "../errors.js";
 export function register(program) {
     // -------------------------------------------------------------------------
     // sandbox / sandboxes command group — built manually to avoid subcommand
@@ -84,10 +86,15 @@ export function register(program) {
     sandbox
         .command("show <sandbox-id>")
         .description("Show a Sandbox by ID")
+        .option("--port <port>", "Include live preview readiness for this port", parseInt)
+        .option("--probe-path <path>", "HTTP path to probe when --port is set", "/")
         .option("--json", "Output as JSON")
         .action((id, opts) => runAction(async () => {
         if (opts.json) {
-            await getAndPrint(`/sandboxes/${enc(id)}`, opts);
+            const data = opts.port != null
+                ? await showSandboxWithPreview(id, opts.port, opts.probePath)
+                : unwrap(await client().apiGet(apiPath(`/sandboxes/${enc(id)}`)));
+            console.log(JSON.stringify(data, null, 2));
             return;
         }
         const raw = unwrap(await client().apiGet(apiPath(`/sandboxes/${enc(id)}`)));
@@ -138,6 +145,7 @@ export function register(program) {
         console.log();
         console.log(hintBlock("Try", [
             `miosa sandbox exec ${str(sb["id"])} --command ...`,
+            `miosa sandbox preview ${str(sb["id"])} --port 5173 --wait`,
             `miosa sandbox destroy ${str(sb["id"])}`,
         ]));
         console.log();
@@ -158,6 +166,9 @@ export function register(program) {
         .option("--memory <mb>", "Memory in MB", parseInt)
         .option("--disk <mb>", "Disk size in MB", parseInt)
         .option("--timeout <sec>", "Idle timeout in seconds", parseInt)
+        .option("--publish-port <port>", "Expose this port after create", parseInt)
+        .option("--wait", "Wait for sandbox running and published port readiness")
+        .option("--probe-path <path>", "HTTP path to probe when --publish-port is set", "/")
         .option("--always-on", "Disable auto-destroy on idle"))
         .option("--json", "Output as JSON")
         .action((opts) => runAction(async () => {
@@ -186,12 +197,35 @@ export function register(program) {
             body["timeout_sec"] = opts.timeout;
         if (opts.alwaysOn)
             body["always_on"] = true;
+        const raw = unwrap(await client().apiPost(apiPath("/sandboxes"), body));
+        const sb = (raw ?? {});
+        const id = String(sb["id"] ?? "");
+        if (opts.publishPort != null && id) {
+            if (opts.wait) {
+                const preview = await waitSandboxReady(id, opts.publishPort, opts.probePath ?? "/", Math.max(opts.timeout ?? 120, 30));
+                sb["preview"] = preview;
+                sb["preview_url"] = preview.url;
+                sb["ready"] = preview.ready;
+            }
+            else {
+                const preview = await previewSandbox(id, opts.publishPort, {
+                    wait: false,
+                    timeout: 1,
+                    probePath: opts.probePath ?? "/",
+                });
+                sb["preview"] = preview;
+                sb["preview_url"] = preview.url;
+            }
+        }
+        else if (opts.wait && id) {
+            await waitForSandboxRunning(client(), id, Math.max(opts.timeout ?? 120, 30));
+            sb["ready"] = true;
+        }
         if (opts.json) {
-            await postAndPrint("/sandboxes", opts, body);
+            console.log(JSON.stringify(sb, null, 2));
             return;
         }
-        const raw = unwrap(await client().apiPost(apiPath("/sandboxes"), body));
-        renderCreateSuccess(raw, Date.now() - t0);
+        renderCreateSuccess(sb, Date.now() - t0);
     }));
     // delete
     sandbox
@@ -291,10 +325,12 @@ export function register(program) {
         const modelFlag = opts.model
             ? ` --model ${`'${opts.model.replace(/'/g, "'\\''")}'`}`
             : "";
-        const command = `${provider}${modelFlag} ${`'${instruction.replace(/'/g, "'\\''")}'`}`;
+        const command = commandInCwd(`${provider}${modelFlag} ${shellQuote(instruction)}`, opts.cwd);
         const body = { command };
-        if (opts.cwd)
+        if (opts.cwd) {
             body["cwd"] = opts.cwd;
+            body["dir"] = opts.cwd;
+        }
         if (opts.timeout != null)
             body["timeout"] = opts.timeout;
         await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, body);
@@ -304,6 +340,9 @@ export function register(program) {
         .command("exec <sandbox-id> [command...]")
         .description("Run a command inside a Sandbox (positional args joined as shell command)")
         .option("--cwd <path>", "Working directory inside the Sandbox")
+        .option("--workdir <path>", "Alias for --cwd")
+        .option("--env <pair>", "Environment variable KEY=VALUE. Repeatable.", collectOption, [])
+        .option("--background", "Start the command in the background and return immediately")
         .option("--timeout <sec>", "Exec timeout in seconds", parseInt))
         .option("--json", "Output as JSON")
         .action((id, words, opts) => runAction(async () => {
@@ -312,9 +351,18 @@ export function register(program) {
             return;
         }
         const cmd = words.join(" ");
-        const body = cmd ? { command: cmd } : {};
-        if (opts.cwd)
-            body["cwd"] = opts.cwd;
+        const effectiveCommand = opts.background ? backgroundCommand(cmd) : cmd;
+        const cwd = opts.cwd ?? opts.workdir;
+        const body = cmd
+            ? { command: commandInCwd(effectiveCommand, cwd) }
+            : {};
+        if (cwd) {
+            body["cwd"] = cwd;
+            body["dir"] = cwd;
+        }
+        const env = parseEnvPairs(opts.env ?? []);
+        if (Object.keys(env).length > 0)
+            body["env"] = env;
         if (opts.timeout != null)
             body["timeout"] = opts.timeout;
         await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, body);
@@ -324,6 +372,9 @@ export function register(program) {
         .command("run <sandbox-id> [command...]")
         .description("Run a command inside a Sandbox (alias for exec)")
         .option("--cwd <path>", "Working directory inside the Sandbox")
+        .option("--workdir <path>", "Alias for --cwd")
+        .option("--env <pair>", "Environment variable KEY=VALUE. Repeatable.", collectOption, [])
+        .option("--background", "Start the command in the background and return immediately")
         .option("--timeout <sec>", "Exec timeout in seconds", parseInt))
         .option("--json", "Output as JSON")
         .action((id, words, opts) => runAction(async () => {
@@ -332,13 +383,168 @@ export function register(program) {
             return;
         }
         const cmd = words.join(" ");
-        const body = cmd ? { command: cmd } : {};
-        if (opts.cwd)
-            body["cwd"] = opts.cwd;
+        const effectiveCommand = opts.background ? backgroundCommand(cmd) : cmd;
+        const cwd = opts.cwd ?? opts.workdir;
+        const body = cmd
+            ? { command: commandInCwd(effectiveCommand, cwd) }
+            : {};
+        if (cwd) {
+            body["cwd"] = cwd;
+            body["dir"] = cwd;
+        }
+        const env = parseEnvPairs(opts.env ?? []);
+        if (Object.keys(env).length > 0)
+            body["env"] = env;
         if (opts.timeout != null)
             body["timeout"] = opts.timeout;
         await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, body);
     }));
+    sandbox
+        .command("deploy [local-dir]")
+        .description("Upload an app directory, start it in a sandbox, expose a preview URL, and wait for readiness")
+        .option("--sandbox <id>", "Existing sandbox ID. Creates one when omitted")
+        .option("--template <template>", "Template for new sandbox", "miosa-sandbox")
+        .option("--name <name>", "Name for a new sandbox")
+        .option("--port <port>", "Preview port", parseInt)
+        .option("--publish-port <port>", "Alias for --port", parseInt)
+        .option("--start <command>", "Start command to run inside /workspace")
+        .option("--install-command <command>", "Install command to run before start")
+        .option("--no-install", "Skip automatic dependency install")
+        .option("--wait", "Wait until the public preview returns a good HTTP status")
+        .option("--timeout <sec>", "Wait timeout in seconds", parseInt, 180)
+        .option("--probe-path <path>", "HTTP path to probe", "/")
+        .option("--json", "Output as JSON")
+        .action((localDir = ".", opts) => runAction(async () => {
+        const result = await deploySandbox(localDir, opts);
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log();
+        console.log(`  ${chalk.bold("Sandbox")}  ${result.sandbox_id}`);
+        console.log(`  ${chalk.bold("Port")}     ${result.port}`);
+        console.log(`  ${chalk.bold("Preview")}  ${chalk.cyan(result.preview_url)}`);
+        console.log(`  ${chalk.bold("Ready")}    ${result.preview_ready ? chalk.green("yes") : chalk.yellow("not verified")}`);
+        console.log();
+    }));
+    sandbox
+        .command("preview <sandbox-id>")
+        .description("Expose a sandbox port and optionally wait for the public preview to answer")
+        .requiredOption("--port <port>", "Port inside the sandbox to expose", parseInt)
+        .option("--wait", "Wait until the public URL returns a good HTTP status")
+        .option("--timeout <sec>", "Wait timeout in seconds", parseInt, 120)
+        .option("--probe-path <path>", "HTTP path to probe", "/")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        const result = await previewSandbox(id, opts.port, {
+            wait: !!opts.wait,
+            timeout: opts.timeout,
+            probePath: opts.probePath,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(result.url);
+        if (!result.ready) {
+            console.error(chalk.yellow(`Preview route created but not verified yet (${result.error ?? result.status ?? "pending"}).`));
+        }
+    }));
+    sandbox
+        .command("wait <sandbox-id>")
+        .description("Wait for sandbox VM, internal app port, edge route, TLS, and public preview readiness")
+        .requiredOption("--port <port>", "Port inside the sandbox to check", parseInt)
+        .option("--url", "Print only the ready public preview URL")
+        .option("--timeout <sec>", "Wait timeout in seconds", parseInt, 120)
+        .option("--probe-path <path>", "HTTP path to probe", "/")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        const result = await waitSandboxReady(id, opts.port, opts.probePath, opts.timeout);
+        if (opts.url && result.url) {
+            console.log(result.url);
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(chalk.green("Ready"));
+        console.log(chalk.cyan(result.url));
+    }));
+    const service = sandbox
+        .command("service")
+        .description("Manage named long-running processes inside a sandbox");
+    service
+        .command("start <sandbox-id> <name>")
+        .requiredOption("--cmd <command>", "Command to start")
+        .option("--cwd <path>", "Working directory inside the sandbox", "/workspace")
+        .option("--port <port>", "Port served by this service", parseInt)
+        .option("--json", "Output as JSON")
+        .action((id, name, opts) => runAction(async () => {
+        const result = await startSandboxService(id, name, opts);
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(chalk.green(`Started ${name}`));
+        if (result.preview_url)
+            console.log(chalk.cyan(String(result.preview_url)));
+    }));
+    service
+        .command("restart <sandbox-id> <name>")
+        .requiredOption("--cmd <command>", "Command to start")
+        .option("--cwd <path>", "Working directory inside the sandbox", "/workspace")
+        .option("--port <port>", "Port served by this service", parseInt)
+        .option("--json", "Output as JSON")
+        .action((id, name, opts) => runAction(async () => {
+        await execSandbox(client(), id, `if [ -f ${shellQuote(servicePidPath(name))} ]; then kill $(cat ${shellQuote(servicePidPath(name))}) >/dev/null 2>&1 || true; fi`, "/");
+        const result = await startSandboxService(id, name, opts);
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(chalk.green(`Restarted ${name}`));
+        if (result.preview_url)
+            console.log(chalk.cyan(String(result.preview_url)));
+    }));
+    service
+        .command("status <sandbox-id> <name>")
+        .option("--json", "Output as JSON")
+        .action((id, name, opts) => runAction(async () => {
+        const result = await execSandbox(client(), id, `if [ -f ${shellQuote(servicePidPath(name))} ] && kill -0 $(cat ${shellQuote(servicePidPath(name))}) >/dev/null 2>&1; then echo running; else echo stopped; fi`, "/");
+        const status = String(result["stdout"] ?? "").trim() || "unknown";
+        if (opts.json) {
+            console.log(JSON.stringify({ sandbox_id: id, name, status }, null, 2));
+            return;
+        }
+        console.log(status === "running" ? chalk.green(status) : chalk.yellow(status));
+    }));
+    service
+        .command("logs <sandbox-id> <name>")
+        .option("--lines <n>", "Number of log lines", parseInt, 100)
+        .option("--json", "Output as JSON")
+        .action((id, name, opts) => runAction(async () => {
+        const result = await execSandbox(client(), id, `tail -n ${Number(opts.lines) || 100} ${shellQuote(serviceLogPath(name))}`, "/");
+        if (opts.json) {
+            console.log(JSON.stringify({ sandbox_id: id, name, logs: String(result["stdout"] ?? "") }, null, 2));
+            return;
+        }
+        process.stdout.write(String(result["stdout"] ?? ""));
+    }));
+    sandbox
+        .command("doctor <sandbox-id>")
+        .description("Diagnose sandbox app readiness across sandbox state, internal HTTP, public route, and TLS/edge reachability")
+        .requiredOption("--port <port>", "Port inside the sandbox to check", parseInt)
+        .option("--probe-path <path>", "HTTP path to probe", "/")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        const report = await doctorSandbox(id, opts.port, opts.probePath);
+        if (opts.json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        renderDoctorReport(report);
+    }));
     // write-file — POST /sandboxes/:id/files with base64 content.
     // If <content-or-file> is an existing local path, reads the file bytes;
     // otherwise treats the argument as literal UTF-8 text.
@@ -429,6 +635,96 @@ export function register(program) {
             handleError(err);
         }
     });
+    sandbox
+        .command("upload-dir <sandbox-id> <local-dir> <remote-dir>")
+        .description("Upload a local directory into a Sandbox")
+        .option("--delete", "Delete the remote directory contents before extracting")
+        .option("--json", "Output as JSON")
+        .action(async (id, localDir, remoteDir, opts) => {
+        try {
+            const result = await uploadDirToSandbox(id, localDir, remoteDir, {
+                delete: !!opts.delete,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(chalk.green(`Uploaded ${result.files_label} → ${remoteDir}`));
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    sandbox
+        .command("sync <local-dir> <remote-dir>")
+        .description("Sync a local directory into a sandbox")
+        .requiredOption("--sandbox <id>", "Sandbox ID")
+        .option("--delete", "Delete the remote directory contents before extracting")
+        .option("--json", "Output as JSON")
+        .action(async (localDir, remoteDir, opts) => {
+        try {
+            const result = await uploadDirToSandbox(opts.sandbox, localDir, remoteDir, {
+                delete: !!opts.delete,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(chalk.green(`Synced ${result.files_label} → ${remoteDir}`));
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    sandbox
+        .command("cp <source> <target>")
+        .alias("copy")
+        .description("Copy a local file or directory into a sandbox, e.g. ./app/. sbx_123:/workspace")
+        .option("--delete", "Delete the remote directory contents before extracting directories")
+        .option("--json", "Output as JSON")
+        .action(async (source, target, opts) => {
+        try {
+            if (isSandboxTarget(source) && !isSandboxTarget(target)) {
+                const parsedSource = parseSandboxTarget(source);
+                const result = await downloadSandboxPath(parsedSource.sandboxId, parsedSource.remotePath, target);
+                if (opts.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                console.log(chalk.green(`Copied ${source} → ${target}`));
+                return;
+            }
+            if (isSandboxTarget(source) || !isSandboxTarget(target)) {
+                throw new UserError("Invalid copy direction.", "Use local → sandbox (`./app/. sbx_123:/workspace`) or sandbox → local (`sbx_123:/workspace/dist ./dist`).");
+            }
+            const parsed = parseSandboxTarget(target);
+            const local = source.endsWith("/.") ? source.slice(0, -2) : source;
+            const stat = fs.statSync(local);
+            if (stat.isDirectory()) {
+                const result = await uploadDirToSandbox(parsed.sandboxId, local, parsed.remotePath, { delete: !!opts.delete });
+                if (opts.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                console.log(chalk.green(`Copied ${result.files_label} → ${target}`));
+                return;
+            }
+            const c = client();
+            await uploadFileToSandbox(c, parsed.sandboxId, local, parsed.remotePath);
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    sandbox_id: parsed.sandboxId,
+                    local_path: path.resolve(local),
+                    remote_path: parsed.remotePath,
+                }, null, 2));
+                return;
+            }
+            console.log(chalk.green(`Copied ${path.basename(local)} → ${target}`));
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
     // download — GET /sandboxes/:id/files/:path; write to --output or stdout.
     sandbox
         .command("download <sandbox-id> <remote-path>")
@@ -497,6 +793,20 @@ export function register(program) {
             handleError(err);
         }
     });
+    sandbox
+        .command("shell <sandbox-id>")
+        .description("Open an interactive shell into a running Sandbox")
+        .option("-p, --port <n>", "Local port for the tunnel listener", parseInt)
+        .option("-l, --user <name>", "SSH user (default: root)")
+        .option("--json", "Output connection info as JSON")
+        .action(async (id, opts) => {
+        try {
+            await runSandboxSsh(id, { ...opts, spawn: !opts.json });
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
     // port-forward — TCP listener → WS tunnel → sandbox port
     sandbox
         .command("port-forward <sandbox-id>")
@@ -510,10 +820,20 @@ export function register(program) {
     ].join("\n"))
         .requiredOption("--remote <port>", "Port inside the sandbox to reach", parseInt)
         .option("--local <port>", "Local port to listen on (default = remote port)", parseInt)
+        .option("--wait", "Probe the local forwarded URL before returning readiness")
+        .option("--timeout <sec>", "Wait timeout in seconds", parseInt, 30)
+        .option("--probe-path <path>", "HTTP path to probe when --wait is set", "/")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
         try {
-            await runSandboxPortForward(id, opts.remote, opts.local ?? opts.remote, !!opts.json);
+            await runSandboxPortForward(id, {
+                remotePort: opts.remote,
+                localPort: opts.local ?? opts.remote,
+                wait: !!opts.wait,
+                timeoutSec: opts.timeout,
+                probePath: opts.probePath,
+                json: !!opts.json,
+            });
         }
         catch (err) {
             handleError(err);
@@ -525,6 +845,55 @@ export function register(program) {
         .description("Create a Checkpoint (memory state snapshot) of a Sandbox"))
         .option("--json", "Output as JSON")
         .action((id, opts) => runAction(() => postAndPrint(`/sandboxes/${enc(id)}/snapshots`, opts, {})));
+    sandbox
+        .command("snapshot <sandbox-id>")
+        .description("Create a Sandbox snapshot")
+        .option("--name <name>", "Human-readable snapshot name/comment")
+        .option("--comment <comment>", "Snapshot comment")
+        .option("--stop", "Pause the sandbox after snapshot creation")
+        .option("--expiration <duration>", "Requested retention duration, e.g. 14d")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        const body = {};
+        const comment = opts.comment ?? opts.name;
+        if (comment)
+            body["comment"] = comment;
+        if (opts.expiration)
+            body["expiration"] = opts.expiration;
+        const snapshot = unwrap(await client().apiPost(apiPath(`/sandboxes/${enc(id)}/snapshots`), body));
+        if (opts.stop) {
+            await client().apiPost(apiPath(`/sandboxes/${enc(id)}/pause`), {});
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ snapshot, stopped: !!opts.stop }, null, 2));
+            return;
+        }
+        const snap = (snapshot ?? {});
+        console.log(chalk.green("Snapshot requested"));
+        if (snap["id"])
+            console.log(String(snap["id"]));
+        if (opts.stop)
+            console.log(chalk.dim("Sandbox pause requested."));
+    }));
+    const snapshots = sandbox
+        .command("snapshots")
+        .description("List, inspect, and delete Sandbox snapshots");
+    snapshots
+        .command("list <sandbox-id>")
+        .description("List snapshots for a sandbox")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(() => getAndPrint(`/sandboxes/${enc(id)}/snapshots`, opts)));
+    snapshots
+        .command("get <sandbox-id> <snapshot-id>")
+        .description("Get a sandbox snapshot")
+        .option("--json", "Output as JSON")
+        .action((id, snapshotId, opts) => runAction(() => getAndPrint(`/sandboxes/${enc(id)}/snapshots/${enc(snapshotId)}`, opts)));
+    snapshots
+        .command("delete <sandbox-id> <snapshot-id>")
+        .alias("rm")
+        .description("Delete a sandbox snapshot")
+        .option("--json", "Output as JSON")
+        .action((id, snapshotId, opts) => runAction(() => deleteAndPrint(`/sandboxes/${enc(id)}/snapshots/${enc(snapshotId)}`, opts)));
     // delete-checkpoint / delete-snapshot
     sandbox
         .command("delete-checkpoint <sandbox-id> <checkpoint-id>")
@@ -702,8 +1071,7 @@ async function runSandboxSsh(id, opts) {
     server.close();
     process.exit(exitCode);
 }
-// ── sandbox port-forward implementation ───────────────────────────────────
-async function runSandboxPortForward(id, remotePort, localPort, json) {
+async function runSandboxPortForward(id, opts) {
     const config = loadConfig();
     const apiKey = config.api_key;
     if (!apiKey)
@@ -711,7 +1079,7 @@ async function runSandboxPortForward(id, remotePort, localPort, json) {
     const endpoint = config.endpoint ?? "https://api.miosa.ai";
     const base = endpoint.replace(/\/$/, "");
     const wsBase = base.replace(/^https?/, (p) => (p === "https" ? "wss" : "ws"));
-    const wsUrl = `${wsBase}/api/v1/sandboxes/${encodeURIComponent(id)}/port-tunnel/${remotePort}`;
+    const wsUrl = `${wsBase}/api/v1/sandboxes/${encodeURIComponent(id)}/port-tunnel/${opts.remotePort}`;
     const stats = { active: 0, total: 0, bytesIn: 0, bytesOut: 0 };
     const server = createServer((socket) => {
         stats.active++;
@@ -748,27 +1116,34 @@ async function runSandboxPortForward(id, remotePort, localPort, json) {
     await new Promise((resolve, reject) => {
         server.on("error", (err) => {
             if (err.code === "EADDRINUSE") {
-                reject(new Error(`Port ${localPort} is already in use. Choose another with --local.`));
+                reject(new Error(`Port ${opts.localPort} is already in use. Choose another with --local.`));
             }
             else {
                 reject(err);
             }
         });
-        server.listen(localPort, "127.0.0.1", resolve);
+        server.listen(opts.localPort, "127.0.0.1", resolve);
     });
-    if (json) {
+    let localProbe = null;
+    if (opts.wait) {
+        localProbe = await waitForLocalHttp(opts.localPort, opts.probePath, opts.timeoutSec);
+    }
+    if (opts.json) {
         console.log(JSON.stringify({
             sandbox_id: id,
-            remote_port: remotePort,
-            local_port: localPort,
+            remote_port: opts.remotePort,
+            local_port: opts.localPort,
+            ready: localProbe?.ok ?? !opts.wait,
+            status: localProbe?.status ?? null,
+            latency_ms: localProbe?.latency_ms ?? null,
         }));
     }
     else {
-        console.log(`${chalk.green("Forwarding")} ${chalk.cyan(`localhost:${localPort}`)} ${chalk.dim("→")} sandbox ${chalk.cyan(id)}:${chalk.bold(String(remotePort))}`);
+        console.log(`${chalk.green(opts.wait ? "Forwarding ready" : "Forwarding")} ${chalk.cyan(`localhost:${opts.localPort}`)} ${chalk.dim("→")} sandbox ${chalk.cyan(id)}:${chalk.bold(String(opts.remotePort))}`);
         console.log(chalk.dim("Press Ctrl+C to close.\n"));
     }
     const ticker = setInterval(() => {
-        if (json || stats.active === 0)
+        if (opts.json || stats.active === 0)
             return;
         process.stderr.write(chalk.dim(`\r[${new Date().toLocaleTimeString()}] connections: ${stats.active}  ↑ ${formatBytes(stats.bytesIn)}  ↓ ${formatBytes(stats.bytesOut)}  `));
     }, 5_000);
@@ -777,6 +1152,514 @@ async function runSandboxPortForward(id, remotePort, localPort, json) {
     process.stderr.write("\n");
     server.close();
 }
+async function showSandboxWithPreview(sandboxId, port, probePath) {
+    const c = client();
+    const sandbox = unwrap(await c.apiGet(apiPath(`/sandboxes/${enc(sandboxId)}`)));
+    let preview = null;
+    try {
+        preview = await previewSandbox(sandboxId, port, {
+            wait: false,
+            timeout: 1,
+            probePath,
+        });
+    }
+    catch (err) {
+        preview = {
+            url: "",
+            ready: false,
+            status: null,
+            latency_ms: null,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    return {
+        ...sandbox,
+        ready: preview?.ready ?? false,
+        preview: {
+            url: preview?.url || null,
+            port,
+            route_ready: Boolean(preview?.url),
+            tls_ready: preview?.ready ?? false,
+            last_status: preview?.status ?? null,
+            latency_ms: preview?.latency_ms ?? null,
+            error: preview?.error,
+        },
+    };
+}
+async function previewSandbox(sandboxId, port, opts) {
+    const c = client();
+    const exposed = unwrap(await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/expose`), {
+        port,
+        title: "app preview",
+    }));
+    const url = extractUrl(exposed);
+    if (!url)
+        throw new UserError("Sandbox expose did not return a preview URL.");
+    const edge = opts.wait
+        ? await waitForPublicPreview(url, opts.probePath, opts.timeout)
+        : await probePublicPreview(url, opts.probePath);
+    return {
+        url,
+        ready: edge.ok,
+        status: edge.status,
+        latency_ms: edge.latency_ms ?? null,
+        error: edge.error,
+    };
+}
+async function waitSandboxReady(sandboxId, port, probePath, timeoutSec) {
+    const c = client();
+    await waitForSandboxRunning(c, sandboxId, Math.min(timeoutSec, 120));
+    const internal = await waitForInternalHttp(c, sandboxId, port, probePath, Math.min(timeoutSec, 60));
+    const preview = await previewSandbox(sandboxId, port, {
+        wait: true,
+        timeout: timeoutSec,
+        probePath,
+    });
+    return {
+        sandbox_id: sandboxId,
+        port,
+        internal_status: internal.status,
+        ...preview,
+    };
+}
+async function startSandboxService(sandboxId, name, opts) {
+    validateServiceName(name);
+    const c = client();
+    const logPath = serviceLogPath(name);
+    const pidPath = servicePidPath(name);
+    const command = [
+        "mkdir -p /tmp/miosa-services",
+        `if [ -f ${shellQuote(pidPath)} ]; then kill $(cat ${shellQuote(pidPath)}) >/dev/null 2>&1 || true; fi`,
+        `nohup sh -lc ${shellQuote(opts.cmd)} > ${shellQuote(logPath)} 2>&1 & echo $! > ${shellQuote(pidPath)}`,
+        `cat ${shellQuote(pidPath)}`,
+    ].join(" && ");
+    const exec = await execSandbox(c, sandboxId, command, opts.cwd, 15);
+    const pid = String(exec["stdout"] ?? "").trim().split(/\s+/).pop() ?? "";
+    let previewUrl = null;
+    if (opts.port != null) {
+        const preview = await previewSandbox(sandboxId, opts.port, {
+            wait: false,
+            timeout: 1,
+            probePath: "/",
+        });
+        previewUrl = preview.url;
+    }
+    return {
+        sandbox_id: sandboxId,
+        name,
+        pid,
+        cwd: opts.cwd,
+        command: opts.cmd,
+        port: opts.port ?? null,
+        log_path: logPath,
+        preview_url: previewUrl,
+    };
+}
+function serviceLogPath(name) {
+    return `/tmp/miosa-services/${name}.log`;
+}
+function servicePidPath(name) {
+    return `/tmp/miosa-services/${name}.pid`;
+}
+function validateServiceName(name) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(name)) {
+        throw new UserError(`Invalid service name: ${name}`, "Use only letters, numbers, dot, dash, and underscore.");
+    }
+}
+async function deploySandbox(localDir, opts) {
+    const sourceDir = path.resolve(localDir);
+    if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) {
+        throw new UserError(`Local directory not found: ${sourceDir}`);
+    }
+    const c = client();
+    const detection = detectFramework(sourceDir);
+    const port = opts.port ?? opts.publishPort ?? detection?.port ?? 5173;
+    const start = opts.start ?? defaultStartCommand(detection?.framework, port);
+    const installCommand = opts.install === false
+        ? null
+        : opts.installCommand ?? defaultInstallCommand(sourceDir);
+    const sandboxId = opts.sandbox ??
+        (await createSandboxForDeploy(c, opts.template ?? "miosa-sandbox", opts.name));
+    await waitForSandboxRunning(c, sandboxId, Math.min(opts.timeout, 120));
+    const archivePath = createDeployArchive(sourceDir);
+    const remoteArchive = `/tmp/miosa-deploy-${Date.now()}.tgz`;
+    try {
+        await uploadFileToSandbox(c, sandboxId, archivePath, remoteArchive);
+    }
+    finally {
+        fs.rmSync(archivePath, { force: true });
+    }
+    await execSandbox(c, sandboxId, `mkdir -p /workspace && tar -xzf ${shellQuote(remoteArchive)} -C /workspace`, "/");
+    if (installCommand) {
+        await execSandbox(c, sandboxId, installCommand, "/workspace", opts.timeout);
+    }
+    await execSandbox(c, sandboxId, `fuser -k ${port}/tcp >/dev/null 2>&1 || true; nohup sh -lc ${shellQuote(start)} > ${shellQuote(`/tmp/miosa-app-${port}.log`)} 2>&1 & echo $!`, "/workspace");
+    const internal = await waitForInternalHttp(c, sandboxId, port, opts.probePath, Math.min(opts.timeout, 60));
+    const exposed = await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/expose`), { port, title: "app preview" });
+    const previewUrl = extractUrl(unwrap(exposed));
+    if (!previewUrl) {
+        throw new UserError("Sandbox expose did not return a preview URL.");
+    }
+    const edge = opts.wait
+        ? await waitForPublicPreview(previewUrl, opts.probePath, opts.timeout)
+        : { ok: false, status: null };
+    return {
+        sandbox_id: sandboxId,
+        port,
+        preview_url: previewUrl,
+        preview_ready: edge.ok,
+        internal_status: internal.status,
+        edge_status: edge.status,
+        latency_ms: edge.latency_ms ?? null,
+    };
+}
+async function doctorSandbox(sandboxId, port, probePath) {
+    const c = client();
+    const sandbox = unwrap(await c.apiGet(apiPath(`/sandboxes/${enc(sandboxId)}`)));
+    const internal = await probeInternalHttp(c, sandboxId, port, probePath);
+    let exposeData = {};
+    try {
+        exposeData = unwrap(await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/expose`), {
+            port,
+            title: "doctor probe",
+        }));
+    }
+    catch (err) {
+        exposeData = { error: err instanceof Error ? err.message : String(err) };
+    }
+    const previewUrl = extractUrl(exposeData);
+    const edge = previewUrl
+        ? await probePublicPreview(previewUrl, probePath)
+        : { ok: false, status: null, error: "No preview URL returned" };
+    return {
+        sandbox_id: sandboxId,
+        sandbox_state: sandbox["state"] ?? sandbox["status"] ?? "unknown",
+        process: internal.ok ? "listening" : "not_ready",
+        route: previewUrl ? "created" : "missing",
+        tls: edge.error && /tls|certificate|ssl/i.test(edge.error) ? "not_ready" : previewUrl ? "checked" : "unknown",
+        internal_probe: internal,
+        edge_probe: edge,
+        preview_ready: edge.ok,
+        preview_url: previewUrl,
+        expose: exposeData,
+    };
+}
+function renderDoctorReport(report) {
+    console.log();
+    console.log(chalk.bold("Sandbox Doctor"));
+    console.log();
+    console.log(`  ${chalk.bold("Sandbox")}       ${report["sandbox_id"]}`);
+    console.log(`  ${chalk.bold("State")}         ${report["sandbox_state"]}`);
+    console.log(`  ${chalk.bold("Process")}       ${report["process"]}`);
+    console.log(`  ${chalk.bold("Route")}         ${report["route"]}`);
+    console.log(`  ${chalk.bold("TLS/edge")}      ${report["tls"]}`);
+    console.log(`  ${chalk.bold("Preview ready")} ${report["preview_ready"] ? chalk.green("yes") : chalk.red("no")}`);
+    if (report["preview_url"]) {
+        console.log(`  ${chalk.bold("Preview URL")}   ${chalk.cyan(String(report["preview_url"]))}`);
+    }
+    console.log();
+    if (!report["preview_ready"]) {
+        console.log(chalk.yellow("  Preview is not externally ready yet. Internal app health and edge probe details are in --json output."));
+        console.log();
+    }
+}
+async function createSandboxForDeploy(c, template, name) {
+    const body = { template_id: template };
+    if (name)
+        body["name"] = name;
+    const created = unwrap(await c.apiPost(apiPath("/sandboxes"), body));
+    const sandboxId = typeof created["id"] === "string" ? created["id"] : "";
+    if (!sandboxId)
+        throw new UserError("Sandbox create did not return an id.");
+    return sandboxId;
+}
+async function waitForSandboxRunning(c, sandboxId, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    while (Date.now() < deadline) {
+        const sandbox = unwrap(await c.apiGet(apiPath(`/sandboxes/${enc(sandboxId)}`)));
+        const state = String(sandbox["state"] ?? sandbox["status"] ?? "").toLowerCase();
+        if (state === "running" || state === "active")
+            return;
+        if (state === "error" || state === "failed") {
+            throw new UserError(`Sandbox ${sandboxId} entered ${state} state.`);
+        }
+        await sleep(1500);
+    }
+    throw new UserError(`Sandbox ${sandboxId} did not become running within ${timeoutSec}s.`);
+}
+function createDeployArchive(sourceDir) {
+    const archivePath = path.join(os.tmpdir(), `miosa-deploy-${process.pid}-${Date.now()}.tgz`);
+    const result = spawnSync("tar", [
+        "--exclude",
+        ".git",
+        "--exclude",
+        "node_modules",
+        "--exclude",
+        ".next",
+        "--exclude",
+        "dist",
+        "-czf",
+        archivePath,
+        "-C",
+        sourceDir,
+        ".",
+    ], { stdio: "pipe" });
+    if (result.status !== 0) {
+        throw new UserError(`Could not archive ${sourceDir}: ${result.stderr.toString().trim() || "tar failed"}`);
+    }
+    return archivePath;
+}
+async function uploadFileToSandbox(c, sandboxId, localPath, remotePath) {
+    await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/files`), {
+        path: remotePath,
+        content: fs.readFileSync(localPath).toString("base64"),
+    });
+}
+async function uploadDirToSandbox(sandboxId, localDir, remoteDir, opts) {
+    const sourceDir = path.resolve(localDir);
+    if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) {
+        throw new UserError(`Local directory not found: ${sourceDir}`);
+    }
+    const c = client();
+    const archivePath = createDeployArchive(sourceDir);
+    const remoteArchive = `/tmp/miosa-upload-${Date.now()}.tgz`;
+    try {
+        await uploadFileToSandbox(c, sandboxId, archivePath, remoteArchive);
+        const clean = opts.delete
+            ? `rm -rf ${shellQuote(remoteDir)} && mkdir -p ${shellQuote(remoteDir)}`
+            : `mkdir -p ${shellQuote(remoteDir)}`;
+        await execSandbox(c, sandboxId, `${clean} && tar -xzf ${shellQuote(remoteArchive)} -C ${shellQuote(remoteDir)} && rm -f ${shellQuote(remoteArchive)}`, "/");
+    }
+    finally {
+        fs.rmSync(archivePath, { force: true });
+    }
+    return {
+        sandbox_id: sandboxId,
+        local_dir: sourceDir,
+        remote_dir: remoteDir,
+        files_label: path.basename(sourceDir) || sourceDir,
+    };
+}
+async function execSandbox(c, sandboxId, command, cwd, timeout) {
+    const body = { command: commandInCwd(command, cwd) };
+    if (cwd) {
+        body["cwd"] = cwd;
+        body["dir"] = cwd;
+    }
+    if (timeout != null)
+        body["timeout"] = timeout;
+    const result = unwrap(await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/exec`), body));
+    const exitCode = Number(result["exit_code"] ?? 0);
+    if (exitCode !== 0) {
+        throw new UserError(`Sandbox command failed with exit code ${exitCode}: ${command}`, String(result["stderr"] ?? result["stdout"] ?? ""));
+    }
+    return result;
+}
+async function waitForInternalHttp(c, sandboxId, port, probePath, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    let last = { ok: false, status: null };
+    while (Date.now() < deadline) {
+        last = await probeInternalHttp(c, sandboxId, port, probePath);
+        if (last.ok)
+            return last;
+        await sleep(1500);
+    }
+    throw new UserError(`App did not answer inside the sandbox on port ${port} within ${timeoutSec}s.`, last.error);
+}
+async function probeInternalHttp(c, sandboxId, port, probePath) {
+    try {
+        const result = await execSandbox(c, sandboxId, `python3 - <<'PY'\nimport urllib.request, sys\nurl = 'http://127.0.0.1:${port}${probePath.startsWith("/") ? probePath : `/${probePath}`}'\ntry:\n    r = urllib.request.urlopen(url, timeout=3)\n    print(r.status)\n    sys.exit(0 if 200 <= r.status < 400 else 1)\nexcept Exception as e:\n    print(e)\n    sys.exit(1)\nPY`, "/", 10);
+        const status = Number(String(result["stdout"] ?? "").trim().split(/\s+/)[0]);
+        return { ok: Number.isFinite(status) && status >= 200 && status < 400, status };
+    }
+    catch (err) {
+        return { ok: false, status: null, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+async function waitForPublicPreview(previewUrl, probePath, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    let last = { ok: false, status: null };
+    while (Date.now() < deadline) {
+        last = await probePublicPreview(previewUrl, probePath);
+        if (last.ok)
+            return last;
+        await sleep(2000);
+    }
+    throw new UserError(`Preview URL was created but did not become publicly ready within ${timeoutSec}s.`, last.error ?? (last.status ? `Last HTTP status: ${last.status}` : undefined));
+}
+async function probePublicPreview(previewUrl, probePath) {
+    try {
+        const url = new URL(previewUrl);
+        url.pathname = joinUrlPath(url.pathname, probePath);
+        const t0 = Date.now();
+        const res = await fetch(url, { method: "GET", redirect: "manual" });
+        return {
+            ok: (res.status >= 200 && res.status < 400) || res.status === 401 || res.status === 403,
+            status: res.status,
+            latency_ms: Date.now() - t0,
+        };
+    }
+    catch (err) {
+        return { ok: false, status: null, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+async function waitForLocalHttp(localPort, probePath, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    let last = { ok: false, status: null };
+    const url = `http://127.0.0.1:${localPort}${probePath.startsWith("/") ? probePath : `/${probePath}`}`;
+    while (Date.now() < deadline) {
+        last = await probePublicPreview(url, "/");
+        if (last.ok)
+            return last;
+        await sleep(1000);
+    }
+    throw new UserError(`Local forwarded URL did not answer within ${timeoutSec}s.`, last.error ?? (last.status ? `Last HTTP status: ${last.status}` : undefined));
+}
+function defaultInstallCommand(sourceDir) {
+    if (fs.existsSync(path.join(sourceDir, "package.json")))
+        return "npm install";
+    if (fs.existsSync(path.join(sourceDir, "requirements.txt")))
+        return "pip install -r requirements.txt";
+    return null;
+}
+function defaultStartCommand(framework, port) {
+    if (framework === "nextjs")
+        return `npm run dev -- -H 0.0.0.0 -p ${port}`;
+    if (framework === "vite-react")
+        return `npm run dev -- --host 0.0.0.0 --port ${port}`;
+    if (framework === "static")
+        return `python3 -m http.server ${port} --bind 0.0.0.0`;
+    return `npm run dev -- --host 0.0.0.0 --port ${port}`;
+}
+function extractUrl(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const row = value;
+    for (const key of ["url", "preview_url", "public_url"]) {
+        if (typeof row[key] === "string" && row[key])
+            return row[key];
+    }
+    return null;
+}
+function isSandboxTarget(value) {
+    const idx = value.indexOf(":");
+    if (idx <= 0)
+        return false;
+    return value.slice(idx + 1).startsWith("/");
+}
+function parseSandboxTarget(target) {
+    const idx = target.indexOf(":");
+    if (idx <= 0 || idx === target.length - 1) {
+        throw new UserError(`Invalid sandbox target: ${target}`, "Use the form <sandbox-id>:/absolute/path");
+    }
+    const sandboxId = target.slice(0, idx);
+    const remotePath = target.slice(idx + 1);
+    if (!remotePath.startsWith("/")) {
+        throw new UserError(`Invalid remote path: ${remotePath}`, "Sandbox copy targets must use an absolute path, e.g. sbx_123:/workspace");
+    }
+    return { sandboxId, remotePath };
+}
+async function downloadSandboxPath(sandboxId, remotePath, localTarget) {
+    const c = client();
+    const kind = await remotePathKind(c, sandboxId, remotePath);
+    if (kind === "directory") {
+        const remoteArchive = `/tmp/miosa-copy-${Date.now()}.tgz`;
+        await execSandbox(c, sandboxId, `tar -czf ${shellQuote(remoteArchive)} -C ${shellQuote(remotePath)} .`, "/");
+        const archiveBytes = await readSandboxFile(c, sandboxId, remoteArchive);
+        const localDir = path.resolve(localTarget);
+        fs.mkdirSync(localDir, { recursive: true });
+        const localArchive = path.join(os.tmpdir(), `miosa-copy-${process.pid}-${Date.now()}.tgz`);
+        fs.writeFileSync(localArchive, archiveBytes);
+        try {
+            const result = spawnSync("tar", ["-xzf", localArchive, "-C", localDir], {
+                stdio: "pipe",
+            });
+            if (result.status !== 0) {
+                throw new UserError(`Could not extract ${remotePath}: ${result.stderr.toString().trim() || "tar failed"}`);
+            }
+        }
+        finally {
+            fs.rmSync(localArchive, { force: true });
+            await execSandbox(c, sandboxId, `rm -f ${shellQuote(remoteArchive)}`, "/").catch(() => ({}));
+        }
+        return {
+            sandbox_id: sandboxId,
+            remote_path: remotePath,
+            local_path: localDir,
+            type: "directory",
+        };
+    }
+    const bytes = await readSandboxFile(c, sandboxId, remotePath);
+    const localPath = fs.existsSync(localTarget) && fs.statSync(localTarget).isDirectory()
+        ? path.join(localTarget, path.basename(remotePath))
+        : localTarget;
+    fs.mkdirSync(path.dirname(path.resolve(localPath)), { recursive: true });
+    fs.writeFileSync(localPath, bytes);
+    return {
+        sandbox_id: sandboxId,
+        remote_path: remotePath,
+        local_path: path.resolve(localPath),
+        type: "file",
+    };
+}
+async function remotePathKind(c, sandboxId, remotePath) {
+    const result = await execSandbox(c, sandboxId, `if [ -d ${shellQuote(remotePath)} ]; then echo directory; elif [ -f ${shellQuote(remotePath)} ]; then echo file; else exit 2; fi`, "/");
+    const kind = String(result["stdout"] ?? "").trim();
+    if (kind === "directory")
+        return "directory";
+    return "file";
+}
+async function readSandboxFile(c, sandboxId, remotePath) {
+    const encoded = enc(remotePath.replace(/^\//, ""));
+    const result = await c.apiGet(apiPath(`/sandboxes/${enc(sandboxId)}/files/${encoded}`));
+    const data = result !== null && typeof result === "object" && !Array.isArray(result)
+        ? (result["data"] ?? result)
+        : result;
+    if (data !== null &&
+        typeof data === "object" &&
+        !Array.isArray(data) &&
+        typeof data["content"] === "string") {
+        return Buffer.from(data["content"], "base64");
+    }
+    throw new UserError(`Could not read sandbox file: ${remotePath}`);
+}
+function commandInCwd(command, cwd) {
+    if (!cwd)
+        return command;
+    return `cd ${shellQuote(cwd)} && ${command}`;
+}
+function backgroundCommand(command) {
+    if (!command.trim())
+        return command;
+    const logPath = `/tmp/miosa-bg-${Date.now()}.log`;
+    return `nohup sh -lc ${shellQuote(command)} > ${shellQuote(logPath)} 2>&1 & echo $!`;
+}
+function collectOption(value, previous) {
+    return [...previous, value];
+}
+function parseEnvPairs(pairs) {
+    const env = {};
+    for (const pair of pairs) {
+        const idx = pair.indexOf("=");
+        if (idx <= 0) {
+            throw new UserError(`Invalid --env value: ${pair}`, "Use KEY=VALUE, for example --env DATABASE_URL=postgresql://...");
+        }
+        env[pair.slice(0, idx)] = pair.slice(idx + 1);
+    }
+    return env;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function joinUrlPath(basePath, probePath) {
+    const probe = probePath.startsWith("/") ? probePath : `/${probePath}`;
+    if (!basePath || basePath === "/")
+        return probe;
+    return `${basePath.replace(/\/$/, "")}${probe}`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 // ── shared helpers ─────────────────────────────────────────────────────────
 function pickFreePort() {
     return new Promise((resolve, reject) => {