@miosa/cli 1.0.56 → 1.0.58

package/dist/commands/sandbox.js

@@ -16,6 +16,10 @@ import { renderTable } from "../ui/table.js";
 import { formatDuration, hintBlock, icon, kvPanel, printBanner, printElapsed, } from "../ui/render.js";
 import { formatBytes } from "../ui/progress.js";
 import { ApiResponseError, MiosaError, NetworkError, ServerError, UserError, } from "../errors.js";
+import { EXIT_USER_ERROR } from "../types.js";
+const DEFAULT_INTERACTIVE_SANDBOX_TIMEOUT_SEC = 3_600;
+const DEFAULT_CREATE_WAIT_TIMEOUT_SEC = 120;
+const EXPIRING_SANDBOX_THRESHOLD_SEC = 5 * 60;
 export function register(program) {
     // -------------------------------------------------------------------------
     // sandbox / sandboxes command group — built manually to avoid subcommand
@@ -207,8 +211,8 @@ export function register(program) {
             body["memory_mb"] = opts.memory;
         if (opts.disk != null)
             body["disk_size_mb"] = opts.disk;
-        if (opts.timeout != null)
-            body["timeout_sec"] = opts.timeout;
+        const timeoutSec = opts.timeout ?? DEFAULT_INTERACTIVE_SANDBOX_TIMEOUT_SEC;
+        body["timeout_sec"] = timeoutSec;
         if (opts.source)
             body["source"] = opts.source;
         if (opts.revision)
@@ -239,7 +243,7 @@ export function register(program) {
         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));
+                const preview = await waitSandboxReady(id, opts.publishPort, opts.probePath ?? "/", Math.max(Math.min(opts.timeout ?? DEFAULT_CREATE_WAIT_TIMEOUT_SEC, DEFAULT_CREATE_WAIT_TIMEOUT_SEC), 30));
                 const latest = unwrap(await client().apiGet(apiPath(`/sandboxes/${enc(id)}`)));
                 Object.assign(sb, latest, {
                     preview,
@@ -258,7 +262,7 @@ export function register(program) {
             }
         }
         else if (opts.wait && id) {
-            const latest = await waitForSandboxRunning(client(), id, Math.max(opts.timeout ?? 120, 30));
+            const latest = await waitForSandboxRunning(client(), id, Math.max(Math.min(timeoutSec, DEFAULT_CREATE_WAIT_TIMEOUT_SEC), 30));
             Object.assign(sb, latest, { ready: true });
         }
         if (json) {
@@ -309,7 +313,7 @@ export function register(program) {
         .command("resume <sandbox-id>")
         .description("Resume a paused Sandbox")
         .option("--json", "Output as JSON")
-        .action((id, opts) => runAction(() => postAndPrint(`/sandboxes/${enc(id)}/resume`, opts, {})));
+        .action((id, opts) => runAction(() => resumeSandboxAndPrint(id, opts)));
     // fork — clone from snapshot in one call (mirrors `box fork`)
     sandbox
         .command("fork <sandbox-id>")
@@ -373,7 +377,7 @@ export function register(program) {
         }
         if (opts.timeout != null)
             body["timeout"] = opts.timeout;
-        await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, body);
+        await postSandboxExecAndPrint(id, opts, body);
     }));
     // exec — positional command arg; --data body overrides when supplied
     addDataOption(sandbox
@@ -383,6 +387,9 @@ export function register(program) {
         .allowExcessArguments()
         .option("--cwd <path>", "Working directory inside the Sandbox")
         .option("--workdir <path>", "Alias for --cwd")
+        .option("--cmd <command>", "Explicit command string to run; avoids CLI parsing command flags")
+        .option("--command <command>", "Alias for --cmd")
+        .option("--shell-cmd <shell>", "Run --cmd through this shell, e.g. 'bash -lc'")
         .option("--env <pair>", "Environment variable KEY=VALUE. Repeatable.", collectOption, [])
         .option("--background", "Start the command in the background and return immediately")
         .option("--detached", "Create a durable backend command and return command_id immediately")
@@ -397,10 +404,10 @@ export function register(program) {
         .action((id, words, opts) => runAction(async () => {
         opts.follow = opts.follow || opts.stream;
         if (opts.data) {
-            await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, {});
+            await postSandboxExecAndPrint(id, opts, {});
             return;
         }
-        const cmd = joinCommandWords(words);
+        const cmd = resolveSandboxCommand(words, opts);
         const effectiveCommand = opts.background
             ? backgroundCommand(cmd)
             : cmd;
@@ -414,7 +421,7 @@ export function register(program) {
         }
         const env = parseEnvPairs(opts.env ?? []);
         if (opts.detached) {
-            const result = await createSandboxCommand(id, words.join(" "), {
+            const result = await createSandboxCommand(id, cmd, {
                 cwd,
                 env,
                 user: opts.user,
@@ -438,7 +445,7 @@ export function register(program) {
             body["env"] = env;
         if (opts.timeout != null)
             body["timeout"] = opts.timeout;
-        await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, body);
+        await postSandboxExecAndPrint(id, opts, body);
     }));
     // run — alias for exec with identical semantics
     addDataOption(sandbox
@@ -448,6 +455,9 @@ export function register(program) {
         .allowExcessArguments()
         .option("--cwd <path>", "Working directory inside the Sandbox")
         .option("--workdir <path>", "Alias for --cwd")
+        .option("--cmd <command>", "Explicit command string to run; avoids CLI parsing command flags")
+        .option("--command <command>", "Alias for --cmd")
+        .option("--shell-cmd <shell>", "Run --cmd through this shell, e.g. 'bash -lc'")
         .option("--env <pair>", "Environment variable KEY=VALUE. Repeatable.", collectOption, [])
         .option("--background", "Start the command in the background and return immediately")
         .option("--detached", "Create a durable backend command and return command_id immediately")
@@ -462,10 +472,10 @@ export function register(program) {
         .action((id, words, opts) => runAction(async () => {
         opts.follow = opts.follow || opts.stream;
         if (opts.data) {
-            await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, {});
+            await postSandboxExecAndPrint(id, opts, {});
             return;
         }
-        const cmd = joinCommandWords(words);
+        const cmd = resolveSandboxCommand(words, opts);
         const effectiveCommand = opts.background
             ? backgroundCommand(cmd)
             : cmd;
@@ -479,7 +489,7 @@ export function register(program) {
         }
         const env = parseEnvPairs(opts.env ?? []);
         if (opts.detached) {
-            const result = await createSandboxCommand(id, words.join(" "), {
+            const result = await createSandboxCommand(id, cmd, {
                 cwd,
                 env,
                 user: opts.user,
@@ -503,19 +513,17 @@ export function register(program) {
             body["env"] = env;
         if (opts.timeout != null)
             body["timeout"] = opts.timeout;
-        await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, body);
+        await postSandboxExecAndPrint(id, opts, body);
     }));
     sandbox
         .command("ports <sandbox-id>")
         .description("List listening TCP ports inside a Sandbox")
         .option("--json", "Output as JSON")
         .action((id, opts) => runAction(async () => {
-        const c = client();
-        const result = await execSandboxRaw(c, id, "ss -ltnH 2>/dev/null || cat /proc/net/tcp /proc/net/tcp6 2>/dev/null");
-        const stdout = String(result["stdout"] ?? "");
-        const ports = parseListeningPorts(stdout);
+        const result = await client().apiGet(apiPath(`/sandboxes/${enc(id)}/ports`));
+        const ports = sandboxPortsFromResponse(result);
         if (isJsonMode(opts)) {
-            console.log(JSON.stringify(ports, null, 2));
+            console.log(JSON.stringify(result, null, 2));
             return;
         }
         if (ports.length === 0) {
@@ -523,6 +531,11 @@ export function register(program) {
             return;
         }
         renderTable(ports, [
+            {
+                header: "PROTO",
+                key: (p) => p.protocol ?? "tcp",
+                width: 8,
+            },
             {
                 header: "PORT",
                 key: "port",
@@ -533,8 +546,33 @@ export function register(program) {
                 key: "address",
                 width: 24,
             },
+            {
+                header: "STATE",
+                key: (p) => p.state ?? "listen",
+                width: 10,
+            },
+            {
+                header: "PROCESS",
+                key: (p) => p.process?.name
+                    ? `${p.process.name}${p.process.pid ? `:${p.process.pid}` : ""}`
+                    : chalk.dim("-"),
+                width: 28,
+            },
         ]);
     }));
+    sandbox
+        .command("metrics <sandbox-id>")
+        .description("Show Sandbox resource, uptime, timeout, and readiness metrics")
+        .option("--window <window>", "Metrics window: 1h, 24h, or 7d", "1h")
+        .option("--json", "Output as JSON")
+        .action((id, opts) => runAction(async () => {
+        const result = await client().apiGet(apiPath(`/sandboxes/${enc(id)}/metrics?window=${enc(opts.window)}`));
+        if (isJsonMode(opts)) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        renderResourceMetrics("Sandbox metrics", result);
+    }));
     sandbox
         .command("deploy [local-dir]")
         .description("Upload an app directory, start it in a sandbox, expose a preview URL, and wait for readiness")
@@ -652,6 +690,7 @@ export function register(program) {
         .option("--run-command <cmd>", "Run command for dynamic/server deployments")
         .option("--docker-deploy", "Publish onto the workspace Docker Deploy runtime instead of standard app hosting")
         .option("--domain <domain>", "Custom domain to attach")
+        .option("--deployment-type <type>", "Deployment runtime type: miosa_deploy, docker_deploy, dynamic, static")
         .option("--database <mode>", "none, create:postgres, postgres, or existing:<db-id>")
         .option("--port <port>", "Runtime port for dynamic deployments", parseIntegerOption)
         .option("--wait", "Wait for the production URL to answer")
@@ -669,6 +708,10 @@ export function register(program) {
         console.log(`  ${chalk.bold("App")}      ${result.deployment_id ?? result.app_id ?? ""}`);
         if (result.release_id)
             console.log(`  ${chalk.bold("Release")}  ${result.release_id}`);
+        if (result.deployment_product)
+            console.log(`  ${chalk.bold("Product")}  ${String(result.deployment_product)}`);
+        if (result.docker_deploy_host_id)
+            console.log(`  ${chalk.bold("Docker")}   ${String(result.docker_deploy_host_id)}`);
         if (result.url)
             console.log(`  ${chalk.bold("URL")}      ${chalk.cyan(String(result.url))}`);
         console.log(`  ${chalk.bold("Ready")}    ${result.ready ? chalk.green("yes") : chalk.yellow("pending")}`);
@@ -733,6 +776,7 @@ export function register(program) {
         .description("Manage named long-running processes inside a sandbox");
     service
         .command("start <sandbox-id> <name>")
+        .alias("up")
         .requiredOption("--cmd <command>", "Command to start")
         .option("--cwd <path>", "Working directory inside the sandbox", "/workspace")
         .option("--port <port>", "Port served by this service", parseIntegerOption)
@@ -901,6 +945,20 @@ export function register(program) {
         }
         renderDoctorReport(report);
     }));
+    sandbox
+        .command("recover <name-or-id>")
+        .description("Inspect a failed or partial sandbox deploy and print recovery commands")
+        .option("--port <port>", "App port to diagnose", parseIntegerOption)
+        .option("--probe-path <path>", "HTTP path to probe", "/")
+        .option("--json", "Output as JSON")
+        .action((idOrName, opts) => runAction(async () => {
+        const report = await recoverSandboxDeploy(idOrName, opts);
+        if (isJsonMode(opts)) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        renderRecoverReport(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.
@@ -1624,6 +1682,13 @@ async function createSandboxCommand(sandboxId, command, opts) {
         status: result["status"] ?? "running",
     };
 }
+function warnOnTemplatePortMismatch(template, port, opts) {
+    if (isJsonMode(opts))
+        return;
+    if ((template === "nextjs" || template === "next-js") && port !== 3000) {
+        console.error(chalk.yellow("Next.js sandbox templates default to port 3000. Use --port 3000 unless you intentionally changed the app readiness port."));
+    }
+}
 function serviceLogPath(name) {
     return `/tmp/miosa-services/${name}.log`;
 }
@@ -1652,6 +1717,7 @@ async function deploySandbox(localDir, opts) {
         manifestPort(appManifest) ??
         detection?.port ??
         5173;
+    warnOnTemplatePortMismatch(opts.template ?? appManifest?.template ?? null, port, opts);
     const probePath = opts.probePath ?? manifestProbePath(appManifest) ?? "/";
     let remoteWorkdir = normalizeRemoteWorkdir(appManifest?.workdir ?? "/workspace");
     const start = opts.start ??
@@ -1802,6 +1868,11 @@ async function publishSandbox(sandboxId, opts) {
         body["domain"] = opts.domain;
     if (opts.port != null)
         body["port"] = opts.port;
+    const deploymentType = opts.dockerDeploy
+        ? "docker-deploy"
+        : opts.deploymentType;
+    if (deploymentType)
+        body["deployment_type"] = deploymentType;
     const database = parsePublishDatabase(opts.database);
     if (database !== undefined)
         body["database"] = database;
@@ -1822,11 +1893,29 @@ async function publishSandbox(sandboxId, opts) {
         extractUrl(deployment) ??
         stringField(data, "url") ??
         null;
+    let deploymentProduct = stringField(response, "deployment_product") ??
+        stringField(data, "deployment_product") ??
+        stringField(deployment, "deployment_product") ??
+        stringField(asRecord(deployment?.["metadata"]), "deployment_product") ??
+        null;
+    let dockerDeployHostId = stringField(response, "docker_deploy_host_id") ??
+        stringField(data, "docker_deploy_host_id") ??
+        stringField(deployment, "docker_deploy_host_id") ??
+        stringField(asRecord(deployment?.["metadata"]), "docker_deploy_host_id") ??
+        null;
     if (opts.wait && deploymentId) {
         deployStep(opts, "Waiting for durable deployment");
         const waited = await waitForDeploymentReady(c, deploymentId, opts.timeout);
         state = stringField(waited, "state") ?? state;
         url = extractUrl(waited) ?? url;
+        deploymentProduct =
+            stringField(waited, "deployment_product") ??
+                stringField(asRecord(waited["metadata"]), "deployment_product") ??
+                deploymentProduct;
+        dockerDeployHostId =
+            stringField(waited, "docker_deploy_host_id") ??
+                stringField(asRecord(waited["metadata"]), "docker_deploy_host_id") ??
+                dockerDeployHostId;
         response["state"] = state;
         if (url)
             response["url"] = url;
@@ -1852,6 +1941,8 @@ async function publishSandbox(sandboxId, opts) {
         version_id: versionId,
         url,
         state,
+        deployment_product: deploymentProduct,
+        docker_deploy_host_id: dockerDeployHostId,
         ready,
         probe,
         data: raw,
@@ -1950,6 +2041,188 @@ function renderDoctorReport(report) {
         console.log();
     }
 }
+async function recoverSandboxDeploy(idOrName, opts) {
+    const c = client();
+    const resolved = await resolveSandboxForRecovery(c, idOrName);
+    if (!resolved.sandbox) {
+        return {
+            query: idOrName,
+            sandbox: null,
+            sandbox_id: null,
+            matched_by: null,
+            exec_ok: false,
+            app_port: opts.port ?? null,
+            preview_ready: null,
+            preview_url: null,
+            doctor: null,
+            recommendations: [
+                "No matching sandbox was found. Run `miosa sandbox list --json` and retry with a sandbox ID.",
+            ],
+            commands: {
+                list: "miosa sandbox list --json",
+            },
+        };
+    }
+    const sandbox = resolved.sandbox;
+    const sandboxId = str(sandbox["id"]);
+    const name = stringOrNull(sandbox["name"]);
+    const template = stringOrNull(sandbox["template_id"]);
+    const port = opts.port ?? suggestedRecoveryPort(template);
+    const execOk = await checkSandboxExec(c, sandboxId);
+    const doctor = port != null ? await safeDoctorSandbox(sandboxId, port, opts.probePath) : null;
+    const previewUrl = stringOrNull(doctor?.["preview_url"]);
+    const previewReady = doctor && typeof doctor["preview_ready"] === "boolean"
+        ? Boolean(doctor["preview_ready"])
+        : null;
+    const recommendations = buildRecoveryRecommendations({
+        sandbox,
+        execOk,
+        port,
+        previewReady,
+        template,
+    });
+    return {
+        query: idOrName,
+        sandbox,
+        sandbox_id: sandboxId,
+        matched_by: resolved.matchedBy,
+        exec_ok: execOk,
+        app_port: port,
+        preview_ready: previewReady,
+        preview_url: previewUrl,
+        doctor,
+        recommendations,
+        commands: recoveryCommands(sandboxId, name, port),
+    };
+}
+async function resolveSandboxForRecovery(c, idOrName) {
+    try {
+        const direct = unwrap(await c.apiGet(apiPath(`/sandboxes/${enc(idOrName)}`)));
+        const sandbox = asRecord(direct);
+        if (sandbox)
+            return { sandbox, matchedBy: "id" };
+    }
+    catch {
+        // Fall through to name lookup.
+    }
+    const list = unwrap(await c.apiGet(apiPath("/sandboxes")));
+    const items = Array.isArray(list)
+        ? list
+        : Array.isArray((asRecord(list) ?? {})["data"])
+            ? (asRecord(list) ?? {})["data"]
+            : [];
+    const matches = items
+        .map(asRecord)
+        .filter((item) => Boolean(item))
+        .filter((item) => {
+        const name = stringOrNull(item["name"]);
+        const id = stringOrNull(item["id"]);
+        return name === idOrName || id?.startsWith(idOrName);
+    })
+        .sort((a, b) => {
+        const aTime = Date.parse(stringOrNull(a["created_at"]) ?? "") || 0;
+        const bTime = Date.parse(stringOrNull(b["created_at"]) ?? "") || 0;
+        return bTime - aTime;
+    });
+    return { sandbox: matches[0] ?? null, matchedBy: matches[0] ? "name" : null };
+}
+async function checkSandboxExec(c, sandboxId) {
+    try {
+        const result = unwrap(await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/exec`), {
+            command: "pwd",
+        }));
+        const record = asRecord(result);
+        return Number(record?.["exit_code"] ?? 0) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeDoctorSandbox(sandboxId, port, probePath) {
+    try {
+        return await doctorSandbox(sandboxId, port, probePath);
+    }
+    catch (err) {
+        return {
+            preview_ready: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function suggestedRecoveryPort(template) {
+    if (template === "nextjs" || template === "next-js")
+        return 3000;
+    return null;
+}
+function buildRecoveryRecommendations(input) {
+    const recs = [];
+    const state = stringOrNull(input.sandbox["state"]);
+    const ready = Boolean(input.sandbox["ready"]);
+    if (state !== "running") {
+        recs.push(`Sandbox state is ${state ?? "unknown"}; wait or recreate before uploading files.`);
+    }
+    else if (!ready) {
+        recs.push("Sandbox exists but is not fully ready; try exec/write-file before retrying deploy.");
+    }
+    if (!input.execOk) {
+        recs.push("Exec health failed; retry later or recreate the sandbox.");
+    }
+    else {
+        recs.push("Exec works; if upload/deploy failed, use write-file/patch plus service up.");
+    }
+    if (input.template === "nextjs" && input.port !== 3000) {
+        recs.push("Next.js templates default to port 3000; use 3000 unless you intentionally reconfigured readiness.");
+    }
+    if (input.port != null && input.previewReady === false) {
+        recs.push("Preview is not ready; start the app process, then run sandbox wait.");
+    }
+    if (input.previewReady === true) {
+        recs.push("Preview is ready; publish the sandbox to a durable deployment.");
+    }
+    return recs;
+}
+function recoveryCommands(sandboxId, name, port) {
+    const commands = {
+        health: `miosa sandbox exec ${sandboxId} --json -- pwd`,
+        files: `miosa sandbox write-file ${sandboxId} /workspace/app/page.jsx ./page.jsx --json`,
+    };
+    if (port != null) {
+        commands.start = `miosa sandbox service up ${sandboxId} next --cwd /workspace --port ${port} --cmd "npm run dev -- --hostname 0.0.0.0 --port ${port}" --json`;
+        commands.wait = `miosa sandbox wait ${sandboxId} --port ${port} --timeout 180 --json`;
+        commands.publish = `miosa sandbox publish ${sandboxId} --path /workspace --name ${shellArg(name ?? "Recovered app")} --build-command "npm run build" --run-command "npm run start" --port ${port} --wait --timeout 900s --json`;
+    }
+    return commands;
+}
+function renderRecoverReport(report) {
+    if (!report.sandbox_id) {
+        console.log(chalk.red("No matching sandbox found."));
+        console.log(`  ${report.commands["list"]}`);
+        return;
+    }
+    console.log(chalk.bold("Sandbox recovery"));
+    console.log();
+    console.log(`  ${chalk.bold("Sandbox")} ${report.sandbox_id}`);
+    console.log(`  ${chalk.bold("Matched")} ${report.matched_by}`);
+    console.log(`  ${chalk.bold("Exec")}    ${report.exec_ok ? chalk.green("ok") : chalk.red("failed")}`);
+    if (report.app_port != null) {
+        console.log(`  ${chalk.bold("Port")}    ${report.app_port}`);
+    }
+    if (report.preview_url) {
+        console.log(`  ${chalk.bold("Preview")} ${chalk.cyan(report.preview_url)}`);
+    }
+    if (report.preview_ready != null) {
+        console.log(`  ${chalk.bold("Ready")}   ${report.preview_ready ? chalk.green("yes") : chalk.yellow("no")}`);
+    }
+    console.log();
+    for (const rec of report.recommendations) {
+        console.log(`  - ${rec}`);
+    }
+    console.log();
+    console.log(chalk.bold("Next commands"));
+    for (const [label, command] of Object.entries(report.commands)) {
+        console.log(`  ${chalk.dim(label.padEnd(7))} ${command}`);
+    }
+}
 async function createSandboxForDeploy(c, template, name, source) {
     const body = { template_id: template };
     if (name)
@@ -2000,12 +2273,115 @@ async function waitForSandboxRunning(c, sandboxId, timeoutSec) {
         if (state === "running" || state === "active")
             return sandbox;
         if (state === "error" || state === "failed") {
-            throw new UserError(`Sandbox ${sandboxId} entered ${state} state.`);
+            throw sandboxStateError(sandboxId, sandbox, state);
+        }
+        if (state === "destroyed") {
+            throw sandboxStateError(sandboxId, sandbox, state);
         }
         await sleep(1500);
     }
     throw new UserError(`Sandbox ${sandboxId} did not become running within ${timeoutSec}s.`);
 }
+async function resumeSandboxAndPrint(sandboxId, opts) {
+    try {
+        await postAndPrint(`/sandboxes/${enc(sandboxId)}/resume`, opts, {});
+    }
+    catch (err) {
+        if (err instanceof ApiResponseError && err.code === "SANDBOX_NOT_PAUSED") {
+            throw await enrichSandboxLifecycleError(sandboxId, err);
+        }
+        throw err;
+    }
+}
+async function postSandboxExecAndPrint(sandboxId, opts, body) {
+    try {
+        const value = unwrap(await client().apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/exec`), body));
+        printValue(value, opts);
+    }
+    catch (err) {
+        if (err instanceof ApiResponseError && err.code === "SANDBOX_NOT_RUNNING") {
+            throw await enrichSandboxLifecycleError(sandboxId, err);
+        }
+        throw err;
+    }
+}
+async function enrichSandboxLifecycleError(sandboxId, err) {
+    let sandbox = null;
+    try {
+        sandbox = unwrap(await client().apiGet(apiPath(`/sandboxes/${enc(sandboxId)}`)));
+    }
+    catch {
+        // Preserve the original API error when the follow-up lookup is unavailable.
+    }
+    if (!sandbox)
+        return err;
+    const state = String(sandbox["state"] ?? sandbox["status"] ?? "unknown");
+    const details = sandboxLifecycleDetails(sandbox);
+    const message = state === "destroyed"
+        ? `Sandbox ${sandboxId} is destroyed, not paused. It cannot be resumed.`
+        : `${err.message}. Current sandbox state: ${state}.`;
+    return new ApiResponseError(err.code, message, EXIT_USER_ERROR, false, sandboxRecoveryHint(sandboxId, sandbox), details, err.requestId);
+}
+function sandboxStateError(sandboxId, sandbox, state) {
+    const reason = sandboxLastErrorReason(sandbox);
+    const message = state === "destroyed"
+        ? `Sandbox ${sandboxId} is destroyed, not paused. It cannot be resumed.`
+        : `Sandbox ${sandboxId} entered ${state} state${reason ? `: ${reason}` : ""}.`;
+    return new UserError(message, sandboxRecoveryHint(sandboxId, sandbox));
+}
+function sandboxRecoveryHint(sandboxId, sandbox) {
+    const state = String(sandbox["state"] ?? sandbox["status"] ?? "unknown");
+    const name = String(sandbox["name"] ?? "new-sandbox");
+    const template = String(sandbox["template_id"] ?? "nextjs");
+    const timeoutRemainingSec = timeoutRemainingSeconds(sandbox);
+    if (state === "running" && timeoutRemainingSec != null && timeoutRemainingSec <= EXPIRING_SANDBOX_THRESHOLD_SEC) {
+        return `Sandbox expires soon. Extend it with: miosa sandbox extend ${sandboxId} --timeout 1h`;
+    }
+    if (state === "paused") {
+        return `Resume it with: miosa sandbox resume ${sandboxId}`;
+    }
+    if (state === "destroyed") {
+        return `Create a replacement with: miosa sandbox create --template ${template} --name ${shellQuote(name)} --timeout 1h --wait --json`;
+    }
+    if (state === "error" || state === "failed") {
+        return `Inspect recovery with: miosa sandbox recover ${sandboxId}`;
+    }
+    return `Inspect it with: miosa sandbox show ${sandboxId} --json`;
+}
+function sandboxLifecycleDetails(sandbox) {
+    return {
+        sandbox_id: sandbox["id"],
+        name: sandbox["name"],
+        state: sandbox["state"] ?? sandbox["status"],
+        timeout_sec: sandbox["timeout_sec"],
+        timeout_remaining_ms: sandbox["timeout_remaining_ms"],
+        destroyed_at: sandbox["destroyed_at"],
+        last_error: sandboxLastError(sandbox),
+    };
+}
+function sandboxLastErrorReason(sandbox) {
+    const lastError = sandboxLastError(sandbox);
+    if (!lastError)
+        return null;
+    const reason = lastError["reason"];
+    return typeof reason === "string" && reason.length > 0 ? reason : null;
+}
+function sandboxLastError(sandbox) {
+    const metadata = sandbox["metadata"];
+    if (!metadata || typeof metadata !== "object")
+        return null;
+    const lastError = metadata["last_error"];
+    return lastError && typeof lastError === "object"
+        ? lastError
+        : null;
+}
+function timeoutRemainingSeconds(sandbox) {
+    const ms = sandbox["timeout_remaining_ms"];
+    if (typeof ms === "number")
+        return Math.ceil(ms / 1000);
+    const sec = sandbox["timeout_remaining_sec"];
+    return typeof sec === "number" ? sec : null;
+}
 function createDeployArchive(sourceDir) {
     const archivePath = path.join(os.tmpdir(), `miosa-deploy-${process.pid}-${Date.now()}.tgz`);
     const result = spawnSync("tar", [
@@ -2077,7 +2453,7 @@ function shouldFallbackSandboxUpload(err) {
             /AGENT_UNAVAILABLE|SANDBOX_FILE_AGENT_UNAVAILABLE/i.test(err.code));
     }
     if (err instanceof Error) {
-        return /fetch failed|ECONNRESET|HTTP 502|AGENT_UNAVAILABLE/i.test(err.message);
+        return /fetch failed|ECONNRESET|HTTP 502|AGENT_UNAVAILABLE|other side closed|socket hang up/i.test(err.message);
     }
     return false;
 }
@@ -2204,37 +2580,93 @@ async function execSandboxRaw(c, sandboxId, command, cwd, timeout) {
         body["timeout"] = timeout;
     return unwrap(await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/exec`), body));
 }
-function parseListeningPorts(stdout) {
-    const lines = stdout.split("\n").map((l) => l.trim());
-    const seen = new Set();
-    const out = [];
-    // ss -ltnH columns: State Recv-Q Send-Q Local-Address:Port Peer-Address:Port
-    const ssLine = /^LISTEN\s+\d+\s+\d+\s+(\S+):(\d+)\s+/;
-    // /proc/net/tcp: sl local_address rem_address st ... (hex)
-    const procLine = /^\d+:\s+([0-9A-Fa-f]+):([0-9A-Fa-f]+)\s+\S+\s+([0-9A-Fa-f]+)/;
-    for (const line of lines) {
-        if (!line)
-            continue;
-        const ss = ssLine.exec(line);
-        if (ss && ss[2]) {
-            const port = Number(ss[2]);
-            if (!seen.has(port)) {
-                seen.add(port);
-                out.push({ port, address: ss[1] ?? "*" });
-            }
-            continue;
-        }
-        const proc = procLine.exec(line);
-        if (proc && proc[3] === "0A" && proc[2]) {
-            const port = parseInt(proc[2], 16);
-            if (!Number.isNaN(port) && !seen.has(port)) {
-                seen.add(port);
-                out.push({ port, address: "*" });
-            }
-        }
+function sandboxPortsFromResponse(raw) {
+    const root = unwrap(raw);
+    if (Array.isArray(root))
+        return root;
+    if (root && typeof root === "object") {
+        const row = root;
+        if (Array.isArray(row["ports"]))
+            return row["ports"];
+        if (Array.isArray(row["data"]))
+            return row["data"];
+    }
+    return [];
+}
+function renderResourceMetrics(title, raw) {
+    const root = unwrap(raw);
+    if (!root || typeof root !== "object") {
+        printValue(root, {});
+        return;
     }
-    out.sort((a, b) => a.port - b.port);
-    return out;
+    const row = root;
+    const current = row["current"] && typeof row["current"] === "object"
+        ? row["current"]
+        : {};
+    printBanner({ subtitle: title });
+    console.log(kvPanel([
+        { label: "resource_id", value: String(row["resource_id"] ?? row["sandbox_id"] ?? "-") },
+        { label: "window", value: String(row["window"] ?? "1h") },
+        { label: "state", value: formatState(current["state"]) },
+        { label: "ready", value: formatBool(current["ready"]) },
+        { label: "cpu", value: formatMaybe(current["cpu_count"]) },
+        { label: "memory", value: formatMb(current["memory_mb"]) },
+        { label: "disk", value: formatMb(current["disk_size_mb"]) },
+        { label: "uptime", value: formatSeconds(current["uptime_sec"]) },
+        {
+            label: "timeout_remaining",
+            value: formatSecondsOrAlwaysOn(current["timeout_remaining_sec"]),
+        },
+        { label: "node", value: formatMaybe(current["node_id"]) },
+        { label: "ip", value: formatMaybe(current["ip_address"]) },
+        { label: "boot", value: formatMs(current["boot_ms"]) },
+        { label: "envd_ready", value: formatMs(current["envd_ready_ms"]) },
+    ]));
+}
+function formatState(value) {
+    const state = String(value ?? "unknown");
+    if (["running", "active", "healthy", "ready"].includes(state)) {
+        return chalk.green(state);
+    }
+    if (["provisioning", "starting", "building", "pending"].includes(state)) {
+        return chalk.yellow(state);
+    }
+    if (["failed", "error", "unhealthy"].includes(state)) {
+        return chalk.red(state);
+    }
+    return state;
+}
+function formatBool(value) {
+    if (value === true)
+        return chalk.green("true");
+    if (value === false)
+        return chalk.red("false");
+    return chalk.dim("-");
+}
+function formatMaybe(value) {
+    if (value === null || value === undefined || value === "")
+        return chalk.dim("-");
+    return String(value);
+}
+function formatMb(value) {
+    if (typeof value !== "number")
+        return formatMaybe(value);
+    return formatBytes(value * 1024 * 1024);
+}
+function formatMs(value) {
+    if (typeof value !== "number")
+        return formatMaybe(value);
+    return `${value}ms`;
+}
+function formatSeconds(value) {
+    if (typeof value !== "number")
+        return formatMaybe(value);
+    return formatDuration(value * 1000);
+}
+function formatSecondsOrAlwaysOn(value) {
+    if (value === null || value === undefined)
+        return chalk.dim("always-on/none");
+    return formatSeconds(value);
 }
 // Stream exec output: run in background to a log file, poll-read new bytes
 // until the process exits, then print the final exit code.
@@ -2524,6 +2956,15 @@ function backgroundCommand(command) {
     const logPath = `/tmp/miosa-bg-${Date.now()}.log`;
     return `nohup sh -lc ${shellQuote(command)} > ${shellQuote(logPath)} 2>&1 & echo $!`;
 }
+function resolveSandboxCommand(words, opts) {
+    const positional = words.length === 1 ? (words[0] ?? "") : joinCommandWords(words);
+    const cmd = opts.cmd ?? opts.command ?? positional;
+    if (!opts.shellCmd)
+        return cmd;
+    if (!cmd.trim())
+        return opts.shellCmd;
+    return `${opts.shellCmd} ${shellQuote(cmd)}`;
+}
 function collectOption(value, previous) {
     return [...previous, value];
 }
@@ -2657,6 +3098,12 @@ function str(v) {
         return chalk.dim("—");
     return String(v);
 }
+function stringOrNull(v) {
+    return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function shellArg(value) {
+    return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
 /** Apply semantic color to a sandbox status string. */
 function statusColor(s) {
     const lower = s.toLowerCase().trim();