agent-dev-env 0.1.0-canary.2.fbbd044

package/dist/commands/status.js

@@ -0,0 +1,142 @@
+// commands/status.ts — `agent-dev-env status [platform]`: live status of
+// one or all platforms. New command (no shell equivalent): reports whether
+// the default image is pulled, whether the working VM exists, and whether
+// it is running, per platform. Read-only and informational: missing
+// tooling is reported, not fatal.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultImageFor, imageVersion } from '../lifecycle/catalog.js';
+import { isAlive, readPidFile, run } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { qemuImagePath, qemuPidFile, qemuStateDir, qemuWorkingDir } from '../lib/qemu.js';
+import { imageRootDir } from '../lib/paths.js';
+import { PLATFORM_DEFAULTS, PLATFORMS } from '../lib/platform.js';
+import { listVms, tartAvailable, vmIp } from '../lib/tart.js';
+import { findVmrun, listRunningVms } from '../lib/vmrun.js';
+/** Prints the live status of one platform (or all platforms when none is
+ *  given).
+ *
+ * @param platformArg - The platform to report on; all when omitted.
+ * @returns Exit code: always 0 (status is informational).
+ */
+export async function statusCmd(platformArg) {
+    const targets = platformArg ? [platformArg] : [...PLATFORMS];
+    for (const [i, platform] of targets.entries()) {
+        if (i > 0) {
+            logger.out('');
+        }
+        await printStatus(platform);
+    }
+    return 0;
+}
+/** Prints one platform's status. */
+async function printStatus(platform) {
+    logger.title(platform);
+    let image;
+    try {
+        image = defaultImageFor(platform);
+    }
+    catch (err) {
+        logger.warn(err.message);
+        return;
+    }
+    let version = '?';
+    try {
+        version = imageVersion(image);
+    }
+    catch {
+        // vars file without image_version — show '?' and let deploy/tag fail.
+    }
+    const defs = PLATFORM_DEFAULTS[platform];
+    const details = [`image: ${image.name} (v${version})`];
+    switch (platform) {
+        case 'macos':
+            await readMacosStatus(image.name, defs.vmName, details);
+            break;
+        case 'windows-qemu':
+            await readQemuStatus(image, details);
+            break;
+        case 'windows-vmware':
+        case 'ubuntu-vmware':
+            await readVmwareStatus(platform, image, details);
+            break;
+    }
+    for (const line of details) {
+        logger.info(line);
+    }
+}
+async function readMacosStatus(imageName, vmName, details) {
+    if (!tartAvailable()) {
+        details.push('tart: not installed (brew install cirruslabs/cli/tart)');
+        return;
+    }
+    const vms = await listVms();
+    const imageState = vms.get(imageName);
+    details.push(imageState ? `image: pulled (${imageState})` : 'image: not pulled');
+    const vmState = vms.get(vmName);
+    if (!vmState) {
+        details.push(`VM: ${vmName} — not created`);
+        return;
+    }
+    if (vmState === 'running') {
+        const ip = await vmIp(vmName);
+        details.push(`VM: ${vmName} — running${ip ? ` (${ip})` : ''}`);
+    }
+    else {
+        details.push(`VM: ${vmName} — ${vmState}`);
+    }
+}
+async function readQemuStatus(image, details) {
+    const stateDir = qemuStateDir(image.name);
+    const workingDir = qemuWorkingDir(image.name);
+    const pidFile = qemuPidFile(image.name);
+    details.push(existsSync(qemuImagePath(image.name)) ? 'image: pulled' : 'image: not pulled');
+    let running = false;
+    let pid;
+    pid = readPidFile(pidFile);
+    if (pid !== undefined) {
+        running = isAlive(pid);
+    }
+    else if (existsSync(stateDir)) {
+        // A VM started without a pidfile (or a stale one): the overlay path is
+        // unique to this sandbox — same fallback as the stop script.
+        const pgrep = await run('pgrep', ['-f', `qemu-system-aarch64.*${stateDir}`]);
+        running = pgrep.code === 0 && pgrep.stdout.trim() !== '';
+    }
+    if (!existsSync(workingDir)) {
+        details.push(`VM: ${image.name} — not created (no state at ${stateDir})`);
+    }
+    else {
+        details.push(running ? `VM: ${image.name} — running (qemu pid ${pid ?? '?'})` : 'VM: stopped');
+    }
+}
+async function readVmwareStatus(platform, image, details) {
+    const stateDir = imageRootDir(platform, image.name);
+    const archive = join(stateDir, 'image', `${image.name}.tar.gz`);
+    const baseDir = join(stateDir, 'base');
+    const workingVmx = join(stateDir, 'working', `${image.name}.vmx`);
+    details.push(existsSync(archive) || existsSync(baseDir) ? 'image: pulled' : 'image: not pulled');
+    if (!existsSync(workingVmx)) {
+        details.push(`VM: ${image.name} — not created (no state at ${stateDir})`);
+        return;
+    }
+    const vmrun = findVmrun();
+    if (!vmrun) {
+        details.push('VM: state unknown — vmrun not found (VMware Fusion missing?)');
+        return;
+    }
+    let running = false;
+    try {
+        const runningVms = await listRunningVms({ vmrun });
+        const wanted = normalizePath(workingVmx);
+        running = runningVms.some((p) => normalizePath(p) === wanted);
+    }
+    catch (err) {
+        details.push(`vmrun list failed: ${err.message}`);
+        return;
+    }
+    details.push(running ? `VM: ${image.name} — running` : 'VM: stopped');
+}
+function normalizePath(p) {
+    return p.replace(/\/+/g, '/');
+}

