agent-dev-env 0.1.0

package/dist/runners/macos-guest.js

@@ -0,0 +1,76 @@
+// runners/macos-guest.ts — the guest side of the macOS step 3: where the
+// bundled guest agent lives, how it is uploaded over `tart exec` and how
+// it is run (upload → install → status). The other step-3 concerns
+// (host bridges, rules) live in their own modules; this one is the
+// transport bits both need.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { execVm } from '../lib/tart.js';
+import { logger } from '../lib/logger.js';
+/** The guest's agent install dir (image-fixed home `/Users/admin`). */
+const GUEST_LIB_DIR = '/Users/admin/.local/lib/agent-dev-env';
+/** The absolute guest-agent path. */
+export const GUEST_AGENT = `${GUEST_LIB_DIR}/guest-agent-mac.js`;
+/** The bundled macOS guest agent (single-file, node-only). */
+function guestAgentPath() {
+    return fileURLToPath(new URL('../assets/guest/guest-agent-mac.js', import.meta.url));
+}
+/** Uploads the bundled guest agent and runs `install` (idempotent:
+ *  launchd jobs reloaded, zprofile/ssh config marker-guarded, docker
+ *  context refreshed). The host alias is passed when the gateway is
+ *  known; the agent falls back to the guest's netstat gateway.
+ *
+ * @param context - The run context (ports).
+ * @param node - The guest's node binary.
+ * @param gateway - The Tart gateway, when determinable.
+ */
+export async function ensureGuestAgent(context, node, gateway) {
+    const upload = await execVm(context.vm, ['sh', '-c', `mkdir -p ${GUEST_LIB_DIR} && cat > ${GUEST_AGENT}`], { input: readFileSync(guestAgentPath(), 'utf8') });
+    if (upload.code !== 0) {
+        logger.warn(`could not upload the guest agent (tart exec: ${upload.code}).`);
+        return;
+    }
+    const installArgs = [
+        node,
+        GUEST_AGENT,
+        'install',
+        '--agent-port',
+        String(context.agentPort),
+        '--docker-port',
+        String(context.dockerPort),
+    ];
+    if (gateway) {
+        installArgs.push('--host-alias', gateway);
+    }
+    const install = await execVm(context.vm, installArgs);
+    if (install.code !== 0) {
+        logger.warn(`guest agent install failed (tart exec: ${install.code}).`);
+        return;
+    }
+    logger.ok('Guest agent installed (SSH agent + Docker bridges persistent).');
+}
+/** Runs `guest-agent status` and folds the bridge-status lines into the
+ *  run state.
+ *
+ * @param context - The run context (VM name).
+ * @param state - The accumulated run state.
+ * @param node - The guest's node binary.
+ */
+export async function readGuestStatus(context, state, node) {
+    const res = await execVm(context.vm, [node, GUEST_AGENT, 'status']);
+    if (res.code !== 0) {
+        return;
+    }
+    for (const line of res.stdout.split('\n')) {
+        const match = /^bridge-status:(ssh-agent|docker)=(up|down)$/.exec(line.trim());
+        if (!match) {
+            continue;
+        }
+        if (match[1] === 'ssh-agent') {
+            state.bridges.agent.guestUp = match[2] === 'up';
+        }
+        else {
+            state.bridges.docker.guestUp = match[2] === 'up';
+        }
+    }
+}

package/dist/runners/macos-rules.js

