windows-development-sandbox 1.5.0 → 1.9.0

package/dist/guest/toolchains/runtimes.js

@@ -1,7 +1,7 @@
 // Bun, uv and Deno: single-binary tools from GitHub releases (claude-mem needs Bun and uv).
 import path from 'node:path';
 import { dryRun, localDir } from '../runtime/paths.js';
-import { exists } from '../runtime/fs.js';
+import { exists, mkdirp } from '../runtime/fs.js';
 import { log } from '../runtime/log.js';
 import { arch, tool, versionOf } from './tool-env.js';
 import { installFromGithub } from './install.js';
@@ -52,5 +52,5 @@ export function uvVars() {
 export async function setupUv(env) {
     await setupSingleExe(env, 'uv', 'astral-sh/uv', arch === 'arm64' ? /^uv-aarch64-pc-windows-msvc\.zip$/ : /^uv-x86_64-pc-windows-msvc\.zip$/, 'uv.exe', tool('uv'), { size: '20 MB' });
     Object.assign(env.vars, uvVars());
-    env.prepend.push(tool('uv-bin'));
+    env.prepend.push(mkdirp(tool('uv-bin')));
 }

package/dist/guest/vpn/index.d.ts

@@ -0,0 +1 @@
+export { setupVpn, setVpnStatus } from './vpn.js';

package/dist/guest/vpn/index.js

@@ -0,0 +1 @@
+export { setupVpn, setVpnStatus } from './vpn.js';

package/dist/guest/vpn/openvpn.d.ts

@@ -0,0 +1,9 @@
+/** Where the MSI puts the program. */
+export declare function openvpnExe(env?: NodeJS.ProcessEnv): string;
+export declare function openvpnDownload(arch?: string): {
+    file: string;
+    sha256: string;
+    url: string;
+};
+/** Installs OpenVPN unless it is there; returns the path of openvpn.exe. Throws with the reason when it cannot. */
+export declare function ensureOpenVpn(): Promise<string>;

package/dist/guest/vpn/openvpn.js

@@ -0,0 +1,47 @@
+// OpenVPN Community for the sandbox: one checksummed MSI from the publisher, installed silently (it brings the driver).
+// The sandbox is new at every boot, so the install runs each time; the MSI itself is cached in the persistent tools
+// folder. downloads.requireChecksum is honoured by the downloader (this entry has a checksum, so it always passes).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { downloader, spawnAsync } from '../../shared/download/index.js';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, isWin, toolsDir } from '../runtime/paths.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { log } from '../runtime/log.js';
+import { OPENVPN_MSI } from '../../shared/vpn/download.js';
+/** Where the MSI puts the program. */
+export function openvpnExe(env = process.env) {
+    return path.join(env.ProgramFiles ?? 'C:\\Program Files', 'OpenVPN', 'bin', 'openvpn.exe');
+}
+export function openvpnDownload(arch = process.arch) {
+    const entry = arch === 'arm64' ? OPENVPN_MSI.arm64 : OPENVPN_MSI.x64;
+    return { ...entry, url: OPENVPN_MSI.base + entry.file };
+}
+const hasHash = (file, sha256) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') === sha256;
+/** Installs OpenVPN unless it is there; returns the path of openvpn.exe. Throws with the reason when it cannot. */
+export async function ensureOpenVpn() {
+    const exe = openvpnExe();
+    if (!isWin || dryRun)
+        return exe;
+    if (exists(exe))
+        return exe;
+    const dl = openvpnDownload();
+    const msi = path.join(mkdirp(path.join(toolsDir, 'downloads')), dl.file);
+    // The tools folder lasts between sandboxes and the agent can write it: a cached file is trusted only by its hash.
+    if (!exists(msi) || !hasHash(msi, dl.sha256)) {
+        log('VPN: downloading OpenVPN ' + OPENVPN_MSI.version + ' (about 6 MB)');
+        await downloader.file(dl.url, msi, dl.sha256);
+    }
+    log('VPN: installing OpenVPN');
+    const logFile = path.join(toolsDir, 'downloads', 'openvpn-install.log');
+    const code = await spawnAsync(SYSTEM.msiexec(), ['/i', msi, '/qn', '/norestart', '/l*v', logFile], {
+        stdio: 'ignore',
+    });
+    // 3010: installed, a restart is wanted (nothing here needs one).
+    if (code !== 0 && code !== 3010)
+        throw new Error('The OpenVPN installer failed (exit ' + code + '). Its log: ' + logFile);
+    if (!exists(exe))
+        throw new Error('OpenVPN was installed but ' + exe + ' is missing. The installer log: ' + logFile);
+    return exe;
+}

package/dist/guest/vpn/tunnel.d.ts

@@ -0,0 +1,17 @@
+export interface TunnelOutcome {
+    readonly ok: boolean;
+    readonly message: string;
+    /** The tunnel's own address (what the kill switch lets through). */
+    readonly tunnelIp?: string;
+}
+export interface TunnelOptions {
+    readonly exe: string;
+    readonly profile: string;
+    readonly username: string;
+    readonly password: string;
+    readonly timeoutMs?: number;
+}
+/** Why the log says OpenVPN stopped, in a short plain sentence (or null when it does not say). */
+export declare function failureReason(text: string): string | null;
+/** Connects. Never leaves the login on disk; kills OpenVPN when the tunnel does not come up in time. */
+export declare function startTunnel(o: TunnelOptions): Promise<TunnelOutcome>;

package/dist/guest/vpn/tunnel.js

@@ -0,0 +1,78 @@
+// Starts OpenVPN with the login in a file that exists only while it connects, waits for the tunnel, and reports. The
+// file is deleted as soon as the tunnel is up (or has failed). OpenVPN reads it again when it must log in again, so a
+// tunnel that drops does not come back on its own (the kill switch then keeps the sandbox offline): the sandbox's
+// login is not left on disk for that.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { tunnelAddressFromLog } from '../../shared/vpn/kill-switch.js';
+import { logsDir } from '../runtime/paths.js';
+import { log } from '../runtime/log.js';
+const DONE = 'Initialization Sequence Completed';
+/** Why the log says OpenVPN stopped, in a short plain sentence (or null when it does not say). */
+export function failureReason(text) {
+    if (/AUTH_FAILED/i.test(text))
+        return 'the VPN refused the login (for NordVPN use the service credentials, not your account password)';
+    if (/TLS Error: TLS key negotiation failed|TLS handshake failed/i.test(text))
+        return 'it could not reach the VPN server (the network blocks it, or the server is down)';
+    if (/All wintun adapters on this system are in use|Cannot open TUN\/TAP|Could not create Wintun|ovpn-dco.*(error|failed)/i.test(text))
+        return 'the network driver for the tunnel could not be used';
+    if (/Exiting due to fatal error/i.test(text))
+        return 'OpenVPN stopped with an error';
+    return null;
+}
+const tail = (text, lines = 12) => text.trim().split(/\r?\n/).slice(-lines).join('\n');
+/** Connects. Never leaves the login on disk; kills OpenVPN when the tunnel does not come up in time. */
+export async function startTunnel(o) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sbx-vpn-'));
+    const auth = path.join(dir, 'login.txt');
+    const logFile = path.join(dir, 'openvpn.log');
+    const keepLog = () => {
+        try {
+            fs.mkdirSync(logsDir, { recursive: true });
+            fs.copyFileSync(logFile, path.join(logsDir, 'openvpn.log'));
+        }
+        catch {
+            // The log is only for finding out what went wrong.
+        }
+    };
+    fs.writeFileSync(auth, o.username + '\r\n' + o.password + '\r\n', 'utf8');
+    try {
+        const child = spawn(o.exe, ['--config', o.profile, '--auth-user-pass', auth, '--auth-nocache', '--verb', '3', '--log', logFile], { detached: true, stdio: 'ignore', windowsHide: true });
+        let exited = null;
+        child.once('exit', (code) => {
+            exited = code ?? -1;
+        });
+        child.once('error', (e) => {
+            exited = -1;
+            log('VPN: could not start OpenVPN: ' + e.message);
+        });
+        child.unref();
+        const deadline = Date.now() + (o.timeoutMs ?? 90000);
+        for (;;) {
+            const text = fs.existsSync(logFile) ? fs.readFileSync(logFile, 'utf8') : '';
+            if (text.includes(DONE)) {
+                keepLog();
+                const tunnelIp = tunnelAddressFromLog(text) ?? undefined;
+                return { ok: true, message: 'the tunnel is up', ...(tunnelIp ? { tunnelIp } : {}) };
+            }
+            const reason = failureReason(text);
+            if (exited !== null || reason) {
+                if (exited === null)
+                    child.kill();
+                keepLog();
+                return { ok: false, message: (reason ?? 'OpenVPN stopped') + '. ' + tail(text, 4) };
+            }
+            if (Date.now() > deadline) {
+                child.kill();
+                keepLog();
+                return { ok: false, message: 'the tunnel did not come up in time. ' + tail(text, 4) };
+            }
+            await new Promise((r) => setTimeout(r, 500));
+        }
+    }
+    finally {
+        fs.rmSync(auth, { force: true });
+    }
+}

