windows-development-sandbox 1.7.0 → 1.9.0

package/dist/guest/governor/governor.js

@@ -0,0 +1,214 @@
+// The memory governor: samples the sandbox's memory every 2 seconds (memgov.exe, sandbox/csharp/MemGov.cs) and, when it
+// runs low, slows the heaviest build programs the agents started down and, as a last resort, pauses the biggest
+// compiler for a few seconds (decide.ts). What it does goes to the memory log and run\pressure.json, for the host.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { z } from 'zod';
+import { now } from '../../shared/channel/run-dir.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { GUEST_THRESHOLDS } from '../../shared/memory/index.js';
+import { ensureCompiled } from '../runtime/csc.js';
+import { dataDir } from '../runtime/paths.js';
+import { warn } from '../runtime/log.js';
+import { run } from '../runtime/paths.js';
+import { session } from '../runtime/session.js';
+import { errMsg } from '../../core/util/errors.js';
+import { decide, INITIAL_STATE } from './decide.js';
+const SampleSchema = z.object({
+    ramTotalMb: z.number(),
+    ramAvailMb: z.number(),
+    commitLimitMb: z.number(),
+    commitAvailMb: z.number(),
+    procs: z
+        .array(z.object({
+        pid: z.number().int(),
+        name: z.string().max(128),
+        mb: z.number(),
+        prio: z.enum(['idle', 'below', 'normal']).catch('normal'),
+    }))
+        .max(1024),
+});
+/** The governor's logic over a port: feed it samples; the host's "slow down" requests go to hostPressure. */
+export class GovernorCore {
+    deps;
+    state = INITIAL_STATE;
+    lastAction = '';
+    lastWrite = '';
+    lastWriteAt = 0;
+    pausedName = '';
+    pausedPid = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    hostPressure(seconds, reason) {
+        const until = this.deps.now() + seconds * 1000;
+        if (until > this.state.hostUntil) {
+            if (this.state.hostUntil <= this.deps.now())
+                this.deps.logLine('governor: this PC is low (' + reason + '); slowing builds down');
+            this.state = { ...this.state, hostUntil: until };
+        }
+    }
+    get current() {
+        return this.state;
+    }
+    onSample(sample) {
+        const nowMs = this.deps.now();
+        const before = this.state.pressure;
+        const d = decide(this.state, sample, nowMs, GUEST_THRESHOLDS[this.deps.profile], this.deps.profile);
+        this.state = d.state;
+        for (const action of d.actions)
+            this.apply(action);
+        if (d.state.pressure !== before)
+            this.deps.logLine(d.state.pressure
+                ? 'governor: memory is low (' +
+                    d.ramFreePercent +
+                    '% RAM free, commit ' +
+                    d.commitPercent +
+                    '% used): slowing builds down'
+                : 'governor: memory is fine again: builds back to normal');
+        const paused = nowMs < d.state.pausedUntil && this.pausedPid
+            ? [{ name: this.pausedName, pid: this.pausedPid, seconds: Math.ceil((d.state.pausedUntil - nowMs) / 1000) }]
+            : [];
+        const status = {
+            level: d.level,
+            profile: this.deps.profile,
+            ramFreePercent: Math.max(0, Math.min(100, d.ramFreePercent)),
+            commitPercent: Math.max(0, Math.min(100, d.commitPercent)),
+            lowered: Object.keys(d.state.lowered).length,
+            paused,
+            pcLow: nowMs < d.state.hostUntil,
+            lastAction: this.lastAction,
+            updatedAt: now(),
+        };
+        // Written when something changed, else once a minute (the host reads it, never polls it hard).
+        const shape = JSON.stringify({ ...status, updatedAt: '', paused: paused.map((p) => p.pid) });
+        if (shape !== this.lastWrite || nowMs - this.lastWriteAt > 60000) {
+            this.lastWrite = shape;
+            this.lastWriteAt = nowMs;
+            this.deps.saveStatus(status);
+        }
+    }
+    apply(action) {
+        try {
+            if (action.kind === 'priority') {
+                this.deps.port.setPriority(action.pid, action.to);
+                this.lastAction = action.name + ' (' + action.pid + ') priority ' + action.to;
+            }
+            else {
+                this.deps.port.pause(action.pid, action.ms);
+                this.pausedName = action.name;
+                this.pausedPid = action.pid;
+                this.lastAction = 'paused ' + action.name + ' (' + action.pid + ') for ' + action.ms / 1000 + ' s';
+                this.deps.logLine('governor: ' + this.lastAction);
+                return;
+            }
+            this.deps.logLine('governor: ' + this.lastAction);
+        }
+        catch (e) {
+            warn('governor: ' + errMsg(e));
+        }
+    }
+}
+/** memgov.exe as a child process: samples come out of its stdout, commands go into its stdin. */
+class MemGovProcess {
+    onSample;
+    child = null;
+    constructor(onSample) {
+        this.onSample = onSample;
+    }
+    start() {
+        try {
+            const child = spawn(ensureCompiled('memgov'), ['serve', '--interval', '2'], {
+                stdio: ['pipe', 'pipe', 'ignore'],
+                windowsHide: true,
+            });
+            this.child = child;
+            createInterface({ input: child.stdout }).on('line', (line) => {
+                try {
+                    this.onSample(SampleSchema.parse(JSON.parse(line)));
+                }
+                catch (e) {
+                    warn('governor: bad sample: ' + errMsg(e));
+                }
+            });
+            child.stdin.on('error', () => undefined);
+            child.once('exit', () => {
+                this.child = null;
+                // It ends only when something is wrong: try again in a while.
+                setTimeout(() => this.start(), 30000).unref();
+            });
+        }
+        catch (e) {
+            warn('governor: could not start memgov.exe (no memory governor): ' + errMsg(e));
+        }
+    }
+    setPriority(pid, to) {
+        this.child?.stdin?.write('priority ' + pid + ' ' + to + '\n');
+    }
+    pause(pid, ms) {
+        this.child?.stdin?.write('suspend ' + pid + ' ' + ms + '\n');
+    }
+}
+/** The newest memory log SandboxTools writes, to add the governor's lines to it. */
+function appendToMemoryLog(line) {
+    try {
+        const logs = path.join(dataDir, 'logs');
+        const newest = fs
+            .readdirSync(logs)
+            .filter((f) => /^memory-\d{8}-\d{6}\.log$/.test(f))
+            .sort()
+            .pop();
+        if (!newest)
+            return;
+        const t = new Date();
+        const stamp = [t.getHours(), t.getMinutes(), t.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':');
+        fs.appendFileSync(path.join(logs, newest), stamp + ' | ' + line + '\r\n');
+    }
+    catch {
+        // The log is for people; a missing or locked one never matters.
+    }
+}
+/** The daemon's governor: on unless sandbox.pressureResponse is off. */
+export class Governor {
+    core = null;
+    describe() {
+        const profile = session.loadProfile === 'gentle' ? 'gentle' : 'normal';
+        const t = GUEST_THRESHOLDS[profile];
+        return session.pressureResponse === false
+            ? 'off (sandbox.pressureResponse)'
+            : profile +
+                ' profile: slows builds down below ' +
+                t.enterAvailablePercent +
+                '% free RAM or above ' +
+                t.enterCommitPercent +
+                '% commit';
+    }
+    start() {
+        if (session.pressureResponse === false)
+            return;
+        const profile = session.loadProfile === 'gentle' ? 'gentle' : 'normal';
+        const proc = new MemGovProcess((s) => this.core?.onSample(s));
+        this.core = new GovernorCore({
+            port: proc,
+            profile,
+            now: () => Date.now(),
+            logLine: appendToMemoryLog,
+            saveStatus: (status) => {
+                try {
+                    writeJsonAtomic(run.pressureFile, status);
+                }
+                catch (e) {
+                    warn('governor: could not write its status: ' + errMsg(e));
+                }
+            },
+        });
+        proc.start();
+    }
+    /** The host's watchdog: this PC is low for a while. */
+    hostPressure(seconds, reason) {
+        this.core?.hostPressure(seconds, reason);
+    }
+}
+export const governor = new Governor();

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

