@pellux/goodvibes-tui 0.19.99 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.20.0] — 2026-05-11
+
+### Changes
+- Updated `@pellux/goodvibes-sdk` to `0.33.30` for guest-side QEMU REPL execution and exec working-directory fixes.
+- Added generated QEMU sandbox setup docs, runtime bootstrap scripts, cloud-init seed files, and guest runtime provisioning guidance.
+- Wired `sandbox.replJavaScriptCommand` through generated QEMU setup manifests so JavaScript-family REPL snippets use the guest Bun runtime.
+- Removed the obsolete `/sandbox qemu create-image` command in favor of the generated `create-image.sh` bootstrap workflow.
+- Added focused coverage for QEMU setup scaffolding, command-level exec working directories, context auto-compaction thresholds, and retrospective setup-guide intent classification.
+
 ## [0.19.99] — 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.19.99-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.20.0-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.
 
@@ -626,13 +626,16 @@ The QEMU path includes:
 
 - setup bundle generation
 - first-run bootstrap scaffolding
-- `qemu-img` image creation helpers
+- Debian cloud-image download, mutable qcow2 clone, resize, and NoCloud ISO creation through the generated `create-image.sh`
 - host-side wrapper generation
+- guest cloud-init seed generation for the `goodvibes` sudo user, SSH key auth, `/workspace`, and `ens3` DHCP
 - guest-test and wrapper-test validation
 - session-backed command execution
 - guest bundle export / inspect flows
 - setup manifest export / apply flows
 - `attach` and `launch-per-command` execution modes
+- REPL/MCP-friendly guest bootstrap packages for Python, JavaScript, TypeScript, SQL, GraphQL, Bun, Deno, DuckDB, Go, Rust, Ruby, and common CLI build/search tools
+- guest JavaScript-family REPL execution through `sandbox.replJavaScriptCommand`, defaulting the generated QEMU setup to `/home/goodvibes/.bun/bin/bun`
 
 Key commands:
 
@@ -643,7 +646,6 @@ Key commands:
 - `/sandbox probe`
 - `/sandbox qemu setup <dir>`
 - `/sandbox qemu bootstrap <dir> [size-gb]`
-- `/sandbox qemu create-image <path> [size-gb]`
 - `/sandbox qemu inspect-setup <manifest>`
 - `/sandbox qemu apply-setup <manifest>`
 - `/sandbox session ...`
@@ -654,10 +656,14 @@ 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 doctor
-/sandbox guest-test eval-js
+/sandbox guest-test eval-py
 ```
 
+See [QEMU sandbox bootstrapping](docs/qemu-sandbox.md) for host prerequisites, generated files, first-boot behavior, guest runtime packages, and troubleshooting logs.
+
 ---
 
 ## Remote, Local Services, And Integration Helpers

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "0.33.27"
+    "version": "0.33.30"
   },
   "auth": {
     "modes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.19.99",
+  "version": "0.20.0",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -97,7 +97,7 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "0.33.27",
+    "@pellux/goodvibes-sdk": "0.33.30",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

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

@@ -155,10 +155,13 @@ export function renderSetupSandboxReview(ctx: CommandContext, snapshot: SetupRev
   ];
   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 doctor');
   } else if (!image || !wrapper) {
     lines.push('    /sandbox qemu setup .goodvibes/tui/sandbox');
-    lines.push('    /sandbox qemu create-image .goodvibes/tui/sandbox/images/goodvibes-sandbox.qcow2 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 doctor');
   } else {
     lines.push('    /sandbox guest-test eval-js');

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

@@ -4,7 +4,6 @@ import type { CommandContext } from '../command-registry.ts';
 import {
   applySandboxQemuSetupManifest,
   bootstrapSandboxQemuSetupBundle,
-  createSandboxQemuImage,
   inspectSandboxQemuSetupManifest,
   loadSandboxQemuSetupManifest,
   scaffoldSandboxQemuSetupBundle,
@@ -27,29 +26,25 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
       return true;
     }
     const bundle = scaffoldSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, dirArg, { surfaceRoot: 'tui' });
-    ctx.platform.configManager.setDynamic('sandbox.vmBackend', 'qemu');
-    ctx.platform.configManager.setDynamic('sandbox.qemuExecWrapper', bundle.wrapperPath);
-    ctx.platform.configManager.setDynamic('sandbox.qemuImagePath', bundle.imagePath);
-    if (!`${ctx.platform.configManager.get('sandbox.qemuGuestHost') ?? ''}`.trim()) {
-      ctx.platform.configManager.setDynamic('sandbox.qemuGuestHost', '127.0.0.1');
-    }
-    if (!`${ctx.platform.configManager.get('sandbox.qemuGuestUser') ?? ''}`.trim()) {
-      ctx.platform.configManager.setDynamic('sandbox.qemuGuestUser', 'goodvibes');
-    }
-    if (!`${ctx.platform.configManager.get('sandbox.qemuWorkspacePath') ?? ''}`.trim()) {
-      ctx.platform.configManager.setDynamic('sandbox.qemuWorkspacePath', '/workspace');
-    }
+    const manifest = loadSandboxQemuSetupManifest(shellPaths.workingDirectory, bundle.manifestPath);
+    applySandboxQemuSetupManifest(ctx.platform.configManager, manifest);
+    ctx.platform.configManager.setDynamic('sandbox.replIsolation', 'shared-vm');
+    ctx.platform.configManager.setDynamic('sandbox.mcpIsolation', 'shared-vm');
     ctx.print([
       `Initialized QEMU sandbox setup bundle in ${bundle.directory}`,
       `  wrapper: ${bundle.wrapperPath}`,
       `  image path: ${bundle.imagePath}`,
       `  image create script: ${bundle.imageCreateScriptPath}`,
       `  guest bootstrap: ${bundle.guestBootstrapScriptPath}`,
+      `  seed directory: ${bundle.seedDirectory}`,
+      `  seed ISO: ${bundle.seedIsoPath}`,
+      `  ssh key: ${bundle.sshKeyPath}`,
       `  projection policy: ${bundle.projectionPolicyPath}`,
       `  ssh config: ${bundle.sshConfigPath}`,
       `  manifest: ${bundle.manifestPath}`,
-      '  applied: backend=qemu, wrapper path, image path, and default guest settings',
-      `  next: /sandbox qemu create-image ${bundle.imagePath} 20`,
+      '  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}`,
     ].join('\n'));
     return true;
   }
