@pellux/goodvibes-tui 0.20.1 → 0.20.3

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.20.3] — 2026-05-13
+
+### Fixes
+- Changed `/sandbox qemu bootstrap` to run image build and guest provisioning asynchronously so the TUI can clear the prompt, render progress, and remain responsive while long QEMU setup steps run.
+- Updated generated QEMU wrappers to fail fast when the QEMU process exits before SSH is available, including a tail of the QEMU log for port conflicts and startup failures.
+
+## [0.20.2] — 2026-05-12
+
+### Changes
+- Changed QEMU sandbox setup/bootstrap defaults to use `~/.goodvibes/tui/sandbox` instead of writing setup bundles into the current project.
+- Made `/sandbox qemu bootstrap` perform the image build and guest runtime provisioning by default, with `--scaffold-only`, `--no-build`, and `--no-provision` escape hatches for manual workflows.
+- Updated sandbox review guidance and QEMU documentation so first-run setup no longer points users at project-local sandbox paths.
+
 ## [0.20.1] — 2026-05-12
 
 ### Changes

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.20.1-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.20.3-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
 
 A terminal-native AI coding, operations, automation, knowledge, and integration console with a typed runtime, omnichannel surfaces, structured memory/knowledge, and a raw ANSI renderer.
 
@@ -624,7 +624,7 @@ Isolation controls:
 
 The QEMU path includes:
 
-- setup bundle generation
+- setup bundle generation under the user GoodVibes data directory by default
 - first-run bootstrap scaffolding
 - Debian cloud-image download, mutable qcow2 clone, resize, and NoCloud ISO creation through the generated `create-image.sh`
 - host-side wrapper generation
@@ -644,8 +644,8 @@ Key commands:
 - `/sandbox recommend`
 - `/sandbox doctor`
 - `/sandbox probe`
-- `/sandbox qemu setup <dir>`
-- `/sandbox qemu bootstrap <dir> [size-gb]`
+- `/sandbox qemu setup [dir]`
+- `/sandbox qemu bootstrap [dir] [size-gb] [--scaffold-only|--no-build|--no-provision]`
 - `/sandbox qemu inspect-setup <manifest>`
 - `/sandbox qemu apply-setup <manifest>`
 - `/sandbox session ...`
@@ -655,13 +655,13 @@ Key commands:
 Typical first-run path:
 
 ```sh
-/sandbox qemu bootstrap .goodvibes/tui/sandbox 20
-.goodvibes/tui/sandbox/create-image.sh .goodvibes/tui/sandbox/goodvibes-sandbox.qcow2 20G
-GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh .goodvibes/tui/sandbox/qemu-wrapper.sh bash -s < .goodvibes/tui/sandbox/guest-bootstrap.sh
+/sandbox qemu bootstrap
 /sandbox doctor
 /sandbox guest-test eval-py
 ```
 
+By default, QEMU setup files, the mutable qcow2 image, SSH keys, logs, and runtime state live in `~/.goodvibes/tui/sandbox`, not in the current project. Pass an explicit directory only when you intentionally want a non-default bundle location. Use `/sandbox qemu setup` or `/sandbox qemu bootstrap --scaffold-only` if you want to generate/review the bundle without building the image or provisioning guest runtimes.
+
 See [QEMU sandbox bootstrapping](docs/qemu-sandbox.md) for host prerequisites, generated files, first-boot behavior, guest runtime packages, and troubleshooting logs.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",

package/src/input/commands/local-setup-review.ts