@@ -0,0 +1,2 @@
+export * from './decide.js';
+export * from './governor.js';

package/dist/guest/governor/index.js

@@ -0,0 +1,2 @@
+export * from './decide.js';
+export * from './governor.js';

package/dist/guest/runtime/csc.d.ts

@@ -7,6 +7,7 @@ declare const SOURCES: {
     readonly cargoshim: "CargoShim.cs";
     readonly linkgate: "LinkGate.cs";
     readonly pathsync: "PathSync.cs";
+    readonly memgov: "MemGov.cs";
 };
 export type Helper = keyof typeof SOURCES;
 /** %TEMP%\agent-sandbox\<name>-<hash>.exe, compiled from this launch's source the first time it is needed. */

package/dist/guest/runtime/csc.js

@@ -20,6 +20,7 @@ const SOURCES = {
     cargoshim: 'CargoShim.cs',
     linkgate: 'LinkGate.cs',
     pathsync: 'PathSync.cs',
+    memgov: 'MemGov.cs',
 };
 function sourceOf(name) {
     return path.join(launchDir, 'sandbox', 'csharp', SOURCES[name]);

package/dist/guest/sessions/viewer.js

@@ -30,7 +30,9 @@ export async function viewSession(id) {
         return 1;
     }
     const socket = await connect({ ...session.attach, addresses: ['127.0.0.1'] });
-    const result = await runTerminalClient(socket, session.attach.token);
+    // The sandbox's own terminal: a copy in the agent reaches the sandbox's clipboard (and yours only through
+    // sandbox.clipboard, which already shares it).
+    const result = await runTerminalClient(socket, session.attach.token, { clipboardWrites: true });
     if (result.reason === 'exit')
         console.log(session.harness + ' exited with code ' + result.exitCode + '.');
     else if (result.reason === 'error')

package/dist/guest/toolchains/native/rust-extras.js

@@ -7,6 +7,7 @@ import { execOutput } from '../../runtime/process.js';
 import { ensureCompiled } from '../../runtime/csc.js';
 import { arch, tool } from '../tool-env.js';
 import { wanted } from '../detect.js';
+import { cargoJobs } from '../../../shared/memory/index.js';
 /**
  * Where cargo builds: shared with the PC's target\, one on the sandbox's disk, or a path. "separate" sets no variable:
  * the cargo shim (sandbox/csharp/CargoShim.cs) gives every checkout its own target\sandbox, so git worktrees of several
@@ -66,8 +67,9 @@ export function cargoDefaults(host) {
     const file = tool('rust', 'cargo', 'config.toml');
     if (exists(file) || !exists(path.dirname(file)))
         return;
-    // Several agents often build at once: up to 4 jobs each (8 each crashed Windows inside the sandbox on 13 Oct 2026).
-    const jobs = Math.max(2, Math.min(4, Math.floor(os.cpus().length / 4)));
+    // Several agents often build at once: up to 4 jobs each (8 each crashed Windows inside the sandbox on 13 Oct 2026),
+    // and about 4 GB of memory per job. The daemon lowers it further per session (CARGO_BUILD_JOBS) when several build.
+    const jobs = cargoJobs(os.cpus().length, os.totalmem() / 1024 ** 3, 1);
     const gnu = host.endsWith('-gnu');
     fs.writeFileSync(file, [
         '# Written by windows-development-sandbox once; edit freely, it is never overwritten.',

package/dist/guest/vpn/vpn.js

@@ -9,6 +9,7 @@ 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';
@@ -18,6 +19,7 @@ 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 {
@@ -46,6 +48,21 @@ async function serverAddresses(remotes) {
     }
     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 {
@@ -74,31 +91,62 @@ export async function setupVpn(secrets, ptyHostExe) {
     try {
         if (!session.networking)
             throw new Error('networking is off for this sandbox');
-        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;
+        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);
         }
-        log('VPN: connecting to ' + vpn.server);
-        const result = await startTunnel({ exe, profile, username: credentials.username, password: credentials.password });
-        if (!result.ok)
+        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');
-        if (killSwitch)
-            netsh(tunnelCommands(result.tunnelIp));
         const publicIp = await publicAddress();
         log('VPN: up' + (publicIp ? ' (the sandbox appears as ' + publicIp + ')' : '') + '.');
         setVpnStatus('up', 'The tunnel is up', publicIp ? { publicIp } : {});

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>;