package/dist/commands/stop.js

@@ -0,0 +1,186 @@
+// commands/stop.ts — `agent-dev-env stop <platform>`: stop the VM
+// ('tart stop' / 'vmrun stop' / the qemu+swtpm pidfiles) and kill the
+// host bridges the runner left up (pidfile-managed bridge.js processes;
+// a foreign listener on the port is left alone). macOS + Ubuntu VMware in
+// Phases 3/4, Windows VMware in Phase 5, Windows QEMU in Phase 6.
+import { existsSync } from 'node:fs';
+import { run } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { workingVmxPath } from '../lib/paths.js';
+import { stopQemu, stopSwtpm } from '../lib/qemu.js';
+import { stopVm, tartAvailable, vmExists, vmState, waitForVmState } from '../lib/tart.js';
+import { findVmrun, isVmRunning, stopVmGraceful } from '../lib/vmrun.js';
+import { stopHostBridge } from '../runners/bridges.js';
+import { resolveRunOptions } from '../runners/options.js';
+/** Stops a sandbox platform (VM + host bridges).
+ *
+ * @param platform - The platform to stop.
+ * @returns The process exit code.
+ */
+export async function stopCmd(platform) {
+    if (platform === 'macos') {
+        await stopMacos();
+        return 0;
+    }
+    if (platform === 'windows-qemu') {
+        await stopQemuSandbox();
+        return 0;
+    }
+    await stopVmware(platform);
+    return 0;
+}
+/** The QEMU stop flow (the stop-windows-qemu-sandbox.sh port): qemu via
+ *  the runner's qemu.pid (with the overlay-path pgrep fallback), swtpm
+ *  (it otherwise holds the TPM state lock), then the host bridges.
+ */
+export async function stopQemuSandbox() {
+    const options = resolveRunOptions('windows-qemu');
+    const image = options.image;
+    logger.title(`Stopping Windows QEMU sandbox: ${image}`);
+    logger.step('Stopping qemu');
+    await stopQemu(image);
+    logger.step('Stopping swtpm');
+    await stopSwtpm(image);
+    logger.step('Host bridges (SSH agent, Docker)');
+    await stopBridgeForPort('ssh-agent', options.agentPort);
+    await stopBridgeForPort('docker', options.dockerPort);
+    logger.step('Sandbox stopped');
+}
+/** The macOS stop flow — shared with `delete` (which stops first).
+ */
+export async function stopMacos() {
+    const options = resolveRunOptions('macos');
+    requireTart();
+    const { vm } = options;
+    logger.title(`Stopping macOS sandbox: ${vm}`);
+    await stopTartVm(vm);
+    logger.step('Host bridges (SSH agent, Docker)');
+    await stopBridgeForPort('ssh-agent', options.agentPort);
+    await stopBridgeForPort('docker', options.dockerPort);
+    const state = (await vmState(vm)) ?? 'stopped';
+    logger.step('Sandbox stopped');
+    logger.out(`    ${'VM'.padEnd(12)}${logger.bold(vm)} (${state})`);
+    logger.out(`    ${'Bridges'.padEnd(12)}host listeners on TCP ${options.agentPort} and ` +
+        `${options.dockerPort} stopped`);
+}
+/** The VMware stop flow — shared by the Ubuntu and Windows backends (the
+ *  legacy stop scripts; the guest-side services/bridges stop with the VM).
+ *
+ * @param platform - The VMware platform to stop.
+ */
+export async function stopVmware(platform) {
+    const options = resolveRunOptions(platform);
+    requireVmrun();
+    const vmx = workingVmxPath(platform, options.image);
+    logger.title(`${platform === 'ubuntu-vmware' ? 'Ubuntu' : 'Windows'} VMware sandbox: ${vmx}`);
+    await stopVmwareVmx(vmx);
+    logger.step('Host bridges (SSH agent, Docker)');
+    await stopBridgeForPort('ssh-agent', options.agentPort);
+    await stopBridgeForPort('docker', options.dockerPort);
+    const running = await isVmRunning(vmx);
+    logger.step('Sandbox stopped');
+    logger.out(`    ${'VM'.padEnd(12)}${logger.bold(vmx)} (${running ? 'running' : 'stopped'})`);
+    logger.out(`    ${'Bridges'.padEnd(12)}host listeners on TCP ${options.agentPort} and ` +
+        `${options.dockerPort} stopped`);
+}
+/** Stops the macOS working VM with the legacy wait-for-stopped flow. */
+async function stopTartVm(vm) {
+    if (!(await vmExists(vm))) {
+        logger.warn(`VM '${vm}' does not exist (was it deleted?) — skipping 'tart stop'.`);
+        return;
+    }
+    if ((await vmState(vm)) !== 'running') {
+        logger.info(`VM '${vm}' is already stopped.`);
+        return;
+    }
+    logger.cmd(`tart stop ${vm}`);
+    const res = await stopVm(vm);
+    if (res.code !== 0) {
+        logger.warn(`'tart stop ${vm}' failed — the VM may already be stopping.`);
+    }
+    process.stdout.write(`    Waiting for '${vm}' to stop`);
+    if (await waitForVmState(vm, 'stopped')) {
+        process.stdout.write(` ${logger.color('green')}stopped${logger.reset()}\n`);
+        logger.ok(`VM '${vm}' is stopped.`);
+    }
+    else {
+        process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+        logger.warn(`'${vm}' is still running — force it with 'tart stop ${vm} --timeout 1'.`);
+    }
+}
+/** Stops the VMware working VM: graceful `soft` first, hard power-off as
+ *  a fallback after a minute (both wait for the running-VM list).
+ */
+async function stopVmwareVmx(vmx) {
+    if (!existsSync(vmx)) {
+        logger.warn(`No working VM (${vmx}) — was the sandbox ever run?`);
+        return;
+    }
+    if (!(await isVmRunning(vmx))) {
+        logger.info('VM is already stopped.');
+        return;
+    }
+    logger.cmd(`vmrun -T fusion stop ${vmx} soft`);
+    process.stdout.write('    Waiting for a graceful shutdown (up to 1 min)');
+    if (await stopVmGraceful(vmx)) {
+        process.stdout.write(` ${logger.color('green')}stopped${logger.reset()}\n`);
+        logger.ok(`VM is stopped (${vmx}).`);
+    }
+    else {
+        process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+        logger.warn("The VM is still running — stop it manually with 'vmrun -T fusion stop'.");
+    }
+}
+/** Kills the bridge we manage on the port (pidfile first), otherwise
+ *  reports the listener state like the legacy stop script.
+ */
+async function stopBridgeForPort(role, port) {
+    const pid = await stopHostBridge(role);
+    if (pid !== undefined) {
+        logger.ok(`Stopped the host bridge on TCP ${port} (pid ${pid}).`);
+        return;
+    }
+    const pids = await listenerPids(port);
+    if (pids.length === 0) {
+        logger.info(`No listener on TCP port ${port} — nothing to stop.`);
+        return;
+    }
+    for (const listener of pids) {
+        const command = await processCommand(listener);
+        if (!command.includes('bridge.js')) {
+            logger.warn(`Listener on TCP ${port} (pid ${listener}) is not an agent-dev-env ` +
+                'bridge — leaving it alone.');
+            continue;
+        }
+        await run('kill', [String(listener)]);
+        logger.ok(`Stopped the host bridge on TCP ${port} (pid ${listener}).`);
+    }
+}
+/** @internal — pids listening on the given TCP port (lsof -ti). */
+async function listenerPids(port) {
+    const res = await run('lsof', ['-tiTCP:' + port, '-sTCP:LISTEN']);
+    if (res.code !== 0) {
+        return [];
+    }
+    return res.stdout
+        .split('\n')
+        .map((line) => Number.parseInt(line.trim(), 10))
+        .filter((pid) => Number.isInteger(pid) && pid > 0);
+}
+/** @internal — the command line of a pid (`ps -p pid -o command=`). */
+async function processCommand(pid) {
+    const res = await run('ps', ['-p', String(pid), '-o', 'command=']);
+    return res.code === 0 ? res.stdout.trim() : '';
+}
+/** tart prereq (same message as the runner). */
+function requireTart() {
+    if (!tartAvailable()) {
+        logger.die("tart is not installed — run 'brew install cirruslabs/cli/tart' first.");
+    }
+}
+/** vmrun prereq (same message as the runner). */
+function requireVmrun() {
+    if (!findVmrun()) {
+        logger.die('vmrun not found — install VMware Fusion (free for personal use) or set FUSION_APP_PATH.');
+    }
+}

