@miosa/cli 1.0.36 → 1.0.38

package/dist/commands/sandbox.js

@@ -7,6 +7,7 @@ import * as http from "node:http";
 import * as https from "node:https";
 import chalk from "chalk";
 import WebSocket from "ws";
+import { loadAppManifest, manifestPort, manifestProbePath, manifestStartCommand, parseAppManifest, } from "../app-manifest.js";
 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";
@@ -371,12 +372,16 @@ export function register(program) {
     // 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)")
+        .description('Run a command inside a Sandbox (positional args joined as shell command). Use `--` before the command to pass flags, e.g. `sandbox exec <id> -- bash -c "cd x && y"`.')
+        .allowUnknownOption()
+        .allowExcessArguments()
         .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("--detached", "Create a durable backend command and return command_id immediately")
+        .option("--follow", "Stream command output until it exits (alias --stream)")
+        .option("--stream", "Alias for --follow")
         .option("--user <user>", "Run command as user")
         .option("--sudo", "Run command through sudo")
         .option("--tty", "Request TTY metadata for command resource")
@@ -384,11 +389,12 @@ export function register(program) {
         .option("--timeout <sec>", "Exec timeout in seconds", parseIntegerOption))
         .option("--json", "Output as JSON")
         .action((id, words, opts) => runAction(async () => {
+        opts.follow = opts.follow || opts.stream;
         if (opts.data) {
             await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, {});
             return;
         }
-        const cmd = words.join(" ");
+        const cmd = joinCommandWords(words);
         const effectiveCommand = opts.background
             ? backgroundCommand(cmd)
             : cmd;
@@ -402,7 +408,7 @@ export function register(program) {
         }
         const env = parseEnvPairs(opts.env ?? []);
         if (opts.detached) {
-            const result = await createSandboxCommand(id, cmd, {
+            const result = await createSandboxCommand(id, words.join(" "), {
                 cwd,
                 env,
                 user: opts.user,
@@ -418,6 +424,10 @@ export function register(program) {
             console.log(String(result["id"] ?? result["command_id"] ?? ""));
             return;
         }
+        if (opts.follow) {
+            await runFollowExec(id, cmd, cwd, env, opts.timeout, opts);
+            return;
+        }
         if (Object.keys(env).length > 0)
             body["env"] = env;
         if (opts.timeout != null)
@@ -427,12 +437,16 @@ export function register(program) {
     // run — alias for exec with identical semantics
     addDataOption(sandbox
         .command("run <sandbox-id> [command...]")
-        .description("Run a command inside a Sandbox (alias for exec)")
+        .description("Run a command inside a Sandbox (alias for exec). Use `--` before the command to pass flags.")
+        .allowUnknownOption()
+        .allowExcessArguments()
         .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("--detached", "Create a durable backend command and return command_id immediately")
+        .option("--follow", "Stream command output until it exits (alias --stream)")
+        .option("--stream", "Alias for --follow")
         .option("--user <user>", "Run command as user")
         .option("--sudo", "Run command through sudo")
         .option("--tty", "Request TTY metadata for command resource")
@@ -440,11 +454,12 @@ export function register(program) {
         .option("--timeout <sec>", "Exec timeout in seconds", parseIntegerOption))
         .option("--json", "Output as JSON")
         .action((id, words, opts) => runAction(async () => {
+        opts.follow = opts.follow || opts.stream;
         if (opts.data) {
             await postAndPrint(`/sandboxes/${enc(id)}/exec`, opts, {});
             return;
         }
-        const cmd = words.join(" ");
+        const cmd = joinCommandWords(words);
         const effectiveCommand = opts.background
             ? backgroundCommand(cmd)
             : cmd;
@@ -458,7 +473,7 @@ export function register(program) {
         }
         const env = parseEnvPairs(opts.env ?? []);
         if (opts.detached) {
-            const result = await createSandboxCommand(id, cmd, {
+            const result = await createSandboxCommand(id, words.join(" "), {
                 cwd,
                 env,
                 user: opts.user,
@@ -474,12 +489,46 @@ export function register(program) {
             console.log(String(result["id"] ?? result["command_id"] ?? ""));
             return;
         }
+        if (opts.follow) {
+            await runFollowExec(id, cmd, cwd, env, opts.timeout, opts);
+            return;
+        }
         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("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);
+        if (isJsonMode(opts)) {
+            console.log(JSON.stringify(ports, null, 2));
+            return;
+        }
+        if (ports.length === 0) {
+            console.log(chalk.dim("(no listening ports)"));
+            return;
+        }
+        renderTable(ports, [
+            {
+                header: "PORT",
+                key: "port",
+                width: 8,
+            },
+            {
+                header: "ADDRESS",
+                key: "address",
+                width: 24,
+            },
+        ]);
+    }));
     sandbox
         .command("deploy [local-dir]")
         .description("Upload an app directory, start it in a sandbox, expose a preview URL, and wait for readiness")
@@ -491,9 +540,12 @@ export function register(program) {
         .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("--source <source>", "Source: git:https://... or tarball:https://... for repo-backed preview deploy")
+        .option("--revision <revision>", "Git revision/branch for --source git:...")
+        .option("--depth <n>", "Git clone depth for --source git:...", parseIntegerOption)
         .option("--wait", "Wait until the public preview returns a good HTTP status")
         .option("--timeout <duration>", "Wait timeout, e.g. 180s or 3m", parseDurationSec, 180)
-        .option("--probe-path <path>", "HTTP path to probe", "/")
+        .option("--probe-path <path>", "HTTP path to probe")
         .option("--json", "Output as JSON")
         .action((localDir = ".", opts) => runAction(async () => {
         const result = await deploySandbox(localDir, opts);
@@ -591,7 +643,8 @@ export function register(program) {
         .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")
-        .option("--timeout <duration>", "Wait timeout", parseDurationSec, 180)
+        .option("--no-wait", "Return immediately without waiting (this is the default)")
+        .option("--timeout <duration>", "Wait timeout", parseDurationSec, 600)
         .option("--json", "Output as JSON")
         .action((id, opts) => runAction(async () => {
         const result = await publishSandbox(id, opts);
@@ -736,15 +789,29 @@ export function register(program) {
             console.log(JSON.stringify(result, null, 2));
             return;
         }
-        const rows = Array.isArray(result) ? result : [];
+        const rows = Array.isArray(result)
+            ? result
+            : [];
         if (rows.length === 0) {
             console.log(chalk.dim("No sandbox env vars."));
             return;
         }
         renderTable(rows, [
-            { header: "NAME", key: "name", width: 32 },
-            { header: "VALUE", key: "preview", width: 24 },
-            { header: "UPDATED", key: "updated_at", width: 28 },
+            {
+                header: "NAME",
+                key: "name",
+                width: 32,
+            },
+            {
+                header: "VALUE",
+                key: "preview",
+                width: 24,
+            },
+            {
+                header: "UPDATED",
+                key: "updated_at",
+                width: 28,
+            },
         ]);
     }));
     env
@@ -1549,42 +1616,71 @@ function validateServiceName(name) {
 }
 async function deploySandbox(localDir, opts) {
     const sourceDir = path.resolve(localDir);
-    if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) {
+    const sourceBacked = !!opts.source;
+    if (!sourceBacked &&
+        (!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
+    let appManifest = sourceBacked
         ? null
-        : (opts.installCommand ?? defaultInstallCommand(sourceDir));
+        : (loadAppManifest(sourceDir)?.manifest ?? null);
+    const detection = sourceBacked ? null : detectFramework(sourceDir);
+    const port = opts.port ??
+        opts.publishPort ??
+        manifestPort(appManifest) ??
+        detection?.port ??
+        5173;
+    const probePath = opts.probePath ?? manifestProbePath(appManifest) ?? "/";
+    let remoteWorkdir = normalizeRemoteWorkdir(appManifest?.workdir ?? "/workspace");
+    const start = opts.start ??
+        manifestStartCommand(appManifest) ??
+        defaultStartCommand(detection?.framework ?? appManifest?.framework, port);
     const sandboxId = opts.sandbox ??
         (deployStep(opts, "Creating sandbox"),
-            await createSandboxForDeploy(c, opts.template ?? "miosa-sandbox", opts.name));
+            await createSandboxForDeploy(c, opts.template ?? appManifest?.template ?? "miosa-sandbox", opts.name, {
+                source: opts.source,
+                revision: opts.revision,
+                depth: opts.depth,
+            }));
     deployStep(opts, "Waiting for sandbox");
     await waitForSandboxRunning(c, sandboxId, Math.min(opts.timeout, 120));
-    deployStep(opts, "Uploading files");
-    const archivePath = createDeployArchive(sourceDir);
-    const remoteArchive = `/tmp/miosa-deploy-${Date.now()}.tgz`;
-    try {
-        await uploadFileToSandbox(c, sandboxId, archivePath, remoteArchive);
+    if (sourceBacked) {
+        deployStep(opts, "Waiting for source import");
+        appManifest = await readRemoteAppManifest(c, sandboxId, opts.timeout);
+        remoteWorkdir = normalizeRemoteWorkdir(appManifest?.workdir ?? "/workspace");
     }
-    finally {
-        fs.rmSync(archivePath, { force: true });
+    else {
+        deployStep(opts, "Uploading files");
+        const archivePath = createDeployArchive(sourceDir);
+        const remoteArchive = `/tmp/miosa-deploy-${Date.now()}.tgz`;
+        try {
+            await uploadFileToSandbox(c, sandboxId, archivePath, remoteArchive);
+            deployStep(opts, "Extracting workspace");
+            await execSandbox(c, sandboxId, `mkdir -p ${shellQuote(remoteWorkdir)} && tar -xzf ${shellQuote(remoteArchive)} -C ${shellQuote(remoteWorkdir)}`, "/");
+        }
+        finally {
+            fs.rmSync(archivePath, { force: true });
+        }
     }
-    deployStep(opts, "Extracting workspace");
-    await execSandbox(c, sandboxId, `mkdir -p /workspace && tar -xzf ${shellQuote(remoteArchive)} -C /workspace`, "/");
+    const resolvedPort = opts.port ?? opts.publishPort ?? manifestPort(appManifest) ?? port;
+    const resolvedProbePath = opts.probePath ?? manifestProbePath(appManifest) ?? probePath;
+    const resolvedStart = opts.start ?? manifestStartCommand(appManifest) ?? start;
+    const installCommand = opts.install === false
+        ? null
+        : (opts.installCommand ??
+            (appManifest?.install === false ? null : appManifest?.install) ??
+            (sourceBacked ? "npm install" : defaultInstallCommand(sourceDir)));
     if (installCommand) {
         deployStep(opts, `Installing dependencies: ${installCommand}`);
-        await execSandbox(c, sandboxId, installCommand, "/workspace", opts.timeout);
+        await execSandbox(c, sandboxId, installCommand, remoteWorkdir, opts.timeout);
     }
-    deployStep(opts, `Starting app on port ${port}`);
-    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");
+    deployStep(opts, `Starting app on port ${resolvedPort}`);
+    await execSandbox(c, sandboxId, `fuser -k ${resolvedPort}/tcp >/dev/null 2>&1 || true; nohup sh -lc ${shellQuote(resolvedStart)} > ${shellQuote(`/tmp/miosa-app-${resolvedPort}.log`)} 2>&1 & echo $!`, remoteWorkdir);
     deployStep(opts, "Checking internal app readiness");
-    const internal = await waitForInternalHttp(c, sandboxId, port, opts.probePath, Math.min(opts.timeout, 60));
+    const internal = await waitForInternalHttp(c, sandboxId, resolvedPort, resolvedProbePath, Math.min(opts.timeout, 60));
     deployStep(opts, "Creating public preview route");
-    const exposed = await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/expose`), { port, title: "app preview" });
+    const exposed = await c.apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/expose`), { port: resolvedPort, title: "app preview" });
     const previewUrl = extractUrl(unwrap(exposed));
     if (!previewUrl) {
         throw new UserError("Sandbox expose did not return a preview URL.");
@@ -1592,11 +1688,11 @@ async function deploySandbox(localDir, opts) {
     if (opts.wait)
         deployStep(opts, "Checking public preview readiness");
     const edge = opts.wait
-        ? await waitForPublicPreview(previewUrl, opts.probePath, opts.timeout)
+        ? await waitForPublicPreview(previewUrl, resolvedProbePath, opts.timeout)
         : { ok: false, status: null };
     return {
         sandbox_id: sandboxId,
-        port,
+        port: resolvedPort,
         preview_url: previewUrl,
         preview_ready: edge.ok,
         internal_status: internal.status,
@@ -1604,6 +1700,41 @@ async function deploySandbox(localDir, opts) {
         latency_ms: edge.latency_ms ?? null,
     };
 }
+const NON_TERMINAL_DEPLOY_STATES = new Set([
+    "building",
+    "pending",
+    "queued",
+    "deploying",
+]);
+// Bug 9: look for an existing non-terminal deployment with a matching name so
+// retries attach a new release instead of creating a duplicate app. Defensive:
+// returns null (fall back to create) if the list call fails or finds nothing.
+async function findExistingDeploymentByName(c, name) {
+    try {
+        const raw = unwrap(await c.apiGet(apiPath("/deployments")));
+        const items = Array.isArray(raw)
+            ? raw
+            : Array.isArray((asRecord(raw) ?? {})["data"])
+                ? (asRecord(raw) ?? {})["data"]
+                : [];
+        for (const item of items) {
+            const rec = asRecord(item);
+            if (!rec)
+                continue;
+            if (stringField(rec, "name") !== name)
+                continue;
+            const state = (stringField(rec, "state") ?? "").toLowerCase();
+            const id = stringField(rec, "id");
+            if (id && NON_TERMINAL_DEPLOY_STATES.has(state)) {
+                return { id, state };
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 async function publishSandbox(sandboxId, opts) {
     const c = client();
     const body = {
@@ -1614,6 +1745,16 @@ async function publishSandbox(sandboxId, opts) {
     };
     if (opts.app)
         body["deployment_id"] = opts.app;
+    // Bug 9: avoid creating a duplicate deployment on retry. When publishing by
+    // name (no explicit app id), reuse an existing non-terminal deployment with
+    // the same name by attaching a new release to it.
+    if (opts.name && !opts.app) {
+        const existing = await findExistingDeploymentByName(c, opts.name);
+        if (existing) {
+            body["deployment_id"] = existing.id;
+            deployStep(opts, chalk.dim(`Attaching to existing deployment ${existing.id} (${existing.state})`));
+        }
+    }
     if (opts.name)
         body["name"] = opts.name;
     if (opts.slug)
@@ -1696,7 +1837,8 @@ async function waitForDeploymentReady(c, deploymentId, timeoutSec) {
         }
         await sleep(2000);
     }
-    throw new UserError(`Deployment ${deploymentId} did not become ready within ${timeoutSec}s.`, last ? `Last state: ${String(last["state"] ?? "unknown")}` : undefined);
+    const lastState = last ? String(last["state"] ?? "unknown") : "unknown";
+    throw new UserError(`Deployment still building after ${timeoutSec}s — it may still finish. Re-check with \`miosa sandbox show ${deploymentId}\` or \`miosa deploy logs\`.`, `Last state: ${lastState}`);
 }
 function parsePublishDatabase(value) {
     if (!value)
@@ -1773,16 +1915,48 @@ function renderDoctorReport(report) {
         console.log();
     }
 }
-async function createSandboxForDeploy(c, template, name) {
+async function createSandboxForDeploy(c, template, name, source) {
     const body = { template_id: template };
     if (name)
         body["name"] = name;
+    if (source?.source)
+        body["source"] = source.source;
+    if (source?.revision)
+        body["revision"] = source.revision;
+    if (source?.depth != null)
+        body["depth"] = source.depth;
     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 readRemoteAppManifest(c, sandboxId, timeoutSec) {
+    const deadline = Date.now() + Math.min(timeoutSec, 120) * 1000;
+    while (Date.now() < deadline) {
+        for (const filename of [
+            "miosa.app.yml",
+            "miosa.app.yaml",
+            "miosa.app.json",
+        ]) {
+            const result = await c
+                .apiPost(apiPath(`/sandboxes/${enc(sandboxId)}/exec`), {
+                command: `test -f /workspace/${filename} && cat /workspace/${filename}`,
+                cwd: "/workspace",
+                timeout: 10,
+            })
+                .then(unwrap)
+                .catch(() => null);
+            const row = asRecord(result);
+            if (Number(row?.["exit_code"] ?? 1) === 0 &&
+                typeof row?.["stdout"] === "string") {
+                return parseAppManifest(filename, row["stdout"]);
+            }
+        }
+        await sleep(1500);
+    }
+    return null;
+}
 async function waitForSandboxRunning(c, sandboxId, timeoutSec) {
     const deadline = Date.now() + timeoutSec * 1000;
     while (Date.now() < deadline) {
@@ -1871,6 +2045,98 @@ async function execSandbox(c, sandboxId, command, cwd, timeout) {
     }
     return result;
 }
+// Like execSandbox but does NOT throw on a non-zero exit code.
+async function execSandboxRaw(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;
+    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: "*" });
+            }
+        }
+    }
+    out.sort((a, b) => a.port - b.port);
+    return out;
+}
+// Stream exec output: run in background to a log file, poll-read new bytes
+// until the process exits, then print the final exit code.
+async function runFollowExec(sandboxId, cmd, cwd, env, timeoutSec, opts) {
+    if (!cmd) {
+        throw new UserError("No command given to follow.");
+    }
+    const c = client();
+    const logPath = `/tmp/miosa-follow-${Date.now()}.log`;
+    const envPrefix = Object.entries(env)
+        .map(([k, v]) => `${k}=${shellQuote(v)} `)
+        .join("");
+    // Run command, capture exit code into a sentinel file, in the background.
+    const exitPath = `${logPath}.exit`;
+    const inner = `${envPrefix}${cmd}`;
+    const launch = `nohup sh -lc ${shellQuote(`( ${inner} ) > ${shellQuote(logPath)} 2>&1; echo $? > ${shellQuote(exitPath)}`)} >/dev/null 2>&1 & echo $!`;
+    const started = await execSandboxRaw(c, sandboxId, launch, cwd, timeoutSec);
+    const pid = String(started["stdout"] ?? "").trim();
+    if (!pid) {
+        throw new UserError("Could not start background command for --follow.");
+    }
+    const deadline = timeoutSec ? Date.now() + timeoutSec * 1000 : Infinity;
+    let offset = 0;
+    for (;;) {
+        const read = await execSandboxRaw(c, sandboxId, `tail -c +${offset + 1} ${shellQuote(logPath)} 2>/dev/null`);
+        const chunk = String(read["stdout"] ?? "");
+        if (chunk.length > 0) {
+            process.stdout.write(chunk);
+            offset += Buffer.byteLength(chunk);
+        }
+        const alive = await execSandboxRaw(c, sandboxId, `kill -0 ${shellQuote(pid)} 2>/dev/null && echo alive || echo done`);
+        if (String(alive["stdout"] ?? "").trim() === "done")
+            break;
+        if (Date.now() > deadline) {
+            console.error(chalk.yellow(`\nTimed out after ${timeoutSec}s — command may still be running (pid ${pid}).`));
+            return;
+        }
+        await sleep(1000);
+    }
+    // Drain any trailing output.
+    const tail = await execSandboxRaw(c, sandboxId, `tail -c +${offset + 1} ${shellQuote(logPath)} 2>/dev/null`);
+    const tailChunk = String(tail["stdout"] ?? "");
+    if (tailChunk.length > 0)
+        process.stdout.write(tailChunk);
+    const exitRead = await execSandboxRaw(c, sandboxId, `cat ${shellQuote(exitPath)} 2>/dev/null`);
+    const exitCode = Number(String(exitRead["stdout"] ?? "0").trim() || "0");
+    if (!isJsonMode(opts) && exitCode !== 0) {
+        console.error(chalk.red(`\nexit code: ${exitCode}`));
+    }
+}
 async function waitForInternalHttp(c, sandboxId, port, probePath, timeoutSec) {
     const deadline = Date.now() + timeoutSec * 1000;
     let last = { ok: false, status: null };
@@ -1964,6 +2230,13 @@ function defaultStartCommand(framework, port) {
         return `python3 -m http.server ${port} --bind 0.0.0.0`;
     return `npm run dev -- --host 0.0.0.0 --port ${port}`;
 }
+function normalizeRemoteWorkdir(value) {
+    if (!value || value === ".")
+        return "/workspace";
+    if (!value.startsWith("/"))
+        return `/workspace/${value.replace(/^\.\//, "")}`;
+    return value;
+}
 function extractUrl(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return null;
@@ -2175,6 +2448,15 @@ function buildNetworkPolicy(opts) {
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
+// Join argv words back into a shell command, quoting only words that contain
+// whitespace or shell-significant characters. Simple tokens stay bare so
+// `exec <id> ls -la` reads naturally, while `bash -c "cd x && y"` survives.
+function joinCommandWords(words) {
+    const SAFE = /^[A-Za-z0-9_./:=@%+-]+$/;
+    return words
+        .map((word) => word.length > 0 && SAFE.test(word) ? word : shellQuote(word))
+        .join(" ");
+}
 function joinUrlPath(basePath, probePath) {
     const probe = probePath.startsWith("/") ? probePath : `/${probePath}`;
     if (!basePath || basePath === "/")