@@ -154,14 +154,12 @@ export function renderSetupSandboxReview(ctx: CommandContext, snapshot: SetupRev
     '  next:',
   ];
   if (backend === 'local') {
-    lines.push('    /sandbox qemu bootstrap .goodvibes/tui/sandbox 20');
-    lines.push('    .goodvibes/tui/sandbox/create-image.sh .goodvibes/tui/sandbox/goodvibes-sandbox.qcow2 20G');
-    lines.push('    GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh .goodvibes/tui/sandbox/qemu-wrapper.sh bash -s < .goodvibes/tui/sandbox/guest-bootstrap.sh');
+    lines.push('    /sandbox qemu bootstrap');
+    lines.push('    default bundle: ~/.goodvibes/tui/sandbox');
     lines.push('    /sandbox doctor');
   } else if (!image || !wrapper) {
-    lines.push('    /sandbox qemu setup .goodvibes/tui/sandbox');
-    lines.push('    .goodvibes/tui/sandbox/create-image.sh .goodvibes/tui/sandbox/goodvibes-sandbox.qcow2 20G');
-    lines.push('    GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh .goodvibes/tui/sandbox/qemu-wrapper.sh bash -s < .goodvibes/tui/sandbox/guest-bootstrap.sh');
+    lines.push('    /sandbox qemu bootstrap');
+    lines.push('    default bundle: ~/.goodvibes/tui/sandbox');
     lines.push('    /sandbox doctor');
   } else {
     lines.push('    /sandbox guest-test eval-js');

package/src/input/commands/local-setup.ts

@@ -73,7 +73,7 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
           ...(`${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'qemu' && !String(ctx.platform.configManager.get('sandbox.qemuImagePath')).trim()
             ? ['  [WARN] sandbox: qemu backend selected without qemuImagePath'] : []),
           ...(`${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'qemu' && !String(ctx.platform.configManager.get('sandbox.qemuExecWrapper')).trim()
-            ? ['  [WARN] sandbox: qemu backend selected without qemuExecWrapper', '    next: /sandbox scaffold-qemu-wrapper .goodvibes/tui/qemu-wrapper.sh'] : []),
+            ? ['  [WARN] sandbox: qemu backend selected without qemuExecWrapper', '    next: /sandbox qemu setup'] : []),
           ...(`${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'qemu' && String(ctx.platform.configManager.get('sandbox.qemuExecWrapper')).trim()
             ? ['  [INFO] sandbox: wrapper bridge can be validated with GV_SANDBOX_WRAPPER_MODE=host-exec before wiring a real guest transport'] : []),
           ...(snapshot.serviceIssues.length > 0

package/src/input/commands/platform-sandbox-qemu.ts

@@ -1,5 +1,5 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
 import type { CommandContext } from '../command-registry.ts';
 import {
   applySandboxQemuSetupManifest,
@@ -11,6 +11,141 @@ import {
 import { requireShellPaths } from './runtime-services.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
+const DEFAULT_QEMU_SIZE_GB = 20;
+
+interface ParsedQemuSetupArgs {
+  readonly directory: string;
+}
+
+interface ParsedQemuBootstrapArgs extends ParsedQemuSetupArgs {
+  readonly sizeGb: number;
+  readonly buildImage: boolean;
+  readonly provisionGuest: boolean;
+}
+
+function defaultQemuSandboxDirectory(shellPaths: ReturnType<typeof requireShellPaths>): string {
+  return shellPaths.resolveUserPath('tui', 'sandbox');
+}
+
+function parseSetupArgs(args: string[], shellPaths: ReturnType<typeof requireShellPaths>): ParsedQemuSetupArgs {
+  const directory = args[2] ?? defaultQemuSandboxDirectory(shellPaths);
+  return {
+    directory,
+  };
+}
+
+function parseBootstrapArgs(args: string[], shellPaths: ReturnType<typeof requireShellPaths>): ParsedQemuBootstrapArgs {
+  let directory = defaultQemuSandboxDirectory(shellPaths);
+  let sizeGb = DEFAULT_QEMU_SIZE_GB;
+  let buildImage = true;
+  let provisionGuest = true;
+  for (const arg of args.slice(2)) {
+    if (arg === '--scaffold-only') {
+      buildImage = false;
+      provisionGuest = false;
+      continue;
+    }
+    if (arg === '--no-build') {
+      buildImage = false;
+      continue;
+    }
+    if (arg === '--no-provision') {
+      provisionGuest = false;
+      continue;
+    }
+    if (/^\d+$/.test(arg)) {
+      sizeGb = Number.parseInt(arg, 10);
+      continue;
+    }
+    directory = arg;
+  }
+  return {
+    directory,
+    sizeGb,
+    buildImage,
+    provisionGuest,
+  };
+}
+
+function tailText(value: string, maxLines = 40): string {
+  const lines = value.trim().split(/\r?\n/).filter(Boolean);
+  return lines.slice(Math.max(0, lines.length - maxLines)).join('\n');
+}
+
+function appendBounded(current: string, chunk: Buffer | string, maxLength = 40_000): string {
+  const next = current + chunk.toString();
+  return next.length > maxLength ? next.slice(next.length - maxLength) : next;
+}
+
+function printProgress(ctx: CommandContext, message: string): void {
+  ctx.print(message);
+  ctx.renderRequest();
+}
+
+async function runQemuBootstrapStep(
+  label: string,
+  command: string,
+  args: readonly string[],
+  options: {
+    readonly cwd: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly input?: string;
+    readonly timeoutMs: number;
+  },
+): Promise<void> {
+  let stdout = '';
+  let stderr = '';
+  let timedOut = false;
+  const child = spawn(command, [...args], {
+    cwd: options.cwd,
+    env: { ...process.env, ...options.env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+
+  child.stdout?.on('data', (chunk) => {
+    stdout = appendBounded(stdout, chunk);
+  });
+  child.stderr?.on('data', (chunk) => {
+    stderr = appendBounded(stderr, chunk);
+  });
+
+  if (options.input !== undefined) {
+    child.stdin?.end(options.input);
+  } else {
+    child.stdin?.end();
+  }
+
+  let killTimer: NodeJS.Timeout | undefined;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    child.kill('SIGTERM');
+    killTimer = setTimeout(() => child.kill('SIGKILL'), 5_000);
+  }, options.timeoutMs);
+
+  const result = await new Promise<{ status: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+    child.once('error', reject);
+    child.once('close', (status, signal) => resolve({ status, signal }));
+  }).finally(() => {
+    clearTimeout(timeout);
+    if (killTimer) clearTimeout(killTimer);
+  });
+
+  if (result.status === 0) return;
+  const stderrTail = tailText(stderr);
+  const stdoutTail = tailText(stdout);
+  const reason = timedOut
+    ? `timed out after ${Math.round(options.timeoutMs / 1000)}s`
+    : result.signal
+      ? `signal ${result.signal}`
+      : `exit ${result.status ?? 'unknown'}`;
+  throw new Error([
+    `${label} failed (${reason}).`,
+    stderrTail ? `stderr:\n${stderrTail}` : '',
+    stdoutTail ? `stdout:\n${stdoutTail}` : '',
+  ].filter(Boolean).join('\n'));
+}
+
 export async function handleSandboxQemuCommand(args: string[], ctx: CommandContext): Promise<boolean> {
   const shellPaths = requireShellPaths(ctx);
   const sub = (args[1] ?? '').toLowerCase();
@@ -20,12 +155,8 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
     return true;
   }
   if (sub === 'setup') {
-    const dirArg = args[2];
-    if (!dirArg) {
-      ctx.print('Usage: /sandbox qemu setup <directory>');
-      return true;
-    }
-    const bundle = scaffoldSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, dirArg, { surfaceRoot: 'tui' });
+    const parsed = parseSetupArgs(args, shellPaths);
+    const bundle = scaffoldSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, parsed.directory, { surfaceRoot: 'tui' });
     const manifest = loadSandboxQemuSetupManifest(shellPaths.workingDirectory, bundle.manifestPath);
     applySandboxQemuSetupManifest(ctx.platform.configManager, manifest);
     ctx.platform.configManager.setDynamic('sandbox.replIsolation', 'shared-vm');
@@ -45,19 +176,21 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
       '  applied: backend=qemu, qemu binary, wrapper path, image path, launch-per-command guest settings, shared VM isolation',
       `  next: ${bundle.imageCreateScriptPath} ${bundle.imagePath} 20G`,
       `  then provision runtimes: GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh ${bundle.wrapperPath} bash -s < ${bundle.guestBootstrapScriptPath}`,
+      '',
+      `Default setup location: ${defaultQemuSandboxDirectory(shellPaths)}`,
+      'Pass an explicit directory only when you intentionally want a non-default bundle location.',
     ].join('\n'));
     return true;
   }
   if (sub === 'bootstrap') {
-    const dirArg = args[2];
-    const sizeGb = Number.parseInt(args[3] ?? '20', 10);
-    if (!dirArg || !Number.isInteger(sizeGb) || sizeGb < 1) {
-      ctx.print('Usage: /sandbox qemu bootstrap <directory> [size-gb]');
+    const parsed = parseBootstrapArgs(args, shellPaths);
+    if (!Number.isInteger(parsed.sizeGb) || parsed.sizeGb < 1) {
+      ctx.print('Usage: /sandbox qemu bootstrap [directory] [size-gb] [--scaffold-only|--no-build|--no-provision]');
       return true;
     }
     try {
-      const bundle = bootstrapSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, dirArg, sizeGb, { surfaceRoot: 'tui' });
-      ctx.print([
+      const bundle = bootstrapSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, parsed.directory, parsed.sizeGb, { surfaceRoot: 'tui' });
+      const lines = [
         `Bootstrapped QEMU sandbox in ${bundle.directory}`,
         `  wrapper: ${bundle.wrapperPath}`,
         `  image path: ${bundle.imagePath}`,
@@ -67,10 +200,45 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
         `  projection policy: ${bundle.projectionPolicyPath}`,
         `  manifest: ${bundle.manifestPath}`,
         '  applied: backend=qemu, qemu binary, wrapper path, image path, launch-per-command guest settings, shared VM isolation',
-        `  next: ${bundle.imageCreateScriptPath} ${bundle.imagePath} ${sizeGb}G`,
-        `  then provision runtimes: GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh ${bundle.wrapperPath} bash -s < ${bundle.guestBootstrapScriptPath}`,
-        '  then: /sandbox guest-test eval-py',
-      ].join('\n'));
+      ];
+      if (parsed.buildImage) {
+        printProgress(ctx, `Building QEMU image at ${bundle.imagePath} (${parsed.sizeGb}G). This can download the Debian cloud image on first run.`);
+        await runQemuBootstrapStep('QEMU image build', bundle.imageCreateScriptPath, [bundle.imagePath, `${parsed.sizeGb}G`], {
+          cwd: bundle.directory,
+          timeoutMs: 30 * 60 * 1000,
+        });
+        lines.push('  image build: complete');
+      } else {
+        lines.push(`  image build: skipped`);
+        lines.push(`  next: ${bundle.imageCreateScriptPath} ${bundle.imagePath} ${parsed.sizeGb}G`);
+      }
+      if (parsed.provisionGuest) {
+        if (!existsSync(bundle.imagePath)) {
+          lines.push('  guest provisioning: skipped because image does not exist');
+          lines.push(`  next: ${bundle.imageCreateScriptPath} ${bundle.imagePath} ${parsed.sizeGb}G`);
+        } else {
+          printProgress(ctx, `Provisioning guest runtimes through ${bundle.wrapperPath}. First boot can take several minutes.`);
+          await runQemuBootstrapStep('QEMU guest runtime provisioning', bundle.wrapperPath, ['bash', '-s'], {
+            cwd: bundle.directory,
+            env: {
+              GV_SANDBOX_SYNC_WORKSPACE: '0',
+              GV_SANDBOX_WRAPPER_MODE: 'launch-qemu-ssh',
+            },
+            input: readFileSync(bundle.guestBootstrapScriptPath, 'utf8'),
+            timeoutMs: 45 * 60 * 1000,
+          });
+          lines.push('  guest provisioning: complete');
+        }
+      } else {
+        lines.push(`  guest provisioning: skipped`);
+        lines.push(`  next: GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh ${bundle.wrapperPath} bash -s < ${bundle.guestBootstrapScriptPath}`);
+      }
+      lines.push('  verify: /sandbox doctor');
+      lines.push('  verify: /sandbox guest-test eval-py');
+      lines.push('');
+      lines.push(`Default setup location: ${defaultQemuSandboxDirectory(shellPaths)}`);
+      lines.push('Pass an explicit directory only when you intentionally want a non-default bundle location.');
+      ctx.print(lines.join('\n'));
     } catch (error) {
       ctx.print(summarizeError(error));
     }
@@ -114,6 +282,6 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
     ctx.print(`Applied QEMU sandbox setup from ${shellPaths.resolveWorkspacePath(pathArg)}.`);
     return true;
   }
-  ctx.print('Usage: /sandbox qemu <setup <directory>|bootstrap <directory> [size-gb]|recover <session-id>|inspect-setup <setup-manifest.json>|apply-setup <setup-manifest.json>>');
+  ctx.print('Usage: /sandbox qemu <setup [directory]|bootstrap [directory] [size-gb] [--scaffold-only|--no-build|--no-provision]|recover <session-id>|inspect-setup <setup-manifest.json>|apply-setup <setup-manifest.json>>');
   return true;
 }

package/src/input/commands/platform-sandbox-runtime.ts

@@ -93,7 +93,7 @@ export function registerPlatformSandboxRuntimeCommands(registry: CommandRegistry
   registry.register({
     name: 'sandbox',
     description: 'Review and configure VM isolation policy for MCP and evaluation runtimes',
-    usage: '[open|review|recommend|profiles|presets|preset <id>|apply-preset <id>|probe|doctor|wrapper-test <profile>|guest-test <profile>|init-qemu <dir>|qemu <setup|bootstrap|recover|inspect-setup|apply-setup> ...|session ...|bundle ...|guest-bundle <export|inspect> <path>|scaffold-qemu-wrapper <path>|set-mcp <mode>|set-repl <mode>|set-windows <mode>|set-backend <mode>|set-qemu-binary <path>|set-qemu-image <path>|set-qemu-wrapper <path>|set-qemu-guest-host <host>|set-qemu-guest-port <port>|set-qemu-guest-user <user>|set-qemu-workspace <path>|set-qemu-session-mode <attach|launch-per-command>]',
+    usage: '[open|review|recommend|profiles|presets|preset <id>|apply-preset <id>|probe|doctor|wrapper-test <profile>|guest-test <profile>|init-qemu <dir>|qemu <setup [dir]|bootstrap [dir] [size-gb]|recover|inspect-setup|apply-setup> ...|session ...|bundle ...|guest-bundle <export|inspect> <path>|scaffold-qemu-wrapper <path>|set-mcp <mode>|set-repl <mode>|set-windows <mode>|set-backend <mode>|set-qemu-binary <path>|set-qemu-image <path>|set-qemu-wrapper <path>|set-qemu-guest-host <host>|set-qemu-guest-port <port>|set-qemu-guest-user <user>|set-qemu-workspace <path>|set-qemu-session-mode <attach|launch-per-command>]',
     async handler(args, ctx) {
       const shellPaths = requireShellPaths(ctx);
       const sub = args[0] ?? 'open';
@@ -144,7 +144,7 @@ export function registerPlatformSandboxRuntimeCommands(registry: CommandRegistry
           windowsMode: `${ctx.platform.configManager.get('sandbox.windowsMode')}`,
           secureSandboxReady: renderSandboxReview(ctx.platform.configManager).includes('available'),
           recommendedCommand: `${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'local'
-            ? '/sandbox qemu bootstrap .goodvibes/tui/sandbox 20'
+            ? '/sandbox qemu bootstrap'
             : '/sandbox doctor',
         };
         ctx.print([inspectSandboxProbe(probe), ...backendProbe.warnings.map((warning: string) => `  warning: ${warning}`)].join('\n'));
@@ -207,7 +207,7 @@ export function registerPlatformSandboxRuntimeCommands(registry: CommandRegistry
           `  wrapper: ${bundle.wrapperPath}`,
           `  guest bundle: ${bundle.guestBundlePath}`,
           `  readme: ${bundle.readmePath}`,
-          '  next: /sandbox qemu setup <dir> for the full first-run setup path',
+          '  next: /sandbox qemu setup for the full default setup path',
         ].join('\n'));
         return;
       }
