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

package/dist/lifecycle/deploy.js

@@ -0,0 +1,161 @@
+// deploy.ts — `agent-dev-env deploy`: pushes built images to GHCR (the
+// port of scripts/deploy.sh + the three platform deploy wrappers).
+// macOS images go via tart push; the qcow2/vmware artifacts go via oras
+// push as OCI artifacts (the tar.gz for the VMware pair). The GHCR owner
+// is resolved GHCR_OWNER → --owner → git remote → ameshkov.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { run, runChecked } from '../lib/exec.js';
+import { findRepoRoot } from '../lib/git.js';
+import { registryRef, resolveOwner } from '../lib/ghcr.js';
+import { logger } from '../lib/logger.js';
+import { buildDirLayout, duHuman, requireCmd } from './build-shared.js';
+import { imageVersion, resolveRequestedImages } from './catalog.js';
+/** `agent-dev-env deploy [image...] [--owner OWNER]`.
+ *
+ * @param requested - Image names (all images when empty).
+ * @param options - Owner override.
+ * @returns The exit code (0 on success).
+ */
+export async function deployCmd(requested = [], options = {}) {
+    const repoRoot = findRepoRoot();
+    const owner = await resolveOwner({ owner: options.owner, repoRoot: repoRoot ?? undefined });
+    const targets = resolveRequestedImages(requested);
+    if (requested.length === 0) {
+        logger.title('Deploying all images:');
+        for (const image of targets) {
+            logger.info(image.name);
+        }
+    }
+    for (const image of targets) {
+        await deployImage(image, owner);
+    }
+    return 0;
+}
+/** Deploys one image with its platform's flow.
+ *
+ * @param image - The catalog image.
+ * @param owner - The resolved GHCR owner.
+ */
+async function deployImage(image, owner) {
+    switch (image.platform) {
+        case 'macos':
+            await deployMacos(image, owner);
+            return;
+        case 'windows-qemu':
+            await deployQemu(image, owner);
+            return;
+        case 'windows-vmware':
+        case 'ubuntu-vmware':
+            await deployVmware(image, owner);
+            return;
+    }
+}
+/** macOS: `tart push <image> --chunk-size 3 <ref>:<ver> <ref>:latest`.
+ *
+ * @param image - The catalog image.
+ * @param owner - The GHCR owner.
+ */
+async function deployMacos(image, owner) {
+    requireCmd('tart', 'brew install cirruslabs/tap/tart');
+    const version = imageVersion(image);
+    const ref = registryRef(image.name, version, owner);
+    logger.title(`Pushing image: ${image.name}`);
+    logger.info(`Registry: ${ref} and :latest`);
+    await runChecked('tart', tartPushArgs(image.name, ref, registryRef(image.name, 'latest', owner)));
+    logger.ok(`Done: ${ref} (and :latest)`);
+}
+/** @internal — the tart push argv (3 MB chunks — GHCR rejects > 4 MB
+ *  chunks; test-only export).
+ *
+ * @param imageName - The local VM image name.
+ * @param versionRef - The version registry ref.
+ * @param latestRef - The latest registry ref.
+ * @returns The tart argv.
+ */
+export function tartPushArgs(imageName, versionRef, latestRef) {
+    return ['push', imageName, '--chunk-size', '3', versionRef, latestRef];
+}
+/** windows-qemu: oras push of the built qcow2 as an OCI artifact.
+ *
+ * @param image - The catalog image.
+ * @param owner - The GHCR owner.
+ */
+async function deployQemu(image, owner) {
+    const dirs = buildDirLayout('windows-qemu');
+    const artifact = join(dirs.output, `${image.name}.qcow2`);
+    if (!existsSync(artifact)) {
+        throw new Error(`no built image at ${artifact}\n       Build it first: agent-dev-env build ${image.name}`);
+    }
+    requireCmd('oras', 'brew install oras');
+    const version = imageVersion(image);
+    const ref = `${registryRef(image.name, version, owner)},latest`;
+    logger.title(`Pushing image: ${image.name}`);
+    logger.info(`Registry: ${registryRef(image.name, version, owner)} and :latest`);
+    logger.info(`Artifact: ${artifact} (${await duHuman(artifact)})`);
+    await runChecked('oras', orasPushArgs(ref, `${image.name}.qcow2`, 'application/vnd.agent-dev-env.qcow2'), {
+        cwd: dirs.output,
+    });
+    logger.ok(`Done: ${registryRef(image.name, version, owner)} (and :latest)`);
+}
+/** @internal — the oras push argv (bare file name — oras rejects absolute
+ *  paths and stores the file under the name it is given; test-only
+ *  export).
+ *
+ * @param ref - The `registry:version,latest` ref.
+ * @param file - The bare file name in the cwd.
+ * @param artifactType - The OCI artifact media type.
+ * @returns The oras argv.
+ */
+export function orasPushArgs(ref, file, artifactType) {
+    return [
+        'push',
+        '--artifact-type',
+        artifactType,
+        ref,
+        `${file}:application/vnd.oci.image.layer.v1.tar`,
+    ];
+}
+/** windows-vmware / ubuntu-vmware: tar.gz of the VM dir, then oras push.
+ *
+ * @param image - The catalog image.
+ * @param owner - The GHCR owner.
+ */
+async function deployVmware(image, owner) {
+    const dirs = buildDirLayout(image.platform);
+    const vmx = join(dirs.output, `${image.name}.vmx`);
+    if (!existsSync(vmx)) {
+        throw new Error(`no built image at ${vmx}\n       Build it first: agent-dev-env build ${image.name}`);
+    }
+    const artifact = join(dirs.output, `${image.name}.tar.gz`);
+    logger.step(`packing ${artifact} (excluding vmware logs)`);
+    await packageVmwareTar(dirs.output, image.name, artifact);
+    requireCmd('oras', 'brew install oras');
+    const version = imageVersion(image);
+    const ref = `${registryRef(image.name, version, owner)},latest`;
+    logger.title(`Pushing image: ${image.name}`);
+    logger.info(`Registry: ${registryRef(image.name, version, owner)} and :latest`);
+    logger.info(`Artifact: ${artifact} (${await duHuman(artifact)})`);
+    await runChecked('oras', orasPushArgs(ref, `${image.name}.tar.gz`, 'application/vnd.agent-dev-env.vmware-vm'), {
+        cwd: dirs.output,
+    });
+    logger.ok(`Done: ${registryRef(image.name, version, owner)} (and :latest)`);
+}
+/** @internal — packages the runnable VM (vmx + nvram + vmdks, no logs)
+ *  into one tar.gz for oras (test-only export; consumers get a single
+ *  pull artifact to extract).
+ *
+ * @param outputDir - Packer's output dir (cwd for the relative names).
+ * @param imageName - The image name (file prefix).
+ * @param artifact - The tar.gz to create.
+ */
+export async function packageVmwareTar(outputDir, imageName, artifact) {
+    const vmdks = readdirSync(outputDir)
+        .filter((file) => file.endsWith('.vmdk'))
+        .sort();
+    const files = [`${imageName}.vmx`, `${imageName}.nvram`, ...vmdks];
+    const res = await run('tar', ['-czf', artifact, ...files], { cwd: outputDir });
+    if (res.code !== 0) {
+        throw new Error(`tar failed: ${res.stderr.trim() || res.stdout.trim()}`);
+    }
+}