@@ -67,33 +62,20 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
         `  wrapper: ${bundle.wrapperPath}`,
         `  image path: ${bundle.imagePath}`,
         `  guest bootstrap: ${bundle.guestBootstrapScriptPath}`,
+        `  seed ISO: ${bundle.seedIsoPath}`,
+        `  ssh key: ${bundle.sshKeyPath}`,
         `  projection policy: ${bundle.projectionPolicyPath}`,
         `  manifest: ${bundle.manifestPath}`,
-        '  applied: backend=qemu, wrapper path, image path, and guest settings',
-        '  next: boot the image, run the guest bootstrap script, then /sandbox guest-test eval-js',
+        '  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'));
     } catch (error) {
       ctx.print(summarizeError(error));
     }
     return true;
   }
-  if (sub === 'create-image') {
-    const imagePath = args[2];
-    const sizeGb = Number.parseInt(args[3] ?? '20', 10);
-    if (!imagePath || !Number.isInteger(sizeGb) || sizeGb < 1) {
-      ctx.print('Usage: /sandbox qemu create-image <path> [size-gb]');
-      return true;
-    }
-    try {
-      const created = createSandboxQemuImage(shellPaths.workingDirectory, imagePath, sizeGb);
-      ctx.platform.configManager.setDynamic('sandbox.qemuImagePath', created.path);
-      ctx.platform.configManager.setDynamic('sandbox.vmBackend', 'qemu');
-      ctx.print(`Created QEMU image ${created.path} (${created.sizeGb}G).`);
-    } catch (error) {
-      ctx.print(summarizeError(error));
-    }
-    return true;
-  }
   if (sub === 'recover') {
     const sessionId = args[2];
     if (!sessionId) {
@@ -132,6 +114,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]|create-image <path> [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]|recover <session-id>|inspect-setup <setup-manifest.json>|apply-setup <setup-manifest.json>>');
   return true;
 }

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

@@ -61,6 +61,7 @@ function applySandboxPreset(
   configManager.setDynamic('sandbox.qemuGuestUser' as never, preset.config.qemuGuestUser);
   configManager.setDynamic('sandbox.qemuWorkspacePath' as never, preset.config.qemuWorkspacePath);
   configManager.setDynamic('sandbox.qemuSessionMode' as never, preset.config.qemuSessionMode);
+  configManager.setDynamic('sandbox.replJavaScriptCommand' as never, preset.config.replJavaScriptCommand);
   return true;
 }
 
@@ -83,6 +84,7 @@ function renderSandboxPresetDetail(presetId: string): string | null {
     `  qemu guest user: ${preset.config.qemuGuestUser || '(not configured)'}`,
     `  qemu workspace: ${preset.config.qemuWorkspacePath || '(not configured)'}`,
     `  qemu session mode: ${preset.config.qemuSessionMode}`,
+    `  repl JavaScript command: ${preset.config.replJavaScriptCommand || 'bun'}`,
     ...preset.notes.map((note) => `  note: ${note}`),
   ].join('\n');
 }
@@ -91,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|create-image|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|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>]',
     async handler(args, ctx) {
       const shellPaths = requireShellPaths(ctx);
       const sub = args[0] ?? 'open';
@@ -400,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|create-image|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|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>]');
     },
   });
 }

package/src/renderer/settings-modal-helpers.ts

