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

package/dist/runners/qemu-image.js

@@ -0,0 +1,183 @@
+// runners/qemu-image.ts — step 1 for the Windows QEMU backend: pick the
+// pristine qcow2 (WINDOWS_IMAGE → local build output → cached pull →
+// oras pull with the owner chain — the same precedence as the VMware
+// backends' pickImage), then create the working VM state: a COW overlay
+// over the pristine image (identity-marker gated so a rebuild over the
+// same path drops the stale overlay), the persistent TPM state dir and
+// the EFI NVRAM store (seeded from the build output's efivars.fd or the
+// Homebrew edk2 template). Port of run-windows-qemu-sandbox.sh
+// §step 1/2 (pick_image + ensure_working_vm).
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { commandExists, run } from '../lib/exec.js';
+import { registryRef, resolveOwner } from '../lib/ghcr.js';
+import { logger } from '../lib/logger.js';
+import { buildDir } from '../lib/paths.js';
+import { confirmDefault } from '../lib/prompt.js';
+import { backingIdentity, QEMU_EFI_VARS_TEMPLATE, qemuBackingMarker, qemuEfivarsPath, qemuImagePath, qemuOverlayPath, qemuTpmDir, } from '../lib/qemu.js';
+/** The env var holding a local qcow2 override (the legacy WINDOWS_IMAGE). */
+const IMAGE_OVERRIDE_ENV = 'WINDOWS_IMAGE';
+/** Step 1: select the pristine qcow2 and create the working VM state.
+ *
+ * @param context - The run context.
+ * @param state - The accumulated run state (imageArchive = disk path).
+ */
+export async function ensureQemuImage(context, state) {
+    const disk = await pickQemuImage(context);
+    state.imageArchive = disk;
+    logger.ok(`Using image: ${disk}`);
+    await ensureWorkingVm(context, disk);
+}
+/** The shell's pick_image: WINDOWS_IMAGE → local build output → cached
+ *  pull → oras pull (confirm + owner chain).
+ *
+ * @param context - The run context.
+ * @returns The qcow2 path to run.
+ */
+async function pickQemuImage(context) {
+    const env = context.options.env;
+    const image = context.image;
+    const override = env[IMAGE_OVERRIDE_ENV];
+    if (override) {
+        if (!existsSync(override)) {
+            logger.die(`${IMAGE_OVERRIDE_ENV} points to a file that does not exist: ${override}`);
+        }
+        return override;
+    }
+    const local = join(buildDir('windows-qemu'), 'output', `${image}.qcow2`);
+    if (existsSync(local)) {
+        return local;
+    }
+    const cached = qemuImagePath(image);
+    if (existsSync(cached)) {
+        return cached;
+    }
+    return pullQemuImage(context, cached);
+}
+/** The oras pull into the image/ cache dir (owner chain + confirm +
+ *  disk presence check).
+ *
+ * @param context - The run context.
+ * @param cached - The destination qcow2 path.
+ * @returns The pulled qcow2 path.
+ */
+async function pullQemuImage(context, cached) {
+    if (!commandExists('oras')) {
+        logger.die('oras is not installed — needed to pull the image (brew install oras). ' +
+            `Set ${IMAGE_OVERRIDE_ENV} to a local qcow2 to skip.`);
+    }
+    const owner = await resolveOwner({ owner: context.options.owner, env: context.options.env });
+    const ref = registryRef(context.image, 'latest', owner);
+    if (!(await confirmDefault(`Pull ${ref} (one-time, ~14 GB download)?`, {
+        default: 'y',
+        yes: context.options.yes,
+    }))) {
+        logger.die(`aborted — no sandbox image available. Set ${IMAGE_OVERRIDE_ENV} to a local qcow2 or pull manually.`);
+    }
+    mkdirSync(dirname(cached), { recursive: true });
+    logger.info(`Pulling ${ref} (one-time, ~14 GB download)...`);
+    const res = await run('oras', ['pull', ref], { cwd: dirname(cached) });
+    if (res.code !== 0) {
+        logger.die('oras pull failed — check your network connection (public GHCR images pull without a login).');
+    }
+    if (!existsSync(cached)) {
+        logger.die(`oras pull produced no ${cached} — is the image published under ${ref}?`);
+    }
+    return cached;
+}
+/** Creates the working VM state on first use: a COW overlay over the
+ *  pristine image, a persistent EFI NVRAM store and a TPM state dir. The
+ *  overlay records its backing image; when the backing image changes (a
+ *  rebuild replaces the file at the same path), the overlay is recreated
+ *  — otherwise Windows would read a corrupt disk.
+ *
+ * @param context - The run context.
+ * @param pristinePath - The pristine qcow2 path.
+ */
+async function ensureWorkingVm(context, pristinePath) {
+    const image = context.image;
+    const overlay = qemuOverlayPath(image);
+    const stat = statSync(pristinePath);
+    const id = backingIdentity(pristinePath, stat.size, stat.mtimeMs);
+    if (backingChanged(image, id)) {
+        logger.warn('The backing image changed (new build or pull) — recreating the working VM.');
+        logger.warn('Discarding the old overlay, EFI NVRAM, and TPM state (they belong to the previous image).');
+        dropWorkingVmState(image);
+    }
+    if (existsSync(overlay) && readMarker(image) === id) {
+        logger.ok(`Working VM exists (${overlay}).`);
+        return;
+    }
+    await createOverlay(image, pristinePath, overlay, id);
+    await seedEfivars(image, pristinePath);
+    logger.ok(`Working VM created (${overlay}).`);
+}
+/** Whether the recorded backing identity differs from the current disk's
+ *  (a rebuild replaces the file at the same path — path alone would
+ *  silently stack the old overlay on a different base, a corrupt disk).
+ */
+function backingChanged(image, id) {
+    const markerPath = qemuBackingMarker(image);
+    if (!existsSync(markerPath)) {
+        return false;
+    }
+    return readFileSync(markerPath, 'utf8').trim() !== id;
+}
+/** The recorded backing identity ('' when the marker is missing). */
+function readMarker(image) {
+    const markerPath = qemuBackingMarker(image);
+    return existsSync(markerPath) ? readFileSync(markerPath, 'utf8').trim() : '';
+}
+/** Removes the overlay + EFI NVRAM + TPM state that belong to the previous
+ *  backing image.
+ */
+function dropWorkingVmState(image) {
+    rmSync(qemuOverlayPath(image), { force: true });
+    rmSync(qemuEfivarsPath(image), { force: true });
+    rmSync(qemuTpmDir(image), { recursive: true, force: true });
+}
+/** Creates the COW overlay over the pristine disk (qemu-img create) and
+ *  records the backing identity it was created from.
+ */
+async function createOverlay(image, pristinePath, overlay, id) {
+    mkdirSync(dirname(overlay), { recursive: true });
+    mkdirSync(qemuTpmDir(image), { recursive: true });
+    logger.cmd(`qemu-img create -f qcow2 -F qcow2 -b ${pristinePath} ${overlay}`);
+    const create = await run('qemu-img', [
+        'create',
+        '-f',
+        'qcow2',
+        '-F',
+        'qcow2',
+        '-b',
+        pristinePath,
+        overlay,
+    ]);
+    if (create.code !== 0) {
+        logger.die(`qemu-img create failed:\n${create.stderr.trim()}`);
+    }
+    writeFileSync(qemuBackingMarker(image), id);
+}
+/** Seeds the EFI NVRAM store: the vars file the image was built with (it
+ *  holds Windows' own Boot0000 for exactly this install) when the build
+ *  output ships one, otherwise the edk2 template (a fresh NVRAM has no
+ *  Boot0000 and relies on the \EFI\BOOT\bootaa64.efi fallback the
+ *  installer writes).
+ */
+async function seedEfivars(image, pristinePath) {
+    const efivars = qemuEfivarsPath(image);
+    if (existsSync(efivars)) {
+        return;
+    }
+    mkdirSync(dirname(efivars), { recursive: true });
+    const seeded = join(dirname(pristinePath), 'efivars.fd');
+    if (existsSync(seeded)) {
+        await run('cp', [seeded, efivars]);
+        logger.info('EFI NVRAM: seeded from the build output\u2019s efivars.fd.');
+        return;
+    }
+    if (!existsSync(QEMU_EFI_VARS_TEMPLATE)) {
+        logger.die(`EFI NVRAM template not found at ${QEMU_EFI_VARS_TEMPLATE} — is Homebrew's qemu installed?`);
+    }
+    await run('cp', [QEMU_EFI_VARS_TEMPLATE, efivars]);
+}