package/dist/lifecycle/tag.js

@@ -0,0 +1,77 @@
+// tag.ts — `agent-dev-env tag`: creates and pushes the git release tag
+// for an image (the port of scripts/tag.sh). The tag is
+// <platform>-v<image_version>, where <platform> is the image's directory
+// under images/ (e.g. `mac` → `mac-v1.2.0`). The release convention is
+// enforced: clean working tree, no existing tag, and a `[<tag>]` entry in
+// the platform's CHANGELOG.md. Requires a repo checkout or --repo.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { changelogHasTagEntry, createAnnotatedTag, findRepoRoot, isWorkingTreeClean, pushTag, tagExists, } from '../lib/git.js';
+import { logger } from '../lib/logger.js';
+import { imageVersion, resolveRequestedImages } from './catalog.js';
+/** @internal — the platform name (the images/<dir> basename, e.g. `mac`;
+ *  test-only export).
+ *
+ * @param image - The catalog image.
+ * @returns The platform dir name.
+ */
+export function platformTagName(image) {
+    return basename(dirname(dirname(image.varsFile)));
+}
+/** @internal — the release tag for an image (<platform>-v<image_version>;
+ *  test-only export).
+ *
+ * @param image - The catalog image.
+ * @returns The tag name.
+ */
+export function releaseTag(image) {
+    return `${platformTagName(image)}-v${imageVersion(image)}`;
+}
+/** @internal — creates and pushes the tag for one image (test-only
+ *  export).
+ *
+ * @param image - The catalog image.
+ * @param repoRoot - The repo checkout.
+ */
+export async function tagImage(image, repoRoot) {
+    const tag = releaseTag(image);
+    const version = imageVersion(image);
+    const changelog = join(dirname(dirname(image.varsFile)), 'CHANGELOG.md');
+    if (!(await isWorkingTreeClean(repoRoot))) {
+        throw new Error('Working tree is dirty — commit the version bump and CHANGELOG entry first.');
+    }
+    if (await tagExists(repoRoot, tag)) {
+        throw new Error(`Tag '${tag}' already exists.`);
+    }
+    const content = existsSync(changelog) ? readFileSync(changelog, 'utf8') : '';
+    if (!changelogHasTagEntry(content, tag)) {
+        throw new Error(`No CHANGELOG entry for [${tag}] in ${changelog}.\n` +
+            'Add it (and bump image_version) before tagging.');
+    }
+    logger.step(`Tagging: ${tag} (${image.name} v${version})`);
+    await createAnnotatedTag(repoRoot, tag, `Release ${image.name} v${version}`);
+    await pushTag(repoRoot, tag);
+}
+/** `agent-dev-env tag [image...] [--repo PATH]`.
+ *
+ * @param requested - Image names (all images when empty).
+ * @param options - Repo override.
+ * @returns The exit code (0 on success).
+ */
+export async function tagCmd(requested = [], options = {}) {
+    const repoRoot = options.repo ?? findRepoRoot();
+    if (!repoRoot) {
+        throw new Error('tag needs a checkout of the agent-dev-env repo (pass --repo or run it inside the repo).');
+    }
+    const targets = resolveRequestedImages(requested);
+    if (requested.length === 0) {
+        logger.title('Tagging all images:');
+        for (const image of targets) {
+            logger.info(image.name);
+        }
+    }
+    for (const image of targets) {
+        await tagImage(image, repoRoot);
+    }
+    return 0;
+}