@@ -402,7 +402,7 @@ export function registerPlatformSandboxRuntimeCommands(registry: CommandRegistry
         ctx.print([`Scaffolded QEMU wrapper to ${targetPath}`, '  bridge test mode: GV_SANDBOX_WRAPPER_MODE=host-exec', '  next: /sandbox set-qemu-wrapper ' + targetPath].join('\n'));
         return;
       }
-      ctx.print('Usage: /sandbox [open|review|recommend|profiles|presets|preset <id>|apply-preset <id>|probe|doctor|wrapper-test <profile>|guest-test <profile>|init-qemu <dir>|qemu <setup|bootstrap|recover|inspect-setup|apply-setup> ...|session ...|bundle export <path>|bundle inspect <path>|guest-bundle <export|inspect> <path>|scaffold-qemu-wrapper <path>|set-mcp <mode>|set-repl <mode>|set-windows <mode>|set-backend <mode>|set-qemu-binary <path>|set-qemu-image <path>|set-qemu-wrapper <path>|set-qemu-guest-host <host>|set-qemu-guest-port <port>|set-qemu-guest-user <user>|set-qemu-workspace <path>|set-qemu-session-mode <attach|launch-per-command>]');
+      ctx.print('Usage: /sandbox [open|review|recommend|profiles|presets|preset <id>|apply-preset <id>|probe|doctor|wrapper-test <profile>|guest-test <profile>|init-qemu <dir>|qemu <setup [dir]|bootstrap [dir] [size-gb]|recover|inspect-setup|apply-setup> ...|session ...|bundle export <path>|bundle inspect <path>|guest-bundle <export|inspect> <path>|scaffold-qemu-wrapper <path>|set-mcp <mode>|set-repl <mode>|set-windows <mode>|set-backend <mode>|set-qemu-binary <path>|set-qemu-image <path>|set-qemu-wrapper <path>|set-qemu-guest-host <host>|set-qemu-guest-port <port>|set-qemu-guest-user <user>|set-qemu-workspace <path>|set-qemu-session-mode <attach|launch-per-command>]');
     },
   });
 }