@@ -0,0 +1,77 @@
+// runners/macos-rules.ts — the agent-rules step: render the bundled rules
+// for this run and drive the guest agent's `rules --probe` / `rules
+// --force` (the sha256 marker semantics live in the guest agent). Port
+// of the shell's install_agent_rules (probe → confirm → overwrite, with
+// the conflict default of no).
+import { execVm } from '../lib/tart.js';
+import { logger } from '../lib/logger.js';
+import { confirmDefault } from '../lib/prompt.js';
+import { GUEST_AGENT } from './macos-guest.js';
+import { loadAgentRules, renderAgentRules } from './rules.js';
+/** The agent-rules probe/confirm/apply.
+ *
+ * @param context - The run context (paths to substitute).
+ * @param state - The accumulated run state (bridge flags).
+ * @param node - The guest's node binary.
+ */
+export async function installAgentRules(context, state, node) {
+    const content = loadAgentRules();
+    if (!content) {
+        logger.warn('agent rules file not found (assets/rules/agent-rules.md).');
+        state.rules = 'failed';
+        return;
+    }
+    const rendered = renderAgentRules(content, { HOST_WORK_DIR: context.workDir, GUEST_MOUNT: context.guestMount }, state.bridges.agent.bridged && state.bridges.agent.guestUp);
+    const probe = await execVm(context.vm, [node, GUEST_AGENT, 'rules'], { input: rendered });
+    const action = /^rules:probe=(.+)$/.exec(probe.stdout.trim())?.[1];
+    if (probe.code !== 0 || !action) {
+        logger.warn('could not inspect the agent rules in the guest.');
+        state.rules = 'failed';
+        return;
+    }
+    await applyRulesAction(context, state, node, rendered, action);
+}
+/** The probe outcome decision tree (shell parity: install/update ask
+ *  with the y default, conflict asks with the n default). */
+async function applyRulesAction(context, state, node, rendered, action) {
+    if (action === 'uptodate') {
+        logger.info('Agent rules are up to date in the guest.');
+        state.rules = 'uptodate';
+        return;
+    }
+    if (action !== 'install' && action !== 'update' && action !== 'conflict') {
+        logger.warn('could not inspect the agent rules in the guest.');
+        state.rules = 'failed';
+        return;
+    }
+    const isConflict = action === 'conflict';
+    if (isConflict) {
+        logger.info('The guest has its own agent rules.');
+    }
+    const ask = isConflict
+        ? "Overwrite the guest's agent rules with the sandbox rules?"
+        : 'Install/update the sandbox agent rules in the guest?';
+    if (!(await confirmDefault(ask, { default: isConflict ? 'n' : 'y', yes: context.options.yes }))) {
+        logger.info(isConflict
+            ? "Keeping the guest's own agent rules."
+            : "Keeping the guest's agent rules as they are.");
+        state.rules = 'kept';
+        return;
+    }
+    const write = await execVm(context.vm, [node, GUEST_AGENT, 'rules', '--force'], {
+        input: rendered,
+    });
+    if (write.code !== 0) {
+        logger.warn('could not install the agent rules into the guest.');
+        state.rules = 'failed';
+        return;
+    }
+    if (isConflict) {
+        state.rules = 'overwritten';
+        logger.ok("Overwrote the guest's agent rules.");
+    }
+    else {
+        state.rules = action === 'install' ? 'installed' : 'updated';
+        logger.ok('Installed/updated the sandbox agent rules (opencode + Copilot CLI).');
+    }
+}

package/dist/runners/macos-summary.js