package/dist/commands/sync.js

@@ -0,0 +1,98 @@
+// commands/sync.ts — `agent-dev-env sync <platform> [--yes]`: copy the
+// host's user settings into the guest on demand (no VM restart), update
+// the version marker and restart OpenChamber. macos | ubuntu-vmware per
+// the plan; macOS lands in Phase 3 (tart transport), Ubuntu in Phase 4
+// (ssh2 transport).
+import { existsSync } from 'node:fs';
+import { sleep } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { workingVmxPath } from '../lib/paths.js';
+import { tartAvailable, vmExists, vmState } from '../lib/tart.js';
+import { findVmrun, getGuestIpAddress, isVmRunning } from '../lib/vmrun.js';
+import { openSshSession } from '../lib/ssh.js';
+import { syncUserSettings } from '../settings/macos-copy.js';
+import { syncUserSettings as syncUbuntuSettings } from '../settings/ubuntu-copy.js';
+import { resolveGuestCredentials } from '../runners/ubuntu-guest.js';
+import { resolveRunOptions } from '../runners/options.js';
+import { notYet } from './not-yet.js';
+/** Syncs the host's user settings into the guest.
+ *
+ * @param platform - The platform to sync.
+ * @param options - --yes flag.
+ * @returns The process exit code.
+ */
+export async function syncCmd(platform, options) {
+    if (platform === 'macos') {
+        await syncMacos(options);
+        return 0;
+    }
+    if (platform === 'ubuntu-vmware') {
+        await syncUbuntu(options);
+        return 0;
+    }
+    return notYet('sync', platform);
+}
+/** The macOS sync flow (VM must be running — `tart exec` needs it). */
+async function syncMacos(options) {
+    if (!tartAvailable()) {
+        logger.die("tart is not installed — run 'brew install cirruslabs/cli/tart' first.");
+    }
+    const runOptions = resolveRunOptions('macos', { yes: options.yes });
+    const { vm } = runOptions;
+    logger.title(`Syncing user settings into ${vm}`);
+    if (!(await vmExists(vm))) {
+        logger.die(`working VM '${vm}' not found — run 'agent-dev-env run macos' first.`);
+    }
+    if ((await vmState(vm)) !== 'running') {
+        logger.die(`VM '${vm}' is not running — start it with 'agent-dev-env run macos' first.`);
+    }
+    const outcome = await syncUserSettings(vm, runOptions.home, runOptions.yes === true);
+    if (outcome === 'copied') {
+        logger.ok(`Done — settings synced into '${vm}'.`);
+    }
+}
+/** The Ubuntu sync flow (VM must be running + sshd up — the settings
+ *  travel over the ssh2 session).
+ */
+async function syncUbuntu(options) {
+    if (!findVmrun()) {
+        logger.die('vmrun not found — install VMware Fusion (free for personal use) or set FUSION_APP_PATH.');
+    }
+    const runOptions = resolveRunOptions('ubuntu-vmware', { yes: options.yes });
+    const vmx = workingVmxPath('ubuntu-vmware', runOptions.image);
+    logger.title(`Syncing user settings into ${vmx}`);
+    if (!existsSync(vmx)) {
+        logger.die(`working VM '${vmx}' not found — run 'agent-dev-env run ubuntu-vmware' first.`);
+    }
+    if (!(await isVmRunning(vmx))) {
+        logger.die(`VM '${vmx}' is not running — start it with 'agent-dev-env run ubuntu-vmware' first.`);
+    }
+    const ip = await waitGuestIp(vmx);
+    const creds = resolveGuestCredentials(runOptions.image, runOptions.env, ip);
+    const session = await openSshSession(creds);
+    try {
+        const outcome = await syncUbuntuSettings(session, runOptions.home, runOptions.yes === true, creds.password);
+        if (outcome === 'copied') {
+            logger.ok(`Done — settings synced into '${vmx}'.`);
+        }
+    }
+    finally {
+        session.end();
+    }
+}
+/** Waits for the guest IP (bounded per call; the sync cannot proceed
+ *  without it).
+ *
+ * @param vmx - The working VM vmx.
+ * @returns The guest IP.
+ */
+async function waitGuestIp(vmx) {
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+        const ip = await getGuestIpAddress(vmx);
+        if (ip) {
+            return ip;
+        }
+        await sleep(2000);
+    }
+    return logger.die('timed out waiting for the guest IP — are open-vm-tools running in the guest?');
+}