package/dist/lifecycle/watch-build.js

@@ -0,0 +1,64 @@
+// watch-build.ts — the hidden `watch-build` command: the port of
+// scripts/watch-build.sh. Checks python3 + vncdotool and swiftc (hard
+// errors — this is the manual watchdog invocation, not a build wrapper),
+// compiles the OCR helper if-stale, then runs the bundled watch-build.py
+// in the foreground (Ctrl+C stops it, same as the shell's `exec`).
+import { spawn } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { commandExists } from '../lib/exec.js';
+import { buildDir } from '../lib/paths.js';
+import { logger } from '../lib/logger.js';
+import { compileOcrHelper, pythonVncdotoolAvailable, watchdogAssets } from './build-watchdog.js';
+/** The default frames dir (<data>/build/windows-qemu/packer_cache/
+ *  watchdog).
+ *
+ * @returns The default outdir.
+ */
+function defaultWatchdogOutdir() {
+    return join(buildDir('windows-qemu'), 'packer_cache', 'watchdog');
+}
+/** `agent-dev-env watch-build <vnc-port> [outdir]` (hidden).
+ *
+ * @param vncPort - The VNC port of the packer build.
+ * @param outdir - The frames dir (defaults per platform state layout).
+ * @param options - The command options (--no-ocr reserved).
+ * @returns The python supervisor's exit code.
+ */
+export async function watchBuildCmd(vncPort, outdir, options = {}) {
+    void options.noOcr;
+    if (!(await pythonVncdotoolAvailable())) {
+        logger.die('the vncdotool module is missing — install it with: pip3 install vncdotool');
+    }
+    if (!commandExists('swiftc')) {
+        logger.die('swiftc is missing — install the Xcode command line tools.');
+    }
+    const assets = watchdogAssets();
+    const dir = outdir ?? defaultWatchdogOutdir();
+    mkdirSync(dir, { recursive: true });
+    const ocr = await compileOcrHelper(dir, assets);
+    if (!ocr) {
+        logger.warn('swiftc failed — the OCR helper is required for the watchdog.');
+        return 1;
+    }
+    logger.step(`watching VNC port ${vncPort} (frames: ${dir}) — Ctrl+C to stop`);
+    return runForeground('python3', [assets.python, String(vncPort), dir, ocr]);
+}
+/** Runs a process with inherited stdio and resolves with its exit code
+ *  (the shell's `exec`-style foreground run).
+ *
+ * @param cmd - The command.
+ * @param args - The argv.
+ * @returns The exit code.
+ */
+function runForeground(cmd, args) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { stdio: 'inherit' });
+        child.on('error', () => {
+            resolve(1);
+        });
+        child.on('close', (code) => {
+            resolve(code ?? 1);
+        });
+    });
+}