@@ -0,0 +1,145 @@
+// runners/macos-summary.ts — the "Sandbox is ready" block (port of the
+// shell's print_summary, same labels, same wording, same color scheme).
+// The lines are printed with the label column right-aligned to 12 chars
+// and the value padded to 4 spaces — like `printf '    %-12s %s\n'`.
+import { existsSync } from 'node:fs';
+import { logger } from '../lib/logger.js';
+import { vmIp, vmState } from '../lib/tart.js';
+/** Prints the macOS summary block (VM/shared dir/keys/bridges/rules/
+ *  settings/OpenChamber/stop hints).
+ *
+ * @param context - The run context.
+ * @param state - The accumulated run state.
+ */
+export async function printMacosSummary(context, state) {
+    const ip = await vmIp(context.vm);
+    const vmStateNow = (await vmState(context.vm)) ?? 'stopped';
+    logger.step('Sandbox is ready');
+    const ipDesc = ip ? `IP ${ip}` : 'IP unavailable';
+    summaryLine('VM', `${logger.bold(context.vm)} (${vmStateNow}, ${ipDesc})`);
+    if (context.workDir && existsSync(context.workDir)) {
+        summaryLine('Shared dir', `${context.workDir} (in the guest: ${context.guestMount})`);
+    }
+    else {
+        summaryLine('Shared dir', 'not shared');
+    }
+    if (state.mode === 'gui') {
+        summaryLine('Keys', 'system shortcuts go to the guest while the window is focused');
+    }
+    printBridgeLines(context, state);
+    printRulesLine(state.rules);
+    printSettingsLine(state.settings);
+    printOpenchamberLine(context, state, ip);
+    printStopLines(context, state);
+}
+/** One `    LABEL........  VALUE` line. */
+function summaryLine(label, value) {
+    logger.out(`    ${label.padEnd(12)}${value}`);
+}
+function printBridgeLines(context, state) {
+    const agent = state.bridges.agent;
+    if (agent.bridged) {
+        const value = agent.guestUp
+            ? `host agent -> TCP ${context.agentPort} -> guest (/tmp/ssh-agent.sock)`
+            : `host bridge up (TCP ${context.agentPort}), guest bridge not running`;
+        summaryLine('SSH agent', agent.guestUp ? loggerOk(value) : loggerWarn(value));
+    }
+    else {
+        summaryLine('SSH agent', 'not bridged');
+    }
+    const docker = state.bridges.docker;
+    if (docker.bridged) {
+        if (docker.engineUp) {
+            summaryLine('Docker', loggerOk(`host engine (v${docker.serverVersion}) -> TCP ${context.dockerPort} -> guest (context 'host')`));
+        }
+        else if (docker.guestUp) {
+            summaryLine('Docker', loggerWarn('bridge up, engine not reachable in the guest — is Docker running on the host?'));
+        }
+        else {
+            summaryLine('Docker', loggerWarn(`host bridge up (TCP ${context.dockerPort}), guest bridge not running`));
+        }
+    }
+    else {
+        summaryLine('Docker', 'not bridged');
+    }
+}
+function printRulesLine(rules) {
+    switch (rules) {
+        case 'installed':
+            summaryLine('Agent rules', loggerOk('installed for opencode + Copilot'));
+            break;
+        case 'updated':
+        case 'overwritten':
+            summaryLine('Agent rules', loggerOk('updated for opencode + Copilot'));
+            break;
+        case 'uptodate':
+            summaryLine('Agent rules', 'up to date in the guest');
+            break;
+        case 'kept':
+            summaryLine('Agent rules', 'guest rules kept (not overwritten)');
+            break;
+        case 'failed':
+            summaryLine('Agent rules', loggerWarn('could not be installed'));
+            break;
+        default:
+            summaryLine('Agent rules', 'not installed');
+    }
+}
+function printSettingsLine(settings) {
+    switch (settings) {
+        case 'copied':
+            summaryLine('Settings', loggerOk('copied into the guest'));
+            break;
+        case 'uptodate':
+            summaryLine('Settings', 'already in the guest');
+            break;
+        case 'skipped':
+            summaryLine('Settings', 'not copied (--no-settings)');
+            break;
+        case 'none':
+            summaryLine('Settings', 'nothing to copy on the host');
+            break;
+        case 'failed':
+            summaryLine('Settings', loggerWarn('copy failed — re-run `agent-dev-env run` to retry'));
+            break;
+        default:
+            summaryLine('Settings', 'not copied');
+    }
+}
+function printOpenchamberLine(context, state, ip) {
+    if (state.openchamberUp && state.openchamberUrl) {
+        summaryLine('OpenChamber', loggerOk(`${state.openchamberUrl} (password: sandbox)`));
+    }
+    else if (ip) {
+        summaryLine('OpenChamber', loggerWarn(`not responding on http://${ip}:${context.openchamberPort}`));
+    }
+    else {
+        summaryLine('OpenChamber', loggerWarn('not responding (VM IP unavailable)'));
+    }
+}
+function printStopLines(context, state) {
+    let hint = 'run "agent-dev-env stop macos"';
+    if (context.options.foreground && context.options.headless) {
+        hint = 'run "agent-dev-env stop macos" in another terminal';
+    }
+    else if (context.options.foreground && state.tartPid !== undefined) {
+        hint = 'press Cmd+C in this terminal, or run "agent-dev-env stop macos" in another terminal';
+    }
+    summaryLine('Stop', hint);
+    if (!context.options.foreground && state.tartPid !== undefined) {
+        summaryLine('Background', `VM keeps running after this script exits (tart log: ${state.tartLog})`);
+        if (state.bridges.agent.bridged) {
+            summaryLine('Bridge', `host listener on TCP ${context.agentPort} stays up — stop it with: agent-dev-env stop macos`);
+        }
+        if (state.bridges.docker.bridged) {
+            summaryLine('Bridge', `host Docker listener on TCP ${context.dockerPort} stays up — stop it with: agent-dev-env stop macos`);
+        }
+    }
+}
+// color helpers — the shell's ${c_green}/${c_yellow} inline.
+function loggerOk(text) {
+    return logger.color('green') + text + logger.reset();
+}
+function loggerWarn(text) {
+    return logger.color('yellow') + text + logger.reset();
+}