package/dist/lib/exec.js

@@ -0,0 +1,250 @@
+// exec.ts — process helpers, the unified replacement for the shell
+// scripts' repeated spawn/nohup/alarm/lsof glue:
+//
+//   run()            spawn + wait, captured stdout/stderr (replaces
+//                    backticks/$(...) subshells)
+//   runChecked()     run, throw on non-zero (replaces `cmd || die`)
+//   commandExists()  `command -v`
+//   which()          full path of a command on PATH
+//   isAlive()        kill -0
+//   readPidFile()    pid files the runners/stop scripts share
+//   spawnDetached()  nohup-style detached process with a log file
+//   killTree()       kill -0 pid && recursive pkill -P
+//   withTimeout()    the perl alarm wrapper (upgradevm, ip polls, ...)
+import { spawn } from 'node:child_process';
+import { accessSync, constants as fsConstants, openSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Spawns a command and waits for it to exit, capturing stdout/stderr.
+ *
+ * @param cmd - The command to run.
+ * @param args - Command-line arguments.
+ * @param options - cwd/env/input/timeout overrides.
+ * @returns The exit code + captured output (never rejects; spawn failures
+ *   yield code -1 with the error in stderr).
+ */
+export function run(cmd, args = [], options = {}) {
+    return new Promise((resolve) => {
+        const child = spawnChild(cmd, args, options);
+        const output = { stdout: '', stderr: '' };
+        attachStdio(child, output);
+        writeInput(child, options.input);
+        const timer = options.timeoutMs !== undefined ? armTimeout(child, options.timeoutMs) : undefined;
+        let settled = false;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            resolve(result);
+        };
+        child.on('error', (err) => {
+            finish({ code: -1, stdout: output.stdout, stderr: err.message, signal: null });
+        });
+        child.on('close', (code, signal) => {
+            finish({
+                code: code ?? -1,
+                stdout: output.stdout,
+                stderr: output.stderr,
+                signal,
+            });
+        });
+    });
+}
+function spawnChild(cmd, args, options) {
+    return spawn(cmd, args, {
+        cwd: options.cwd,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+}
+function attachStdio(child, output) {
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (d) => {
+        output.stdout += d;
+    });
+    child.stderr.on('data', (d) => {
+        output.stderr += d;
+    });
+}
+function writeInput(child, input) {
+    child.stdin.on('error', () => {
+        // EPIPE when the child exits before reading stdin — not fatal.
+    });
+    if (input !== undefined) {
+        child.stdin.write(input);
+    }
+    child.stdin.end();
+}
+function armTimeout(child, ms) {
+    return setTimeout(() => {
+        child.kill('SIGKILL');
+    }, ms);
+}
+/** run() with a strict non-zero contract; throws with the command's
+ *  stderr on failure (the `cmd || die` replacement).
+ * @param cmd - The command to run.
+ * @param args - Command-line arguments.
+ * @param options - cwd/env/input/timeout overrides.
+ * @returns The result on success.
+ * @throws Error with the stderr detail on a non-zero exit.
+ */
+export async function runChecked(cmd, args = [], options = {}) {
+    const res = await run(cmd, args, options);
+    if (res.code !== 0) {
+        const detail = (res.stderr.trim() || res.stdout.trim()).trim();
+        throw new Error(`command failed (${res.code}): ${cmd}${args.length ? ` ${args.join(' ')}` : ''}` +
+            (detail ? `\n${detail}` : ''));
+    }
+    return res;
+}
+/** True when the file exists and is executable (access X_OK). */
+export function isExecutable(path) {
+    try {
+        accessSync(path, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `command -v`-style lookup.
+ *
+ * @param command - The command name (or a path with `/`).
+ * @param env - Environment to resolve PATH from (defaults to process.env).
+ * @returns The full path, or undefined when not found.
+ */
+export function which(command, env = process.env) {
+    if (command.includes('/')) {
+        return isExecutable(command) ? command : undefined;
+    }
+    for (const dir of (env.PATH ?? '').split(':')) {
+        if (!dir) {
+            continue;
+        }
+        const candidate = join(dir, command);
+        if (isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/** Whether the command resolves on PATH.
+ *
+ * @param command - The command name.
+ * @param env - Environment to resolve PATH from (defaults to process.env).
+ * @returns True when found executable.
+ */
+export function commandExists(command, env = process.env) {
+    return which(command, env) !== undefined;
+}
+/** Delays the promise (the shell's `sleep`).
+ *
+ * @param ms - Milliseconds to wait.
+ * @returns A promise that resolves after the delay.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** kill -0: whether the process is alive (EPERM counts as alive).
+ *
+ * @param pid - The process id.
+ * @returns True when a process with this pid exists.
+ */
+export function isAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Reads a pid file.
+ *
+ * @param path - The pid file path.
+ * @returns The pid, or undefined when missing/invalid.
+ */
+export function readPidFile(path) {
+    try {
+        const pid = Number.parseInt(readFileSync(path, 'utf8').trim(), 10);
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** nohup-equivalent: a detached process that survives the
+ *  CLI exiting. Returns the pid for the runner's pid file.
+ * @param cmd - The command to run detached.
+ * @param args - Command-line arguments.
+ * @param options - Log file / cwd / env overrides.
+ * @returns The spawned pid.
+ */
+export function spawnDetached(cmd, args, options = {}) {
+    let logFd;
+    if (options.logFile) {
+        logFd = openSync(options.logFile, 'a');
+    }
+    const child = spawn(cmd, args, {
+        detached: true,
+        cwd: options.cwd,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        stdio: logFd !== undefined ? ['ignore', logFd, logFd] : 'ignore',
+    });
+    // detached:true alone still keeps the parent's event loop alive until
+    // the child exits — without unref() the CLI would hang past its work
+    // (run macos printed the "ready" summary and never exited). unref()
+    // lets the CLI exit while the daemon (tart run, bridge forwarders,
+    // qemu, watchdog) keeps running under its pid file.
+    child.unref();
+    return child.pid ?? -1;
+}
+/** Kills a process and all of its descendants (recursive
+ *  pgrep -P).
+ * @param pid - The root process id.
+ * @param signal - Signal to send (default SIGTERM).
+ */
+export async function killTree(pid, signal = 'SIGTERM') {
+    if (!isAlive(pid)) {
+        return;
+    }
+    const out = await run('pgrep', ['-P', String(pid)]);
+    for (const line of out.stdout.split('\n')) {
+        const child = Number.parseInt(line.trim(), 10);
+        if (Number.isInteger(child) && child > 0) {
+            await killTree(child, signal);
+        }
+    }
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        // already gone
+    }
+}
+/** Rejects when the promise does not settle in time (perl alarm
+ *  equivalent — vmrun/getGuestIPAddress can hang past their own
+ *  timeouts).
+ * @param promise - The promise to race against the timer.
+ * @param ms - Timeout in milliseconds.
+ * @param message - Optional timeout error message.
+ * @returns The promise's value when it settles in time.
+ */
+export function withTimeout(promise, ms, message) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message ?? `timed out after ${ms} ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    });
+}