@miosa/cli 1.0.8 → 1.0.10

package/dist/commands/sandbox.js

@@ -1,12 +1,18 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import os from "node:os";
+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
@@ -80,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)}`)));
@@ -134,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();
@@ -154,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 () => {
@@ -182,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
@@ -214,11 +252,95 @@ export function register(program) {
         }
         await postAndPrint(`/sandboxes/${enc(id)}/${enc(action)}`, opts, {});
     }));
+    // stop — snapshot + pause (mirrors `box stop`)
+    sandbox
+        .command("stop <sandbox-id>")
+        .description("Snapshot the Sandbox and pause billing")
+        .option("--no-snapshot", "Skip the snapshot step (pause only)")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        if (opts.snapshot !== false) {
+            await postAndPrint(`/sandboxes/${enc(id)}/snapshots`, opts, {});
+        }
+        await postAndPrint(`/sandboxes/${enc(id)}/pause`, opts, {});
+    }));
+    // resume — direct shortcut (mirrors `box resume`)
+    sandbox
+        .command("resume <sandbox-id>")
+        .description("Resume a paused Sandbox")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(() => postAndPrint(`/sandboxes/${enc(id)}/resume`, opts, {})));
+    // fork — clone from snapshot in one call (mirrors `box fork`)
+    sandbox
+        .command("fork <sandbox-id>")
+        .description("Clone (fork) a Sandbox from its current state")
+        .option("--name <name>", "Optional name for the forked Sandbox")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        const body = {};
+        if (opts.name)
+            body["name"] = opts.name;
+        await postAndPrint(`/sandboxes/${enc(id)}/fork`, opts, body);
+    }));
+    // desktop — open the Sandbox's web desktop URL (mirrors `box desktop`).
+    // Sandboxes are headless by default; only templates that expose a desktop
+    // port (e.g. `miosa-sandbox` w/ Kasm) emit a `preview_url`. We surface that.
+    sandbox
+        .command("desktop <sandbox-id>")
+        .description("Print the Sandbox's web desktop URL (when the template exposes one)")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        if (opts.json) {
+            await getAndPrint(`/sandboxes/${enc(id)}`, opts);
+            return;
+        }
+        const sb = (await getAndPrint(`/sandboxes/${enc(id)}`, {
+            json: true,
+        }));
+        if (sb?.preview_url) {
+            console.log(sb.preview_url);
+        }
+        else {
+            console.error(chalk.yellow("No desktop URL on this Sandbox. Use `miosa desktop open <computer-id>` for Computers, or expose a port via `miosa sandbox` for headless previews."));
+            process.exitCode = 1;
+        }
+    }));
+    // prompt — invoke an in-Sandbox AI agent CLI (mirrors `box prompt`).
+    // Implemented as `exec claude/codex/claude-code <instruction>`.
+    sandbox
+        .command("prompt <sandbox-id> <instruction...>")
+        .description("Run an in-Sandbox AI agent (claude/codex) with the given instruction")
+        .option("--provider <name>", "AI provider: claude (default), codex, claude-code")
+        .option("--model <name>", "Provider-specific model name")
+        .option("--cwd <path>", "Working directory inside the Sandbox")
+        .option("--timeout <sec>", "Exec timeout in seconds", parseInt)
+        .option("--json", "Output as JSON")
+        .action((id, words, opts) => runAction(async () => {
+        const provider = opts.provider ?? "claude";
+        const allowedProviders = ["claude", "codex", "claude-code"];
+        if (!allowedProviders.includes(provider)) {
+            throw new Error(`Unsupported provider "${provider}". Use: ${allowedProviders.join(", ")}`);
+        }
+        const instruction = words.join(" ");
+        const modelFlag = opts.model
+            ? ` --model ${`'${opts.model.replace(/'/g, "'\\''")}'`}`
+            : "";
+        const command = commandInCwd(`${provider}${modelFlag} ${shellQuote(instruction)}`, opts.cwd);
+        const body = { command };
+        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);
+    }));
     // exec — positional command arg; --data body overrides when supplied
     addDataOption(sandbox
         .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("--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 () => {
@@ -227,9 +349,14 @@ export function register(program) {
             return;
         }
         const cmd = words.join(" ");
-        const body = cmd ? { command: cmd } : {};
-        if (opts.cwd)
+        const effectiveCommand = opts.background ? backgroundCommand(cmd) : cmd;
+        const body = cmd
+            ? { command: commandInCwd(effectiveCommand, 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);
@@ -239,6 +366,7 @@ 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("--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 () => {
@@ -247,13 +375,163 @@ export function register(program) {
             return;
         }
         const cmd = words.join(" ");
-        const body = cmd ? { command: cmd } : {};
-        if (opts.cwd)
+        const effectiveCommand = opts.background ? backgroundCommand(cmd) : cmd;
+        const body = cmd
+            ? { command: commandInCwd(effectiveCommand, 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);
     }));
+    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("--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.
@@ -344,6 +622,82 @@ 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>")
+        .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 {
+            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>")
@@ -396,26 +750,53 @@ export function register(program) {
         const qs = opts.lines != null ? `?lines=${opts.lines}` : "";
         await getAndPrint(`/sandboxes/${enc(id)}/logs${qs}`, opts);
     }));
-    // ssh — open browser terminal via platform PTY endpoint
+    // ssh — WS tunnel → local listener → spawn system ssh client
     sandbox
         .command("ssh <sandbox-id>")
-        .description("Open an interactive terminal session for a Sandbox")
-        .option("--print-url", "Print the URL instead of opening a browser")
+        .description("Open an SSH session into a running Sandbox via the platform WS tunnel")
+        .option("-p, --port <n>", "Local port for the tunnel listener", parseInt)
+        .option("-l, --user <name>", "SSH user (default: root)")
+        .option("--no-spawn", "Print connection info instead of spawning the ssh client")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const config = loadConfig();
-        const baseUrl = (config.endpoint || "https://api.miosa.ai").replace(/\/$/, "");
-        const url = `${baseUrl}/api/v1/sandboxes/${enc(id)}/terminal`;
-        if (opts.json) {
-            console.log(JSON.stringify({ url }, null, 2));
-            return;
+        try {
+            await runSandboxSsh(id, opts);
         }
-        if (opts.printUrl) {
-            console.log(url);
-            return;
+        catch (err) {
+            handleError(err);
+        }
+    });
+    // port-forward — TCP listener → WS tunnel → sandbox port
+    sandbox
+        .command("port-forward <sandbox-id>")
+        .alias("forward")
+        .description([
+        "Forward a local TCP port to a port inside a Sandbox via the platform WS tunnel.",
+        "",
+        "Examples:",
+        "  miosa sandbox port-forward sbx_123 --remote 5173",
+        "  miosa sandbox port-forward sbx_123 --remote 5432 --local 15432",
+    ].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, {
+                remotePort: opts.remote,
+                localPort: opts.local ?? opts.remote,
+                wait: !!opts.wait,
+                timeoutSec: opts.timeout,
+                probePath: opts.probePath,
+                json: !!opts.json,
+            });
+        }
+        catch (err) {
+            handleError(err);
         }
-        openUrl(url);
-        console.log(`Opening terminal for sandbox ${id}...`);
     });
     // checkpoint — POST /sandboxes/:id/snapshots
     addDataOption(sandbox
@@ -451,6 +832,686 @@ export function register(program) {
         .option("--json", "Output as JSON")
         .action((id, opts) => runAction(() => getAndPrint(`/sandbox-templates/${enc(id)}`, opts)));
 }
+// ── sandbox ssh implementation ─────────────────────────────────────────────
+//
+// Protocol:
+//   1. Ensure the user has an SSH keypair at ~/.ssh/miosa_sandbox_ed25519.
+//      If not, generate one and register it via POST /sandboxes/:id/ssh-keys.
+//   2. Open a local TCP server on a random (or chosen) port.
+//   3. Each accepted connection is bridged bidirectionally to the platform WS
+//      endpoint wss://<api>/api/v1/sandboxes/:id/ssh-tunnel.
+//   4. Spawn `ssh` pointing at localhost:<port> with the key and user.
+//   5. On ssh exit, close the TCP server and exit.
+const SANDBOX_KEY_PATH = path.join(os.homedir(), ".ssh", "miosa_sandbox_ed25519");
+async function ensureSandboxSshKey(id, apiKey, endpoint) {
+    if (fs.existsSync(SANDBOX_KEY_PATH))
+        return;
+    console.log(chalk.dim("Generating SSH keypair for MIOSA sandbox access..."));
+    fs.mkdirSync(path.join(os.homedir(), ".ssh"), { recursive: true });
+    await new Promise((resolve, reject) => {
+        const child = spawn("ssh-keygen", [
+            "-t",
+            "ed25519",
+            "-f",
+            SANDBOX_KEY_PATH,
+            "-N",
+            "",
+            "-C",
+            "miosa-sandbox",
+        ], { stdio: "pipe" });
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`ssh-keygen exited with code ${code}`));
+        });
+        child.on("error", reject);
+    });
+    // Register the public key with the sandbox
+    const pubKey = fs.readFileSync(`${SANDBOX_KEY_PATH}.pub`, "utf8").trim();
+    const base = endpoint.replace(/\/$/, "");
+    const res = await fetch(`${base}/api/v1/sandboxes/${encodeURIComponent(id)}/ssh-keys`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({ public_key: pubKey }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Failed to register SSH key: ${res.status} ${body}`);
+    }
+    console.log(chalk.green("SSH key registered."));
+}
+function bridgeSandboxWs(socket, wsUrl, apiKey) {
+    let closed = false;
+    function cleanup() {
+        if (closed)
+            return;
+        closed = true;
+        if (!socket.destroyed)
+            socket.destroy();
+    }
+    const ws = new WebSocket(wsUrl, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    ws.on("open", () => {
+        socket.on("data", (chunk) => {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.send(chunk);
+        });
+        socket.on("close", () => {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.close();
+        });
+        socket.on("error", () => ws.close());
+    });
+    ws.on("message", (data) => {
+        if (!socket.destroyed) {
+            socket.write(typeof data === "string" ? Buffer.from(data) : data);
+        }
+    });
+    ws.on("close", cleanup);
+    ws.on("error", (err) => {
+        process.stderr.write(`\r\nWS error for sandbox tunnel: ${err.message}\r\n`);
+        cleanup();
+    });
+}
+async function runSandboxSsh(id, opts) {
+    const config = loadConfig();
+    const apiKey = config.api_key;
+    if (!apiKey)
+        throw new Error("Not authenticated. Run: miosa login");
+    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)}/ssh-tunnel`;
+    await ensureSandboxSshKey(id, String(apiKey), endpoint);
+    // Pick a free local port
+    const localPort = opts.port ?? (await pickFreePort());
+    const user = opts.user ?? "root";
+    if (opts.json) {
+        console.log(JSON.stringify({
+            sandbox_id: id,
+            local_port: localPort,
+            user,
+            ws_url: wsUrl,
+            key_path: SANDBOX_KEY_PATH,
+        }));
+        return;
+    }
+    const server = createServer((socket) => {
+        bridgeSandboxWs(socket, wsUrl, String(apiKey));
+    });
+    await new Promise((resolve, reject) => {
+        server.on("error", reject);
+        server.listen(localPort, "127.0.0.1", resolve);
+    });
+    console.log(chalk.green("Tunnel ready.") +
+        chalk.dim(` 127.0.0.1:${localPort} → sandbox ${id}`));
+    if (opts.spawn === false) {
+        console.log(chalk.dim(`Connect manually: ssh -i ${SANDBOX_KEY_PATH} -p ${localPort} ${user}@127.0.0.1`));
+        console.log(chalk.dim("Press Ctrl+C to close."));
+        await waitForSignal();
+        server.close();
+        return;
+    }
+    const sshArgs = [
+        "-i",
+        SANDBOX_KEY_PATH,
+        "-p",
+        String(localPort),
+        "-o",
+        "StrictHostKeyChecking=no",
+        "-o",
+        "UserKnownHostsFile=/dev/null",
+        "-o",
+        "LogLevel=ERROR",
+        `${user}@127.0.0.1`,
+    ];
+    const sshProc = spawn("ssh", sshArgs, { stdio: "inherit" });
+    const exitCode = await new Promise((resolve) => {
+        sshProc.on("close", (code) => resolve(code ?? 1));
+        sshProc.on("error", (err) => {
+            console.error(chalk.red(`Failed to spawn ssh: ${err.message}`));
+            resolve(1);
+        });
+    });
+    server.close();
+    process.exit(exitCode);
+}
+async function runSandboxPortForward(id, opts) {
+    const config = loadConfig();
+    const apiKey = config.api_key;
+    if (!apiKey)
+        throw new Error("Not authenticated. Run: miosa login");
+    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/${opts.remotePort}`;
+    const stats = { active: 0, total: 0, bytesIn: 0, bytesOut: 0 };
+    const server = createServer((socket) => {
+        stats.active++;
+        stats.total++;
+        const ws = new WebSocket(wsUrl, {
+            headers: { Authorization: `Bearer ${String(apiKey)}` },
+        });
+        ws.on("open", () => {
+            socket.on("data", (chunk) => {
+                stats.bytesIn += chunk.length;
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.send(chunk);
+            });
+            socket.on("close", () => ws.readyState === WebSocket.OPEN && ws.close());
+            socket.on("error", () => ws.close());
+        });
+        ws.on("message", (data) => {
+            const buf = typeof data === "string" ? Buffer.from(data) : data;
+            stats.bytesOut += buf.length;
+            if (!socket.destroyed)
+                socket.write(buf);
+        });
+        ws.on("close", () => {
+            stats.active = Math.max(0, stats.active - 1);
+            if (!socket.destroyed)
+                socket.destroy();
+        });
+        ws.on("error", (err) => {
+            process.stderr.write(`\r\nWS error: ${err.message}\r\n`);
+            if (!socket.destroyed)
+                socket.destroy();
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                reject(new Error(`Port ${opts.localPort} is already in use. Choose another with --local.`));
+            }
+            else {
+                reject(err);
+            }
+        });
+        server.listen(opts.localPort, "127.0.0.1", resolve);
+    });
+    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: 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(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 (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);
+    await waitForSignal();
+    clearInterval(ticker);
+    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 ?? 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 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 };
+}
+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 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) => {
+        const srv = createServer();
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            srv.close(() => {
+                if (addr && typeof addr === "object")
+                    resolve(addr.port);
+                else
+                    reject(new Error("Could not pick a free port"));
+            });
+        });
+    });
+}
+function waitForSignal() {
+    return new Promise((resolve) => {
+        function done() {
+            process.off("SIGINT", done);
+            process.off("SIGTERM", done);
+            resolve();
+        }
+        process.on("SIGINT", done);
+        process.on("SIGTERM", done);
+    });
+}
 function openUrl(url) {
     const command = process.platform === "darwin"
         ? "open"