package/dist/runners/rules.js

@@ -0,0 +1,49 @@
+// runners/rules.ts — the agent-rules step: render the bundled
+// assets/rules/agent-rules.md (macOS) or agent-rules-linux.md (Ubuntu)
+// with the run's actual paths and stream it into the guest's agent
+// (`rules --probe` / `rules --force`), keeping the shell's
+// probe/confirm/overwrite semantics (see run-macos-sandbox.sh
+// §"agent rules").
+//
+// The probe only inspects the guest and reports the pending action; the
+// write happens only after the user confirmed. The SSH agent section is
+// dropped from the render when no agent bridge is actually up, so the
+// rules never claim a bridge that is not running.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dropSectionFrom, render } from '../lib/template.js';
+/** The SSH section heading in the rules files (shared by both assets). */
+const SSH_RULES_HEADING = '## SSH agent bridge';
+/** Path of a bundled rules asset.
+ *
+ * @param name - The asset file name (agent-rules.md / agent-rules-linux.md).
+ * @returns The absolute path in dist/assets/rules.
+ */
+function agentRulesPath(name) {
+    return fileURLToPath(new URL(`../assets/rules/${name}`, import.meta.url));
+}
+/** Loads a bundled rules document (missing file → warn, no content).
+ *
+ * @param name - The asset file name (default agent-rules.md).
+ * @returns The raw rules text; empty when the asset is missing.
+ */
+export function loadAgentRules(name = 'agent-rules.md') {
+    try {
+        return readFileSync(agentRulesPath(name), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** Renders the rules document for this run.
+ *
+ * @param content - The raw rules text.
+ * @param substitutions - {{HOST_WORK_DIR}} / {{GUEST_MOUNT}} (and
+ *   {{NAT_GATEWAY}} for the linux asset) values.
+ * @param includeSsh - Whether the SSH agent bridge section stays.
+ * @returns The rendered document.
+ */
+export function renderAgentRules(content, substitutions, includeSsh) {
+    const rendered = render(content, substitutions);
+    return includeSsh ? rendered : dropSectionFrom(rendered, SSH_RULES_HEADING);
+}

package/dist/runners/ubuntu-bridges.js

@@ -0,0 +1,154 @@
+// runners/ubuntu-bridges.ts — step 3 for the Ubuntu backend: the host
+// side of the SSH agent + Docker bridges, bound to the host's address on
+// the guest's NAT segment (the shell's find_host_alias — Fusion's NAT is
+// userspace; the guest gateway x.y.z.2 is vmnetd and does not forward to
+// the host loopback, so the bridges bind the host's x.y.z.1 instead of a
+// gateway). The guest side (upload/install/status over ssh2) lives in
+// ubuntu-guest.ts, the rules step in ubuntu-rules.ts.
+import { sleep } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { findHostAlias } from '../lib/network.js';
+import { openSshSession } from '../lib/ssh.js';
+import { findHostAgentSocket, findHostDockerSocket, startHostBridge } from './bridges.js';
+import { ensureGuestAgent, findGuestNode, readGuestStatus, resolveGuestCredentials, } from './ubuntu-guest.js';
+import { installLinuxAgentRules } from './ubuntu-rules.js';
+/** The Ubuntu step 3: host alias → host bridges → guest agent → guest
+ *  bridges → rules. Unlike macOS (Tart gateway), every bridge here binds
+ *  the host's NAT-segment address, resolved once and reused.
+ */
+export async function ubuntuBridges(context, state) {
+    const ip = state.vmIp;
+    if (!ip) {
+        logger.warn('no guest IP — skipping the host bridges, guest setup and rules.');
+        return;
+    }
+    const hostAlias = await findHostAlias(ip);
+    if (!hostAlias) {
+        logger.warn('could not determine the host NAT-segment address — skipping the bridges.');
+        return;
+    }
+    const creds = resolveGuestCredentials(context.image, context.options.env, ip);
+    const session = await openSshSession(creds);
+    try {
+        const node = await findGuestNode(session);
+        if (!node) {
+            logger.warn('node not found in the guest — skipping the guest bridges and rules.');
+            return;
+        }
+        if (context.options.noAgent) {
+            logger.info('Skipping SSH agent bridge setup (--no-agent).');
+        }
+        else {
+            await setupSshAgent(context, state, hostAlias);
+        }
+        if (context.options.noDocker) {
+            logger.info('Skipping Docker bridge setup (--no-docker).');
+        }
+        else {
+            await setupDockerBridge(context, state, hostAlias);
+        }
+        const anyBridged = state.bridges.agent.bridged || state.bridges.docker.bridged;
+        if (anyBridged) {
+            await ensureGuestAgent(session, node, hostAlias, context);
+            await readGuestStatus(session, state, node);
+            reportBridgeState(context, state);
+            if (state.bridges.docker.bridged && state.bridges.docker.guestUp) {
+                await verifyGuestDocker(session, state);
+            }
+        }
+        await installLinuxAgentRules(context, state, session, node, hostAlias);
+    }
+    finally {
+        session.end();
+    }
+}
+async function setupSshAgent(context, state, hostAlias) {
+    const sock = findHostAgentSocket(context.options.env, context.options.home);
+    if (!sock) {
+        logger.info('No SSH agent override detected — using the default macOS agent.');
+        logger.info('To share a password manager\u2019s agent (Bitwarden, 1Password, ...), ' +
+            'enable its SSH agent on the host and re-run.');
+        return;
+    }
+    logger.ok(`Host SSH agent socket found: ${sock}`);
+    logger.info(`Bridging it into the guest on TCP port ${context.agentPort} (see docs/ssh-agent.md).`);
+    logger.ok(`Guest reaches the host at ${hostAlias}`);
+    if (!(await startBridge(context, state, 'ssh-agent', sock, hostAlias))) {
+        return;
+    }
+}
+async function setupDockerBridge(context, state, hostAlias) {
+    const sock = findHostDockerSocket(context.options.home);
+    if (!sock) {
+        logger.info('No Docker engine socket found on the host (Docker Desktop, Colima, OrbStack).');
+        logger.info('Start an engine on the host and re-run to bridge it into the guest.');
+        return;
+    }
+    logger.ok(`Host Docker engine socket found: ${sock}`);
+    logger.info(`Bridging it into the guest on TCP port ${context.dockerPort}.`);
+    logger.ok(`Guest reaches the host at ${hostAlias}`);
+    if (!(await startBridge(context, state, 'docker', sock, hostAlias))) {
+        return;
+    }
+}
+/** The shared bridge start: the host spawn + state bookkeeping (the
+ *  shell's start_host_bridge; pidfile + detached bridge.js via
+ *  runners/bridges.ts — no socat). Returns false when skipped.
+ */
+async function startBridge(context, state, role, socket, hostAlias) {
+    const result = await startHostBridge({
+        role,
+        bindHost: hostAlias,
+        port: role === 'ssh-agent' ? context.agentPort : context.dockerPort,
+        forwardSocket: socket,
+    });
+    if (result.state === 'failed') {
+        logger.warn(`skipping the ${role === 'ssh-agent' ? 'SSH agent' : 'Docker'} bridge.`);
+        return false;
+    }
+    const bridge = role === 'ssh-agent' ? state.bridges.agent : state.bridges.docker;
+    bridge.bridged = true;
+    bridge.socket = socket;
+    bridge.pid = result.state === 'started' ? result.pid : undefined;
+    return true;
+}
+function reportBridgeState(context, state) {
+    const agent = state.bridges.agent;
+    if (agent.bridged) {
+        if (agent.guestUp) {
+            logger.ok(`Guest bridge is up: /tmp/ssh-agent.sock -> host TCP ${context.agentPort}`);
+        }
+        else {
+            logger.warn('guest bridge did not start — run the guest commands from docs/ssh-agent.md manually.');
+        }
+    }
+    const docker = state.bridges.docker;
+    if (docker.bridged) {
+        if (docker.guestUp) {
+            logger.ok(`Guest Docker bridge is up: /tmp/docker.sock -> host TCP ${context.dockerPort}`);
+        }
+        else {
+            logger.warn('guest Docker bridge did not start — check the guest agent install.');
+        }
+    }
+}
+/** End-to-end check: can the guest's docker CLI reach the host engine
+ *  through the bridge? Retries briefly (the engine may still be
+ *  starting), like the shell's verify_guest_docker (15 x 1 s).
+ */
+async function verifyGuestDocker(session, state) {
+    const probe = 'bash -lc \'docker info --format "{{.ServerVersion}}"\'';
+    for (let attempt = 0; attempt < 15; attempt += 1) {
+        const res = await session.exec(probe, { timeoutMs: 20_000 });
+        const version = res.code === 0 ? res.stdout.trim() : '';
+        if (version) {
+            state.bridges.docker.serverVersion = version;
+            state.bridges.docker.engineUp = true;
+            logger.ok(`Docker engine is reachable from the guest (server version ${version}).`);
+            return;
+        }
+        await sleep(1000);
+    }
+    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/ubuntu-guest.js

@@ -0,0 +1,136 @@
+// runners/ubuntu-guest.ts — the guest side of the Ubuntu step 3: the
+// credentials (from the image's vars file, UBUNTU_PASSWORD override),
+// where the bundled guest agent lives, how it is uploaded over SFTP and
+// how it is run (upload → sudo install → status), plus the status-line
+// parsing. The transport is the ssh2 session (lib/ssh.ts) — the twin of
+// runners/macos-guest.ts, which runs over `tart exec`.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { varsFor, resolveImage } from '../lifecycle/catalog.js';
+import { logger } from '../lib/logger.js';
+/** The guest's agent install dir (image-fixed home `/home/admin`). */
+const GUEST_LIB_DIR = '/home/admin/.local/lib/agent-dev-env';
+/** The absolute guest-agent path. */
+export const GUEST_AGENT = `${GUEST_LIB_DIR}/guest-agent-ubuntu.js`;
+/** The guest's sshd port (fixed in the image; no hostfwd — the VM sits
+ *  on Fusion's NAT and the host reaches it directly). */
+const GUEST_SSH_PORT = 22;
+/** The bundled Ubuntu guest agent (single-file, node-only). */
+function guestAgentPath() {
+    return fileURLToPath(new URL('../assets/guest/guest-agent-ubuntu.js', import.meta.url));
+}
+/** @internal — resolves the guest credentials from the image's vars file
+ *  (+ UBUNTU_PASSWORD override). Pure so the fallbacks are testable.
+ *
+ * @param vars - The vars file values.
+ * @param env - Environment (UBUNTU_PASSWORD).
+ * @param ip - The guest IP.
+ * @returns The credentials.
+ * @throws Error when no ssh_password is available.
+ */
+export function guestCredentials(vars, env, ip) {
+    const username = typeof vars.ssh_username === 'string' && vars.ssh_username.trim() ? vars.ssh_username : 'admin';
+    const password = env.UBUNTU_PASSWORD ?? (typeof vars.ssh_password === 'string' ? vars.ssh_password : '');
+    if (!password) {
+        throw new Error('could not read ssh_password from the vars file — set UBUNTU_PASSWORD to the guest password.');
+    }
+    return { host: ip, port: GUEST_SSH_PORT, 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.
+ * @returns The credentials.
+ */
+export function resolveGuestCredentials(image, env, ip) {
+    return guestCredentials(varsFor(resolveImage(image)), env, ip);
+}
+/** Reports the path of the node binary inside the guest (opencode needs
+ *  it, so the image ships it; resolve once per session like the mac
+ *  backend).
+ *
+ * @param session - The connected guest session.
+ * @returns The absolute node path, or undefined when not found.
+ */
+export async function findGuestNode(session) {
+    const res = await session.exec('sh -lc "command -v node"');
+    const node = res.code === 0 ? res.stdout.trim() : '';
+    return node && node.startsWith('/') ? node : undefined;
+}
+/** Uploads the bundled guest agent and runs `install` (idempotent:
+ *  systemd user units rewritten + the bridge env exports). Runs as the
+ *  guest user — the agent's systemd units live under the user's
+ *  ~/.config/systemd/user, and `systemctl --user` must target the admin
+ *  session (running the agent through sudo would place them under /root;
+ *  the agent then falls back to the user-level ~/.profile exports).
+ *
+ * @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 session.exec(`mkdir -p ${GUEST_LIB_DIR}`);
+    if (mkdir.code !== 0) {
+        logger.warn(`could not prepare the guest agent dir (ssh: ${mkdir.code}).`);
+        return;
+    }
+    try {
+        await session.sftpWrite(GUEST_AGENT, readFileSync(guestAgentPath()));
+    }
+    catch (err) {
+        logger.warn(`could not upload the guest agent: ${err.message}`);
+        return;
+    }
+    const install = await session.exec(`${node} ${GUEST_AGENT} install ` +
+        `--agent-port ${context.agentPort} --docker-port ${context.dockerPort} ` +
+        `--host-alias ${hostAlias}`, { timeoutMs: 60_000 });
+    if (install.code !== 0) {
+        logger.warn(`guest agent install failed (ssh: ${install.code}).`);
+        return;
+    }
+    logger.ok('Guest agent installed (SSH agent + Docker bridges persistent).');
+}
+/** Parses the guest agent's machine-readable status lines — shared by
+ *  the Ubuntu and Windows guests (identical bridge-status format).
+ *
+ * @param output - The `guest-agent status` stdout.
+ * @returns The per-role bridge state (present per reported line).
+ */
+export function parseGuestStatus(output) {
+    const status = {};
+    for (const line of output.split('\n')) {
+        const match = /^bridge-status:(ssh-agent|docker)=(up|down)$/.exec(line.trim());
+        if (!match) {
+            continue;
+        }
+        if (match[1] === 'ssh-agent') {
+            status.sshAgent = match[2] === 'up';
+        }
+        else {
+            status.docker = match[2] === 'up';
+        }
+    }
+    return status;
+}
+/** Runs `guest-agent status` and folds the bridge-status lines into the
+ *  run state.
+ *
+ * @param session - The connected guest session.
+ * @param state - The accumulated run state.
+ * @param node - The guest's node binary.
+ */
+export async function readGuestStatus(session, state, node) {
+    const res = await session.exec(`${node} ${GUEST_AGENT} status`, { timeoutMs: 20_000 });
+    if (res.code !== 0) {
+        return;
+    }
+    const status = parseGuestStatus(res.stdout);
+    if (status.sshAgent !== undefined) {
+        state.bridges.agent.guestUp = status.sshAgent;
+    }
+    if (status.docker !== undefined) {
+        state.bridges.docker.guestUp = status.docker;
+    }
+}

package/dist/runners/ubuntu-image.js

@@ -0,0 +1,26 @@
+// runners/ubuntu-image.ts — step 1 for the Ubuntu backend: the
+// ubuntu-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 UBUNTU_VMWARE_IMAGE override var.
+import { ensureVmwareImage, vmwareWorkingVmx } from './vmware-image.js';
+/** The platform id for the VMware path helpers. */
+const PLATFORM = 'ubuntu-vmware';
+/** @internal — the pristine-archive identity (see vmware-image.ts) —
+ *  re-exported so the co-located test keeps its import path.
+ */
+export { archiveIdentity } from './vmware-image.js';
+/** The working clone's vmx. */
+export function ubuntuWorkingVmx(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 ensureUbuntuImage(context, state) {
+    return ensureVmwareImage(PLATFORM, 'UBUNTU_VMWARE_IMAGE', context, state);
+}

package/dist/runners/ubuntu-rules.js

@@ -0,0 +1,86 @@
+// runners/ubuntu-rules.ts — the agent-rules step for the Ubuntu backend:
+// render the bundled agent-rules-linux.md (extra {{NAT_GATEWAY}}
+// substitution) and drive the guest agent's `rules --probe` / `rules
+// --force` over ssh (the mac twin in macos-rules.ts runs over `tart
+// exec`; the probe/confirm/overwrite semantics are the same). The
+// sha256 marker semantics live in the guest agent (guest-rules).
+import { logger } from '../lib/logger.js';
+import { confirmDefault } from '../lib/prompt.js';
+import { loadAgentRules, renderAgentRules } from './rules.js';
+import { GUEST_AGENT } from './ubuntu-guest.js';
+/** The rules asset for Ubuntu (vs agent-rules.md on macOS). */
+const RULES_ASSET = 'agent-rules-linux.md';
+/** The agent-rules probe/confirm/apply over ssh.
+ *
+ * @param context - The run context (paths to substitute).
+ * @param state - The accumulated run state (bridge flags).
+ * @param session - The connected guest session.
+ * @param node - The guest's node binary.
+ * @param hostAlias - The NAT host address ({{NAT_GATEWAY}}).
+ */
+export async function installLinuxAgentRules(context, state, session, node, hostAlias) {
+    const content = loadAgentRules(RULES_ASSET);
+    if (!content) {
+        logger.warn('agent rules file not found (assets/rules/agent-rules-linux.md).');
+        state.rules = 'failed';
+        return;
+    }
+    const natGateway = hostAlias ?? (state.vmIp ? `${state.vmIp.split('.').slice(0, 3).join('.')}.1` : '');
+    const rendered = renderAgentRules(content, {
+        HOST_WORK_DIR: context.workDir || '<not shared>',
+        GUEST_MOUNT: context.guestMount,
+        NAT_GATEWAY: natGateway,
+    }, state.bridges.agent.bridged && state.bridges.agent.guestUp);
+    const probe = await session.exec(`${node} ${GUEST_AGENT} rules`, {
+        input: rendered,
+    });
+    const action = /^rules:probe=(.+)$/.exec(probe.stdout.trim())?.[1];
+    if (probe.code !== 0 || !action) {
+        logger.warn('could not inspect the agent rules in the guest.');
+        state.rules = 'failed';
+        return;
+    }
+    await applyRulesAction(context, state, session, node, rendered, action);
+}
+/** The probe outcome decision tree (shell parity: install/update ask
+ *  with the y default, conflict asks with the n default). */
+async function applyRulesAction(context, state, session, node, rendered, action) {
+    if (action === 'uptodate') {
+        logger.info('Agent rules are up to date in the guest.');
+        state.rules = 'uptodate';
+        return;
+    }
+    if (action !== 'install' && action !== 'update' && action !== 'conflict') {
+        logger.warn('could not inspect the agent rules in the guest.');
+        state.rules = 'failed';
+        return;
+    }
+    const isConflict = action === 'conflict';
+    if (isConflict) {
+        logger.info('The guest has its own agent rules.');
+    }
+    const ask = isConflict
+        ? "Overwrite the guest's agent rules with the sandbox rules?"
+        : 'Install/update the sandbox agent rules in the guest?';
+    if (!(await confirmDefault(ask, { default: isConflict ? 'n' : 'y', yes: context.options.yes }))) {
+        logger.info(isConflict
+            ? "Keeping the guest's own agent rules."
+            : "Keeping the guest's agent rules as they are.");
+        state.rules = 'kept';
+        return;
+    }
+    const write = await session.exec(`${node} ${GUEST_AGENT} rules --force`, { input: rendered });
+    if (write.code !== 0) {
+        logger.warn('could not install the agent rules into the guest.');
+        state.rules = 'failed';
+        return;
+    }
+    if (isConflict) {
+        state.rules = 'overwritten';
+        logger.ok("Overwrote the guest's agent rules.");
+    }
+    else {
+        state.rules = action === 'install' ? 'installed' : 'updated';
+        logger.ok('Installed/updated the sandbox agent rules (opencode + Copilot CLI).');
+    }
+}