package/dist/runners/bridges.js

@@ -0,0 +1,156 @@
+// runners/bridges.ts — the host side of the SSH agent + Docker bridges:
+// socket discovery, the port probe (the legacy "is a listener already
+// bound" check), and the detached spawn of the bundled bridge.js (the
+// socat replacement). The guest side lives in the
+// per-platform guest agents (launchd/schtasks/systemd).
+//
+// The bridge is spawned detached with a pidfile under the logs/state dir
+// and keeps running after the CLI exits (the VM needs it while it runs);
+// `stop` kills it by pidfile. Idempotent: when a listener is already up,
+// nothing is spawned.
+import net from 'node:net';
+import { lstatSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isAlive, killTree, readPidFile, spawnDetached } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { paths } from '../lib/paths.js';
+/** The bundled bridge entry — where copy-assets.mjs puts it. */
+function bridgeJsPath() {
+    // dist/runners/bridges.js -> dist/assets/bridge/bridge.js
+    return fileURLToPath(new URL('../assets/bridge/bridge.js', import.meta.url));
+}
+/** @internal — pidfile for a host bridge (logs/state dir). */
+export function bridgePidFile(role) {
+    return join(paths.logs, `bridge-${role}.pid`);
+}
+/** @internal — log file for a host bridge. */
+export function bridgeLogFile(role) {
+    return join(paths.logs, `bridge-${role}.log`);
+}
+/** Whether the path is a Unix socket. */
+function isUnixSocket(path) {
+    try {
+        return lstatSync(path).isSocket();
+    }
+    catch {
+        return false;
+    }
+}
+/** The host's SSH agent socket when it is overridden by a password
+ *  manager's agent (Bitwarden, 1Password, ...). The stock macOS launchd
+ *  agent (a socket under /var/run/com.apple.launchd.*) is NOT bridged.
+ *
+ * @param env - Environment (SSH_AUTH_SOCK).
+ * @param home - Host home directory (unused, kept for signature parity).
+ * @returns The socket path, or undefined when nothing is bridged.
+ */
+export function findHostAgentSocket(env = process.env, _home = process.env.HOME ?? '') {
+    const sock = env.SSH_AUTH_SOCK;
+    if (!sock || /^\/var\/run\/com\.apple\.launchd\..*\/Listeners$/.test(sock)) {
+        return undefined;
+    }
+    if (isUnixSocket(sock)) {
+        return sock;
+    }
+    logger.warn(`SSH_AUTH_SOCK points to '${sock}', but no such socket exists.`);
+    return undefined;
+}
+/** The host's Docker engine socket — the engines the sandbox supports:
+ *  Docker Desktop (4.30+), Colima, OrbStack, then the legacy /var/run.
+ *  The system-wide candidate is injectable so tests can be deterministic
+ *  on any host (Linux CI runners always expose /var/run/docker.sock).
+ *
+ * @param home - Host home directory.
+ * @param systemSocket - System-wide Docker socket candidate.
+ * @returns The socket path, or undefined when no engine is running.
+ */
+export function findHostDockerSocket(home, systemSocket = '/var/run/docker.sock') {
+    const candidates = [
+        join(home, '.docker', 'run', 'docker.sock'),
+        join(home, '.colima', 'default', 'docker.sock'),
+        join(home, '.orbstack', 'run', 'docker.sock'),
+        systemSocket,
+    ];
+    return candidates.find((candidate) => isUnixSocket(candidate));
+}
+/** @internal — TCP probe: can a client connect to host:port?
+ *
+ * @param host - Bind/target host.
+ * @param port - TCP port.
+ * @param timeoutMs - Probe timeout (default 1000).
+ * @returns True when a connection is accepted.
+ */
+export function canConnectTcp(host, port, timeoutMs = 1000) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port });
+        const done = (ok) => {
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+        setTimeout(() => done(false), timeoutMs);
+    });
+}
+/** Spawns the detached host bridge (or reports it is already up).
+ *
+ * @param args - role (pidfile/log naming), bind host + port and the
+ *   forward socket (unix path on the host).
+ * @returns The outcome; nothing is spawned when the port is already
+ *   served.
+ */
+export async function startHostBridge(args) {
+    if (await canConnectTcp(args.bindHost, args.port)) {
+        logger.ok(`A listener is already bound to TCP port ${args.port} — assuming the bridge is up.`);
+        return { state: 'already-up' };
+    }
+    const pidFile = bridgePidFile(args.role);
+    const pid = spawnDetached(process.execPath, [
+        bridgeJsPath(),
+        '--listen',
+        `tcp:${args.bindHost}:${args.port}`,
+        '--forward',
+        `unix:${args.forwardSocket}`,
+        '--pidfile',
+        pidFile,
+    ], { logFile: bridgeLogFile(args.role) });
+    if (pid <= 0) {
+        logger.warn('host bridge failed to start — check the agent socket path.');
+        return { state: 'failed' };
+    }
+    // Give the bridge a moment to bind; a dead socket path makes the
+    // listener exit immediately (the legacy `kill -0` sleep-1 check).
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    if (!isAlive(pid) && !readPidFile(pidFile)) {
+        rmSync(pidFile, { force: true });
+        logger.warn('host bridge exited immediately — check the agent socket path.');
+        return { state: 'failed' };
+    }
+    logger.ok(`Host bridge is up (pid ${pid}).`);
+    return { state: 'started', pid };
+}
+/** Stops the detached bridge for a role: pidfile → killTree, pidfile
+ *  removed. No-op when nothing is running (idempotent, like the legacy
+ *  stop script's "no listener" branch).
+ *
+ * @param role - The bridge role.
+ * @returns The pid when something was stopped, undefined otherwise.
+ */
+export async function stopHostBridge(role) {
+    const pidFile = bridgePidFile(role);
+    const pid = readPidFile(pidFile);
+    if (pid !== undefined && isAlive(pid)) {
+        await killTree(pid);
+        rmSync(pidFile, { force: true });
+        return pid;
+    }
+    rmSync(pidFile, { force: true });
+    return undefined;
+}
+/** Ensures the logs/state dir exists (pidfiles + logs for the bridges
+ *  and the tart run log).
+ */
+export function ensureBridgeDir() {
+    mkdirSync(dirname(bridgePidFile('ssh-agent')), { recursive: true });
+}