@@ -121,6 +121,7 @@ export const SETTING_LABELS: Partial<Record<string, string>> = {
   'sandbox.qemuBinary': 'QEMU Binary',
   'sandbox.qemuImagePath': 'QEMU Image',
   'sandbox.qemuExecWrapper': 'QEMU Wrapper',
+  'sandbox.replJavaScriptCommand': 'REPL JS Command',
   'tools.llmProvider': 'Tool LLM Provider',
   'tools.llmModel': 'Tool LLM Model',
   'tools.autoHeal': 'Auto-Heal',

package/src/runtime/sandbox-public-gaps.ts

@@ -9,6 +9,14 @@ import {
   type SandboxLaunchPlan,
   type SandboxProfile,
 } from '@pellux/goodvibes-sdk/platform/runtime/sandbox';
+import {
+  renderQemuGuestBootstrapScript,
+  renderQemuImageCreateScript,
+  renderQemuSetupReadme,
+  renderQemuWrapperTemplate,
+} from './sandbox-qemu-templates.ts';
+
+export { renderQemuWrapperTemplate } from './sandbox-qemu-templates.ts';
 
 export interface SandboxGuestBundle {
   readonly version: 1;
@@ -22,6 +30,7 @@ export interface SandboxGuestBundle {
     readonly user: string;
     readonly workspacePath: string;
     readonly sessionMode: string;
+    readonly replJavaScriptCommand: string;
   };
   readonly nextSteps: readonly string[];
 }
@@ -39,6 +48,10 @@ export interface SandboxQemuSetupBundle extends SandboxQemuInitBundle {
   readonly guestBootstrapScriptPath: string;
   readonly projectionPolicyPath: string;
   readonly sshConfigPath: string;
+  readonly seedDirectory: string;
+  readonly seedIsoPath: string;
+  readonly sshKeyPath: string;
+  readonly sshPublicKeyPath: string;
   readonly manifestPath: string;
 }
 
@@ -51,8 +64,13 @@ export interface SandboxQemuSetupManifest {
   readonly guestBootstrapScriptPath: string;
   readonly projectionPolicyPath: string;
   readonly sshConfigPath: string;
+  readonly seedDirectory: string;
+  readonly seedIsoPath: string;
+  readonly sshKeyPath: string;
+  readonly sshPublicKeyPath: string;
   readonly recommendedSettings: {
     readonly backend: 'qemu';
+    readonly qemuBinary: string;
     readonly wrapperPath: string;
     readonly imagePath: string;
     readonly guestHost: string;
@@ -60,6 +78,7 @@ export interface SandboxQemuSetupManifest {
     readonly guestUser: string;
     readonly guestWorkspacePath: string;
     readonly sessionMode: string;
+    readonly replJavaScriptCommand: string;
   };
 }
 
@@ -71,21 +90,6 @@ export interface WritableConfigManagerLike extends ConfigManagerLike {
   setDynamic(key: string, value: unknown): void;
 }
 
-export function renderQemuWrapperTemplate(): string {
-  return `#!/usr/bin/env bash
-set -euo pipefail
-mode="\${GV_SANDBOX_WRAPPER_MODE:-ssh-guest}"
-if [[ "$mode" == "host-exec" ]]; then
-  exec "$@"
-fi
-host="\${GOODVIBES_QEMU_GUEST_HOST:-127.0.0.1}"
-port="\${GOODVIBES_QEMU_GUEST_PORT:-2222}"
-user="\${GOODVIBES_QEMU_GUEST_USER:-goodvibes}"
-workspace="\${GOODVIBES_QEMU_WORKSPACE:-/workspace}"
-exec ssh -o StrictHostKeyChecking=accept-new -p "$port" "$user@$host" "cd '$workspace' && exec \\"$@\\""
-`;
-}
-
 export function probeSandboxBackends(manager: ConfigManagerLike): SandboxBackendProbe {
   const host = detectSandboxHostStatus(manager);
   const config = getSandboxConfigSnapshot(manager);
@@ -155,15 +159,25 @@ export function buildSandboxLaunchPlan(
       throw new Error(`Requested QEMU sandbox backend is unavailable (${qemuAvailability?.detail ?? 'probe failed'}); refusing to downgrade to local process isolation. Set sandbox.vmBackend to "local" to use host-local isolation explicitly.`);
     }
     const guestPort = config.qemuGuestPort || 2222;
+    const wrapperDirectory = config.qemuExecWrapper ? dirname(config.qemuExecWrapper) : resolve(safeWorkspaceRoot, '.goodvibes/tui/sandbox');
+    const serialLog = resolve(wrapperDirectory, `logs/serial-${guestPort}.log`);
+    const monitorSocket = resolve(wrapperDirectory, `run/monitor-${guestPort}.sock`);
+    const seedIso = resolve(wrapperDirectory, 'seed/nocloud.iso');
+    ensureDir(dirname(serialLog));
+    ensureDir(dirname(monitorSocket));
     const args = [
       '-display', 'none',
-      '-nodefaults',
       '-name', `gv-${profile.id}`,
-      '-snapshot',
-      '-m', '512',
-      '-nic', `user,hostfwd=tcp::${guestPort}-:22`,
+      '-serial', `file:${serialLog}`,
+      '-monitor', `unix:${monitorSocket},server,nowait`,
+      '-m', '1024',
+      '-smp', '2',
+      '-netdev', `user,id=net0,hostfwd=tcp:127.0.0.1:${guestPort}-:22`,
+      '-device', 'virtio-net-pci,netdev=net0',
+      '-smbios', 'type=1,serial=ds=nocloud',
     ];
     if (config.qemuImagePath) args.push('-drive', `file=${config.qemuImagePath},if=virtio,format=qcow2`);
+    if (existsSync(seedIso)) args.push('-drive', `file=${seedIso},if=virtio,media=cdrom,readonly=on`);
     return {
       backend,
       command: config.qemuBinary || 'qemu-system-x86_64',
@@ -326,6 +340,70 @@ function ensureDir(path: string): void {
   mkdirSync(path, { recursive: true });
 }
 
+function ensureQemuSshKey(directory: string): { readonly keyPath: string; readonly publicKeyPath: string; readonly publicKey: string } {
+  const keyPath = resolve(directory, 'keys/goodvibes_qemu_ed25519');
+  const publicKeyPath = `${keyPath}.pub`;
+  ensureDir(dirname(keyPath));
+  if (!existsSync(keyPath) || !existsSync(publicKeyPath)) {
+    const generated = spawnSync('ssh-keygen', ['-t', 'ed25519', '-N', '', '-C', 'goodvibes-qemu', '-f', keyPath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (generated.status !== 0) {
+      writeFileSync(resolve(directory, 'keys/README.txt'), [
+        'ssh-keygen was not available when this bundle was scaffolded.',
+        'Generate the key manually before building the image:',
+        `  ssh-keygen -t ed25519 -N '' -C goodvibes-qemu -f ${keyPath}`,
+        '',
+      ].join('\n'));
+    }
+  }
+  const publicKey = existsSync(publicKeyPath) ? readFileSync(publicKeyPath, 'utf8').trim() : '';
+  return { keyPath, publicKeyPath, publicKey };
+}
+
+function renderQemuUserData(publicKey: string): string {
+  const authorizedKeys = publicKey
+    ? `    ssh_authorized_keys:\n      - ${publicKey}\n`
+    : '    # Generate keys/goodvibes_qemu_ed25519.pub before rebuilding nocloud.iso.\n';
+  return `#cloud-config
+users:
+  - default
+  - name: goodvibes
+    groups: [sudo]
+    shell: /bin/bash
+    sudo: ['ALL=(ALL) NOPASSWD:ALL']
+    lock_passwd: true
+${authorizedKeys}
+ssh_pwauth: false
+disable_root: true
+manage_etc_hosts: true
+
+bootcmd:
+  - [ sh, -c, 'systemctl disable systemd-networkd-wait-online.service || true' ]
+  - [ sh, -c, 'systemctl mask systemd-networkd-wait-online.service || true' ]
+
+runcmd:
+  - [ mkdir, -p, /workspace ]
+  - [ chown, goodvibes:goodvibes, /workspace ]
+  - [ sh, -c, 'systemctl enable ssh ssh.service 2>/dev/null || true' ]
+  - [ sh, -c, 'systemctl restart ssh ssh.service 2>/dev/null || true' ]
+`;
+}
+
+function renderQemuNetworkConfig(): string {
+  return `version: 2
+ethernets:
+  ens3:
+    match:
+      name: "ens3"
+    dhcp4: true
+    dhcp6: false
+    optional: true
+`;
+}
+
 export function scaffoldSandboxQemuInitBundle(
   manager: ConfigManagerLike,
   workspaceRoot: string,
@@ -358,8 +436,9 @@ function buildGuestBundle(manager: ConfigManagerLike, _workspaceRoot: string, wr
       user: config.qemuGuestUser,
       workspacePath: config.qemuWorkspacePath,
       sessionMode: config.qemuSessionMode,
+      replJavaScriptCommand: config.replJavaScriptCommand,
     },
-    nextSteps: ['Create or attach a QEMU guest, run the bootstrap script, then run /sandbox guest-test eval-js.'],
+    nextSteps: ['Create the QEMU image, provision guest runtimes, then run /sandbox guest-test eval-py.'],
   };
 }
 
@@ -376,7 +455,18 @@ export function scaffoldSandboxQemuSetupBundle(
   const projectionPolicyPath = resolve(init.directory, 'projection-policy.json');
   const sshConfigPath = resolve(init.directory, 'ssh-config');
   const manifestPath = resolve(init.directory, 'setup-manifest.json');
+  const seedDirectory = resolve(init.directory, 'seed');
+  const seedIsoPath = resolve(seedDirectory, 'nocloud.iso');
+  const logsDirectory = resolve(init.directory, 'logs');
+  const runDirectory = resolve(init.directory, 'run');
+  const imagesDirectory = resolve(init.directory, 'images');
   const config = getSandboxConfigSnapshot(manager);
+  const qemuBinary = config.qemuBinary || 'qemu-system-x86_64';
+  const guestPort = config.qemuGuestPort || 2222;
+  const guestUser = config.qemuGuestUser || 'goodvibes';
+  const guestWorkspacePath = config.qemuWorkspacePath || '/workspace';
+  const replJavaScriptCommand = `/home/${guestUser}/.bun/bin/bun`;
+  const sshKey = ensureQemuSshKey(init.directory);
   const manifest: SandboxQemuSetupManifest = {
     version: 1,
     createdAt: Date.now(),
@@ -386,23 +476,57 @@ export function scaffoldSandboxQemuSetupBundle(
     guestBootstrapScriptPath,
     projectionPolicyPath,
     sshConfigPath,
+    seedDirectory,
+    seedIsoPath,
+    sshKeyPath: sshKey.keyPath,
+    sshPublicKeyPath: sshKey.publicKeyPath,
     recommendedSettings: {
       backend: 'qemu',
+      qemuBinary,
       wrapperPath: init.wrapperPath,
       imagePath,
       guestHost: config.qemuGuestHost || '127.0.0.1',
-      guestPort: config.qemuGuestPort || 2222,
-      guestUser: config.qemuGuestUser || 'goodvibes',
-      guestWorkspacePath: config.qemuWorkspacePath || '/workspace',
-      sessionMode: config.qemuSessionMode || 'attach',
+      guestPort,
+      guestUser,
+      guestWorkspacePath,
+      sessionMode: 'launch-per-command',
+      replJavaScriptCommand,
     },
   };
-  writeFileSync(imageCreateScriptPath, '#!/usr/bin/env bash\nset -euo pipefail\nqemu-img create -f qcow2 "$1" "${2:-20G}"\n', { mode: 0o755 });
-  writeFileSync(guestBootstrapScriptPath, '#!/usr/bin/env bash\nset -euo pipefail\nmkdir -p /workspace\n');
+  ensureDir(seedDirectory);
+  ensureDir(logsDirectory);
+  ensureDir(runDirectory);
+  ensureDir(imagesDirectory);
+  writeFileSync(resolve(seedDirectory, 'meta-data'), 'instance-id: goodvibes-qemu-sandbox\nlocal-hostname: goodvibes-qemu\n');
+  writeFileSync(resolve(seedDirectory, 'user-data'), renderQemuUserData(sshKey.publicKey));
+  writeFileSync(resolve(seedDirectory, 'network-config'), renderQemuNetworkConfig());
+  writeFileSync(imageCreateScriptPath, renderQemuImageCreateScript(init.directory, imagePath, 20), { mode: 0o755 });
+  writeFileSync(guestBootstrapScriptPath, renderQemuGuestBootstrapScript(), { mode: 0o755 });
   writeFileSync(projectionPolicyPath, `${JSON.stringify({ version: 1, workspace: '/workspace' }, null, 2)}\n`);
-  writeFileSync(sshConfigPath, 'Host goodvibes-qemu\n  HostName 127.0.0.1\n  Port 2222\n  User goodvibes\n');
+  writeFileSync(sshConfigPath, [
+    'Host goodvibes-qemu',
+    '  HostName 127.0.0.1',
+    `  Port ${guestPort}`,
+    `  User ${guestUser}`,
+    `  IdentityFile ${sshKey.keyPath}`,
+    '  StrictHostKeyChecking accept-new',
+    '',
+  ].join('\n'));
   writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
-  return { ...init, imagePath, imageCreateScriptPath, guestBootstrapScriptPath, projectionPolicyPath, sshConfigPath, manifestPath };
+  writeFileSync(init.readmePath, renderQemuSetupReadme(init.directory, imagePath, seedIsoPath));
+  return {
+    ...init,
+    imagePath,
+    imageCreateScriptPath,
+    guestBootstrapScriptPath,
+    projectionPolicyPath,
+    sshConfigPath,
+    seedDirectory,
+    seedIsoPath,
+    sshKeyPath: sshKey.keyPath,
+    sshPublicKeyPath: sshKey.publicKeyPath,
+    manifestPath,
+  };
 }
 
 export function bootstrapSandboxQemuSetupBundle(
@@ -413,19 +537,13 @@ export function bootstrapSandboxQemuSetupBundle(
   options: SandboxProvisioningOptions,
 ): SandboxQemuSetupBundle {
   const bundle = scaffoldSandboxQemuSetupBundle(manager, workspaceRoot, pathArg, options);
-  manager.setDynamic('sandbox.vmBackend', 'qemu');
-  manager.setDynamic('sandbox.qemuExecWrapper', bundle.wrapperPath);
-  manager.setDynamic('sandbox.qemuImagePath', bundle.imagePath);
+  const manifest = loadSandboxQemuSetupManifest(workspaceRoot, bundle.manifestPath);
+  applySandboxQemuSetupManifest(manager, manifest);
+  manager.setDynamic('sandbox.replIsolation', 'shared-vm');
+  manager.setDynamic('sandbox.mcpIsolation', 'shared-vm');
   return bundle;
 }
 
-export function createSandboxQemuImage(workspaceRoot: string, imagePathArg: string, sizeGb: number): { readonly path: string; readonly sizeGb: number } {
-  const path = resolveWorkspacePath(workspaceRoot, imagePathArg);
-  ensureDir(dirname(path));
-  if (!existsSync(path)) writeFileSync(path, '');
-  return { path, sizeGb };
-}
-
 export function inspectSandboxQemuSetupManifest(manifest: SandboxQemuSetupManifest): string {
   return [
     'QEMU sandbox setup manifest',
@@ -442,6 +560,7 @@ export function loadSandboxQemuSetupManifest(workspaceRoot: string, pathArg: str
 
 export function applySandboxQemuSetupManifest(manager: WritableConfigManagerLike, manifest: SandboxQemuSetupManifest): void {
   manager.setDynamic('sandbox.vmBackend', 'qemu');
+  manager.setDynamic('sandbox.qemuBinary', manifest.recommendedSettings.qemuBinary);
   manager.setDynamic('sandbox.qemuExecWrapper', manifest.recommendedSettings.wrapperPath);
   manager.setDynamic('sandbox.qemuImagePath', manifest.recommendedSettings.imagePath);
   manager.setDynamic('sandbox.qemuGuestHost', manifest.recommendedSettings.guestHost);
@@ -449,6 +568,7 @@ export function applySandboxQemuSetupManifest(manager: WritableConfigManagerLike
   manager.setDynamic('sandbox.qemuGuestUser', manifest.recommendedSettings.guestUser);
   manager.setDynamic('sandbox.qemuWorkspacePath', manifest.recommendedSettings.guestWorkspacePath);
   manager.setDynamic('sandbox.qemuSessionMode', manifest.recommendedSettings.sessionMode);
+  manager.setDynamic('sandbox.replJavaScriptCommand', manifest.recommendedSettings.replJavaScriptCommand);
 }
 
 export function exportSandboxGuestBundle(

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

@@ -0,0 +1,340 @@
+import { resolve } from 'node:path';
+
+function shellSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export function renderQemuWrapperTemplate(): string {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+mode="\${GV_SANDBOX_WRAPPER_MODE:-\${GOODVIBES_QEMU_WRAPPER_MODE:-ssh-guest}}"
+script_dir="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+host="\${GV_SANDBOX_GUEST_HOST:-\${GOODVIBES_QEMU_GUEST_HOST:-127.0.0.1}}"
+port="\${GV_SANDBOX_GUEST_PORT:-\${GOODVIBES_QEMU_GUEST_PORT:-2222}}"
+user="\${GV_SANDBOX_GUEST_USER:-\${GOODVIBES_QEMU_GUEST_USER:-goodvibes}}"
+workspace="\${GV_SANDBOX_GUEST_WORKSPACE:-\${GOODVIBES_QEMU_WORKSPACE:-/workspace}}"
+workspace_root="\${GV_SANDBOX_WORKSPACE_ROOT:-$PWD}"
+qemu_bin="\${GV_SANDBOX_QEMU_BINARY:-\${GOODVIBES_QEMU_BINARY:-qemu-system-x86_64}}"
+qemu_image="\${GV_SANDBOX_QEMU_IMAGE:-\${GOODVIBES_QEMU_IMAGE:-$script_dir/goodvibes-sandbox.qcow2}}"
+ssh_key="\${GV_SANDBOX_SSH_KEY:-\${GOODVIBES_QEMU_SSH_KEY:-$script_dir/keys/goodvibes_qemu_ed25519}}"
+known_hosts="\${GV_SANDBOX_KNOWN_HOSTS:-$script_dir/known_hosts}"
+logs_dir="\${GV_SANDBOX_LOGS_DIR:-$script_dir/logs}"
+run_dir="\${GV_SANDBOX_RUN_DIR:-$script_dir/run}"
+seed_iso="\${GV_SANDBOX_SEED_ISO:-$script_dir/seed/nocloud.iso}"
+ssh_timeout="\${GOODVIBES_QEMU_SSH_TIMEOUT:-300}"
+
+mkdir -p "$logs_dir" "$run_dir"
+
+ssh_opts=(-o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile="$known_hosts" -p "$port")
+if [[ -f "$ssh_key" ]]; then
+  chmod 600 "$ssh_key" 2>/dev/null || true
+  ssh_opts=(-i "$ssh_key" "\${ssh_opts[@]}")
+fi
+
+shell_quote() {
+  printf '%q' "$1"
+}
+
+remote_command() {
+  local remote="export PATH=\\$HOME/.bun/bin:\\$HOME/.deno/bin:\\$HOME/.local/bin:\\$PATH; cd $(shell_quote "$workspace") && exec"
+  for arg in "$@"; do
+    remote+=" $(shell_quote "$arg")"
+  done
+  printf '%s' "$remote"
+}
+
+wait_for_ssh() {
+  local timeout="$1"
+  local start now
+  start="$(date +%s)"
+  while true; do
+    if ssh "\${ssh_opts[@]}" "$user@$host" "true" >/dev/null 2>&1; then
+      return 0
+    fi
+    now="$(date +%s)"
+    if (( now - start >= timeout )); then
+      echo "Timed out waiting for SSH on $host:$port" >&2
+      return 1
+    fi
+    sleep 2
+  done
+}
+
+sync_workspace() {
+  if [[ "\${GV_SANDBOX_SYNC_WORKSPACE:-1}" == "0" ]]; then
+    return 0
+  fi
+  tar -C "$workspace_root" \\
+    --exclude='./.git' \\
+    --exclude='./.goodvibes/tui/sandbox' \\
+    -cf - . \\
+    | ssh "\${ssh_opts[@]}" "$user@$host" "mkdir -p $(shell_quote "$workspace") && tar -C $(shell_quote "$workspace") -xf -"
+}
+
+run_guest_command() {
+  ssh "\${ssh_opts[@]}" "$user@$host" "$(remote_command "$@")"
+}
+
+start_qemu() {
+  if [[ ! -f "$qemu_image" ]]; then
+    echo "QEMU image not found: $qemu_image" >&2
+    return 1
+  fi
+  local pidfile="$run_dir/qemu-$port.pid"
+  local serial_log="$logs_dir/serial-$port.log"
+  local qemu_log="$logs_dir/qemu-$port.log"
+  local monitor_sock="$run_dir/monitor-$port.sock"
+  rm -f "$monitor_sock"
+  if [[ -f "$pidfile" ]]; then
+    local old_pid
+    old_pid="$(<"$pidfile")"
+    if [[ -n "$old_pid" ]] && kill -0 "$old_pid" 2>/dev/null; then
+      return 0
+    fi
+    rm -f "$pidfile"
+  fi
+  local qemu_args=(
+    -display none
+    -serial "file:$serial_log"
+    -monitor "unix:$monitor_sock,server,nowait"
+    -m "\${GOODVIBES_QEMU_MEMORY:-1024}"
+    -smp "\${GOODVIBES_QEMU_CPUS:-2}"
+    -drive "file=$qemu_image,if=virtio,format=qcow2"
+    -netdev "user,id=net0,hostfwd=tcp:127.0.0.1:$port-:22"
+    -device "virtio-net-pci,netdev=net0"
+    -smbios "type=1,serial=ds=nocloud"
+  )
+  if [[ -r "$seed_iso" ]]; then
+    qemu_args+=( -drive "file=$seed_iso,if=virtio,media=cdrom,readonly=on" )
+  fi
+  if [[ -e /dev/kvm && -r /dev/kvm && -w /dev/kvm && "\${GOODVIBES_QEMU_ENABLE_KVM:-1}" != "0" ]]; then
+    qemu_args=( -enable-kvm "\${qemu_args[@]}" )
+  fi
+  "$qemu_bin" "\${qemu_args[@]}" >"$qemu_log" 2>&1 &
+  echo "$!" > "$pidfile"
+}
+
+stop_qemu() {
+  local pidfile="$run_dir/qemu-$port.pid"
+  local pid=""
+  if [[ -f "$pidfile" ]]; then
+    pid="$(<"$pidfile")"
+  fi
+  if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
+    kill "$pid" 2>/dev/null || true
+    for _ in {1..20}; do
+      kill -0 "$pid" 2>/dev/null || break
+      sleep 0.25
+    done
+    kill -9 "$pid" 2>/dev/null || true
+  fi
+  rm -f "$pidfile" "$run_dir/monitor-$port.sock"
+}
+
+if [[ "$mode" == "host-exec" ]]; then
+  exec "$@"
+fi
+
+if [[ "$mode" == "ssh-guest" ]]; then
+  wait_for_ssh "$ssh_timeout"
+  sync_workspace
+  run_guest_command "$@"
+  exit $?
+fi
+
+if [[ "$mode" == "launch-qemu-ssh" ]]; then
+  start_qemu
+  trap stop_qemu EXIT
+  wait_for_ssh "$ssh_timeout"
+  sync_workspace
+  run_guest_command "$@"
+  exit $?
+fi
+
+echo "Unknown GV_SANDBOX_WRAPPER_MODE: $mode" >&2
+exit 2
+`;
+}
+
+export function renderQemuImageCreateScript(directory: string, imagePath: string, sizeGb: number): string {
+  const baseImage = resolve(directory, 'images/debian-12-genericcloud-amd64.qcow2');
+  const seedIso = resolve(directory, 'seed/nocloud.iso');
+  return `#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+BASE_URL="\${GOODVIBES_QEMU_BASE_IMAGE_URL:-https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2}"
+BASE_IMAGE="\${GOODVIBES_QEMU_BASE_IMAGE:-${baseImage}}"
+TARGET_IMAGE="\${1:-${imagePath}}"
+SIZE="\${2:-${sizeGb}G}"
+SEED_DIR="$SCRIPT_DIR/seed"
+SEED_ISO="\${GOODVIBES_QEMU_SEED_ISO:-${seedIso}}"
+
+mkdir -p "$(dirname "$BASE_IMAGE")" "$(dirname "$TARGET_IMAGE")" "$SEED_DIR"
+
+if [[ ! -f "$BASE_IMAGE" ]]; then
+  if command -v curl >/dev/null 2>&1; then
+    curl -fL "$BASE_URL" -o "$BASE_IMAGE"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -O "$BASE_IMAGE" "$BASE_URL"
+  else
+    echo "curl or wget is required to download $BASE_URL" >&2
+    exit 1
+  fi
+fi
+
+cp "$BASE_IMAGE" "$TARGET_IMAGE"
+qemu-img resize "$TARGET_IMAGE" "$SIZE" >/dev/null
+
+if command -v xorriso >/dev/null 2>&1; then
+  ( cd "$SEED_DIR" && xorriso -as mkisofs -quiet -output "$SEED_ISO" -volid CIDATA -joliet -rock user-data meta-data network-config )
+elif command -v genisoimage >/dev/null 2>&1; then
+  ( cd "$SEED_DIR" && genisoimage -quiet -output "$SEED_ISO" -volid CIDATA -joliet -rock user-data meta-data network-config )
+elif command -v mkisofs >/dev/null 2>&1; then
+  ( cd "$SEED_DIR" && mkisofs -quiet -output "$SEED_ISO" -volid CIDATA -joliet -rock user-data meta-data network-config )
+else
+  echo "xorriso, genisoimage, or mkisofs is required to build $SEED_ISO" >&2
+  exit 1
+fi
+
+chmod 600 "$SCRIPT_DIR/keys/goodvibes_qemu_ed25519" 2>/dev/null || true
+echo "QEMU image ready: $TARGET_IMAGE"
+echo "NoCloud seed ready: $SEED_ISO"
+`;
+}
+
+export function renderQemuGuestBootstrapScript(): string {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+export DEBIAN_FRONTEND=noninteractive
+
+sudo apt-get update
+sudo apt-get install -y \\
+  ca-certificates \\
+  curl \\
+  wget \\
+  git \\
+  jq \\
+  tar \\
+  unzip \\
+  xz-utils \\
+  build-essential \\
+  python3 \\
+  python3-pip \\
+  python3-venv \\
+  nodejs \\
+  npm \\
+  sqlite3 \\
+  postgresql-client \\
+  mariadb-client \\
+  openssh-server \\
+  ripgrep \\
+  fd-find \\
+  shellcheck \\
+  make \\
+  pkg-config \\
+  libssl-dev \\
+  python3-dev \\
+  golang \\
+  cargo \\
+  ruby \\
+  ruby-dev
+
+if command -v fdfind >/dev/null 2>&1 && ! command -v fd >/dev/null 2>&1; then
+  sudo ln -sf /usr/bin/fdfind /usr/local/bin/fd
+fi
+
+if command -v npm >/dev/null 2>&1; then
+  sudo npm install -g typescript tsx ts-node graphql || true
+  sudo npm install -g graphql-cli || true
+fi
+
+if [[ "\${GOODVIBES_QEMU_INSTALL_BUN:-1}" == "1" ]]; then
+  curl -fsSL https://bun.sh/install | bash || true
+fi
+
+if [[ "\${GOODVIBES_QEMU_INSTALL_DENO:-1}" == "1" ]]; then
+  curl -fsSL https://deno.land/install.sh | sh || true
+fi
+
+if [[ "\${GOODVIBES_QEMU_INSTALL_UV:-1}" == "1" ]]; then
+  curl -LsSf https://astral.sh/uv/install.sh | sh || true
+fi
+
+if [[ "\${GOODVIBES_QEMU_INSTALL_DUCKDB:-1}" == "1" ]]; then
+  curl https://install.duckdb.org | sh || true
+fi
+
+if [[ -x "$HOME/.bun/bin/bun" ]]; then
+  sudo ln -sf "$HOME/.bun/bin/bun" /usr/local/bin/bun
+fi
+if [[ -x "$HOME/.deno/bin/deno" ]]; then
+  sudo ln -sf "$HOME/.deno/bin/deno" /usr/local/bin/deno
+fi
+if [[ -x "$HOME/.local/bin/uv" ]]; then
+  sudo ln -sf "$HOME/.local/bin/uv" /usr/local/bin/uv
+fi
+if [[ -x "$HOME/.duckdb/cli/latest/duckdb" ]]; then
+  sudo ln -sf "$HOME/.duckdb/cli/latest/duckdb" /usr/local/bin/duckdb
+fi
+
+grep -qxF 'export PATH="$HOME/.bun/bin:$HOME/.deno/bin:$HOME/.local/bin:$PATH"' "$HOME/.profile" 2>/dev/null \\
+  || echo 'export PATH="$HOME/.bun/bin:$HOME/.deno/bin:$HOME/.local/bin:$PATH"' >> "$HOME/.profile"
+
+mkdir -p /workspace
+sudo chown goodvibes:goodvibes /workspace
+
+echo "GoodVibes guest bootstrap complete."
+`;
+}
+
+export function renderQemuSetupReadme(directory: string, imagePath: string, seedIsoPath: string): string {
+  return `GoodVibes QEMU sandbox bootstrap bundle
+
+Host prerequisites:
+  qemu-system-x86_64 qemu-img ssh ssh-keygen curl-or-wget xorriso-or-genisoimage
+  KVM is optional but strongly recommended: /dev/kvm
+
+Generated files:
+  qemu-wrapper.sh                         launch/attach wrapper used by GoodVibes
+  create-image.sh                         downloads Debian 12 cloud image, clones it, resizes it, builds NoCloud ISO
+  guest-bootstrap.sh                      run inside the guest to install REPL/MCP-friendly runtimes
+  keys/goodvibes_qemu_ed25519             SSH key for goodvibes guest user
+  seed/user-data                          cloud-init user/bootstrap config
+  seed/meta-data                          cloud-init identity
+  seed/network-config                     cloud-init ens3 DHCP config
+  seed/nocloud.iso                        generated cloud-init ISO
+  logs/                                   QEMU and serial logs
+  run/                                    pid/socket runtime files
+
+First-run workflow:
+  1. Run: ${shellSingleQuote(resolve(directory, 'create-image.sh'))} ${shellSingleQuote(imagePath)} 20G
+  2. GoodVibes settings should point to:
+       sandbox.vmBackend = qemu
+       sandbox.qemuBinary = qemu-system-x86_64
+       sandbox.qemuImagePath = ${imagePath}
+       sandbox.qemuExecWrapper = ${resolve(directory, 'qemu-wrapper.sh')}
+       sandbox.qemuGuestHost = 127.0.0.1
+       sandbox.qemuGuestPort = 2222
+       sandbox.qemuGuestUser = goodvibes
+       sandbox.qemuWorkspacePath = /workspace
+       sandbox.qemuSessionMode = launch-per-command
+       sandbox.replJavaScriptCommand = /home/goodvibes/.bun/bin/bun
+  3. Provision guest runtimes:
+       GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh ${shellSingleQuote(resolve(directory, 'qemu-wrapper.sh'))} bash -s < ${shellSingleQuote(resolve(directory, 'guest-bootstrap.sh'))}
+  4. Run: /sandbox guest-test eval-py
+
+Guest runtimes installed by guest-bootstrap.sh:
+  python3, pip, venv, nodejs, npm, typescript, tsx, ts-node, sqlite3,
+  postgresql-client, mariadb-client, GraphQL tools, Bun, Deno, uv,
+  DuckDB, Go, Rust/Cargo, Ruby, ripgrep, fd, shellcheck, make, pkg-config,
+  libssl-dev, and python3-dev.
+
+Debugging:
+  serial log: ${resolve(directory, 'logs/serial-2222.log')}
+  qemu log:   ${resolve(directory, 'logs/qemu-2222.log')}
+  seed ISO:   ${seedIsoPath}
+
+The wrapper accepts GOODVIBES_QEMU_SSH_TIMEOUT, defaulting to 300 seconds, because first boot cloud-init can be slow.
+`;
+}

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.19.99';
+let _version = '0.20.0';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8'));
   _version = pkg.version ?? _version;