windows-development-sandbox 1.7.0 → 1.10.0

package/dist/guest/runtime/process.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { moveIntoPlace, spawnAsync, stagingFolder } from '../../shared/download/index.js';
 import { safeRemove } from '../../shared/io/safe-remove.js';
+import { robocopyErrors, robocopyFailed, robocopyMeaning } from '../../shared/io/robocopy-result.js';
 import { SYSTEM } from '../../shared/system.js';
 import { scriptArgs } from '../../shared/scripts.js';
 import { isWin } from './paths.js';
@@ -27,7 +28,18 @@ export function execOutput(file, args, options = {}) {
 }
 /** Runs sandbox\scripts\<name> (a .ps1 in the launch folder) with `args`; throws when it fails. */
 export function runScript(name, args = []) {
-    exec(SYSTEM.powershell(), scriptArgs(name, args));
+    const result = spawnSync(SYSTEM.powershell(), scriptArgs(name, args), {
+        stdio: ['inherit', 'inherit', 'pipe'],
+        encoding: 'utf8',
+        windowsHide: true,
+    });
+    if (result.error)
+        throw result.error;
+    const errors = String(result.stderr ?? '').trim();
+    if (errors)
+        process.stderr.write(errors + '\n');
+    if (result.status !== 0)
+        throw new Error(name + ' failed with exit code ' + result.status + (errors ? ': ' + errors.slice(0, 400) : ''));
 }
 /** runScript for what it prints ('' when it fails). */
 export function scriptOutput(name, args = [], options = {}) {
@@ -59,10 +71,46 @@ export function robocopy(from, to, files = []) {
             fs.copyFileSync(path.join(from, f), path.join(to, f));
         return;
     }
-    const what = files.length ? files : ['/E', '/MT:16'];
-    const result = spawnSync(SYSTEM.robocopy(), [from, to, ...what, '/NFL', '/NDL', '/NJH', '/NJS', '/NP', '/R:1', '/W:1', '/XJ'], { stdio: 'ignore', windowsHide: true });
-    if ((result.status ?? 16) >= 8)
-        throw new Error('robocopy ' + from + ' -> ' + to + ' failed (exit ' + result.status + ')');
+    const what = files.length ? files : ['/E'];
+    // A second pass for what the first could not copy (a file another program holds open for a moment, a busy mapped
+    // folder): one thread and more patience; robocopy skips what is already in place.
+    const passes = [
+        ['/MT:16', '/R:1', '/W:1'],
+        ['/MT:1', '/R:4', '/W:3'],
+    ];
+    let code = null;
+    let output = '';
+    for (const pass of passes) {
+        const result = spawnSync(SYSTEM.robocopy(), [
+            from,
+            to,
+            ...what,
+            ...(files.length ? [] : [pass[0]]),
+            pass[1],
+            pass[2],
+            '/NFL',
+            '/NDL',
+            '/NJH',
+            '/NJS',
+            '/NP',
+            '/XJ',
+        ], { encoding: 'utf8', windowsHide: true });
+        code = result.status;
+        output = String(result.stdout ?? '') + String(result.stderr ?? '');
+        if (!robocopyFailed(code))
+            return;
+    }
+    const why = robocopyErrors(output);
+    throw new Error('robocopy ' +
+        from +
+        ' -> ' +
+        to +
+        ' failed (exit ' +
+        code +
+        ': ' +
+        robocopyMeaning(code) +
+        ')' +
+        (why.length ? ': ' + why.join(' | ') : ''));
 }
 /**
  * A Node install without its global packages (nvm keeps those per version: often tens of thousands of small files,

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/setup/claude-mem.js

@@ -6,6 +6,7 @@ import { dryRun } from '../runtime/paths.js';
 import { exists, mkdirp } from '../runtime/fs.js';
 import { log, warn } from '../runtime/log.js';
 import { robocopy } from '../runtime/process.js';
+import { copyTreeTolerant } from '../../shared/io/copy-tree.js';
 /**
  * claude-mem keeps SQLite + a vector store. They run from the sandbox's own disk (SQLite and mapped folders do not
  * mix) and are mirrored to persistent storage, from where the host syncs them back to your PC.
@@ -49,8 +50,13 @@ const databaseFingerprint = (dir) => {
             if (entry.isDirectory())
                 walk(full);
             else if (entry.isFile() && /\.(db|sqlite3?)(-wal)?$/i.test(entry.name)) {
-                const s = fs.statSync(full);
-                parts.push(full + ':' + s.size + ':' + s.mtimeMs);
+                try {
+                    const s = fs.statSync(full);
+                    parts.push(full + ':' + s.size + ':' + s.mtimeMs);
+                }
+                catch {
+                    // Gone since the listing (a database being replaced): left out, the next save looks again.
+                }
             }
         }
     };
@@ -116,8 +122,10 @@ export function saveClaudeMem() {
     const incoming = store + '.incoming';
     const previous = store + '.previous';
     fs.rmSync(incoming, { recursive: true, force: true });
-    // The database, its -wal and -shm files are copied together, so the copy is consistent with itself.
-    fs.cpSync(local, incoming, { recursive: true, filter: (src) => !/\.(pid|lock)$/i.test(src) });
+    // The database and its -wal are copied together, so the copy is consistent with itself. A -journal is never copied:
+    // beside a database taken at another moment it would be rolled back over it. The -shm is rebuilt by SQLite. Files the
+    // agent removes while this runs (hook spool files) are skipped.
+    copyTreeTolerant(local, incoming, (name) => /\.(pid|lock)$|-journal$|-shm$/i.test(name));
     // Swap without a window where no copy exists: old aside, new in, then keep the old one as a dated backup.
     fs.rmSync(previous, { recursive: true, force: true });
     if (exists(store))

package/dist/guest/toolchains/languages/node.js

@@ -14,6 +14,7 @@ import { arch, tool } from '../tool-env.js';
 import { installOnce } from '../package-ledger.js';
 import { resolveCached } from '../version-cache.js';
 import { duringSession } from '../../runtime/project-context.js';
+import { session } from '../../runtime/session.js';
 import { pickNodeVersion, pickSpreadVersions } from '../../../core/detect/versions.js';
 const NVM_HOME = tool('nvm');
 const NVM_SYMLINK = path.join(localDir, 'nodejs');
@@ -73,7 +74,14 @@ const ensureNvm = async () => {
     log('Downloading nvm-windows (' + asset.url.split('/').slice(-2, -1)[0] + ') ...');
     await downloader.archive(asset.url, NVM_HOME, { sha256: asset.sha256, locate: 'nvm.exe', fileName: asset.name });
 };
-/** A Node version: from the host's nvm when it has it (fast, offline), else `nvm install`. */
+/** This PC's own Node folder (mapped read-only), when it is exactly this version. */
+const hostNodeFolder = (version) => {
+    const dir = path.join(hostToolsDir, 'node');
+    return session.hostTools.nodeVersion?.replace(/^v/, '') === version && exists(path.join(dir, 'node.exe'))
+        ? dir
+        : null;
+};
+/** A Node version: from the host's nvm or Node when it has it (fast, offline), else `nvm install`. */
 const installNodeVersion = async (version) => {
     const dir = path.join(NVM_HOME, 'v' + version);
     const fromHost = path.join(HOST_NVM, 'v' + version);
@@ -84,6 +92,12 @@ const installNodeVersion = async (version) => {
         copyNode(fromHost, dir);
         return;
     }
+    const hostNode = hostNodeFolder(version);
+    if (hostNode) {
+        log('Copying Node ' + version + ' from this PC (without global packages) ...');
+        copyNode(hostNode, dir);
+        return;
+    }
     log('Downloading Node ' + version + ' (~30 MB once) ...');
     mkdirp(NVM_TEMP);
     let out;
@@ -93,8 +107,20 @@ const installNodeVersion = async (version) => {
     finally {
         safeRemove(NVM_TEMP, NVM_HOME);
     }
-    if (!exists(path.join(dir, 'node.exe')))
-        throw new Error('nvm install ' + version + ' failed: ' + out.trim().split('\n').slice(-2).join(' '));
+    if (!exists(path.join(dir, 'node.exe'))) {
+        const tail = out.trim().split(/\r?\n/).filter(Boolean).slice(-3).join(' ');
+        const why = /complete/i.test(out)
+            ? 'nvm said it finished, but its move into the data folder did not happen'
+            : 'nvm could not download or unpack it: check the internet connection and the free disk space';
+        throw new Error('nvm install ' +
+            version +
+            ' did not leave ' +
+            path.join(dir, 'node.exe') +
+            ' (' +
+            why +
+            ')' +
+            (tail ? '. nvm printed: ' + tail : ''));
+    }
 };
 const activate = async (version) => {
     await nvm(['use', version]);

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

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

@@ -16,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>;

package/dist/host/channel/attach.js

@@ -53,7 +53,7 @@ export async function findUnwatchedSession(dataPath, harness, cwd) {
     return null;
 }
 /** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
-export async function attachTerminal(session) {
+export async function attachTerminal(session, o = {}) {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         fail('--terminal / attach needs an interactive terminal.', 'Run it directly in Windows Terminal or PowerShell, not through a pipe or script.');
     if (!session.attach)
@@ -71,7 +71,10 @@ export async function attachTerminal(session) {
         safeText(session.cwd) +
         '). Detach any time with Ctrl+]');
     await sleep(400);
-    const result = await runTerminalClient(socket, session.attach.token, { detachKey: DETACH_KEY });
+    const result = await runTerminalClient(socket, session.attach.token, {
+        detachKey: DETACH_KEY,
+        clipboardWrites: o.clipboardWrites,
+    });
     switch (result.reason) {
         case 'detach':
             console.log('Detached. The session keeps running; reattach with: sandbox attach ' + session.id);

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

@@ -46,6 +46,8 @@ export declare class SandboxChannel {
     exec(command: string[], cwd: string, timeoutSeconds: number): Promise<GuestResponse>;
     /** Restarts running sessions in place (they resume via the harness's resumeArguments, e.g. claude --continue). */
     restart(harness: string | null, cwd?: string): Promise<GuestResponse>;
+    /** The PC is low on memory or CPU: the sandbox slows its builds down for `seconds`. Never waits for an answer. */
+    pressure(reason: string, seconds: number): void;
     ping(): Promise<GuestResponse>;
     runningSessions(): SessionStatus[];
     /** Running sessions of the sandbox that is running now (its launch id), newest last, capped. */

package/dist/host/channel/channel.js

@@ -179,6 +179,10 @@ export class SandboxChannel {
         this.send({ kind: 'restart', id: requestId, harness, ...(cwd ? { cwd } : {}), createdAt: now() });
         return this.waitForResponse(requestId, 30000);
     }
+    /** The PC is low on memory or CPU: the sandbox slows its builds down for `seconds`. Never waits for an answer. */
+    pressure(reason, seconds) {
+        this.send({ kind: 'pressure', id: newId(), reason, seconds, createdAt: now() });
+    }
     async ping() {
         const requestId = newId();
         this.send({ kind: 'ping', id: requestId, createdAt: now() });