package/dist/runners/framework.js

@@ -0,0 +1,66 @@
+// runners/framework.ts — the shared runner flow: the step order and state
+// types every platform backend follows, plus the host/arch preflight. The
+// four backends (runners/macos.ts, runners/windows-qemu.ts,
+// runners/windows.ts, runners/ubuntu.ts) implement the per-platform hooks;
+// the step titles and their order stay shell-identical.
+//
+// Step order: preflight → 1 image+VM → 2 boot → 3 bridges + rules → 4
+// settings → 5 OpenChamber → summary → foreground wait.
+import { logger } from '../lib/logger.js';
+/** Builds a fresh state object for a run.
+ *
+ * @param context - The run context (mode + log dir).
+ * @returns The initial state.
+ */
+function createRunState(context) {
+    return {
+        mode: context.options.headless ? 'headless' : 'gui',
+        created: false,
+        vmAlreadyRunning: false,
+        tartLog: '',
+        bridges: {
+            agent: { bridged: false, guestUp: false },
+            docker: { bridged: false, guestUp: false, engineUp: false },
+        },
+        rules: 'not-installed',
+        settings: 'skipped',
+        openchamberUp: false,
+        sharedFolderSkipped: false,
+    };
+}
+/** The host requirement, shared by every backend (doctor's §1 checks).
+ *  Host = macOS Apple Silicon; the runners cannot virtualize ARM64
+ *  guests on Intel.
+ */
+function assertSandboxHost() {
+    if (process.platform !== 'darwin') {
+        logger.die('the sandbox runners run on macOS only (Linux is not supported at runtime).');
+    }
+    if (process.arch !== 'arm64') {
+        logger.die('Apple Silicon required — Tart/QEMU/Fusion cannot virtualize ARM64 guests on Intel.');
+    }
+}
+/** Runs the shared step order for a backend.
+ *
+ * @param backend - The platform backend.
+ * @param context - The resolved run context.
+ * @returns The process exit code (0 after a successful run).
+ */
+export async function runSandbox(backend, context) {
+    assertSandboxHost();
+    const state = createRunState(context);
+    await backend.preflight(context, state);
+    logger.step('Step 1/5: Sandbox image and working VM');
+    await backend.ensureImageAndVm(context, state);
+    logger.step('Step 2/5: Starting the VM');
+    await backend.boot(context, state);
+    logger.step('Step 3/5: Host bridges (SSH agent, Docker)');
+    await backend.setupBridges(context, state);
+    logger.step('Step 4/5: User settings');
+    await backend.setupSettings(context, state);
+    logger.step('Step 5/5: OpenChamber');
+    await backend.verifyOpenchamber(context, state);
+    await backend.summarize(context, state);
+    await backend.finish(context, state);
+    return 0;
+}