package/dist/guest/vpn/vpn.d.ts

@@ -0,0 +1,6 @@
+import type { VpnStatus } from '../../shared/channel/schema.js';
+import type { SecretsFile } from '../../shared/channel/secrets.js';
+/** Writes run\vpn.json (what `sandbox vpn status` and the launch show). Never throws. */
+export declare function setVpnStatus(state: VpnStatus['state'], message: string, extra?: Partial<VpnStatus>): void;
+/** The whole step. Returns true when the tunnel is up. */
+export declare function setupVpn(secrets: SecretsFile, ptyHostExe: string | null): Promise<boolean>;

package/dist/guest/vpn/vpn.js

@@ -0,0 +1,174 @@
+// The VPN boot step (after the toolchains, before the agent): install OpenVPN, block everything that does not go
+// through the tunnel (the kill switch, applied BEFORE the tunnel starts), connect, check, delete the login, report. A
+// tunnel that fails never stops the boot: with the kill switch the sandbox stays offline and says so; without it, it
+// warns.
+import dns from 'node:dns';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { now } from '../../shared/channel/run-dir.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { assertSafeOvpn } from '../../shared/vpn/ovpn.js';
+import { assertSafeWireguard, renderWireguard, routesEverything, wireguardEndpoints, wireguardTunnelAddress, } from '../../shared/vpn/wireguard.js';
+import { isIPv4 } from '../../shared/network/firewall-rules.js';
+import { killSwitchCommands, tunnelCommands } from '../../shared/vpn/kill-switch.js';
+import { errMsg } from '../../core/util/errors.js';
+import { run as netsh } from '../network/firewall.js';
+import { dryRun, isWin, launchDir, run } from '../runtime/paths.js';
+import { log, warn } from '../runtime/log.js';
+import { session } from '../runtime/session.js';
+import { ensureOpenVpn } from './openvpn.js';
+import { startTunnel } from './tunnel.js';
+import { ensureWireguard, removeWireguardTunnel, startWireguardTunnel, waitForHandshake } from './wireguard.js';
+/** Writes run\vpn.json (what `sandbox vpn status` and the launch show). Never throws. */
+export function setVpnStatus(state, message, extra = {}) {
+    try {
+        writeJsonAtomic(run.vpnFile, {
+            state,
+            message: message.slice(0, 1900),
+            killSwitch: session.vpn?.killSwitch ?? false,
+            updatedAt: now(),
+            ...(session.vpn ? { server: session.vpn.server.slice(0, 120) } : {}),
+            ...extra,
+        });
+    }
+    catch (e) {
+        warn('Could not write the VPN status: ' + errMsg(e));
+    }
+}
+/** IPv4 addresses of the servers the profile names: names are looked up now, before the kill switch closes DNS. */
+async function serverAddresses(remotes) {
+    const out = [];
+    for (const r of remotes) {
+        const ips = isIPv4(r.host)
+            ? [r.host]
+            : await dns.promises.lookup(r.host, { all: true, family: 4 }).then((all) => all.map((a) => a.address), () => []);
+        for (const ip of ips)
+            out.push({ ip, port: r.port, proto: r.proto });
+    }
+    return out;
+}
+/** The WireGuard peers' endpoints as IPv4 servers (udp), and the config with those addresses in place of host names. */
+async function wireguardServers(config) {
+    const endpointIps = {};
+    const servers = [];
+    const found = wireguardEndpoints(config);
+    for (let i = 0; i < found.length; i++) {
+        const [ip] = await serverAddresses([{ host: found[i].host, port: found[i].port, proto: 'udp' }]).then((all) => all.map((s) => s.ip));
+        if (!ip)
+            throw new Error('the VPN server address could not be found');
+        // WireGuard looks the name up itself at start, after the kill switch has closed DNS: give it the address.
+        endpointIps[i] = ip;
+        servers.push({ ip, port: found[i].port, proto: 'udp' });
+    }
+    return { servers, text: renderWireguard(config, endpointIps) };
+}
+/** What the sandbox looks like from outside, through the tunnel (null when it cannot be told quickly). */
+async function publicAddress() {
+    try {
+        const text = (await (await fetch('https://api.ipify.org', { signal: AbortSignal.timeout(10000) })).text()).trim();
+        return /^[0-9a-fA-F.:]{3,45}$/.test(text) ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+const hasAdapter = (ip) => Object.values(os.networkInterfaces()).some((list) => (list ?? []).some((i) => i.address === ip));
+/** The whole step. Returns true when the tunnel is up. */
+export async function setupVpn(secrets, ptyHostExe) {
+    const vpn = session.vpn;
+    if (!vpn)
+        return true;
+    const killSwitch = vpn.killSwitch;
+    let blocked = false;
+    const block = (servers) => {
+        if (isWin && !dryRun)
+            netsh(killSwitchCommands(servers, ptyHostExe));
+        blocked = true;
+        log('VPN: kill switch on: nothing leaves the sandbox except through the tunnel.');
+    };
+    setVpnStatus('starting', 'Starting the VPN');
+    try {
+        if (!session.networking)
+            throw new Error('networking is off for this sandbox');
+        let result;
+        let wireguardExe = null;
+        if (vpn.provider === 'wireguard-file') {
+            // The config came from the host (through the one-shot file), but it is data like any other: checked again here.
+            if (!secrets.wireguardConfig)
+                throw new Error('the WireGuard config did not arrive (start the sandbox again)');
+            const config = assertSafeWireguard(secrets.wireguardConfig, vpn.server);
+            const exe = await ensureWireguard();
+            const { servers, text } = await wireguardServers(config);
+            if (killSwitch && !routesEverything(config))
+                warn('VPN: AllowedIPs does not include 0.0.0.0/0: with the kill switch on, only the tunnel traffic can leave the sandbox.');
+            if (killSwitch)
+                block(servers);
+            if (dryRun || !isWin) {
+                log('(dry run) would start the WireGuard tunnel ' + vpn.server);
+                setVpnStatus('off', 'dry run');
+                return true;
+            }
+            log('VPN: connecting with ' + vpn.server);
+            wireguardExe = exe;
+            result = await startWireguardTunnel({ exe, config: text, tunnelIp: wireguardTunnelAddress(config) });
+            if (result.ok && result.tunnelIp && killSwitch)
+                netsh(tunnelCommands(result.tunnelIp));
+            if (result.ok)
+                result = await waitForHandshake(exe, publicAddress);
+        }
+        else {
+            const credentials = secrets.vpn;
+            if (!credentials)
+                throw new Error('the VPN login did not arrive (start the sandbox again)');
+            // The profile came from the host, but it is data like any other: checked again here before OpenVPN reads it.
+            const profile = path.join(launchDir, 'vpn', 'server.ovpn');
+            const remotes = assertSafeOvpn(fs.readFileSync(profile, 'utf8'), vpn.server);
+            const exe = await ensureOpenVpn();
+            const servers = await serverAddresses(remotes);
+            if (servers.length === 0)
+                throw new Error('the VPN server addresses could not be found');
+            if (killSwitch)
+                block(servers);
+            if (dryRun || !isWin) {
+                log('(dry run) would start the VPN tunnel to ' + vpn.server);
+                setVpnStatus('off', 'dry run');
+                return true;
+            }
+            log('VPN: connecting to ' + vpn.server);
+            result = await startTunnel({ exe, profile, username: credentials.username, password: credentials.password });
+            if (result.ok && result.tunnelIp && hasAdapter(result.tunnelIp) && killSwitch)
+                netsh(tunnelCommands(result.tunnelIp));
+        }
+        if (!result.ok) {
+            if (wireguardExe)
+                await removeWireguardTunnel(wireguardExe);
+            throw new Error(result.message);
+        }
+        if (!result.tunnelIp || !hasAdapter(result.tunnelIp))
+            throw new Error('the tunnel reported it was up, but no network adapter with its address appeared');
+        const publicIp = await publicAddress();
+        log('VPN: up' + (publicIp ? ' (the sandbox appears as ' + publicIp + ')' : '') + '.');
+        setVpnStatus('up', 'The tunnel is up', publicIp ? { publicIp } : {});
+        return true;
+    }
+    catch (e) {
+        const reason = errMsg(e);
+        // Without the kill switch the sandbox keeps its normal connection: the rest of the boot goes on, with a warning.
+        try {
+            if (killSwitch && !blocked)
+                block([]);
+        }
+        catch (blockError) {
+            warn('VPN: could not close the network after the failure: ' + errMsg(blockError));
+        }
+        const text = 'VPN failed: ' +
+            reason +
+            (killSwitch
+                ? ' The kill switch is on, so this sandbox has NO internet access.'
+                : ' The kill switch is off, so this sandbox is using your normal connection.');
+        warn(text);
+        setVpnStatus('failed', reason);
+        return false;
+    }
+}

package/dist/guest/vpn/wireguard.d.ts

@@ -0,0 +1,32 @@
+import type { TunnelOutcome } from './tunnel.js';
+/** The tunnel's name: the config file is sandbox.conf and the Windows service WireGuardTunnel$sandbox. */
+export declare const WIREGUARD_TUNNEL = "sandbox";
+export declare function wireguardDir(env?: NodeJS.ProcessEnv): string;
+export declare function wireguardExe(env?: NodeJS.ProcessEnv): string;
+export declare function wireguardDownload(arch?: string): {
+    file: string;
+    sha256: string;
+    url: string;
+};
+/** Installs WireGuard unless it is there; returns the path of wireguard.exe. Throws with the reason when it cannot. */
+export declare function ensureWireguard(): Promise<string>;
+/** Takes the tunnel away again (a failed tunnel must not leave a route into nothing). Never throws. */
+export declare function removeWireguardTunnel(exe: string): Promise<void>;
+export interface WireguardOptions {
+    readonly exe: string;
+    /** The checked config text (private key inside). */
+    readonly config: string;
+    /** The tunnel's own IPv4 address from the config's Address. */
+    readonly tunnelIp: string;
+    readonly timeoutMs?: number;
+}
+/**
+ * Installs the tunnel service from a config file that is deleted when the service has it, and waits until the service
+ * runs and its adapter has the tunnel address. Removes the service again when that fails.
+ */
+export declare function startWireguardTunnel(o: WireguardOptions): Promise<TunnelOutcome>;
+/**
+ * Waits for the server to answer: the first handshake. `poke` sends some traffic through the tunnel (a handshake only
+ * starts when there is something to send, unless PersistentKeepalive is set). Without wg.exe the check is skipped.
+ */
+export declare function waitForHandshake(exe: string, poke: () => Promise<unknown>, timeoutMs?: number): Promise<TunnelOutcome>;

package/dist/guest/vpn/wireguard.js

@@ -0,0 +1,132 @@
+// WireGuard for the sandbox: one checksummed MSI from the publisher (installed silently, it brings wireguard.exe and
+// wg.exe), the checked config in a file that exists only while the tunnel service starts, and a wait for the
+// tunnel. The config holds the private key: it is written from the one-shot secrets file and deleted as soon as the
+// service has it (or has failed). The kill switch is applied by the caller BEFORE this runs.
+import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { downloader, spawnAsync } from '../../shared/download/index.js';
+import { SYSTEM } from '../../shared/system.js';
+import { WIREGUARD_MSI } from '../../shared/vpn/download.js';
+import { handshakeDone, serviceRunning } from '../../shared/vpn/wireguard.js';
+import { dryRun, isWin, toolsDir } from '../runtime/paths.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { log } from '../runtime/log.js';
+/** The tunnel's name: the config file is sandbox.conf and the Windows service WireGuardTunnel$sandbox. */
+export const WIREGUARD_TUNNEL = 'sandbox';
+export function wireguardDir(env = process.env) {
+    return path.join(env.ProgramFiles ?? 'C:\\Program Files', 'WireGuard');
+}
+export function wireguardExe(env = process.env) {
+    return path.join(wireguardDir(env), 'wireguard.exe');
+}
+export function wireguardDownload(arch = process.arch) {
+    const entry = arch === 'arm64' ? WIREGUARD_MSI.arm64 : WIREGUARD_MSI.x64;
+    return { ...entry, url: WIREGUARD_MSI.base + entry.file };
+}
+const hasHash = (file, sha256) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') === sha256;
+/** Installs WireGuard unless it is there; returns the path of wireguard.exe. Throws with the reason when it cannot. */
+export async function ensureWireguard() {
+    const exe = wireguardExe();
+    if (!isWin || dryRun)
+        return exe;
+    if (exists(exe))
+        return exe;
+    const dl = wireguardDownload();
+    const msi = path.join(mkdirp(path.join(toolsDir, 'downloads')), dl.file);
+    // The tools folder lasts between sandboxes and the agent can write it: a cached file is trusted only by its hash.
+    if (!exists(msi) || !hasHash(msi, dl.sha256)) {
+        log('VPN: downloading WireGuard ' + WIREGUARD_MSI.version + ' (about 3 MB)');
+        await downloader.file(dl.url, msi, dl.sha256);
+    }
+    log('VPN: installing WireGuard');
+    const logFile = path.join(toolsDir, 'downloads', 'wireguard-install.log');
+    // DO_NOT_LAUNCH: the installer would otherwise start the manager window.
+    const code = await spawnAsync(SYSTEM.msiexec(), ['/i', msi, '/qn', '/norestart', 'DO_NOT_LAUNCH=1', '/l*v', logFile], {
+        stdio: 'ignore',
+    });
+    if (code !== 0 && code !== 3010)
+        throw new Error('The WireGuard installer failed (exit ' + code + '). Its log: ' + logFile);
+    if (!exists(exe))
+        throw new Error('WireGuard was installed but ' + exe + ' is missing. The installer log: ' + logFile);
+    return exe;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function output(file, args) {
+    return new Promise((resolve) => {
+        execFile(file, args, { windowsHide: true, timeout: 15000, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+            const code = error ? (typeof error.code === 'number' ? error.code : -1) : 0;
+            resolve({ code, text: String(stdout) + String(stderr) });
+        });
+    });
+}
+const serviceName = () => 'WireGuardTunnel$' + WIREGUARD_TUNNEL;
+const hasAdapter = (ip) => Object.values(os.networkInterfaces()).some((list) => (list ?? []).some((i) => i.address === ip));
+/** Takes the tunnel away again (a failed tunnel must not leave a route into nothing). Never throws. */
+export async function removeWireguardTunnel(exe) {
+    try {
+        await output(exe, ['/uninstalltunnelservice', WIREGUARD_TUNNEL]);
+    }
+    catch {
+        // Nothing installed, nothing to remove.
+    }
+}
+/**
+ * Installs the tunnel service from a config file that is deleted when the service has it, and waits until the service
+ * runs and its adapter has the tunnel address. Removes the service again when that fails.
+ */
+export async function startWireguardTunnel(o) {
+    const root = path.join(process.env.SystemRoot ?? 'C:\\Windows', 'Temp');
+    const dir = fs.mkdtempSync(path.join(fs.existsSync(root) ? root : os.tmpdir(), 'sbx-wg-'));
+    const file = path.join(dir, WIREGUARD_TUNNEL + '.conf');
+    fs.writeFileSync(file, o.config, 'utf8');
+    const fail = async (message) => {
+        await removeWireguardTunnel(o.exe);
+        return { ok: false, message };
+    };
+    try {
+        const install = await output(o.exe, ['/installtunnelservice', file]);
+        if (install.code !== 0)
+            return await fail('WireGuard could not install the tunnel (exit ' + install.code + ')');
+        const deadline = Date.now() + (o.timeoutMs ?? 60000);
+        for (;;) {
+            const state = await output(SYSTEM.sc(), ['query', serviceName()]);
+            if (serviceRunning(state.text) && hasAdapter(o.tunnelIp)) {
+                return { ok: true, message: 'the tunnel service is running', tunnelIp: o.tunnelIp };
+            }
+            if (/STOPPED/i.test(state.text) || /1060/.test(state.text))
+                return await fail('the WireGuard tunnel service stopped (check the config: keys, address, endpoint)');
+            if (Date.now() > deadline)
+                return await fail('the WireGuard tunnel did not start in time (the network driver may not work here)');
+            await sleep(500);
+        }
+    }
+    finally {
+        // The service has read the file by now (or never will): the private key is not left on disk.
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Waits for the server to answer: the first handshake. `poke` sends some traffic through the tunnel (a handshake only
+ * starts when there is something to send, unless PersistentKeepalive is set). Without wg.exe the check is skipped.
+ */
+export async function waitForHandshake(exe, poke, timeoutMs = 30000) {
+    const wg = path.join(path.dirname(exe), 'wg.exe');
+    if (!exists(wg))
+        return { ok: true, message: 'the tunnel service is running (no wg.exe to check the handshake)' };
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        await poke().catch(() => undefined);
+        const shown = await output(wg, ['show', WIREGUARD_TUNNEL, 'latest-handshakes']);
+        if (shown.code === 0 && handshakeDone(shown.text))
+            return { ok: true, message: 'the server answered' };
+        if (Date.now() > deadline)
+            return {
+                ok: false,
+                message: 'the VPN server did not answer (check the endpoint, the keys and that its UDP port is reachable)',
+            };
+        await sleep(1000);
+    }
+}

package/dist/host/agent-commands/commands.d.ts

@@ -9,5 +9,9 @@ export interface AgentCommand {
 export declare function cmdSafe(p: string): boolean;
 /** The agent's own executable on this PC, skipping this tool's forwarding files. */
 export declare function realAgent(command: string, skipDir: string, pathValue?: string): string | null;
+/** realAgent without blocking the program: every candidate is looked up at once, the first in PATH order wins. */
+export declare function realAgentAsync(command: string, skipDir: string, pathValue?: string): Promise<string | null>;
 /** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
 export declare function agentCommands(config: Config, storageRoot: string, pathValue?: string): AgentCommand[];
+/** agentCommands without blocking the program. */
+export declare function agentCommandsAsync(config: Config, storageRoot: string, pathValue?: string): Promise<AgentCommand[]>;

package/dist/host/agent-commands/commands.js

@@ -3,7 +3,7 @@
 // <storage>\agent-commands go first on YOUR PATH (so they win over npm's and the installers' copies); turning it off
 // removes the files and that one PATH entry. SANDBOX_AGENT_DIRECT=1 runs the real agent on this PC instead.
 import path from 'node:path';
-import { fileExists } from '../../core/util/index.js';
+import { fileExists, fileExistsAsync } from '../../core/util/index.js';
 export function commandsDir(storageRoot) {
     return path.join(storageRoot, 'agent-commands');
 }
@@ -12,11 +12,14 @@ const EXTENSIONS = ['.exe', '.cmd', '.bat'];
 export function cmdSafe(p) {
     return !/[%"^\r\n]/.test(p);
 }
+/** The folders of PATH to look in, without this tool's forwarding folder. */
+function searchDirs(skipDir, pathValue) {
+    const skip = path.resolve(skipDir).toLowerCase();
+    return pathValue.split(path.delimiter).filter((d) => d && path.resolve(d).toLowerCase() !== skip);
+}
 /** The agent's own executable on this PC, skipping this tool's forwarding files. */
 export function realAgent(command, skipDir, pathValue = process.env.PATH ?? process.env.Path ?? '') {
-    const skip = path.resolve(skipDir).toLowerCase();
-    const dirs = pathValue.split(path.delimiter).filter((d) => d && path.resolve(d).toLowerCase() !== skip);
-    for (const dir of dirs)
+    for (const dir of searchDirs(skipDir, pathValue))
         for (const ext of EXTENSIONS) {
             const candidate = path.join(dir, command + ext);
             if (fileExists(candidate))
@@ -24,14 +27,35 @@ export function realAgent(command, skipDir, pathValue = process.env.PATH ?? proc
         }
     return null;
 }
-/** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
-export function agentCommands(config, storageRoot, pathValue) {
+/** realAgent without blocking the program: every candidate is looked up at once, the first in PATH order wins. */
+export async function realAgentAsync(command, skipDir, pathValue = process.env.PATH ?? process.env.Path ?? '') {
+    const candidates = searchDirs(skipDir, pathValue).flatMap((dir) => EXTENSIONS.map((ext) => path.join(dir, command + ext)));
+    const found = await Promise.all(candidates.map(fileExistsAsync));
+    const at = found.indexOf(true);
+    return at < 0 ? null : candidates[at];
+}
+/** The agents that may get a forwarding command (listed, or "auto" = all) and the command each is typed as. */
+function wantedCommands(config) {
     const wanted = config.agentCommands.agents;
     return Object.entries(config.harnesses).flatMap(([harness, h]) => {
         if (wanted !== 'auto' && !wanted.includes(harness))
             return [];
         const command = h.npmBin ?? (h.hostExecutable ? path.parse(h.hostExecutable).name : harness);
-        const real = /^[A-Za-z0-9._-]+$/.test(command) ? realAgent(command, commandsDir(storageRoot), pathValue) : null;
+        return /^[A-Za-z0-9._-]+$/.test(command) ? [{ harness, command }] : [];
+    });
+}
+/** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
+export function agentCommands(config, storageRoot, pathValue) {
+    return wantedCommands(config).flatMap(({ harness, command }) => {
+        const real = realAgent(command, commandsDir(storageRoot), pathValue);
         return real && cmdSafe(real) ? [{ harness, command, real }] : [];
     });
 }
+/** agentCommands without blocking the program. */
+export async function agentCommandsAsync(config, storageRoot, pathValue) {
+    const found = await Promise.all(wantedCommands(config).map(async ({ harness, command }) => {
+        const real = await realAgentAsync(command, commandsDir(storageRoot), pathValue);
+        return real && cmdSafe(real) ? [{ harness, command, real }] : [];
+    }));
+    return found.flat();
+}

package/dist/host/audit/log.d.ts

@@ -5,9 +5,9 @@ export declare const AuditEventSchema: z.ZodObject<{
     k: z.ZodEnum<{
         file: "file";
         session: "session";
+        note: "note";
         proc: "proc";
         guard: "guard";
-        note: "note";
     }>;
     p: z.ZodOptional<z.ZodString>;
     c: z.ZodOptional<z.ZodString>;

package/dist/host/channel/attach.d.ts

@@ -1,11 +1,13 @@
 import os from 'node:os';
 import type { SessionStatus } from '../../core/types.js';
-import { type Viewers } from '../../shared/pty/index.js';
+import { type Endpoint, type Viewers } from '../../shared/pty/index.js';
 /**
  * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
  * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
  */
 export declare function isSandboxAddress(ip: string, interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>): boolean;
+/** Where this PC may connect for a session: only addresses on its own Hyper-V network (null if there are none). */
+export declare const hostEndpoint: (session: SessionStatus) => Endpoint | null;
 /** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
 export declare function sessionViewers(session: SessionStatus): Promise<Viewers | null>;
 /**
@@ -14,4 +16,6 @@ export declare function sessionViewers(session: SessionStatus): Promise<Viewers
  */
 export declare function findUnwatchedSession(dataPath: string, harness: string, cwd: string): Promise<SessionStatus | null>;
 /** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
-export declare function attachTerminal(session: SessionStatus): Promise<number>;
+export declare function attachTerminal(session: SessionStatus, o?: {
+    clipboardWrites?: boolean;
+}): Promise<number>;