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

package/dist/runners/windows-guest.js

@@ -0,0 +1,213 @@
+// runners/windows-guest.ts — the guest side of the Windows step 3
+// (VMware + QEMU backends): the credentials (from the image's vars file,
+// WINDOWS_PASSWORD override, the sshd port — 22 direct, the hostfwd port
+// behind QEMU), the PowerShell transport over the ssh2 session (utf16le
+// base64 → -EncodedCommand, the expect guest_ps port) and the wiring of
+// the bundled guest-agent-windows.js (upload over SFTP → install →
+// status → docker info verification). Only the host alias differs
+// (10.0.2.2 vs the NAT router x.y.z.1).
+//
+// Every PowerShell command is wrapped with a completion sentinel: the
+// Windows OpenSSH channel does not close when the guest session's command
+// finishes (the guest relays and OpenChamber hold the console handles),
+// so the exec ends early when the sentinel arrives — the shell's
+// `echo $sentinel` + kill-ssh-client trick, now in lib/ssh.ts.
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { varsFor, resolveImage } from '../lifecycle/catalog.js';
+import { sleep } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { parseGuestStatus } from './ubuntu-guest.js';
+/** The guest's agent install dir (image-fixed C:\tools), SFTP style. */
+const GUEST_AGENT_DIR_WS = 'C:/tools/agent-dev-env';
+/** The guest's agent install dir, PowerShell style. */
+const GUEST_AGENT_DIR_PS = 'C:\\tools\\agent-dev-env';
+/** The absolute guest-agent path, PowerShell style. */
+const GUEST_AGENT_PS = `${GUEST_AGENT_DIR_PS}\\guest-agent-windows.js`;
+/** The guest's sshd port (fixed in the image; the VMware backends reach
+ *  it directly, the QEMU backend through the hostfwd forward). */
+const GUEST_SSH_PORT = 22;
+/** The bundled Windows guest agent (single-file, node-only). */
+function guestAgentPath() {
+    return fileURLToPath(new URL('../assets/guest/guest-agent-windows.js', import.meta.url));
+}
+/** @internal — resolves the guest credentials from the image's vars file
+ *  (+ WINDOWS_PASSWORD override). Pure so the fallbacks are testable.
+ *
+ * @param vars - The vars file values.
+ * @param env - Environment (WINDOWS_PASSWORD).
+ * @param ip - The guest IP (the hostfwd loopback for QEMU).
+ * @param sshPort - The sshd port to reach (guest 22; the forwarded host
+ *   port when the guest sits behind QEMU's hostfwd).
+ * @returns The credentials.
+ * @throws Error when no winrm_password is available.
+ */
+export function guestCredentials(vars, env, ip, sshPort = GUEST_SSH_PORT) {
+    const username = typeof vars.winrm_username === 'string' && vars.winrm_username.trim()
+        ? vars.winrm_username
+        : 'Administrator';
+    const password = env.WINDOWS_PASSWORD ?? (typeof vars.winrm_password === 'string' ? vars.winrm_password : '');
+    if (!password) {
+        throw new Error('could not read winrm_password from the vars file — set WINDOWS_PASSWORD to the guest password.');
+    }
+    return { host: ip, port: sshPort, username, password };
+}
+/** The credentials for the current run (image vars + env + guest IP).
+ *
+ * @param image - The image name.
+ * @param env - Environment.
+ * @param ip - The guest IP (the hostfwd loopback for QEMU).
+ * @param sshPort - The sshd port to reach (guest 22; the forwarded host
+ *   port when the guest sits behind QEMU's hostfwd).
+ * @returns The credentials.
+ */
+export function resolveGuestCredentials(image, env, ip, sshPort = GUEST_SSH_PORT) {
+    return guestCredentials(varsFor(resolveImage(image)), env, ip, sshPort);
+}
+/** @internal — strips the trailing output after the completion sentinel
+ *  (the guest's background relays keep trickling output past it).
+ *
+ * @param output - The raw exec stdout.
+ * @param sentinel - The sentinel the remote command echoed.
+ * @returns The output up to (and excluding) the sentinel.
+ */
+export function stripSentinel(output, sentinel) {
+    const index = output.indexOf(sentinel);
+    return index === -1 ? output : output.slice(0, index);
+}
+/** @internal — the -EncodedCommand payload: UTF-16LE base64 (the legacy
+ *  `iconv -f UTF-8 -t UTF-16LE | base64` port; --encoded-command decodes
+ *  UTF-16 regardless of BOM). Exported for the co-located test only.
+ *
+ * @param script - The PowerShell script (ASCII).
+ * @returns The base64 string.
+ */
+export function encodePsCommand(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}
+/** Runs a PowerShell snippet in the guest (the expect guest_ps port:
+ *  UTF-16LE base64 via -EncodedCommand, so quoting stays sane; the
+ *  completion sentinel ends the exec early, because the Windows OpenSSH
+ *  channel never closes on its own once the guest relays hold the console
+ *  handles). The snippet MUST be ASCII-only (the packed-agents rule).
+ *
+ * @param session - The connected guest session.
+ * @param script - The PowerShell script (ASCII).
+ * @param timeoutMs - Hard budget for the whole command (5 min default,
+ *   like the perl alarm in the shell).
+ * @returns The script's stdout (pre-sentinel; errors land on stderr).
+ */
+export async function psExec(session, script, timeoutMs = 300_000) {
+    const b64 = encodePsCommand(script);
+    const sentinel = `ade-${randomBytes(8).toString('hex')}`;
+    const command = `powershell -NoProfile -NonInteractive -EncodedCommand ${b64} ; ` + `Write-Output ${sentinel}`;
+    const res = await session.exec(command, { sentinel, timeoutMs });
+    return { stdout: stripSentinel(res.stdout, sentinel), stderr: res.stderr };
+}
+/** Reports the path of the node binary inside the guest (the image ships
+ *  node; resolve once per session like the other backends).
+ *
+ * @param session - The connected guest session.
+ * @returns The node path, or undefined when not found.
+ */
+export async function findGuestNode(session) {
+    const script = [
+        '$p = where.exe node 2>$null | Select-Object -First 1',
+        'if ($p) { Write-Output $p }',
+    ].join('\n');
+    const res = await psExec(session, script, 20_000);
+    const node = res.stdout.trim().split('\n')[0] ?? '';
+    return node ? node : undefined;
+}
+/** Uploads the bundled guest agent and runs `install` (idempotent:
+ *  schtasks re-registered + the env/docker-context setup + the immediate
+ *  relay start, persisted as ONLOGON tasks). The install writes
+ *  start-relays.cmd into C:\tools, so the agent dir is created first.
+ *
+ * @param session - The connected guest session.
+ * @param node - The guest's node binary.
+ * @param hostAlias - The NAT host address the bridges point at.
+ * @param context - The run context (ports).
+ */
+export async function ensureGuestAgent(session, node, hostAlias, context) {
+    const mkdir = await psExec(session, `New-Item -ItemType Directory -Force '${GUEST_AGENT_DIR_PS}' | Out-Null`, 30_000);
+    if (mkdir.stderr.trim()) {
+        logger.warn(`could not prepare the guest agent dir: ${mkdir.stderr.trim()}`);
+        return;
+    }
+    try {
+        await session.sftpWrite(`${GUEST_AGENT_DIR_WS}/guest-agent-windows.js`, readFileSync(guestAgentPath()));
+    }
+    catch (err) {
+        logger.warn(`could not upload the guest agent: ${err.message}`);
+        return;
+    }
+    const install = await psExec(session, `& "${node}" "${GUEST_AGENT_PS}" install --agent-port ${context.agentPort} ` +
+        `--docker-port ${context.dockerPort} --host-alias ${hostAlias}`, 120_000);
+    if (!install.stdout.includes('installed:')) {
+        logger.warn(`guest agent install failed (${install.stderr.trim() || 'no status line'}).`);
+        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. The pipes need a moment after `install` starts the relays
+ *  (schtasks /Run), so the status is polled a few times; the Windows
+ *  OpenSSH channel never reports the remote exit code, so the outcome is
+ *  purely stdout-based (the legacy's `grep bridge-status: | tail -1`).
+ *
+ * @param session - The connected guest session.
+ * @param state - The accumulated run state.
+ * @param node - The guest's node binary.
+ * @param tries - Poll attempts (6 = up to ~15 s at 3 s apart).
+ */
+export async function readGuestStatus(session, state, node, tries = 6) {
+    for (let attempt = 0; attempt < tries; attempt += 1) {
+        const res = await psExec(session, `& "${node}" "${GUEST_AGENT_PS}" status`, 20_000);
+        const status = parseGuestStatus(res.stdout);
+        const anyKnown = status.sshAgent !== undefined || status.docker !== undefined;
+        if (anyKnown) {
+            if (status.sshAgent !== undefined) {
+                state.bridges.agent.guestUp = status.sshAgent;
+            }
+            if (status.docker !== undefined) {
+                state.bridges.docker.guestUp = status.docker;
+            }
+            // Both roles we expect are reported — no need to keep polling.
+            if (status.sshAgent !== undefined && status.docker !== undefined) {
+                return;
+            }
+        }
+        if (attempt < tries - 1) {
+            await sleep(3000);
+        }
+    }
+}
+/** End-to-end check: can the guest's docker CLI reach the host engine
+ *  through the bridge? The probe loop runs inside one guest script (the
+ *  legacy guest-setup's 20 x 1 s docker retry).
+ *
+ * @param session - The connected guest session.
+ * @param state - The accumulated run state.
+ */
+export async function verifyGuestDocker(session, state) {
+    const script = [
+        '$v = $null',
+        'for ($i = 0; $i -lt 20 -and -not $v; $i++) {',
+        '  Start-Sleep -Milliseconds 1000',
+        "  $v = docker info --format '{{.ServerVersion}}' 2>$null",
+        '}',
+        'if ($v) { Write-Output "docker-ok:$v" } else { Write-Output \'docker-fail\' }',
+    ].join('\n');
+    const res = await psExec(session, script, 60_000);
+    const match = /^docker-(ok|fail):?([^\r\n]*)$/m.exec(res.stdout.trim());
+    if (match?.[1] === 'ok') {
+        state.bridges.docker.serverVersion = match[2] ?? '';
+        state.bridges.docker.engineUp = true;
+        logger.ok(`Docker engine is reachable from the guest (server version ${state.bridges.docker.serverVersion}).`);
+        return;
+    }
+    logger.warn('Docker engine not reachable from the guest yet — is it running on the host?');
+    logger.warn('The bridge reconnects on its own once it is; re-run to re-check.');
+}

package/dist/runners/windows-image.js

@@ -0,0 +1,23 @@
+// runners/windows-image.ts — step 1 for the Windows VMware backend: the
+// windows-vmware binding of the shared VMware image flow
+// (vmware-image.ts). The shared module holds the archive pick/extract,
+// the base clone + the display name + the one-time hardware upgrade;
+// this wrapper only binds the platform id and the WINDOWS_VMWARE_IMAGE
+// override var.
+import { ensureVmwareImage, vmwareWorkingVmx } from './vmware-image.js';
+/** The platform id for the VMware path helpers. */
+const PLATFORM = 'windows-vmware';
+/** The working clone's vmx. */
+export function windowsWorkingVmx(image) {
+    return vmwareWorkingVmx(PLATFORM, image);
+}
+/** Step 1: select the archive, extract the base, clone the working VM
+ *  and upgrade it if the installed Fusion supports a newer hardware
+ *  version.
+ *
+ * @param context - The run context.
+ * @param state - The accumulated run state (imageArchive set here).
+ */
+export async function ensureWindowsImage(context, state) {
+    return ensureVmwareImage(PLATFORM, 'WINDOWS_VMWARE_IMAGE', context, state);
+}

package/dist/runners/windows-qemu-summary.js

@@ -0,0 +1,85 @@
+// runners/windows-qemu-summary.ts — the Windows QEMU "Sandbox is ready"
+// block (port of the shell's print_summary in
+// run-windows-qemu-sandbox.sh: same labels, same wording, same color
+// scheme — with the CLI's 12-char label column, like the other
+// summaries). The QEMU guest is reached through the hostfwd forwards on
+// 127.0.0.1, unlike the VMware backends' direct guest-IP lines.
+import { logger } from '../lib/logger.js';
+import { qemuLogPath, qemuPidFile, qemuStateDir } from '../lib/qemu.js';
+import { resolveGuestCredentials } from './windows-guest.js';
+/** Prints the QEMU Windows summary block (image/SSH/RDP/WinRM/bridges/
+ *  OpenChamber/state/stop hints).
+ *
+ * @param context - The run context.
+ * @param state - The accumulated run state.
+ */
+export async function printQemuSummary(context, state) {
+    const creds = resolveGuestCredentials(context.image, context.options.env, '127.0.0.1', context.sshPort);
+    logger.step('Sandbox is ready');
+    summaryLine('Image:', state.imageArchive ?? 'not available');
+    summaryLine('SSH:', `ssh -p ${context.sshPort} ${creds.username}@127.0.0.1 (password: ${creds.password})`);
+    summaryLine('RDP:', `127.0.0.1:${context.rdpPort} (${creds.username} / ${creds.password})`);
+    summaryLine('WinRM:', `127.0.0.1:${context.winrmPort} (advanced use)`);
+    printBridgeLines(context, state);
+    printOpenchamberLine(context, state);
+    summaryLine('State:', `${qemuStateDir(context.image)} (overlay + TPM + EFI NVRAM; --reset wipes it)`);
+    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 \\\\.\\pipe\\openssh-ssh-agent`
+            : `host bridge up (TCP ${context.agentPort}), guest pipe 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 pipe not running`));
+        }
+    }
+    else {
+        summaryLine('Docker:', 'not bridged');
+    }
+}
+function printOpenchamberLine(context, state) {
+    if (state.openchamberUp && state.openchamberUrl) {
+        summaryLine('OpenChamber:', loggerOk(`${state.openchamberUrl} (password: sandbox)`));
+    }
+    else {
+        summaryLine('OpenChamber:', loggerWarn(`not responding on http://127.0.0.1:${context.openchamberPort}`));
+    }
+}
+function printStopLines(context, state) {
+    summaryLine('Stop:', `agent-dev-env stop windows-qemu (or: kill $(cat ${qemuPidFile(context.image)}))`);
+    if (!context.options.foreground) {
+        summaryLine('Background:', `VM keeps running after this CLI exits (qemu log: ${qemuLogPath()})`);
+        if (state.bridges.agent.bridged) {
+            summaryLine('Bridge:', `host bridge on TCP ${context.agentPort} stays up — stop it with: agent-dev-env stop windows-qemu`);
+        }
+        if (state.bridges.docker.bridged) {
+            summaryLine('Bridge:', `host Docker bridge on TCP ${context.dockerPort} stays up — stop it with: agent-dev-env stop windows-qemu`);
+        }
+    }
+}
+// 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/windows-qemu.js

@@ -0,0 +1,189 @@
+// runners/windows-qemu.ts — the Windows 11 (ARM64) QEMU backend (Phase 6
+// of the port): qemu-system-aarch64 drives the qcow2 disk with swtpm
+// (lib/qemu.ts: overlay + TPM + EFI NVRAM + the exact launch_qemu args),
+// the guest is reached through the hostfwd forwards on 127.0.0.1, the
+// one-time auto-logon (windows-autologon.ts) so OpenChamber fires at
+// boot, the hostfwd bridges + the same guest agent wiring over ssh2
+// (windows-bridges.ts / windows-guest.ts) and the summary. Port of
+// run-windows-qemu-sandbox.sh §steps 0-5.
+import { rmSync } from 'node:fs';
+import { isAlive, sleep } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { confirmDefault } from '../lib/prompt.js';
+import { buildQemuArgs, isQemuAlive, launchQemu, QEMU_EFI_CODE, qemuEfivarsPath, qemuOverlayPath, qemuStateDir, requireQemu, startSwtpm, stopQemu, stopSwtpm, swtpmSockPath, } from '../lib/qemu.js';
+import { probeSshd, waitForSshd } from '../lib/ssh.js';
+import { ensureBridgeDir } from './bridges.js';
+import { offerOpenInBrowser, waitForOpenchamber } from './openchamber.js';
+import { ensureQemuImage } from './qemu-image.js';
+import { cleanupRunBridge } from './vmware-common.js';
+import { windowsBridges } from './windows-bridges.js';
+import { configureAutologon } from './windows-autologon.js';
+import { resolveGuestCredentials } from './windows-guest.js';
+import { printQemuSummary } from './windows-qemu-summary.js';
+const PLATFORM = 'windows-qemu';
+/** The QEMU Windows backend — qemu-system-aarch64 + swtpm + ssh2 (the
+ *  state lives under the CLI's data dir, like the VMware backends).
+ */
+export const windowsQemuBackend = {
+    preflight: (context) => preflight(context),
+    ensureImageAndVm: (context, state) => ensureQemuImage(context, state),
+    boot: boot,
+    setupBridges: (context, state) => windowsBridges(context, state),
+    setupSettings: (context, state) => setupSettings(context, state),
+    verifyOpenchamber: (context, state) => verifyOpenchamber(context, state),
+    summarize: (context, state) => printQemuSummary(context, state),
+    finish: finish,
+};
+async function preflight(context) {
+    requireQemu();
+    ensureBridgeDir();
+    if (context.options.reset) {
+        const root = qemuStateDir(context.image);
+        logger.info('Resetting the working VM (--reset) — deleting the overlay, TPM state, and EFI NVRAM.');
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+// --- step 2: boot -----------------------------------------------------------
+async function boot(context, state) {
+    await stopRunningQemu(context);
+    await startSwtpm(context.image);
+    const args = buildQemuArgs({
+        efiCode: QEMU_EFI_CODE,
+        efivars: qemuEfivarsPath(context.image),
+        overlay: qemuOverlayPath(context.image),
+        tpmSock: swtpmSockPath(context.image),
+        sshPort: context.sshPort,
+        rdpPort: context.rdpPort,
+        openchamberPort: context.openchamberPort,
+        winrmPort: context.winrmPort,
+        cpuCount: context.cpuCount,
+        memoryMb: context.memoryMb,
+        headless: context.options.headless,
+    });
+    state.qemuPid = await launchQemu(context.image, args);
+    const creds = resolveGuestCredentials(context.image, context.options.env, '127.0.0.1', context.sshPort);
+    await waitForQemuBoot(creds, state.qemuPid);
+    await ensureQemuAutologon(context, creds);
+}
+/** Stops a qemu left running by a previous (detached) run — the old qemu
+ *  holds the overlay and its swtpm holds the TPM state lock. The legacy
+ *  stop_running_vm: restart confirm defaults to no (checked via the
+ *  pidfile, since a previous run's qemu predates this run's state).
+ */
+async function stopRunningQemu(context) {
+    if (!isQemuAlive(context.image)) {
+        return;
+    }
+    if (!(await confirmDefault('The sandbox VM is already running — restart it?', {
+        default: 'n',
+        yes: context.options.yes,
+    }))) {
+        logger.die(`aborted — the VM is already running. Stop it with: agent-dev-env stop ${PLATFORM}`);
+    }
+    await stopQemu(context.image);
+    await sleep(1000);
+}
+/** The sshd wait with the qemu-alive check (the legacy wait_for_sshd:
+ *  the hostfwd listener binds the moment qemu starts, before the guest
+ *  even boots — probe for a real sshd instead of the port).
+ */
+async function waitForQemuBoot(creds, qemuPid) {
+    process.stdout.write('    Waiting for the VM to boot (up to 10 min)');
+    for (let attempt = 0; attempt < 150; attempt += 1) {
+        if (!isAlive(qemuPid)) {
+            process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+            logger.die(`qemu exited before the VM booted — check the qemu log.`);
+        }
+        if ((await probeSshd(creds)) === 'up') {
+            process.stdout.write(` ${logger.color('green')}done${logger.reset()}\n`);
+            logger.ok(`VM is up: ssh ${creds.username}@127.0.0.1:${creds.port}`);
+            return;
+        }
+        if (attempt < 149) {
+            await sleep(4000);
+        }
+    }
+    process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+    logger.die(`timed out waiting for the VM to boot (no SSH on 127.0.0.1:${creds.port}).`);
+}
+/** The QEMU auto-logon: configure, then wait for sshd on the same
+ *  hostfwd target (the guest IP never changes — unlike the VMware flow,
+ *  no guest-IP refresh is needed).
+ */
+async function ensureQemuAutologon(context, creds) {
+    if (!(await configureAutologon(context, creds))) {
+        return;
+    }
+    logger.info('Rebooting the guest (a minute or two)...');
+    process.stdout.write('    Waiting for the guest to reboot (up to 10 min)');
+    if (await waitForSshd(creds)) {
+        process.stdout.write(` ${logger.color('green')}done${logger.reset()}\n`);
+        logger.ok('Guest rebooted with auto-logon enabled.');
+    }
+    else {
+        process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+        logger.die(`timed out waiting for the guest to reboot (no SSH on 127.0.0.1:${creds.port}).`);
+    }
+}
+// --- step 4/5 hooks ---------------------------------------------------------
+async function setupSettings(context, state) {
+    logger.info('Windows guests have no user settings copy — skipping.');
+    state.settings = 'skipped';
+}
+async function verifyOpenchamber(context, state) {
+    state.openchamberUrl = `http://127.0.0.1:${context.openchamberPort}`;
+    state.openchamberUp = await waitForOpenchamber(state.openchamberUrl);
+    if (state.openchamberUp) {
+        await offerOpenInBrowser(state.openchamberUrl, context.options.yes);
+    }
+}
+// --- finish: foreground wait + bridge/swtpm cleanup --------------------------
+async function finish(context, state) {
+    if (!context.options.foreground) {
+        return;
+    }
+    await waitForQemuStop(state.qemuPid ?? -1);
+    // The VM stopped (or Cmd+C was pressed) — kill the bridges this run
+    // started and swtpm (it holds the TPM state lock); in background mode
+    // they stay up, outliving the CLI by design.
+    await cleanupRunBridge(state.bridges.agent.pid, 'agent bridge');
+    await cleanupRunBridge(state.bridges.docker.pid, 'Docker bridge');
+    await stopSwtpm(context.image);
+}
+/** The foreground wait: poll qemu until it exits; a Cmd+C stops it
+ *  through a SIGTERM (the shell's EXIT trap killed qemu with the script
+ *  group; we own the detached child, so kill it explicitly).
+ */
+async function waitForQemuStop(qemuPid) {
+    if (!isAlive(qemuPid)) {
+        logger.info('VM is not running.');
+        return;
+    }
+    let stopping = false;
+    const onSignal = () => {
+        if (stopping) {
+            return;
+        }
+        stopping = true;
+        logger.info('Stopping the VM (Cmd+C)...');
+        try {
+            process.kill(qemuPid, 'SIGTERM');
+        }
+        catch {
+            // already gone
+        }
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    logger.info('Waiting for the VM to stop (Cmd+C to stop it now)...');
+    try {
+        while (isAlive(qemuPid)) {
+            await sleep(3000);
+        }
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+    }
+    logger.info('VM stopped.');
+}

package/dist/runners/windows-shared.js

@@ -0,0 +1,68 @@
+// runners/windows-shared.ts — step 4 for the Windows backend: the shared
+// host directory over HGFS (best-effort, like the Ubuntu backend). VMware
+// Tools for Windows Arm ships no HGFS driver, so Windows 11 ARM guests on
+// Apple silicon can never mount the share — detected via the vmx guestos
+// string and skipped with a warning (the legacy hgfs_unsupported). The
+// vmrun registration path is kept for parity: a share registered by a
+// previous run persists in the vmx.
+import { existsSync, readFileSync } from 'node:fs';
+import { logger } from '../lib/logger.js';
+import { enableSharedFolders, isVmRunning } from '../lib/vmrun.js';
+import { addSharedFolderRetry, waitForTools } from './vmware-common.js';
+/** @internal — whether the VM's guest os string is an ARM Windows guest
+ *  (VMware Tools for Windows Arm has no HGFS driver — the guest can never
+ *  mount \\vmware-host\Shared Folders\work even when the host publishes
+ *  it). Pure for the co-located test.
+ *
+ * @param vmxContent - The raw vmx text.
+ * @returns True when the guest cannot mount HGFS shares.
+ */
+export function hgfsUnsupported(vmxContent) {
+    return /^[ \t]*guestos[ \t]*=[ \t]*"arm-/m.test(vmxContent);
+}
+/** The shared-folder step: skipped with the platform warning for ARM
+ *  guests; otherwise the vmrun register + enable flow with the tools
+ *  gate. Failures warn only — the sandbox works without the share.
+ *
+ * @param context - The run context (workDir).
+ * @param state - The accumulated run state (sharedFolderSkipped).
+ * @param workVmx - The working VM vmx.
+ */
+export async function setupWindowsSharedFolder(context, state, workVmx) {
+    if (!context.workDir) {
+        return;
+    }
+    let vmxContent = '';
+    try {
+        vmxContent = readFileSync(workVmx, 'utf8');
+    }
+    catch {
+        // no vmx — nothing to share; the running check below reports.
+    }
+    if (vmxContent && hgfsUnsupported(vmxContent)) {
+        state.sharedFolderSkipped = true;
+        logger.warn('shared host folder not supported: VMware Tools for Windows 11 ARM guests on ' +
+            'Apple silicon has no HGFS driver, so the guest can never see ' +
+            '\\\\vmware-host\\Shared Folders\\work.');
+        logger.warn('use an alternative instead (SMB share from the Mac, SSH/SCP, RDP clipboard, git) ' +
+            '— see docs/windows-vmware.md.');
+        return;
+    }
+    if (!existsSync(context.workDir)) {
+        logger.warn(`work directory '${context.workDir}' does not exist — skipping the shared-directory share.`);
+        return;
+    }
+    if (!(await isVmRunning(workVmx))) {
+        logger.warn('shared folder skipped — the VM is not running.');
+        return;
+    }
+    logger.info(`Sharing ${context.workDir} into the guest as 'work' ` +
+        '(\\\\vmware-host\\Shared Folders\\work).');
+    if (!(await waitForTools(workVmx))) {
+        logger.warn('VMware Tools did not report running — skipping the shared-directory share (re-run to retry).');
+        return;
+    }
+    await addSharedFolderRetry(workVmx, 'work', context.workDir);
+    await enableSharedFolders(workVmx);
+    logger.ok('Shared folder registered (best-effort — HGFS must be enabled by VMware Tools).');
+}