package/dist/runners/macos-bridges.js

@@ -0,0 +1,143 @@
+// runners/macos-bridges.ts — step 3 for the macOS backend: the host side
+// of the SSH agent + Docker bridges (socket discovery + detached bridge.js
+// spawn). The guest side (upload/install/status) lives in macos-guest.ts,
+// the rules step in macos-rules.ts; this module wires them together —
+// port of run-macos-sandbox.sh §step 3, with the socat pair replaced by
+// the Node forwarder on both sides.
+import { sleep } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { execVm, findGuestNode, gatewayFromVmIp, vmIp } from '../lib/tart.js';
+import { findHostAgentSocket, findHostDockerSocket, startHostBridge } from './bridges.js';
+import { ensureGuestAgent, readGuestStatus } from './macos-guest.js';
+import { installAgentRules } from './macos-rules.js';
+/** The macOS step 3: guest agent + bridges (agent/docker) + rules. The
+ *  guest agent is installed up front (rules need it; install is
+ *  idempotent), then each bridge is wired independently.
+ */
+export async function macosBridges(context, state) {
+    const node = await findGuestNode(context.vm);
+    if (!node) {
+        logger.warn('node not found in the guest — skipping the guest bridges and rules.');
+        return;
+    }
+    const gateway = await resolveGateway(context, state);
+    await ensureGuestAgent(context, node, gateway);
+    if (context.options.noAgent) {
+        logger.info('Skipping SSH agent bridge setup (--no-agent).');
+    }
+    else {
+        await setupSshAgent(context, state, node);
+    }
+    if (context.options.noDocker) {
+        logger.info('Skipping Docker bridge setup (--no-docker).');
+    }
+    else {
+        await setupDockerBridge(context, state, node);
+    }
+    await installAgentRules(context, state, node);
+}
+/** The host's address on Tart's VM network (`.1` of the VM's /24),
+ *  retrying the IP fetch — it can fail right after boot.
+ */
+async function resolveGateway(context, state) {
+    let ip = state.vmIp;
+    for (let attempt = 0; attempt < 5 && !ip; attempt += 1) {
+        ip = await vmIp(context.vm);
+        if (!ip) {
+            await sleep(2000);
+        }
+    }
+    state.vmIp = ip;
+    if (!ip) {
+        return undefined;
+    }
+    return gatewayFromVmIp(ip);
+}
+async function setupSshAgent(context, state, node) {
+    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 '${context.vm}' on TCP port ${context.agentPort} (see docs/ssh-agent.md).`);
+    if (!(await startBridge(context, state, 'ssh-agent', sock))) {
+        return;
+    }
+    await readGuestStatus(context, state, node);
+    if (state.bridges.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.');
+    }
+}
+async function setupDockerBridge(context, state, node) {
+    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 '${context.vm}' on TCP port ${context.dockerPort}.`);
+    if (!(await startBridge(context, state, 'docker', sock))) {
+        return;
+    }
+    await readGuestStatus(context, state, node);
+    if (state.bridges.docker.guestUp) {
+        logger.ok(`Guest Docker bridge is up: ~/.docker/run/docker.sock -> host TCP ${context.dockerPort}`);
+    }
+    else {
+        logger.warn('guest Docker bridge did not start — check the guest agent install.');
+        return;
+    }
+    await verifyGuestDocker(context, state);
+}
+/** The shared bridge start: gateway resolution + host spawn + state
+ *  bookkeeping. Returns false when the bridge was skipped.
+ */
+async function startBridge(context, state, role, socket) {
+    const gateway = await resolveGateway(context, state);
+    if (!gateway) {
+        logger.warn(`could not determine the host gateway address ('tart ip ${context.vm}' failed).`);
+        return false;
+    }
+    const result = await startHostBridge({
+        role,
+        bindHost: gateway,
+        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;
+}
+/** 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(context, state) {
+    const probe = 'export PATH="/opt/homebrew/bin:$PATH"; docker info --format "{{.ServerVersion}}"';
+    for (let attempt = 0; attempt < 15; attempt += 1) {
+        const res = await execVm(context.vm, ['sh', '-c', probe]);
+        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 this script to re-check.');
+}