package/src/runtime/sandbox-qemu-templates.ts

@@ -49,6 +49,18 @@ wait_for_ssh() {
   local start now
   start="$(date +%s)"
   while true; do
+    if [[ -n "\${GV_SANDBOX_ACTIVE_QEMU_PIDFILE:-}" && -f "\${GV_SANDBOX_ACTIVE_QEMU_PIDFILE:-}" ]]; then
+      local qemu_pid
+      qemu_pid="$(<"\${GV_SANDBOX_ACTIVE_QEMU_PIDFILE:-}")"
+      if [[ -n "$qemu_pid" ]] && ! kill -0 "$qemu_pid" 2>/dev/null; then
+        echo "QEMU process exited before SSH became available." >&2
+        if [[ -n "\${GV_SANDBOX_ACTIVE_QEMU_LOG:-}" && -f "\${GV_SANDBOX_ACTIVE_QEMU_LOG:-}" ]]; then
+          echo "QEMU log tail:" >&2
+          tail -80 "\${GV_SANDBOX_ACTIVE_QEMU_LOG:-}" >&2 || true
+        fi
+        return 1
+      fi
+    fi
     if ssh "\${ssh_opts[@]}" "$user@$host" "true" >/dev/null 2>&1; then
       return 0
     fi
@@ -85,6 +97,9 @@ start_qemu() {
   local serial_log="$logs_dir/serial-$port.log"
   local qemu_log="$logs_dir/qemu-$port.log"
   local monitor_sock="$run_dir/monitor-$port.sock"
+  GV_SANDBOX_ACTIVE_QEMU_PIDFILE="$pidfile"
+  GV_SANDBOX_ACTIVE_QEMU_LOG="$qemu_log"
+  export GV_SANDBOX_ACTIVE_QEMU_PIDFILE GV_SANDBOX_ACTIVE_QEMU_LOG
   rm -f "$monitor_sock"
   if [[ -f "$pidfile" ]]; then
     local old_pid

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.20.1';
+let _version = '0.20.3';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8'));
   _version = pkg.version ?? _version;