package/dist/runners/macos.js

@@ -0,0 +1,258 @@
+// runners/macos.ts — the macOS backend (Phase 3 of the port, tart only):
+// image select (pull with confirm) + working VM clone, boot with the
+// recommended settings, and the flow hooks the framework calls. The
+// step-3 bridges live in macos-bridges.ts, the summary in
+// macos-summary.ts — this module is the backend wiring.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isAlive, killTree, sleep, spawnDetached } from '../lib/exec.js';
+import { registryRef, resolveOwner } from '../lib/ghcr.js';
+import { logger } from '../lib/logger.js';
+import { paths } from '../lib/paths.js';
+import { PLATFORM_DEFAULTS } from '../lib/platform.js';
+import { confirmDefault } from '../lib/prompt.js';
+import { cloneVm, deleteVm, dirArg, pullImage, setVm, stopVm, tartAvailable, tartRunArgs, tartSetArgs, vmExists, vmIp, vmState, waitForVmState, } from '../lib/tart.js';
+import { ensureUserSettings, restartOpenchamber } from '../settings/macos-copy.js';
+import { ensureBridgeDir } from './bridges.js';
+import { macosBridges } from './macos-bridges.js';
+import { printMacosSummary } from './macos-summary.js';
+import { offerOpenInBrowser, waitForOpenchamber } from './openchamber.js';
+/** The macOS backend — tart only (no data footprint; Tart owns the VM
+ *  store, our logs live under the logs/state dir).
+ */
+export const macosBackend = {
+    preflight: (context) => preflight(context),
+    ensureImageAndVm: ensureImageAndVm,
+    boot: boot,
+    setupBridges: macosBridges,
+    setupSettings: setupSettings,
+    verifyOpenchamber: verifyOpenchamber,
+    summarize: (context, state) => printMacosSummary(context, state),
+    finish: finish,
+};
+async function preflight(context) {
+    if (!tartAvailable()) {
+        logger.die("tart is not installed — run 'brew install cirruslabs/cli/tart' first.");
+    }
+    ensureBridgeDir();
+    if (context.options.reset) {
+        await teardownWorkingVm(context);
+    }
+}
+/** `--reset`: stop + delete the working VM so the next step re-clones it
+ *  fresh (a "start over" without touching the pristine image). */
+async function teardownWorkingVm(context) {
+    const { vm } = context;
+    if (!(await vmExists(vm))) {
+        return;
+    }
+    if ((await vmState(vm)) === 'running') {
+        await stopVm(vm);
+        await waitForVmState(vm, 'stopped');
+    }
+    await deleteVm(vm);
+    logger.info(`Removed the working VM '${vm}' (--reset).`);
+}
+// --- step 1: image + working VM ---------------------------------------------
+async function ensureImageAndVm(context, state) {
+    const { vm, image } = context;
+    const yes = context.options.yes;
+    if (await vmExists(vm)) {
+        logger.ok(`Working VM '${vm}' found (state: ${await vmState(vm)}).`);
+        return;
+    }
+    if (await vmExists(image)) {
+        logger.info(`Sandbox image '${image}' is present.`);
+    }
+    else {
+        logger.info(`Sandbox image '${image}' is not pulled on this machine.`);
+        if (!(await confirmDefault('Pull it now?', { default: 'y', yes }))) {
+            logger.die("aborted — no sandbox image available. Run 'tart pull' manually when ready.");
+        }
+        await pullSandboxImage(context);
+    }
+    if ((await vmState(image)) === 'running') {
+        logger.die(`image VM '${image}' is running — stop it first: tart stop ${image}`);
+    }
+    const ask = `No working VM '${vm}' yet — clone it from the pristine image '${image}'?`;
+    if (await confirmDefault(ask, { default: 'y', yes })) {
+        logger.cmd(`tart clone ${image} ${vm}`);
+        const res = await cloneVm(image, vm);
+        if (res.code !== 0) {
+            throw new Error(`tart clone failed:\n${res.stderr.trim()}`);
+        }
+        state.created = true;
+        logger.ok(`Cloned '${vm}' from '${image}'.`);
+    }
+    else {
+        logger.die(`aborted — '${vm}' is required. Clone it manually with 'tart clone ${image} ${vm}'.`);
+    }
+}
+async function pullSandboxImage(context) {
+    const owner = await resolveOwner({ owner: context.options.owner, env: context.options.env });
+    const ref = registryRef(context.image, 'latest', owner);
+    const hint = PLATFORM_DEFAULTS[context.platform].downloadHint;
+    logger.info(`Pulling ${ref} (one-time, ${hint} download)...`);
+    const res = await pullImage(ref);
+    if (res.code !== 0) {
+        logger.die('pull failed — check your network connection (public GHCR images pull without a login).');
+    }
+}
+// --- step 2: boot -----------------------------------------------------------
+async function boot(context, state) {
+    if ((await vmState(context.vm)) === 'running') {
+        state.vmAlreadyRunning = true;
+        const ask = `VM '${context.vm}' is already running — restart it?`;
+        if (await confirmDefault(ask, { default: 'n', yes: context.options.yes })) {
+            await stopAndWait(context);
+            await sleep(1000); // let tart release the VM lock before running it again
+            await launchVm(context, state);
+        }
+        else {
+            logger.ok(`Keeping the running VM — skipping 'tart run'.`);
+        }
+        return;
+    }
+    if (state.created) {
+        await applyRecommendedSettings(context);
+    }
+    await launchVm(context, state);
+}
+async function stopAndWait(context) {
+    logger.cmd(`tart stop ${context.vm}`);
+    const stopped = await stopVm(context.vm);
+    if (stopped.code !== 0) {
+        logger.die(`'tart stop ${context.vm}' failed.`);
+    }
+    if (!(await waitForVmState(context.vm, 'stopped'))) {
+        logger.die(`timed out waiting for '${context.vm}' to stop.`);
+    }
+    logger.ok(`VM '${context.vm}' is stopped.`);
+}
+async function applyRecommendedSettings(context) {
+    const args = tartSetArgs(context.vm, context.cpuCount, context.memoryMb);
+    logger.cmd(`tart ${args.join(' ')}`);
+    const res = await setVm(args);
+    if (res.code !== 0) {
+        throw new Error(`tart set failed:\n${res.stderr.trim()}`);
+    }
+    logger.ok(`Applied recommended settings: ${context.cpuCount} CPUs / ` +
+        `${Math.round(context.memoryMb / 1024)} GB / 1280x800 display-refit.`);
+}
+async function launchVm(context, state) {
+    const { workDir } = context;
+    let shareArg;
+    if (workDir && existsSync(workDir)) {
+        shareArg = dirArg(context.mountName, workDir);
+    }
+    else if (workDir) {
+        logger.warn(`work directory '${workDir}' does not exist — skipping the shared-directory mount.`);
+    }
+    const args = tartRunArgs(context.vm, { headless: context.options.headless, dirArg: shareArg });
+    logger.cmd(`tart ${args.join(' ')}`);
+    state.tartLog = join(paths.logs, `tart-${context.vm}.log`);
+    if (context.options.foreground) {
+        const child = spawn('tart', args, { stdio: 'inherit' });
+        state.tartChild = child;
+        state.tartPid = child.pid;
+    }
+    else {
+        logger.info(`Running the VM in the background (output: ${state.tartLog}).`);
+        state.tartPid = spawnDetached('tart', args, { logFile: state.tartLog });
+    }
+    await waitForBoot(context, state);
+}
+/** Polls `tart list` + the `tart run` process until the VM is up. */
+async function waitForBoot(context, state) {
+    process.stdout.write('    Waiting for the VM to boot (up to 3 min)');
+    for (let attempt = 0; attempt < 90; attempt += 1) {
+        if (state.tartPid !== undefined && !isAlive(state.tartPid)) {
+            process.stdout.write('\n');
+            logger.die("'tart run' exited before the VM started.");
+        }
+        if ((await vmState(context.vm)) === 'running') {
+            const ip = await vmIp(context.vm);
+            state.vmIp = ip;
+            process.stdout.write(` ${logger.color('green')}done${logger.reset()}\n`);
+            logger.ok(ip ? `VM is running (IP: ${ip}).` : 'VM is running.');
+            return;
+        }
+        process.stdout.write('.');
+        await sleep(2000);
+    }
+    process.stdout.write('\n');
+    logger.die(`timed out waiting for '${context.vm}' to boot.`);
+}
+// --- step 4/5 hooks ---------------------------------------------------------
+async function setupSettings(context, state) {
+    if (context.options.noSettings) {
+        logger.info('Skipping user settings copy (--no-settings).');
+        state.settings = 'skipped';
+        return;
+    }
+    state.settings = await ensureUserSettings(context.vm, context.options.home, context.options.yes);
+    if (state.settings === 'copied') {
+        await restartOpenchamber(context.vm);
+    }
+}
+async function verifyOpenchamber(context, state) {
+    let ip = state.vmIp;
+    if (!ip) {
+        ip = await vmIp(context.vm);
+        state.vmIp = ip;
+    }
+    if (!ip) {
+        logger.warn('OpenChamber: VM IP unavailable — cannot probe.');
+        return;
+    }
+    state.openchamberUrl = `http://${ip}:${context.openchamberPort}`;
+    state.openchamberUp = await waitForOpenchamber(state.openchamberUrl);
+    if (state.openchamberUp) {
+        await offerOpenInBrowser(state.openchamberUrl, context.options.yes);
+    }
+}
+// --- finish: foreground wait + bridge cleanup --------------------------------
+async function finish(context, state) {
+    if (!context.options.foreground) {
+        return;
+    }
+    await waitForForegroundVm(context, state);
+    // The VM stopped (or Cmd+C was pressed) — kill the bridges this run
+    // started; in background mode (and for a bridge that was already up
+    // from an earlier run) they stay up, outliving the CLI by design.
+    await cleanupRunBridge(state.bridges.agent.pid, 'agent bridge');
+    await cleanupRunBridge(state.bridges.docker.pid, 'Docker bridge');
+}
+/** @internal — kills one of this run's bridges. */
+async function cleanupRunBridge(pid, label) {
+    if (pid === undefined) {
+        return;
+    }
+    await killTree(pid);
+    logger.info(`Stopped the host ${label} (pid ${pid}).`);
+}
+async function waitForForegroundVm(context, state) {
+    const child = state.tartChild;
+    if (!child) {
+        return;
+    }
+    const exitCode = await new Promise((resolve) => {
+        const drain = () => {
+            // keep the wait going — `tart run` received the same signal
+        };
+        process.on('SIGINT', drain);
+        process.on('SIGTERM', drain);
+        child.on('close', (code) => {
+            process.removeListener('SIGINT', drain);
+            process.removeListener('SIGTERM', drain);
+            resolve(code);
+        });
+    });
+    if (exitCode === 0) {
+        logger.info(`VM '${context.vm}' has stopped.`);
+    }
+    else {
+        logger.warn(`VM '${context.vm}' exited with an error (see tart output above).`);
+    }
+}

package/dist/runners/openchamber.js

@@ -0,0 +1,60 @@
+// runners/openchamber.ts — the OpenChamber verification step (everything
+// after "Step 5/5" in the shell runners): an HTTP probe with retries
+// (curl -fsS --max-time 3 parity, via fetch + AbortSignal.timeout) and
+// the open-in-browser offer. Shared by the backends — only the URL (VM
+// IP vs 127.0.0.1 vs guest IP) differs per platform.
+import { run } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { confirmDefault } from '../lib/prompt.js';
+/** Probes the OpenChamber URL until it answers (or the tries run out).
+ *
+ * @param url - e.g. `http://192.168.64.34:4000`.
+ * @param tries - Poll attempts (60 = up to 120 s at 2 s apart).
+ * @param delayMs - Delay between attempts.
+ * @returns True when OpenChamber answered within the window.
+ */
+export async function waitForOpenchamber(url, tries = 60, delayMs = 2000) {
+    logger.info(`Waiting for OpenChamber (up to ${Math.round((tries * delayMs) / 1000)} s)`);
+    for (let attempt = 0; attempt < tries; attempt += 1) {
+        if (await openchamberIsUp(url)) {
+            logger.ok(`OpenChamber is up: ${url} (default password: sandbox)`);
+            return true;
+        }
+        if (attempt < tries - 1) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    logger.warn(`OpenChamber did not respond on ${url} within ${Math.round((tries * delayMs) / 1000)}s.`);
+    logger.warn('check it from inside the VM: openchamber status / openchamber logs');
+    return false;
+}
+/** @internal — one HTTP probe (fetch in Node 20+; signal via
+ *  AbortSignal.timeout like curl --max-time 3). */
+export async function openchamberIsUp(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** The open-in-browser offer (+ confirm). Bypassed with `yes` or when
+ *  the URL is empty.
+ *
+ * @param url - The OpenChamber URL.
+ * @param yes - Skip the confirmation (--yes).
+ */
+export async function offerOpenInBrowser(url, yes) {
+    if (!url) {
+        return;
+    }
+    logger.info(`OpenChamber URL: ${url}`);
+    if (!(await confirmDefault(`Open ${url} in your browser now?`, { default: 'y', yes }))) {
+        return;
+    }
+    const res = await run('open', [url]);
+    if (res.code !== 0) {
+        logger.warn(`could not open a browser — open ${url} manually.`);
+    }
+}

package/dist/runners/options.js

@@ -0,0 +1,56 @@
+// runners/options.ts — `run` option resolution: commander flags merged over
+// the SANDBOX_* environment variables onto the platform defaults (the same
+// precedence chain the shell runners had: env holds the defaults, flags
+// override them). Pure + unit-tested; the command layer just builds this.
+import { homedir } from 'node:os';
+import { PLATFORM_DEFAULTS } from '../lib/platform.js';
+/** @internal — port env override validation (1-65535). */
+export function parsePortEnv(value, name) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`invalid ${name} port: ${value} (expected 1-65535)`);
+    }
+    return port;
+}
+function parseIntEnv(value, name, def) {
+    const n = Number(value);
+    return Number.isInteger(n) && n > 0 ? n : def;
+}
+/** Resolves the run options for a platform from flags + env.
+ *
+ * @param platform - The target platform.
+ * @param flags - Overrides from the CLI flags.
+ * @param env - Environment (defaults to process.env).
+ * @param home - Host home directory (defaults to os.homedir()).
+ * @returns The resolved options.
+ * @throws Error on an invalid port override.
+ */
+export function resolveRunOptions(platform, flags = {}, env = process.env, home = homedir()) {
+    const defs = PLATFORM_DEFAULTS[platform];
+    const workDirFlag = flags.workDir !== undefined ? flags.workDir : env.SANDBOX_WORK_DIR;
+    return {
+        platform,
+        image: flags.image ?? env.SANDBOX_IMAGE ?? defs.image,
+        vm: env.SANDBOX_VM ?? defs.vmName,
+        workDir: workDirFlag ?? defs.workDir ?? '',
+        mountName: env.SANDBOX_MOUNT_NAME ?? defs.mountName ?? 'dev',
+        agentPort: parsePortEnv(env.SANDBOX_AGENT_PORT ?? String(defs.agentPort), 'SANDBOX_AGENT_PORT'),
+        dockerPort: parsePortEnv(env.SANDBOX_DOCKER_PORT ?? String(defs.dockerPort), 'SANDBOX_DOCKER_PORT'),
+        openchamberPort: parsePortEnv(env.SANDBOX_OPENCHAMBER_PORT ?? String(defs.openchamberPort), 'SANDBOX_OPENCHAMBER_PORT'),
+        sshPort: parsePortEnv(env.SANDBOX_SSH_PORT ?? String(defs.sshPort ?? 22), 'SANDBOX_SSH_PORT'),
+        rdpPort: parsePortEnv(env.SANDBOX_RDP_PORT ?? String(defs.rdpPort ?? 3389), 'SANDBOX_RDP_PORT'),
+        winrmPort: parsePortEnv(env.SANDBOX_WINRM_PORT ?? String(defs.winrmPort ?? 5985), 'SANDBOX_WINRM_PORT'),
+        cpuCount: parseIntEnv(env.SANDBOX_CPU_COUNT ?? '', 'SANDBOX_CPU_COUNT', defs.cpuCount),
+        memoryMb: parseIntEnv(env.SANDBOX_MEMORY_MB ?? '', 'SANDBOX_MEMORY_MB', defs.memoryMb),
+        headless: flags.headless === true,
+        foreground: flags.foreground === true,
+        noAgent: flags.noAgent === true,
+        noDocker: flags.noDocker === true,
+        noSettings: flags.noSettings === true,
+        reset: flags.reset === true,
+        yes: flags.yes === true,
+        owner: flags.owner,
+        env,
+        home,
+    };
+}